Controlling coupling facility data table server regions

You can issue commands to control a coupling facility data table server, using the MVS™ MODIFY (F) command to specify the job or started task name of the server region, followed by the server command. The general form of a coupling facility data table server command, using the short form F, is as follows:

F job_name,command parameters... comments

The commands supported by a coupling facility data table server are:

These commands and their options are as follows:

SET keyword=operand[,keyword=operand,...]
Change one or more server parameter values. The command can be abbreviated to T, as for the MVS SET command. See The SET command options for details.
DISPLAY keyword[=operand][,keyword[=operand,]...]
Display one or more parameter values, or statistics summary information, on the console. The valid keywords for DISPLAY are all the initialization parameters, plus an additional set described under DISPLAY and PRINT command options.

The command can be abbreviated to D, as for the MVS DISPLAY command.

PRINT keyword[=operand][,keyword[=operand,]...]
Produces the same output as DISPLAY, supporting the same keywords, but on the print file only.
DELETE TABLE=name
Delete the named table. The table must not be in use for this command to succeed. The command can be abbreviated to DEL.
STOP
Terminate the server normally. The server waits for any active connections to terminate first, and prevents any new connections while it is waiting. The command can be abbreviated to P, as for the MVS STOP command.
Note:
You can also use the MVS STOP command.
P jobname
This is equivalent to issuing the server STOP command through the MVS MODIFY command.
CANCEL {RESTART={NO|YES}}
Terminate the server immediately. You can specify whether automatic restart should be requested.

For information about CANCEL RESTART see The CANCEL command options.

The SET command options

You can use the SET command to modify the following groups of server initialization parameters:

See Coupling facility data table server parameters for details of these keywords.

The following SET keywords are used to modify the server's recovery status of an inactive CICS® region that had unresolved units of work when it last terminated:

RESTARTED=applid
Establish a temporary recoverable connection for the given APPLID. This resolves any units of work that were in commit or backout processing when the region last terminated, and indicates whether there are any remaining in-doubt units of work.

This keyword can be abbreviated to RESTART or REST.

COMMITTED={applid|applid.uowid}
Establish a temporary recoverable connection for the specified APPLID and commit all in-doubt units of work, or, if uowid is also specified, commit that specific unit of work.

This command should be used only when it is not possible to restart the original CICS region to resolve the work normally, because it can result in inconsistency between coupling facility data table resources and other CICS resources updated by the same unit of work.

This keyword can be abbreviated to COMMIT or COMM.

BACKEDOUT={applid|applid.uowid}
Establish a temporary recoverable connection for the specified APPLID and back out all in-doubt units of work, or, if uowid is also specified, back out that specific unit of work.

This command should be used only when it is not possible to restart the original CICS region to resolve the work normally, because it can result in inconsistency between coupling facility data table resources and other CICS resources updated by the same unit of work.

This keyword can be abbreviated to BACKOUT or BACK.

Use the following SET parameters to modify options relating to a specific table:

TABLE=name
specifies the table to which the following table-related parameters in the same command are to be applied. This parameter is required before any table-related parameters.
MAXRECS=number
Modify the maximum number of records that can be stored in the table specified by the preceding TABLE parameter.

If the maximum number is set to a value less than the current number of records in the table, no new records can be stored until records have been deleted to reduce the current number to within the new maximum limit. For a recoverable table, this also means that records cannot be updated, because the recoverable update process adds a new record on the rewrite operation then deletes the original record when the transaction completes.

This keyword can also be specified as MAXNUMRECS.

AVAILABLE={YES|NO}
Specify whether the table named by the preceding TABLE parameter is available for new OPEN requests. If the table is made unavailable, a CICS region that subsequently issues an OPEN request for the table receives a response indicating that it is unavailable, but regions that currently have the table open are not affected. Even when a table is marked as unavailable, a server can implicitly open it on behalf of a CICS region to allow recoverable work to be resolved during restart processing.

This keyword can be abbreviated to AVAIL.

Examples of the SET command: The following example changes the statistics options:

SET STATSOPT=BOTH,EOD=21:00,STATSINT=06:00

The following example modifies the maximum number of records allowed in the specified table:

SET TABLE=PAYECFT1,MAXRECS=200000

DISPLAY and PRINT command options

You can use the DISPLAY (and PRINT) commands to display the values of any initialization parameters plus some additional information.

Some of the parameters that provide additional information support generic names. You specify generic names using the following wildcard characters:

The parameters supported by the DISPLAY and PRINT commands are as follows:

APPLIDS
Display the APPLID and MVS system name for every CICS region that currently has a recoverable connection to the pool. This command returns information not only for the server to which the MODIFY command is issued, but for all other servers connected to the same pool.

This keyword can be abbreviated to APPLID, APPLS or APPL.

APPLID={applid|generic}
Display the APPLID and MVS system name for each region that currently has a recoverable connection to the server's pool, and whose APPLID matches applid or generic. This command returns information not only for the server to which the MODIFY command is issued, but for all other servers connected to the same pool.
applid
Use this for a specific APPLID, which should match only one region in the sysplex.
generic
Use a suitable generic value when you want to obtain information about several regions.

If applid or generic is not specified, the server treats this as equivalent to the command DISPLAY APPLIDS.

This keyword can also be specified as APPLIDS, APPLS or APPL.

ARMREGISTERED
Shows whether ARM registration was successful (YES or NO).
CONNECTIONS
Display the jobnames and applids of the regions currently connected to the server to which the command is issued.

This keyword can be abbreviated to CONN.

TABLES
Display the names of all tables currently allocated in the pool.
TABLE={name|generic_name}
Display information about the attributes and status of a specific table, or of a set of tables whose names match the generic name.

If no table name is specified, this is treated as equivalent to DISPLAY TABLES.

TABLEUSERS
Display the CICS APPLIDs of the regions that are currently using each of the tables currently defined in the pool.

This keyword can be abbreviated to TABLEU.

TABLEUSERS={name|generic_name}
Display the CICS APPLIDs of the regions that are currently using the specified table, or using each of the set of tables whose names match the generic name.

If no table name is specified, this is treated as equivalent to DISPLAY TABLEUSERS.

This keyword can be abbreviated to TABLEU

UOWIDS
Display the applids of all regions that currently have unresolved recoverable units of work, together with the number of units of work that are currently in doubt, or are in the process of being committed or backed out.

This keyword can be abbreviated to UOWS.

UOWIDS={applid|generic_applid}|{applid.*|generic_applid.*}
Display, for the specified regions if they currently have unresolved recoverable units of work, information about those units of work. The information returned depends on the form of operand used.
applid|generic_applid
This form of operand displays simply the number of units of work that are currently in doubt, or are in the process of being committed or backed out.

If you specify applid, the server displays UOW information for a specific APPLID, which should correspond to only one region in the sysplex.

If you specify generic_applid the server displays UOW information for all the APPLIDs that match the generic APPLID specified.

applid.*|generic_applid.*
This form of operand displays:
  • The state and local UOWID of each individual unit of work, followed by
  • A summary of the number of units of work that are currently in doubt, or are in the process of being committed or backed out.

If you specify applid.*, the server displays the UOW information for a specific APPLID, which should correspond to only one region in the sysplex.

If you specify generic_applid.*, the server displays UOW information for all the APPLIDs that match the generic APPLID specified.

This keyword can be abbreviated to UOWS.

UOWID=applid.uowid
Display the state of an individual unresolved unit of work, identified by its applid and local unit of work ID (UOWID). Enter the local UOWID as 16 hexadecimal digits.

This keyword can be abbreviated to UOW.

DISPLAY and PRINT options for statistics summaries

Use the following parameters to display or print statistics:

CFSTATS
Display statistics for coupling facility interface accesses and responses from the server.

This keyword can also be specified as CFST or STATSCF.

POOLSTATS
Display usage statistics for the pool list structure as a whole. This is based on information returned by coupling facility access requests, therefore it is only as current as the most recent request made through the server to which the command is issued.

This keyword can be abbreviated to POOLST.

TABLESTATS
Display statistics for requests, processed by the server to which the command is issued, for each table plus a summary of all requests processed, including those that are not table-specific, such as unit of work control.

Note that only tables with a non-zero number of requests since the start of the current statistics interval are shown.

This keyword can also be specified as TABLEST.

TABLESTATS={name|generic_name}
Display request statistics for the specified table or tables.
name
A specific table name in the pool accessed by the server. Returns statistics for this table only.
generic_name
A generic name that you can use to obtain statistics about a number of tables. Returns statistics for any table name that matches the generic name.

This keyword can be abbreviated to TABLEST.

STORAGESTATS
Display main storage allocation statistics for the server address space.

This keyword can be abbreviated to STORAGEST or STGST.

DISPLAY and PRINT options for combined lists of information

These keywords represent combined lists of information:

PARAMETERS
Display the main parameter values. These are POOLNAME, SECURITY, SECURITYPREFIX, statistics options, and list structure options.

This keyword can be abbreviated to PARM or PARMS.

ALLPARAMETERS
Display all parameter values.

This keyword can be abbreviated to ALLPARMS.

STATISTICS
Display all available statistics.

This keyword can be abbreviated to STAT or STATS.

INITIALIZED
Display the parameters and statistics that are usually displayed when initialization is complete. This is equivalent to PARM, POOLSTATS, STGSTATS.

This keyword can be abbreviated to INIT.

ARM
Display all ARM-related parameter values:

This keyword can be coded as ARMSTATUS.

The CANCEL command options

You can use the CANCEL command to request automatic restart by specifying the following parameter:

RESTART={NO|YES}
Terminate the server immediately, specifying whether or not automatic restart should be requested. The default is RESTART=NO.

If the server encounters an unrecoverable problem with the coupling facility connection, consisting either of lost connectivity or a structure failure, it cancels itself using the CANCEL RESTART=YES command. This terminates the existing connection and shuts down the server. A new instance of the server job is then started.

A server can also be restarted explicitly using either the server command CANCEL RESTART=YES or the MVS command CANCEL jobname, ARMRESTART.

You can also enter RESTART on its own for RESTART=YES, NORESTART for RESTART=NO.

SETXCF commands

The server also responds to XES events such as an operator SETXCF command to alter the structure size. If the server can no longer access the coupling facility, it automatically issues a server CANCEL command to close itself down immediately.

[[ Contents Previous Page | Next Page Index ]]