Dump control XPI functions

There are two XPI dump control functions. These are the DFHDUDUX macro calls SYSTEM_DUMP and TRANSACTION_DUMP.

DFHDUDUX calls cannot be used in any exit program invoked from any global user exit point in the:

The SYSTEM_DUMP call

SYSTEM_DUMP causes a system dump to be taken. If the system dump code that you supply on input is in the system dump code table, the dump may be suppressed. For information about the dump table and how it works, refer to the CICS® Problem Determination Guide and the CICS System Programming Reference manual.

SYSTEM_DUMP

DFHDUDUX [CALL,]
      [CLEAR,]
      [IN,
      FUNCTION(SYSTEM_DUMP),
      SYSTEM_DUMPCODE(name8 | string | "string"),
      [CALLER(block-descriptor),]
      [TITLE(block-descriptor),]]
      [OUT,
      DUMPID(name9 | *),
      RESPONSE(name1 | *),
      REASON(name1 | *)]

Start of changeThis command is threadsafe.End of change

CALLER(block-descriptor)
specifies the source of a system dump request. The information that you supply here appears in the dump header, so you could use it to identify the exit program that initiated the system dump request. For a description of valid block-descriptors, see block-descriptor.
DUMPID(name9 | *)
returns the dump identifier.
name9
The name of a 9-byte field to receive the assigned ID.
SYSTEM_DUMPCODE(name8 | string | "string")
specifies the code corresponding to the error that caused this system dump call. System dump codes are held in the dump table; for information about the dump table and how it works, refer to the CICS Problem Determination Guide and the CICS System Programming Reference manual.
name8
The name of a location containing an 8-byte string.
string
A string of characters without intervening blanks. The macro generates, from the string, a literal constant of length 8 bytes, extending with blanks or truncating as required.
"string"
A string, enclosed in quotation marks and possibly containing blanks. This value is processed in the same way as the "string" above.
TITLE(block-descriptor)
specifies an area containing the text you want to appear in the dump header when the system dump is printed.

RESPONSE and REASON values for SYSTEM_DUMP:

RESPONSE REASON
OK None
EXCEPTION FESTAE_FAILED
INSUFFICIENT_STORAGE
IWMWQWRK_FAILED
NO_DATASET
PARTIAL_SYSTEM_DUMP
SDUMP_BUSY
SDUMP_FAILED
SDUMP_NOT_AUTHORIZED
SUPPRESSED_BY_DUMPOPTION
SUPPRESSED_BY_DUMPTABLE
SUPPRESSED_BY_USEREXIT
DISASTER None
INVALID INVALID_DUMPCODE
INVALID_PROBDESC
INVALID_SVC_CALL
KERNERROR None
PURGED None
Note:
For more detail, refer to the explanation of RESPONSE and REASON in Making an XPI call.

The TRANSACTION_DUMP call

TRANSACTION_DUMP causes a transaction dump to be taken. If the transaction dump code that you supply on input is in the transaction dump code table, the dump may be suppressed and, optionally, a system dump may be taken. For information about the dump table and how it works, refer to the CICS Problem Determination Guide manual.

Important

There is a restriction in using the XPI early during initialization. Do not start exit programs that use the XPI functions TRANSACTION_DUMP, WRITE_JOURNAL_DATA, MONITOR, and INQUIRE_MONITOR_DATA until the second phase of the PLTPI. For further information about the PLTPI, refer to Writing initialization and shutdown programs.

TRANSACTION_DUMP

DFHDUDUX [CALL,]
      [CLEAR,]
      [IN,
      FUNCTION(TRANSACTION_DUMP),
      TRANSACTION_DUMPCODE(name4 | string | 'string')
      [CSA(NO|YES),]
      [PROGRAM(NO|YES),]
      [SEGMENT(block-descriptor),]
      [SEGMENT_LIST(block-descriptor),]
      [TCA(NO|YES),]
      [TERMINAL(NO|YES),]
      [TRANSACTION(NO|YES),]
      [TRT(NO|YES),]]
      [OUT,
      DUMPID(name9 | *),
      RESPONSE(name1 | *),
      REASON(name1 | *)]
Note:
Start of change
This command is NOT threadsafe.
End of change
CSA(NO|YES)
specifies whether the common system area (CSA) is to be included in the transaction dump. The default is NO.
DUMPID(name9 | *)
returns the dump identifier.
name9
The name of a 9-byte field to receive the assigned ID.
PROGRAM(NO|YES)
specifies whether all program storage areas associated with this task are to be included in the transaction dump. The default is NO.
SEGMENT(block-descriptor)
specifies the address and the length of a single block of storage that is to be dumped. See block-descriptor for a description of valid block-descriptors. SEGMENT and SEGMENT_LIST are mutually exclusive.
SEGMENT_LIST(block-descriptor)
specifies the address and length of a set of contiguous word pairs. The first word in each pair specifies the length in bytes of a storage segment to be dumped; the second word contains the address of the storage segment. The end of the list must be marked by a word containing X'FFFFFFFF'. SEGMENT and SEGMENT_LIST are mutually exclusive.
TCA(NO|YES)
specifies whether the task control area (TCA) is to be included in the transaction dump. The default is NO.
TERMINAL(NO|YES)
specifies whether all terminal storage areas associated with the task are to be included in the transaction dump. The default is NO.
TRANSACTION(NO|YES)
specifies whether all transaction storage areas associated with the task are to be included in the transaction dump. The default is NO.
TRANSACTION_DUMPCODE(name4 | string | "string")
specifies the code corresponding to the error that caused this transaction dump call. Transaction dump codes are held in the dump table; for information about the dump table and how it works, refer to the CICS Problem Determination Guide and the CICS System Programming Reference manual.
name4
The name of a location containing a 4-byte string.
string
A string of characters without intervening blanks. The macro generates a literal constant of length 4 bytes from the string, extending with blanks or truncating as required.
"string"
A string, enclosed in quotation marks and possibly containing blanks. This value is processed in the same way as the "string" above.
TRT(NO|YES)
specifies whether the trace table (TRT) is to be included in the transaction dump. The default is NO.

RESPONSE and REASON values for TRANSACTION_DUMP:

RESPONSE REASON
OK None
EXCEPTION FESTAE_FAILED
INSUFFICIENT_STORAGE
IWMWQWRK_FAILED
NOT_OPEN
OPEN_ERROR
PARTIAL_SYSTEM_DUMP
PARTIAL_TRANSACTION_DUMP
SDUMP_BUSY
SDUMP_FAILED
SDUMP_NOT_AUTHORIZED
SUPPRESSED_BY_DUMPOPTION
SUPPRESSED_BY_DUMPTABLE
SUPPRESSED_BY_USEREXIT
DISASTER None
INVALID INVALID_DUMPCODE
INVALID_PROBDESC
INVALID_SVC_CALL
KERNERROR None
PURGED None
Notes:
  1. For more detail, refer to the explanation of RESPONSE and REASON in Making an XPI call.
  2. ‘NOT_OPEN’ means that the CICS dump data set is closed.
  3. ‘OPEN_ERROR’ means that an error occurred while a CICS dump data set was being opened.
  4. ‘PARTIAL’ means that the transaction dump resulting from this request is incomplete.

Related concepts
Overview of the XPI
Global user exit XPI examples, showing the use of storage
Related tasks
Making an XPI call
Writing global user exit programs
Writing a task-related user exit program
Related reference
The XPI functions
[[ Contents Previous Page | Next Page Index ]]