Request a transaction dump.

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 (FCT,
PCT, PPT, SIT, or TCT), 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 CICS Problem
Determination Guide.
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.
- 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 destination
control table entry 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 definition.
- PPT
- dumps
the processing program table.
- 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 destination
control table entry 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 destination
control table entry 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, PCT, PPT, SIT, and the TCT.
- 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 destination
control table entry 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 destination
control table entry 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
- 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.
- 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.
- NOSPACE
- RESP2
values:
- 4
- The transaction dump is incomplete due to lack of space.
Default action: terminate the task abnormally.
- NOSTG
- RESP2
values:
- 5
- CICS has run out of working storage.
Default action: terminate the task abnormally.
- NOTOPEN
- RESP2
values:
- 6
- The current CICS dump data set is not open.
Default action: terminate the task abnormally.
- 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.
- 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);