DUMP TRANSACTION

Request a transaction dump.

Read syntax diagramSkip visual syntax diagram
DUMP TRANSACTION

>>-DUMP TRANSACTION--DUMPCODE(name)----------------------------->

>--+------------------------------------------+--+----------+--->
   '-FROM(data-area)--+-LENGTH(data-value)--+-'  '-COMPLETE-'   
                      '-FLENGTH(data-value)-'                   

>--+-----+------------------------------------------------------>
   '-TRT-'   

>--+-----------------------------------------------------------------------+-->
   '-SEGMENTLIST(data-area)--LENGTHLIST(data-area)--NUMSEGMENTS(data-area)-'   

>--+------+--+---------+--+---------+--+----------+------------->
   '-TASK-'  '-STORAGE-'  '-PROGRAM-'  '-TERMINAL-'   

>--+--------+--+-----+--+-----+--+-----+--+-----+--+-----+------>
   '-TABLES-'  '-FCT-'  '-PCT-'  '-PPT-'  '-SIT-'  '-TCT-'   

>--+-------------------+---------------------------------------><
   '-DUMPID(data-area)-'   

Conditions: INVREQ, IOERR, NOSPACE, NOSTG, NOTOPEN, OPENERR, SUPPRESSED

 

Description

DUMP TRANSACTION dumps all, a series, or any single main storage area related to a task, any or all of the CICS® tables, or all of these together.

Note that if you issue a DUMP TRANSACTION for a DUMPCODE that is defined in the transaction dump table with SYSDUMP, you also get a system dump.

If there is no entry in the system dump table for the specified DUMPCODE, a temporary entry is made. This entry is lost on the next CICS start. The system dump table is described in the The dump code options you can specify .

Options

COMPLETE
dumps all main storage areas related to a task, all the CICS tables, and the DL/I control blocks.
DUMPCODE(name)
specifies a name (1–4 characters) that identifies the dump. If the name contains any leading or imbedded blanks, the dump is produced but INVREQ is raised. No entry is added to the system dump table.

If you omit all the options except DUMPCODE, you get the same dump as if you specified TASK, but without the DL/I control blocks.

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 to 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.
FCT
dumps the file control table, which contains FILE resource definitions.
FLENGTH(data-value)
specifies the length (fullword binary value) of the storage area (specified in the FROM option) that is to be dumped. The maximum length that you can specify is 16 777 215 bytes.

FLENGTH and LENGTH are mutually exclusive.

FROM(data-area)
dumps the specified data area, which must be a valid area; that is, storage allocated by the operating system within the CICS region. In addition, the following areas are dumped:
  • Task control area (TCA) and, if applicable, the transaction work area (TWA).
  • Common system area (CSA), including the user's portion of the CSA (CWA).
  • If TRAN is specified for the TRTRANTY SIT parameter, only the trace entries associated with the current task are formatted. If TRTRANTY=ALL is specified, the entire internal trace table is formatted. This applies only when the CICS trace facility is active.
  • Either the terminal control table terminal entry (TCTTE) or the transient data queue definition associated with the requesting task.

Whenever the TCTTE is dumped, the terminal control table user area (if any) and the message control blocks (if any) associated with the TCTTE are dumped. The latter are used by basic mapping support.

LENGTH(data-value)
specifies the length (halfword binary) of the data area specified in the FROM option. For a description of a safe upper limit, see LENGTH options in CICS commands.

LENGTH and FLENGTH are mutually exclusive.

LENGTHLIST(data-area)
specifies a list of 32-bit binary values showing the lengths of the storage areas to be dumped. This corresponds to the list of segments specified in the SEGMENTLIST option. You must use both the SEGMENTLIST and NUMSEGMENTS options when you use the LENGTHLIST option.
NUMSEGMENTS(data-area)
specifies the number (fullword binary) of areas to be dumped. You must use both the SEGMENTLIST and LENGTHLIST options when you use the NUMSEGMENTS option.
PCT
formats a summary of each installed transaction resource definition.
PPT
formats a summary of each installed program resource definition.
PROGRAM
specifies that program storage areas associated with this task are to be dumped, as follows:
  • Task control area (TCA) and, if applicable, the transaction work area (TWA)
  • Common system area (CSA), including the user's portion of the CSA (CWA)
  • Trace entries relating to the task written to the internal trace table (only when the CICS trace facility is active)
  • All program storage areas containing user-written application programs active on behalf of the requesting task
  • Register save areas (RSAs) indicated by the RSA chain off the TCA
  • Either the terminal control table terminal entry (TCTTE) or the transient data queue definition associated with the requesting task.

Whenever the TCTTE is dumped, the terminal control table user area (if any) and the message control blocks (if any) associated with the TCTTE are dumped.

SEGMENTLIST(data-area)
specifies a list of addresses, which are the starting points of the segments to be dumped. Each segment is a task-related storage area. You must use both the NUMSEGMENTS and LENGTHLIST options when you use the SEGMENTLIST option.
SIT
dumps the system initialization table.
STORAGE
specifies that storage areas associated with this task are to be dumped, as follows:
  • Task control area (TCA) and, if applicable, the transaction work area (TWA)
  • Common system area (CSA), including the user's portion of the CSA (CWA)
  • Trace entries relating to the task written to the internal trace table (only when the CICS trace facility is active)
  • All transaction storage areas
  • Either the terminal control table terminal entry (TCTTE) or the transient data queue definition associated with the requesting task

Whenever the TCTTE is dumped, the terminal control table user area (if any) and the message control blocks (if any) associated with the TCTTE are dumped.

TABLES
dumps the FCT (file control table, containing FILE resource definitions), PCT (program control table, containing TRANSACTION resource definitions), PPT (processing program table, containing PROGRAM resource definitions), SIT (system initialization table, containing CICS system initialization parameters), and the TCT (terminal control table, containing TERMINAL resource definitions).
TASK
specifies that storage areas associated with this task are to be dumped, as follows:
  • A summary of the transaction environment associated with this task
  • Common system area (CSA), including the user's portion of the CSA (CWA)
  • Trace entries relating to the task written to the internal trace table (only when the CICS trace facility is active)
  • All program storage areas containing user-written application programs active on behalf of the requesting task
  • All transaction storage areas
  • Either the terminal control table terminal entry (TCTTE) or the transient data queue definition associated with the requesting task
  • Register save areas (RSAs) indicated by the RSA chain off the TCA
  • All terminal input/output areas (TIOAs) chained off the terminal control table terminal entry (TCTTE) for the terminal associated with the requesting task
  • DL/I control blocks

Whenever the TCTTE is dumped, the terminal control table user area (if any) and the message control blocks (if any) associated with the TCTTE are dumped.

TCT
dumps the terminal control table.
TERMINAL
specifies that storage areas associated with the terminal are to be dumped, as follows:
  • Task control area (TCA) and, if applicable, the transaction work area (TWA)
  • Common system area (CSA), including the user's portion of the CSA (CWA)
  • Trace entries relating to the task written to the internal trace table (only when the CICS trace facility is active)
  • All terminal input/output areas (TIOAs) chained off the terminal control table terminal entry (TCTTE) for the terminal associated with the requesting task as long as the request is not a write, or storage freezing is on for the task or the terminal
  • Either the terminal control table terminal entry (TCTTE) or the transient data queue definition associated with the requesting task.

Whenever the TCTTE is dumped, the terminal control table user area (if any) and the message control blocks (if any) associated with the TCTTE are dumped. The latter are used by basic mapping support.

TRT
dumps the trace entries relating to the task written to the internal trace table.

Conditions

16 INVREQ
RESP2 values:
13
An incorrect DUMPCODE is specified. DUMPCODE contains unprintable characters, or leading or imbedded blanks.

The dump is produced but no entry is added to the system dump table.

Default action: terminate the task abnormally.

17 IOERR
RESP2 values:
9
The SDUMP process is not authorized.
10
An error occurred during system dumping.
13
The CICS routine issuing the SDUMP is unable to establish a recovery routine (FESTAE).

Default action: terminate the task abnormally.

18 NOSPACE
RESP2 values:
4
The transaction dump is incomplete due to lack of space.

Default action: terminate the task abnormally.

42 NOSTG
RESP2 values:
5
CICS has run out of working storage.

Default action: terminate the task abnormally.

19 NOTOPEN
RESP2 values:
6
The current CICS dump data set is not open.

Default action: terminate the task abnormally.

87 OPENERR
RESP2 values:
7
There is an error on opening, closing, or writing to the current CICS dump routine.

Default action: terminate the task abnormally.

72 SUPPRESSED
RESP2 values:
1
The transaction dump is suppressed by MAXIMUM in table.
2
The transaction dump is suppressed by NOTRANDUMP in table.
3
The transaction dump is suppressed by a user exit program.

Default action: terminate the task abnormally.

Examples

The following example shows how to request a dump of all the task-related storage areas, the terminal control table, and a specified data area: 
EXEC CICS DUMP TRANSACTION
     DUMPCODE('name')
     FROM(data-area)
     LENGTH(data-value)
This second example (written in PL/I) shows you a case in which five task-related storage areas are dumped: 
DCL storage_address(5)   POINTER,
    storage_length(5)    FIXED BIN(31),
    nsegs                FIXED BIN(31);
storage_address(1) = ADDR(areal);
storage_length(1)  = CSTG(areal);
⋮
nsegs = 5;
EXEC CICS DUMP TRANSACTION
     DUMPCODE('name')
     SEGMENTLIST(storage_address)
     LENGTHLIST(storage_length)
     NUMSEGMENTS(nsegs);

Parent topic: CICS API commands

dfhp4_dumptransaction.html | Timestamp icon Last updated: Thursday, 27 June 2019