CALL %DUMP command

Calls a dump service to obtain a formatted dump.

Read syntax diagramSkip visual syntax diagramCALL%DUMP(options_string,title);
title
Specifies the identification printed at the top of each page of the dump. It must be a fixed-length character string. It must conform to the syntax rules for a character string constant enclosed in quotation marks (") or apostrophes (') for the current programming language. The string length cannot exceed 80 bytes.
options_string
A fixed-length character string that specifies the type, format, and destination of dump information. The string must conform to the syntax rules for a character string constant enclosed in quotation marks (") or apostrophes (') for the current programming language. The string length cannot exceed 247 bytes.

Options are declared as a string of keywords separated by blanks or commas. Some options have suboptions that follow the option keyword and are contained in parentheses. The options can be specified in any order, but the last option declaration is honored if there is a conflict between it and any preceding options.

The options_string can include the following:

THREAD(ALL|CURRENT)
Dumps the current thread or all threads associated with the current enclave. The default is to dump only the current thread. Only one thread is supported.For enclaves that consist of a single thread, THREAD(ALL) and THREAD(CURRENT) are equivalent.

THREAD can be abbreviated as THR.

CURRENT can be abbreviated as CUR.

CICS®: This option is not supported when you are running under CICS without Language Environment®, where z/OS® Debugger issues an EXEC CICS DUMP TRANSACTION.

TRACEBACK
Requests a traceback of active procedures, blocks, condition handlers, and library modules on the call chain. The traceback shows transfers of control from either calls or exceptions. The traceback extends backward to the main program of the current thread.

TRACEBACK can be abbreviated as TRACE.

NOTRACEBACK
Suppresses traceback.

NOTRACEBACK can be abbreviated as NOTRACE.

FILES
Requests a complete set of attributes of all files that are open and the contents of the buffers used by the files.

FILES can be abbreviated as FILE.

NOFILES
Suppresses file attributes of files that are open.

NOFILES can be abbreviated as NOFILE.

VARIABLES
Requests a symbolic dump of all variables, arguments, and registers.

Variables include arrays and structures. Register values are those saved in the stack frame at the time of call. There is no way to print a subset of this information.

Variables and arguments are printed only if the symbol tables are available. A symbol table is generated if a program is compiled using the compile options shown below for each language:

Language Compiler option
C TEST(SYM)
C++ TEST
COBOL TEST or TEST(h,SYM)
PL/I TEST(,SYM)

The variables, arguments, and registers are dumped starting with z/OS Debugger. The dump proceeds up the chain for the number of routines specified by the STACKFRAME option.

VARIABLES can be abbreviated as VAR.

NOVARIABLES
Suppresses dump of variables, arguments, and registers.

NOVARIABLES can be abbreviated as NOVAR.

BLOCKS
Produces a separate hexadecimal dump of control blocks.

Global control blocks and control blocks associated with routines on the call chain are printed. Control blocks are printed for z/OS Debugger. The dump proceeds up the call chain for the number of routines specified by the STACKFRAME option.

If FILES is specified, this is used to produce a separate hexadecimal dump of control blocks used in the file analysis.

BLOCKS can be abbreviated as BLOCK.

CICS: This option is not supported when you are running under CICS without Language Environment, where z/OS Debugger issues an EXEC CICS DUMP TRANSACTION.

NOBLOCKS
Suppresses the hexadecimal dump of control blocks.

NOBLOCKS can be abbreviated as NOBLOCK.

STORAGE
Dumps the storage used by the program.

The storage is displayed in hexadecimal and character format. Global storage and storage associated with each routine on the call chain is printed. Storage is dumped for z/OS Debugger. The dump proceeds up the call chain for the number of routines specified by the STACKFRAME option. Storage for all file buffers is also dumped if the FILES option is specified. When the Dynamic Debug facility is activated, some of the original application instructions are not displayed because they are replaced by '0A91'x instructions.

STORAGE can be abbreviated as STOR.

NOSTORAGE
Suppresses storage dumps.

NOSTORAGE can be abbreviated as NOSTOR.

STACKFRAME(n|ALL)
Specifies the number of stack frames dumped from the call chain.

If STACKFRAME(ALL) is specified, all stack frames are dumped. No stack frame storage is dumped if STACKFRAME(0) is specified.

The particular information dumped for each stack frame depends on the VARIABLE, BLOCK, and STORAGE option declarations specified. The first stack frame dumped is the one associated with z/OS Debugger, followed by its caller, and proceeding backward up the call chain.

STACKFRAME can be abbreviated to SF.

PAGESIZE(n)
Specifies the number of lines on each page of the dump.

This value must be greater than 9. A value of zero (0) indicates that there should be no page breaks in the dump.

PAGESIZE can be abbreviated to PAGE.

FNAME(s)
Specifies the ddname of the file where the dump report is written.

The default ddname CEEDUMP is used if this option is not specified.

CONDITION
Specifies that for each condition active on the call chain, the following information is dumped from the Condition Information Block (CIB):
  • The address of the CIB
  • The message associated with the current condition token
  • The message associated with the original condition token, if different from the current one
  • The location of the error
  • The machine state at the time the condition manager was started
  • The ABEND code and REASON code, if the condition occurred because of an ABEND.

The particular information that is dumped depends on the condition that caused the condition manager to be started. The machine state is included only if a hardware condition or ABEND occurred. The ABEND and REASON codes are included only if an ABEND occurred.

CONDITION can be abbreviated as COND.

NOCONDITION
Suppresses dump condition information for active conditions on the call chain.

NOCONDITION can be abbreviated as NOCOND.

ENTRY
Includes in the dump a description of the z/OS Debugger routine that called the dump service and the contents of the registers at the point of the call. For the currently supported programming languages, ENTRY is extraneous and will be ignored.

CICS: This option is not supported when you are running under CICS without Language Environment, where z/OS Debugger issues an EXEC CICS DUMP TRANSACTION.

NOENTRY
Suppresses the description of the z/OS Debugger routine that called the dump service and the contents of the registers at the point of the call.

CICS: This option is not supported when you are running under CICS without Language Environment, where z/OS Debugger issues an EXEC CICS DUMP TRANSACTION.

The defaults for the preceding options are:
  • CONDITION
  • FILES
  • FNAME(CEEDUMP)
  • NOBLOCKS
  • NOENTRY
  • NOSTORAGE
  • PAGESIZE(60)
  • STACKFRAME(ALL)
  • THREAD(CURRENT)
  • TRACEBACK
  • VARIABLES
Usage notes
  • If incorrect options are used, a default dump is written.
  • The service used to format the dump is determined by the following conditions:
    Language Environment is active
    Language Environment dump service: z/OS Debugger does not analyze any of the CALL %DUMP options, but just passes them to the Language Environment dump service. Some of these options might not be appropriate, because the call is being made from z/OS Debugger rather than from your program.
    Language Environment not active and you are running under CICS
    The command: EXEC CICS DUMP TRANSACTION DUMPCODE('$DT$') COMPLETE
    Language Environment not active and you are not running under CICS
    The MVS SNAP dump service
  • When you use CALL %DUMP, one of the following DD names must be allocated for you to receive a formatted dump:
    • CEEDUMP (default)
    • SYSPRINT.
    Control might not be returned to z/OS Debugger after the dump is produced, depending on the option string specified.

    CICS: You do not need this allocation when you are running without Language Environment under CICS. Under those conditions, EXEC CICS DUMP TRANSACTION is issued, and a transaction dump with a code of $DT$ is written to the CICS dump data set.

  • COBOL does not do anything if the FILES option is specified; the BLOCKS option gives the file information instead.
  • Using a small n (like 1 or 2) with the STACKFRAME option will not produce useful results because only the z/OS Debugger stack frames appear in your dump. Larger values of n or ALL should be used to ensure that application stack frames are shown.
  • When you use the CALL %DUMP command and the Language Environment run time is not active, the MVS SNAP macro or the EXEC CICS DUMP command is used to generate the dump. When you are not running under CICS, the following restrictions apply:
    • The specified or default ddname must be allocated to a data set with these attributes: RECFM=VBA, LRECL=125, and BLKSIZE=1632
    • The previously described options are mapped into SNAP options as shown in the following table:
      Table 1. %DUMP options mapping to SNAP options
      %DUMP option SNAP option
      THREAD ignored
      TRACEBACK SDATA=(PCDATA),PDATA=(SA,SAH)
      FILES SDATA=(DM,IO)
      VARIABLES SDATA=(CB)
      BLOCKS SDATA=(SQA,LSAQ,SWA)
      STORAGE PDATA=(LPA,JPA,SPLS)
      STACKFRAME ignored
      PAGESIZE ignored
      FNAME ddname for dump
      CONDITION SDATA=(Q,TRT,ERR)
      ENTRY PDATA=(SUBTASKS)
  • The CALL %DUMP command cannot be used while you replay recorded statements by using the PLAYBACK commands.

Examples

  • Request a formatted dump that traces active procedures, blocks, condition handlers, and library modules. Identify the dump as "Dump after read". 
    CALL %DUMP ("TRACEBACK", "Dump after read");
  • Call the dump service to obtain a formatted dump including traceback information, file attributes, and buffers. 
    CALL %DUMP ("TRACEBACK FILES");

Refer to the following topics for more information related to the material discussed in this topic.

  • Related references
  • PLAYBACK commands
  • z/OS Language Environment Programming Guide
  • z/OS Language Environment Debugging Guide