Skip to content

Prepare the Xmanager Started Task Procedure

Last update August 27, 2018

To prepare the Xmanager started ask procedure, customize the execution parameters in the default procedure (PTXMAN) in hlq.CDBASAMP. You can accept the default values for the supplied execution parameters or can edit them to execute multiple Xmanagers and to implement cross-system support. You can assign default values to JCL symbolic parameters. You can also control Xmanager execution by providing optional parameters on the EXEC statement in the Xmanager JCL procedure.

Important! The PTXMAN started task must be running at the same release or maintenance level as the release or maintenance level being installed. To complete the post-installation configuration process when a prior release or maintenance level of the same major release of the products is installed and running, start an alternate PTXMAN or recycle the current PTXMAN.

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 task. Every Xmanager task executing on the same LPAR must be assigned a unique 4-digit numeric ID. 

    Default: 0000

    Accept the default value unless you are executing multiple Xmanager tasks on the same LPAR.

    During Xmanager execution, the default value is converted to the current Xmanager version number. This setting facilitates migration to new Xmanager versions. Xmanager-based applications are able to connect to multiple Xmanager versions without having to change the XMANID that the application uses.

    More information

    Execute Multiple Xmanagers

    To enable communication between the Xmanager and the products, the XMANID value in the JCL must match the XMANID value in the SETUPxx global parmlib member. You can connect to multiple Xmanagers by maintaining multiple suffixed SETUPxx parmlib members. The XMANID parameter of each SETUPxx member corresponds to the XMANID JCL parameter for one of the Xmanagers.

  • INIT(membername)
    Specifies the name of a member that is used to execute the modify commands automatically when Xmanager is started. Xmanager looks for the member upon startup and if found, the commands in the member are executed.

    For a list of commands that you can execute using XMANINIT, see Manage the Xmanager Started Task.


    To execute commands automatically, create a member with as many commands as you want in the hlq.CDBAPXMP library. Note the following considerations:

    • Start each command with a hyphen (-) or dollar sign ($).
    • Use the same value (hyphen or dollar sign) for all commands in the same member.
    • You can extend a command over as many lines as necessary.
    • Columns 1 through 72 of each line are assumed to contain command text.
    • Columns 73 through 80 are assumed to contain sequence numbers and are ignored.
    • Start all comment lines with an asterisk (*). 

    Default: XMANINIT in hlq.CDBAPXMP
    Example: The following sample member shows how to set the sysplex interval value to 0200 and start CA Subsystem Analyzer for DB2 for z/OS data collection on DB2 subsystems DB2$ when Xmanager starts.

    -START(SSA)

    -PLEXINTV(0200)

     DB2(DB2$)

     PLAN(SSAPLAN1)

     INT(0015)

     DUR(0800)

     EXT(YES)

     DST(DB2$DATA)

     HLVL(hhhhh)

     AUTO(Y)

  • XSYS(Y|N)
    Implements Xmanager cross-system communications support. In this environment, each Xmanager in a sysplex complex connects to all other Xmanagers in the same complex. These connections provide transparent access to any DB2 subsystem in the sysplex complex executing on a z/OS platform that has an active Xmanager task.
    Enabling this support provides a distributed communications environment to access DB2 subsystems executing on any LPAR in a sysplex complex. When XSYS=Y, the Xmanager started task must be started on a z/OS system that is a member of a sysplex complex.

    Note: When XSYS=Y, we recommend that the involved Xmanagers use the same load library so they are at the same maintenance level. If the Xmanagers are at different maintenance levels, you must access data from the local Xmanager. The maintenance mismatch can potentially result in the display of user values that are inaccurate, an unexpected user abend, or both. If CA MIM Resource Sharing is used to ensure cross-system integrity of objects across all members of the sysplex, enable the QNAME CADB2 to propagate cross-system enqueues. If IBM Global Resource Serialization (GRS) is used instead, no further action is required.

    Default: N

    To implement cross-system support, adhere to the following guidelines:

    • An Xmanager started task must be active on each LPAR.

    • When starting each Xmanager started task, set XSYS to Y in the PTXMAN member in hlq.SPFSLIB to enable the cross-system communications support feature.

Optional Execution Parameters

The following Xmanager execution parameters are optional and can be used to customize Xmanager behavior. They are not supplied in the PTXMAN JCL procedure that is installed in hlq.CDBASAMP.

Note: If you are using the standard PTXMAN JCL procedure that CA Technologies supplies, you can specify these parameters using the OPT= parameter.

The following optional execution parameters can be specified:

  • CPUTIME(10|10-999)
    Specifies the number of CPU seconds Xmanager lets a process consume when satisfying a request routed from another Xmanager in the sysplex complex. The default value is sufficient for most sites. When the following conditions exist, you might need to increase the value of this parameter:
    • A request fails while accessing nonlocal DB2 subsystems
    • User 996 abends in the Xmanager on the LPAR where the nonlocal DB2 is located also accompany the failed request
    Limits: 10 to 999
    Default: 10 seconds
  • CUSHION(low,high)
    Specifies a numeric pair of storage limits interpreted in MB. The high value is optional, but if present it must be greater than the low value. 

    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. CA Detector® for DB2 for z/OS and CA Subsystem Analyzer for DB2 for z/OS recognize a short on storage condition and act to reduce their storage footprint before the shortage becomes critical. This action consists of suspending current active collections until the short on storage 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 region critical limit.

    Note:  In previous releases, Xmanager default behavior terminated the region if the amount of available storage fell below 10 MB. This behavior is the same as specifying CUSHION(10).

    Limits: 10 to 1000
    Default: 20,50

  • CUSH64(low,high)
    Specifies a numeric pair of memory object (64-bit storage) limits interpreted in MB. The high value is optional, but if present it must be greater than the low value.

    If the amount of 64-bit storage that is used to hold memory objects plus the CUSH64(high) value exceeds the memory object limit, a short on storage condition is signaled to the processes in the region. CA Detector® for DB2 for z/OS and CA Subsystem Analyzer for DB2 for z/OS recognize a short on storage condition and act to reduce their storage footprint before the shortage becomes critical. This action consists of suspending current active collections until the short on storage condition is relieved.

    The CUSH64(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 and Xmanager region termination begins.

    Limits: 0 to 2147483647

    Default: 100,200

  • ENV(eeeeeeee)
    Supplies an ENV string that passes into the CA Health Checker common service. This parameter enables the CA Health Checker common service to access CA Database Management Solutions for DB2 for z/OS parmlib information. This parameter helps the CA Health Checker common service perform health checks successfully when two or more Xmanagers running on a single LPAR are sharing a parmlib.
    Limits: 1 to 8 characters
    Default: Blank
  • FENCE (2|0-8)
    Specifies the amount of 1 MB storage (below the line) that is reserved for Xmanager abnormal 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-8
    Default: 2
  • HB (5|0-30)
    Specifies how often (in minutes) to send status information to the System State Manager (SSM) component of CA OPS/MVS® Event Management and Automation. Status updates are provided on Xmanager events at a specified interval.

    Note: Specify HB(0) to turn off this processing.

    Limits: 0 to 30 minutes
    Default: 5 minutes

  • MAXREGN(Y|N)
    Controls whether Xmanager can force the equivalent of REGION=0. The following values are valid:
    • Y
      Forces REGION=0. This value is the default.
    • N
      Does not alter any specified region size.
    Note: Be cautious about specifying MAXREGN(N) as enforcing too small of an Xmanager region size could result in frequent storage shortages in the Xmanager address space.

    The principal applications that execute in the Xmanager region are CA Detector® for DB2 for z/OS and CA Subsystem Analyzer for DB2 for z/OS. The monitoring activities of these applications can consume considerable storage. Especially, for example, if you enable CA Detector® for DB2 for z/OS collection options like dynamic SQL text statistics or additional view by keys. In addition, multiple DB2 subsystems can be monitored from a single Xmanager address space.

    Note: To help in ensure sufficient storage in prior releases, the Xmanager default behavior would be to alter the region storage limits to the equivalent of specifying REGION=0 regardless of the actual region size specified.
  • 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 exceeding 100 characters to your Xmanager startup job. Parameters are separated by a comma, for example:

    CUSHION(64,100),CPUTIME(999),CUSH64(200,5000)

    The Xmanager processes this parameter first. If the JCL contains duplicate values, the values in this parameter are overridden.
    Limits: 8 characters
    Default: XMANPARM

  • PLEXINTV(hhmm)
    Sets the Xmanager sysplex interval. The sysplex interval is an Xmanager managed time interval that you can use to provide a consistent time interval across all LPARS in a sysplex complex. Products such as CA Detector® for DB2 for z/OS and CA Subsystem Analyzer for DB2 for z/OS 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.

    Note: If you are using CA Detector® for DB2 for z/OS or CA Subsystem Analyzer for DB2 for z/OS, add this parameter to the START command.
  • SERVERS(5|5-100)
    Specifies the number of service tasks that are used to route requests between Xmanagers in a sysplex complex. The default value is sufficient for most sites. If you experience errors accessing nonlocal DB2 subsystems, it could be necessary to increase the value of this parameter.
    Limits: 5 to 100
    Default: 5

  • SUFFIX(xx)

    Supplies a suffix value that passes into the CA Health Checker common service. This parameter enables the CA Health Checker common service to access CA Database Management Solutions for DB2 for z/OS parmlib information. This parameter helps the CA Health Checker common service perform health checks successfully when two or more Xmanagers running on a single LPAR are sharing 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 be concurrently started in this Xmanager. For example, specifying TASKS(250) causes the Xmanager to allocate 205 MSW$COMM control blocks during the Xmanager startup initialization.
    Limits: 30-500
    Default: 50
  • TERMWAIT(1|0-30)
    Specifies the number of minutes Xmanager waits for subtasks, such as the collection manager, to terminate during Xmanager shut down before forcing subtask termination. The default of 1 minute is sufficient for most sites. A value of 0 results in the Xmanager waiting indefinitely for subtask termination.
    Limits: 0 to 30 minutes
    Default: 1 minute
  • TIMEOUT(20|0-600)
    Specifies the number of seconds Xmanager waits for a request that is routed to another Xmanager in the sysplex complex for execution to complete before signaling a timeout error. The default of 20 seconds is sufficient for most installations. If you experience timeouts accessing nonlocal DB2 subsystems, it could be necessary to increase the value of this parameter. A value of 0 results in the Xmanager waiting indefinitely for routed requests to complete.
    Limits: 0 to 600 seconds
    Default: 20 seconds
  • XTRACE(Y)
    Starts an Xmanager communication trace. The communication trace writes diagnostic messages to the Xmanager job log for requests that are routed between Xmanager tasks in the sysplex complex. The communication trace is intended for CA Support use only and can result in many messages being written to the Xmanager job log and system console. The XTRACE modify command can also control the Xmanager communications trace.

    Note: For assistance, contact CA Support.

Example: Specify Optional Execution Parameters

The following example shows how to use the OPT= parameter to specify the optional execution parameters:

S PTXMAN,XMANID=0000,XSYS=Y,OPT='parm1,parm2,...'

Example: Perform Health Checks for Multiple Xmanagers

After integration is completed with the IBM Health Checker and the CA Health Checker common service, several health checks are performed for licensed products automatically when Xmanager is started.

Within the Xmanager started task output, there are messages indicating that the Health Checker has started and ended:

GEN0901 CA-DB2 Tools Health Checker task attached

GEN0911 CA-DB2 Tools Health Checker interface initialization in progress

GEN0912 CA-DB2 Tools Health Checker interface initialization complete

...

GEN0913 CA-DB2 Tools Health Checker interface termination in progress

GEN0914 CA-DB2 Tools Health Checker interface termination complete

Under SDSF, you can display the health checks using the CK command. With CA SYSVIEW® Performance Management, you can display and update health check parameters. For example:

  • To display all health checks that are performed on an LPAR, specify:

    HCHECKER (HC)

  • To display only CA Database Management Solutions for DB2 for z/OS health checks, specify:

    HCHECKER CA_DB2

Was this helpful?

Please log in to post comments.