INQUIRE SYSDUMPCODE
Retrieve information about a system dump table entry.
Conditions: END, ILLOGIC, NOTAUTH, NOTFND
For more information about the use of CVDAs, see CICS-value data areas (CVDAs).
Description
You can use the INQUIRE SYSDUMPCODE command to look at some of the information in a system dump code table entry.
The table entry tells CICS® what actions to take when a system dump request with this code occurs, and how many times to take them (the MAXIMUM option). Requests received after the maximum is reached are counted (the CURRENT option), but are otherwise ignored.
CICS provides a system dump table with entries for some CICS-defined system dump codes. CICS builds table entries, using default values, when it receives a dump request with a code for which it does not have an entry. You can add your own entries with the SET SYSDUMPCODE command or with a CEMT transaction. Entries you add remain over executions of CICS until an initial or cold start occurs, but the entries that CICS builds are considered to be temporary and are discarded at shutdown. Consequently, if you inquire about a code that is not explicitly defined before it appears in a dump request, you get a not found response.
Browsing
You can also browse through all of the entries in the system dump code table by using the browse options (START, NEXT, and END) on INQUIRE SYSDUMPCODE commands. See Browsing resource definitions for general information about browsing, including syntax, exception conditions, and examples.
The resource signature
You can use this command to retrieve the resource signature fields. You can use these fields to manage resources by capturing details of when the resource was defined, installed, and last changed. For more information, see Auditing resources. The resource signature fields are BUNDLE, CHANGEAGENT, CHANGEAGREL, CHANGETIME, CHANGEUSRID, DEFINESOURCE, DEFINETIME, INSTALLAGENT, INSTALLTIME, and INSTALLUSRID. See Summary of the resource signature field values for detailed information about the content of the resource signature fields.
Options
- CHANGEAGENT(cvda)
- Returns a CVDA value that identifies the agent that made the last change to the resource
definition. The possible values are as follows:
- CREATESPI
- The resource definition was last changed by an EXEC CICS CREATE command.
- CSDAPI
- The resource definition was last changed by a CEDA transaction or the programmable interface to DFHEDAP.
- CSDBATCH
- The resource definition was last changed by a DFHCSDUP job.
- DYNAMIC
- The resource was last changed by a SET SYSDUMPCODE command.
- OVERRIDE
- The resource definition was last changed by application of an override rule in the resource overrides file.
- SYSTEM
- The resource definition was last changed by CICS.
- CHANGEAGREL(data-area)
- Returns a 4-digit number of the CICS release that was running when the resource definition was last changed.
- CHANGETIME(data-area)
- Returns an ABSTIME value that represents the time stamp when the resource definition was last changed. For more information about the format of the ABSTIME value, see FORMATTIME.
- CHANGEUSRID(data-area)
- Returns the 8-character user ID that ran the change agent.
- CURRENT(data-area)
- Returns a
fullword binary field that shows the number of dump requests with this dump code that have been made
since the count was last reset.
The count is reset automatically at CICS shutdown and can be reset explicitly with a SET SYSDUMPCODE command or its CEMT equivalent. The count includes requests that do not result in a dump because either CICS or MVS™ suppressed it.
- DAEOPTION(data-area)
- Returns
a CVDA value that shows whether a dump produced for this dump code
is eligible for subsequent suppression by the MVS Dump Analysis and Elimination (DAE) component.
CVDA values are as follows:
- 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, MVS does not suppress
it. Note: Be aware of the SUPPRESS and SUPPRESSALL options in the ADYSETxx parmlib member, which are controlled by the VRADAE and VRANODAE keys in the SDWA. These options might lead to dump suppression even though NODAE is in effect. For information about these options, see z/OS MVS Diagnosis: Tools and Service Aids.
- DEFINESOURCE(data-area)
- Returns the 8-character source of the resource definition. The DEFINESOURCE value depends on the CHANGEAGENT value. For more information, see Summary of the resource signature field values.
- DEFINETIME(data-area)
- Returns an ABSTIME value that represents the time stamp when the resource definition was created.
- DSPLIST(data-area)
- Returns a list of data spaces to be dumped. Data space names are separated with commas. This field contains up to 255 characters.
- DUMPSCOPE(cvda)
- Returns
a CVDA value that shows whether a request for a dump with this dump
code should cause an SDUMP (system dump) request to be sent to related z/OS® images.
A related z/OS image is one that contains a CICS region doing work on behalf of your CICS region. Specifically, it is a region that has one or more tasks doing work under the same APPC token as a task in your region.
The sending of SDUMP requests occurs only when the table entry for this code specifies a dump (that is, the SYSDUMPING value is SYSDUMP), and only in a sysplex environment executing under MVS/ESA Version 5.1 or later and the z/OS Workload Manager.
CVDA values are as follows:- 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.
- INSTALLAGENT(cvda)
- Returns a CVDA value that identifies the agent that installed the resource. The possible values
are as follows:
- AUTOINSTALL
- The resource was autoinstalled.
- CREATESPI
- The resource was installed by an EXEC CICS CREATE command.
- CSDAPI
- The resource was installed by a CEDA transaction or the programmable interface to DFHEDAP.
- DYNAMIC
- The resource was installed by a SET SYSDUMPCODE ADD command.
- GRPLIST
- The resource was installed by GRPLIST INSTALL.
- SYSTEM
- The resource was installed by CICS.
- INSTALLTIME(data-area)
- Returns an ABSTIME value that represents the time stamp when the resource was installed.
- INSTALLUSRID(data-area)
- Returns the 8-character user ID that installed the resource.
- JOBLIST(data-area)
- Returns a list of address spaces to be dumped. Address space names are separated with commas. This field contains up to 134 characters.
- MAXIMUM(data-area)
- Returns a fullword binary field that shows the maximum number of dumps with this code that CICS will take. A value of 999 means the default of no limit.
- SHUTOPTION(cvda)
- Returns
a CVDA value that shows whether the CICS system
is to be shut down after a request for a dump with this dump code.
CVDA values are as follows:
- NOSHUTDOWN
- The CICS system is not to be shut down.
- SHUTDOWN
- The CICS system is to be shut down.
- SYSDUMPCODE(data-value)
- Specifies the 8-character system dump code about which you are inquiring. A valid code contains no leading or imbedded blanks.
- SYSDUMPING(cvda)
- Returns a CVDA value that shows whether a dump request with this code
should produce a dump or not. Even when a dump is specified, CICS will produce one only when the CURRENT value is no greater than the MAXIMUM, and when
system dumps are not suppressed globally (see the DUMPING option of the INQUIRE SYSTEM command. MVS can also
suppress the dump if appropriate (the DAE option). CVDA values are as follows:
- NOSYSDUMP
- A dump is not to be produced.
- SYSDUMP
- A dump is to be produced.
Note: Dumps from the kernel domain of CICS are not subject to suppression and are taken regardless of the SYSDUMPCODE value.
Conditions
- END
- RESP2 values:
- 2
- There are no more resource definitions of this type.
- ILLOGIC
- RESP2 values:
- 1
- You have issued a START command when a browse of this resource type is already in progress, or you have issued a NEXT or an END command when a browse of this resource type is not in progress.
- NOTAUTH
- RESP2 values:
- 100
- The user associated with the issuing task is not authorized to use this command.
- NOTFND
- RESP2 values:
- 1
- The named dump code cannot be found.