SET SYSDUMPCODE

Change an entry in the system dump table.

Syntax

SET SYSDUMPCODE

Conditions: DUPREC, INVREQ, IOERR, NOSPACE, NOTAUTH, NOTFND

NOHANDLE, RESP, and RESP2 are common options that can be added to all EXEC CICS commands to process error conditions. They are not explicitly included in the command syntax diagram and option descriptions. For information about these common options and EXEC CICS command syntax, see EXEC CICS command format and programming considerations. For more information about the use of CVDAs, see CICS-value data areas (CVDAs).

Description

The SET SYSDUMPCODE command allows you to change the system dump table entry for a particular dump code, to add a new dump code to the table, or to delete one.

The table entry tells CICS® the actions to take when a system dump request with this code occurs. Possible actions include taking a system dump (an SDUMP), initiating requests for SDUMPs of related CICS regions, and shutting down CICS. The table entry also indicates how many times this set of actions is to be taken (the MAXIMUM value); after the maximum is reached, requests are counted but otherwise ignored.

Table updates are recorded in the CICS global catalog and preserved over executions of CICS until an initial or cold start occurs, except in the case of temporary table entries. CICS creates a temporary entry using default values when it receives a dump request with code for which there is no table entry; these entries, and any changes to them, last only for the current execution of CICS. If you want to preserve changes to a temporary entry over restarts, you must remove the dump code from the table and then add it back. For more information, see What happens to a dump request if there is no dump table entry.

For information about system dumps, see How it works: Dumps, The system dump table, and The dump code options you can specify.

Options

ACTION(cvda)

Specifies the action to be taken for the dump code. CVDA values are:

ADD: An entry for this code is to be added to the table.
REMOVE: The entry for this code is to be removed from the table. No other option can be specified on a SET SYSDUMPCODE REMOVE command.
RESET: The current number of dump requests for this code is to be set to zero. See the CURRENT option of the INQUIRE SYSDUMPCODE command.

DAEOPTION(cvda)

Specifies whether a dump produced for this dump code is eligible for suppression by the z/OS® Dump Analysis and Elimination (DAE) component. CVDA values are:

DAE: The dump is eligible for DAE suppression.
NODAE: The dump is not eligible for DAE suppression. If CICS determines that a dump should be written, z/OS does not suppress it. However, the SUPPRESS and SUPPRESSALL options in the ADYSETxx parmlib member are controlled by the VRADAE and VRANODAE keys in the SDWA. They might lead to dump suppression even though NODAE is set here. For information about these options, see z/OS MVS Diagnosis: Tools and Service Aids.

When SET SYSDUMPCODE ADD is specified, if you do not also specify DAEOPTION, NODAE is used by default, regardless of the setting of the DAE system initialization parameter.

DSPLIST(data-value)

Specifies a list of data spaces to be dumped. This field contains up to 255 characters. Data space names are separated with commas. Wildcards are also supported. To specify a data space, you must provide its owning address space name, followed by a period and the data space name. The following example shows how to request the dumping of the data spaces of the SMSVSAM and the coupling facility:

DSPLIST(SMSVSAM.*,XCFAS.*)

Note: A user must have at least CONTROL access to the SET command to specify DSPLIST on SET SYSDUMPCODE.

For more information, see the SDUMPX documentation in z/OS MVS Programming: Authorized Assembler Services Reference (Volume 3).

DUMPSCOPE(cvda)

Specifies whether a request for a dump with this dump code causes CICS to initiate requests for SDUMPs (system dumps) of related CICS regions.

A related CICS region is one in the same sysplex, connected by MRO/XCF and doing work on behalf of your CICS region - specifically, a region that has one or more tasks doing work under the same APPC token as a task in your region.

This propagation of SDUMP requests occurs only when the table entry for this code also specifies a SYSDUMPING value of SYSDUMP, and only in a sysplex environment.

If you specify RELATED in other systems, this causes an exception condition.

CVDA values are:

LOCAL: SDUMP requests are not to be sent.
RELATED: SDUMP requests are to be sent.
Note: A setting of DUMPSCOPE(RELATED) results in a single dump being taken for each affected z/OS image. This dump contains the output from all the affected CICS regions in the image. For more information, see Automatic dump data capture from related CICS regions.

LOCAL is the default for entries you add, if you do not specify a DUMPSCOPE value.

JOBLIST(data-value)

Specifies a list of address spaces to be dumped. This field contains a maximum of 134 characters. Address space names are separated with commas. Wildcards are also supported. You can enter up to 15 address space names. However, if the matching results exceed 15 address spaces, only the first 15 spaces are dumped. The following example shows how to request the dumping of the SMSVSAM and coupling facility address spaces:

JOBLIST(SMSVSAM,XCFAS)

Note: A user must have at least CONTROL access to the SET command to specify JOBLIST on SET SYSDUMPCODE.

For more information, see the SDUMPX documentation in z/OS MVS Programming: Authorized Assembler Services Reference (Volume 3).

MAXIMUM(data-value)

Specifies, as a fullword binary value, the maximum number of dumps with this code that CICS should request, in the range 0-999. After the maximum is reached, CICS counts but ignores dump requests with this code. A value of 999 means there is no limit, and is the default for new entries if you do not specify a MAXIMUM value.

SHUTOPTION(cvda)

Specifies whether the system is to be shut down after a request for a dump with this dump code. CVDA values are:

NOSHUTDOWN: The system is not to be shut down. This value is assumed if you omit it from a SET SYSDUMPCODE ADD command.
SHUTDOWN: The system is to be shut down.; End-of-day statistics (shutdown statistics) are not written to SMF when you specify the SHUTDOWN option, so these statistics are lost.

SYSDUMPCODE(data-value)

Specifies the 8-character system dump code for which the system dump table entry is to be modified. A valid system dump code contains no leading or imbedded blanks.

SYSDUMPING(cvda)

Specifies whether a system dump request with this code should produce a dump. CVDA values are:

NOSYSDUMP: A dump is not to be taken.
SYSDUMP: A dump is to be taken.

Even when you specify SYSDUMP, CICS takes a dump only if the number of requests for this code is less than the MAXIMUM and system dumps are not suppressed globally (see the DUMPING option of the INQUIRE SYSTEM command). z/OS may also be allowed to suppress the dump if appropriate, depending on the DAEOPTION value.

If the SYSDUMPING option is omitted from a SET SYSDUMPCODE ADD command, SYSDUMP is assumed.

Conditions

DUPREC

RESP2 values:

10: ADD is specified for a dump code already in the system dump table.

INVREQ

RESP2 values:

2: ACTION has an invalid CVDA value.
4: SYSDUMPING has an invalid CVDA value.
5: The MAXIMUM value is out of range.
6: SHUTOPTION has an invalid CVDA value.
7: REMOVE is specified with other options.
9: The dump code is invalid.
13: DUMPSCOPE has an invalid CVDA value.
15: DAEOPTION has an invalid CVDA value.
16: The JOBLIST value is invalid.
17: The DSPLIST value is invalid.

IOERR

RESP2 values:

11: An error occurred updating the CICS catalog. The entry is changed for the current run, but is not recorded for restarts.

NOSPACE

RESP2 values:

12: The CICS catalog is full. The entry is changed for the current run, but is not recorded for restarts.

NOTAUTH

RESP2 values:

100: The user associated with the issuing task is not authorized to use this command.

NOTFND

RESP2 values:

1: The dump code cannot be found.