Prepare the Xmanager Started Task Procedure

Preparing the Xmanager started task procedure consists of customizing the execution parameters in
hlq
.CDBASAMP(PTXMAN).
staging
Each Xmanager executes as a started task in its own address space. A sample JCL procedure for this started task is created during installation and placed in
hlq
.CDBASAMP. The default procedure name is PTXMAN.
If you plan to run a single Xmanager on an LPAR, you only need a single PTXMAN.
If you plan to run multiple Xmanagers on a single LPAR, you might use a single PTXMAN for all Xmanagers on the LPAR, or you might require multiple PTXMANs.
The products and non-Xmanager address spaces that connect to an Xmanager must be running a maintenance Level Set that meets or exceeds the highest active Level Set of that Xmanager. If you have just applied a new maintenance Level Set to the load library that an Xmanager uses, restart the Xmanager to pick up the change.
2
2
Prepare the Started Task Procedure
Preparing the started task procedure consists of customizing its execution parameters and copying it to a systems procedure library.
Review the guidance in Determine the Number of Xmanagers Per LPAR, and then follow this procedure for each PTXMAN that you need.
Follow these steps:
  1. Select option
    2 (Customize)
    from the Post-Install Tailoring menu and press Enter.
  2. Select a PTISYS parmlib member and press Enter.
  3. Type
    S
    next to
    PXM (Xmanager)
    and press Enter.
  4. Select option
    4 (Prepare Xmanager Started Task Procedure)
    and press Enter.
  5. Enter the fully qualified data set name of the loadlib for the
    oldest
    Db2 release that you use and press Enter. Compatibility issues can occur when an older Db2 release attempts to use a newer loadlib. Specifying the oldest loadlib helps prevent this problem.
    The default started task procedure (PTXMAN in
    hlq
    .CDBASAMP) appears in an edit session.
  6. Customize the PTXMAN procedure:
    • Specify values for XMANID, XSYS, and INIT. These parameters are described later in this article.
    • Specify which Xmanager configuration file (XMCF) to use. You can allocate the file dynamically or manually; we recommend dynamic allocation.
      • To allocate the configuration file dynamically, specify the CFHLQ parameter and (optionally) the CFMLQ parameter. These parameters are described later in this article.
      • To allocate the configuration file manually, add a PXMCNFG DD statement that specifies the XMCF data set name with DISP=SHR.
      Use only one method to allocate the data set name. If you specify the CFHLQ and CFMLQ parameters and also specify a PXMCNFG DD statement, the DD statement is used. The parameters are ignored.
    • (Optional) Use the OPT parameter to specify more parameters. These parameters are described later in this article.
      If you specify XSYS(Y):
      • Also specify a value for PLEXINTV to provide a consistent time interval across all LPARs in a sysplex.
      • Omit the GROUP parameter to assign the Xmanager to the default coupling facility group, or include the GROUP parameter to assign the Xmanager to a different group.
    • Review the REGION and MEMLIMIT values and adjust them as needed.
    • Complete the DD statements. For descriptions of these statements, see the comments in the PTXMAN procedure.
    Press F3.
    Your changes are saved and you return to the PXM Customization panel.
  7. Copy the PTXMAN member from your CDBASAMP library to a systems procedure library (PROCLIB) where procedures that start tasks are stored. If you create multiple PTXMANs, give each one a unique name.
    This step is required even when the PROCLIB contains a PTXMAN procedure from a previous version. Replace the older procedure with your new one.
Supplied Execution Parameters
The following Xmanager execution parameters are supplied in the PTXMAN JCL procedure in
hlq
.CDBASAMP:
  • XMANID(
    xmanid
    )
    Specifies the ID for this Xmanager. Every Xmanager that executes on the same LPAR must have a unique 4-digit numeric ID.
    If either of the following conditions are true, accept the default value for XMANID:
    • This LPAR has only one Xmanager.
    • This LPAR has multiple Xmanagers and they are sharing this started task procedure. When you start each Xmanager, specify a unique ID and job name in the START command. (See the command syntax in Start an Xmanager.)
    If this LPAR has multiple Xmanagers and they are
    not
    sharing this started task procedure, specify a different value for XMANID.
    The XMANID value that you specify here must match the XMANID value in the
    SETUP
    xx
    global parmlib member of the corresponding Xmanager.
    Default:
    0000
    The default value is represented internally as 2000. This internal change provides migration support from Version 19.0, which was represented internally as 1900. If you use the default value of 0000, the Xmanager ID will appear as 2000 in job log messages, Level Set reports, and anywhere else that the ID is externalized for viewing.
  • XSYS(Y|
    N
    )
    Specifies whether to enable Xmanager cross-system (sysplex) communications support. The Xmanagers within a sysplex are organized into one or more groups. When sysplex support is enabled, each Xmanager in a group connects to all other Xmanagers in the same group. These connections provide transparent access to any Db2 subsystem in the sysplex that is executing on a z/OS platform with an active Xmanager task.
    The Xmanagers in each group must be running a maintenance Level Set that is equal to or higher than the highest active Level Set for that group. Any Xmanager with a lower Level Set is not permitted to start up within the group. For more information, see Add an Xmanager to an Existing Group.
    When XSYS(Y) is specified, the Xmanager started task must be started on a z/OS system that is a sysplex member.
    When you implement cross-system support, follow these guidelines:
    • Specify XSYS(Y) for each Xmanager started task.
    • Omit the GROUP parameter to assign the Xmanager to the default coupling facility group, or include the GROUP parameter to assign the Xmanager to a different group.
    • If CA MIM Resource Sharing is used to ensure cross-system integrity of objects across all sysplex members, enable the QNAME CADB2 to propagate cross-system enqueues. If IBM Global Resource Serialization (GRS) is used instead, no further action is required.
    • Verify that an Xmanager started task is active on each LPAR.
    • Add the PLEXINTV parameter to establish a consistent time interval across all LPARs in a sysplex.
    Default:
    N
  • INIT(
    membername
    )
    Specifies the member that is used to execute modify commands automatically when Xmanager is started. Xmanager looks for this member upon startup and, if it is found, executes the commands in the member.
    For more information about executing modify commands automatically, see Execute Xmanager Modify Commands.
    Default:
    XMANINIT in
    hlq.
    CDBAPXMP
Optional Execution Parameters
Use the following optional Xmanager execution parameters to customize the Xmanager behavior. These parameters are not supplied in the PTXMAN JCL procedure in
hlq
.CDBASAMP; you can add them by using the OPT= parameter. See the example at the end of this article.
  • CFHLQ(
    high-level-qualifier
    )
    Specifies the high-level qualifier of the Xmanager configuration file (XMCF) to use. Each Xmanager requires its own XMCF. These files are created during post-installation.
    If multiple Xmanagers will share an
    hlq
    .CDBAPXMP(XMANPARM) member, we recommend specifying CFHLQ in XMANPARM and specifying PARMS(XMANPARM) here in the PTXMAN to point to that member. Placing the parameter in XMANPARM lets you specify it in one place instead of specifying it individually for each Xmanager.  Alternately, you can specify CFHLQ here. The value that you specify here overrides the value in XMANPARM.
    You can also specify the XMCF to use by adding a PXMCNFG DD statement to this PTXMAN.
    Only use one method to specify the data set name.
    When you specify a PXMCNFG DD statement, any CFHLQ values that are specified here or in XMANPARM are ignored.
    Limits:
    1 to 17 bytes
    Default:
    None
  • CFMLQ(
    middle-level-qualifier
    )
    Specifies the middle-level qualifier of the Xmanager configuration file (XMCF) to use. Only specify this parameter when the XMCF does not use the default middle-level qualifier. When you omit this parameter, the default value is used.
    This parameter should only be specified here in the PTXMAN JCL. Do not specify CFMLQ in the XMANPARM member. If multiple Xmanagers share that member, they all try to use the same XCMF. Each Xmanager requires its own XCMF with a unique name.
    If you specify CFMLQ, you must also specify CFHLQ.
    You can also specify the XMCF to use by adding a PXMCNFG DD statement to this PTXMAN.
    Only use one method to specify the data set name.
    When you specify a PXMCNFG DD statement, any CFMLQ values that are specified here are ignored.
    Limits:
    1 to 17 bytes
    Default:
    lparname
    .N
    xmanid
  • CPUTIME(
    10
    |10-999)
    Specifies the number of CPU seconds that Xmanager lets a process consume when it is satisfying a request from another Xmanager in the sysplex. The default value is sufficient for most sites. Consider increasing the value when the following conditions exist:
    • A request fails when nonlocal Db2 subsystems are accessed.
    • The failed request is accompanied by user 996 abends in the Xmanager on the nonlocal LPAR.
    Limits:
    10 to 999
    Default:
    10 seconds
  • CUSHION(
    low
    ,
    high
    )
    Specifies a numeric pair of storage limits in MB. The high value is optional.
    If the amount of available region storage falls below the high limit, a "short on storage" condition is signaled to the processes in the region.
    Detector
    and
    Subsystem Analyzer
    recognize the condition and suspend their current active collections until the condition is relieved.
    The low limit is considered a region-critical limit. If the amount of available storage falls below the low limit, a "short on storage" condition is signaled and Xmanager region termination begins.
    If you specify CUSHION with only one value, it is interpreted as the low value.
    Limits:
    10 to 1000
    Default:
    20,50
  • CUSH64(
    low
    ,
    high
    )
    Specifies a numeric pair of memory object (64-bit storage) limits in MB. The high value is optional.
    If the amount of 64-bit storage plus the high-limit value exceeds the memory object limit, a "short on storage" condition is signaled to the processes in the region. CA Detector and CA Subsystem Analyzer recognize the condition and suspend their active collections until the condition is relieved.
    The low limit is considered a region critical limit. If the available 64-bit storage (memory object limit minus the memory object used) falls below this limit, a "short on storage" condition is signaled. Xmanager region termination begins.
    Limits:
    0 to 2147483647
    Default:
    100,200
  • ECSA(
    nn
    )
    Monitors the amount of ECSA storage that is in use. If the used storage exceeds the specified percentage, Xmanager terminates any active
    Detector
    data collections to free up the storage space. If you are receiving ECSA error messages during CA Detector collections, use this parameter to avoid ECSA constraints. We recommend specifying a value of 95. If you omit this parameter, the ECSA storage is not monitored.
    Limits:
    From 1 to 99 percent
  • ENV(
    eeeeeeee
    )
    Supplies an ENV string that is passed to the CA Health Checker common service. This parameter lets the CA Health Checker access
    CA Database Management Solutions for DB2 for z/OS
    parmlib information and perform health checks when two or more Xmanagers on the same LPAR share a parmlib.
    The SUFFIX parameter overrides the ENV parameter. Do not specify these parameters together.
    Limits:
    1 to 8 characters
    Default:
    Blank
  • FENCE(
    2
    |0-8)
    Specifies how much storage (below the line) to reserve for abnormal Xmanager termination. If the value exceeds the available low region size, minus a 1-MB minimum reserve, the Xmanager issues message PXM0371 and ignores the parameter.
    Limits:
    0 to 8
    Default:
    2 MB
  • GROUP(
    groupname
    )
    Assigns the Xmanager to a coupling facility group other than the default group. By default, any Xmanager that has XSYS(Y) specified is added to the PXM2000 group automatically. The GROUP parameter is needed only when you specify XSYS(Y) and you want to assign an Xmanager to a different group.
    All Xmanagers in a group must specify the same group name in their PTXMAN JCL. Alternately, you can specify the group name in
    hlq
    .CDBAPXMP(XMANPARM) and then specify PARMS(XMANPARM) here in PTXMAN to point to that member. The PARMS parameter is described later in this article.
    You cannot exceed the number of groups or the number of members (Xmanagers) per group that the coupling facility can support. These numbers are specified when the coupling facility data set is created by using the IBM IXCL1DSU utility. Use the DISPLAY XCF,COUPLE command to determine the maximum values for your coupling facility. For more information about this command, see the IBM documentation.
    Limits:
    1 to 8 alphanumeric characters
    Default:
    PXM2000
    You cannot use NOXCFGRP as a group name; this name is reserved.
  • HB(
    5
    |0-30)
    Specifies how often (in minutes) to send Xmanager status information to the System State Manager (SSM) component of CA OPS/MVS® Event Management and Automation. Specifying HB(0) turns off this processing.
    Limits:
    0 to 30 minutes
    Default:
    5 minutes
  • MAXREGN(
    Y
    |N)
    Controls whether Xmanager can force the equivalent of REGION=0:
    • Y
      Forces REGION=0. This value is the default.
    • N
      Does not alter any specified region size.
      Be cautious about specifying MAXREGN(N). Enforcing an Xmanager region size that is too small can cause frequent storage shortages in the Xmanager address space.
      CA Detector and CA Subsystem Analyzer are the principal applications that execute in the Xmanager region. The monitoring activities of these applications can consume considerable storage, especially collection options like dynamic SQL text statistics or additional view by keys. Also keep in mind that a single Xmanager address space can monitor multiple Db2 subsystems. The more subsystems that an Xmanager monitors, the more storage it may need.
  • PARMS(
    mbr-name
    )
    Specifies a member name in the PDS on the PXMPARM DD statement of the Xmanager. This member lets you pass a list of parameters that exceeds 100 characters to your Xmanager startup job. Parameters are separated by a comma as shown in the following example:
    CUSHION(64,100),CPUTIME(999),CUSH64(200,5000)
    Xmanager processes this parameter list first. If the started task JCL contains any of the same parameters as the list, the JCL values override the list values.
    Limits:
    1 to 8 characters
    Default:
    XMANPARM
  • PLEXINTV(
    hhmm
    )
    Sets the Xmanager sysplex interval. Use this Xmanager-managed time interval to provide a consistent time interval across all LPARs in a sysplex. Products such as CA Detector and CA Subsystem Analyzer use this time interval to coordinate time-related activities.
    We recommend that you set this parameter by adding a PLEXINTV(
    hhmm
    ) modify command to the XMANINIT member in the
    hlq
    .CDBAPXMP library. (See Execute Xmanager Modify Commands.) If you specify PLEXINTV in XMANINIT and also here in PTXMAN, the PTXMAN value is used.
    Alternately, when you are using CA Detector and CA Subsystem Analyzer, you can add this parameter to the START command. If you specify PLEXINTV as part of the START command, that value overrides any PTXMAN or XMANINIT value.
    If you use these products, use the Xmanager sysplex interval when starting data collection in those products. If you start the collections using the product panels, specify Use Sysplex Interval Time=Y on the panels. If you start the collections using the START modify command, specify PLEXINTV(Y) in the command. For more information about starting data collections, see the product documentation.
  • SERVERS(
    5
    |5-100)
    Specifies the number of service tasks to use when routing requests between Xmanagers in a sysplex. The default value is sufficient for most sites. If you experience errors when accessing nonlocal Db2 subsystems, increase the value of this parameter.
    Limits:
    5 to 100 tasks
    Default:
    5 tasks
  • SUFFIX(
    xx
    )
    Supplies a suffix value that is passed to the CA Health Checker common service. This parameter lets the CA Health Checker access
    CA Database Management Solutions for DB2 for z/OS
    parmlib information and perform health checks when two or more Xmanagers on the same LPAR share a parmlib.
    The SUFFIX parameter overrides the ENV parameter. Do not specify these parameters together.
    Limits:
    2 characters
    Default:
    blank
  • TASKS(
    50
    |30-500)
    Specifies the number of subtasks that can run concurrently for this Xmanager. For example, specifying TASKS(250) causes the Xmanager to allocate 250 MSW$COMM control blocks during the Xmanager startup.
    Limits:
    30-500
    Default:
    50
  • TERMWAIT(
    1
    |0-30)
    Specifies how long the Xmanager waits for subtasks like the collection manager to terminate during Xmanager shutdown before it forces the subtasks to terminate. The default of 1 minute is sufficient for most sites. If you specify 0, Xmanager waits indefinitely for subtasks to terminate.
    Limits:
    0 to 30 minutes
    Default:
    1 minute
  • TIMEOUT(
    20
    |0-600)
    Specifies the number of seconds that Xmanager waits for a request to another Xmanager in the sysplex to complete before signaling a timeout error. The default of 20 seconds is sufficient for most installations. If you experience timeouts when accessing nonlocal Db2 subsystems, increase the value. If you specify 0, the Xmanager waits indefinitely for routed requests to complete.
    Limits:
    0 to 600 seconds
    Default:
    20 seconds
Example: Specify Optional Execution Parameters
The following example shows how to use the OPT= parameter to specify optional execution parameters:
//PTXMAN PROC XMANID='0000',XSYS='Y',INIT='XMANINIT', // OPT='
parm1
,
parm2
,...'