PERFORM DUMP

Description

The PERFORM DUMP command requests a system dump (an MVS SDUMP) of the CICS region in which it is issued.

The system dump table entry for the dump code specified in the DUMPCODE option determines the processing that occurs on a PERFORM DUMP command: whether a dump is taken, whether the request is propagated for related CICS regions in a sysplex environment, and whether shutdown occurs. If there is no entry for the dump code you specify, CICS creates a temporary one by using default values. See the INQUIRE SYSDUMPCODE command for more information about this process and The dump code options you can specify for general information about the system dump table.

While an MVS SDUMP is being taken, all other CICS activity ceases. The program issuing the command does not regain control until the dump is complete, and then only if the dump does not cause CICS to shut down.

Options

CALLER(data-value)

Specifies the text that appears after ‘CALLER' in the summary of dump domain information at the top of the dump. This text can be up to 8 characters long. It is intended to identify the source of the request for the dump, but is not restricted to that purpose.

CALLERLENGTH(data-value)

Specifies, as a fullword binary value, the number of characters in the CALLER text.

DUMPCODE(data-value)

Specifies the 8-character dump code for this dump request, which determines the system dump table entry used in processing it.

The code can be either CICS-defined or user-defined. Most CICS codes are a CICS message identifier with the initial ‘DFH' removed, but there are a few additional ones. CICS Messages and Codes Vol 1 lists all CICS messages and also the additional codes (under “System dump codes”).

User-defined codes can be any character string that does not contain leading or imbedded blanks.

CICS provides system dump table entries for some CICS-defined codes and builds them as needed for others. The installation can provide entries for user-defined codes, or CICS builds temporary entries, as previously explained.

DUMPID(data-area)

Returns a 6- to 9-character dump identifier generated for this particular dump. The format of the identifier is xxxx/yyyy, where xxxx represents the dump run number, yyyy is the dump count, and the slash (/) symbol is a separator character. The dump identifier is generated as follows:

Dump run number

A number in the range 1 - 9999. (Leading zeros are not used for this number, which is why the dump ID can vary from 6 to 9 characters.) The dump run number begins at 1 when you first start CICS with a newly-initialized local catalog, and is incremented by 1 each time you restart CICS. The dump run number is saved in the local catalog when you perform a normal shutdown, but is reset if you start CICS with a START=INITIAL or START=COLD system initialization parameter.

Dump count

A number in the range 0001 through 9999. (Leading zeros are required in the dump ID.) This is the number assigned to the dump in this run of CICS, starting at 0001 for the first dump, and incremented by 1 with each dump taken.

TITLE(data-area)

Is the text that is printed as a title in the summary of dump domain information at the top of the dump. It can be up to 80 characters long.

TITLELENGTH(data-value)

Specifies, as a fullword binary value, the number of characters in the TITLE text.

Conditions

INVREQ

RESP2 values:

6

TITLELENGTH is greater than 80 bytes.

7

CALLERLENGTH is greater than 8 bytes.

13

The DUMPCODE contains leading or imbedded blanks.

IOERR

RESP2 values:

9

CICS is not authorized by MVS to take dumps.

10

An error occurred during system dumping.

12

MVS cannot process the dump because there is no dump data set or because it is full.

13

An error occurred in the CICS routine that issues MVS SDUMP requests.

NOSPACE

RESP2 values:

4

The dump is incomplete due to lack of dump data set space.

NOSTG

RESP2 values:

5

CICS cannot complete the dump because of insufficient storage.

NOTAUTH

RESP2 values:

100

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

SUPPRESSED

RESP2 values:

1

The dump was not taken because the number of dumps with this dump code exceeds the maximum for the code.

2

The dump was not taken because the system dump table entry for this code indicates no system dump.

3

The dump was not taken because it was suppressed by a user exit program.

8

The dump was not taken because system dumps are suppressed globally.

SYSBUSY

RESP2 values:

11

The MVS dump routine is busy. Retry the command.