CEE3DMP—Generate the dump
- The directory found in _CEE_DMPTARG, if found.
- The current working directory, if this is not the root (/), and if the directory is writable, and if the dump path name (made up of the cwd path name plus the dump file name) does not exceed 1024 characters.
- The directory found in environment variable TMPDIR (if the temporary directory is not /tmp.
- /tmp.
If it is longer than 60 characters, the dump title is truncated to 60 characters in order to match the record size of the dump file. Only nested enclaves within a single process are supported.
Exception occurred during dump processing at nnnnnnnn
- The title is
Condition processing resulted in the unhandled condition
to indicate why the dump was produced. - The dump options are 'TRACE COND THR(ALL) BLOCKS STOR NOENTRY' for dump output and 'TRACE COND THR(ALL) NOBLOCK NOSTOR NOENTRY' for trace output.
CEE3DMP: ...
is reprinted.
- title (input)
- An 80-byte fixed-length character string containing a title printed at the beginning of each page of the dump.
- options
- Options are declared as a string of keywords that are 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 following options are recognized by Language Environment:
- ENCLave(ALL | CURrent | n)
- Dumps the current enclave, a fixed number of enclaves, or all enclaves associated with the
current process; n is an integer ranging from 1 to 2**31-1, inclusive,
that indicates the maximum number of enclaves that should be dumped. ENCLAVE(CURRENT) and ENCLAVE(1)
are equivalent.
ALL is the default.
- THRead(ALL|CURrent)
- Dumps the current thread (the thread that invoked this service) or all threads associated with
the current enclave. When you specify THREAD(ALL) and more than one thread is running, the library
quiesces all threads before writing the dump. Therefore, the state of the library changes from the
time the dump is requested to the time the dump is written.
The default is CURRENT.
- TRACEBACK
- Includes a traceback of all routines on the call chain. The traceback shows transfers of control
from either calls or exceptions. The traceback extends backwards to the main program of the current
thread. PL/I transfers of control into BEGIN-END blocks or ON-units are considered calls.
TRACEBACK is the default.
- NOTRACEback
- Does not include a traceback.
- FILEs
- Includes attributes of all open files and the buffer contents that are used by the files. The
particular attributes displayed are defined by the member languages. File buffers are dumped when
FILE and STORAGE are specified. File control blocks are dumped when FILE and BLOCKS are
specified.
FILES is the default.
- NOFILEs
- Does not include file attributes of open files.
- VARiables
- Includes 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 when a program is compiled
with the options in the following table for each HLL, except for PL/I, which does not support the VARIABLE option.
Table 1. Symbol table Language Compile-time option C TEST(SYM) C++ TEST COBOL TEST or TEST(h,SYM) The variables, arguments, and registers are dumped, beginning with the routine that called CEE3DMP. The dump proceeds up the chain for the number of routines that are specified by the STACKFRAME option.
- NOVARiables
- Does not include a dump of variables, arguments, and registers.
- BLOCKs
- Dumps the control blocks used in Language Environment and member language libraries. Global control blocks, as well as control blocks associated with routines on the call chain, are printed. Control blocks are printed for the routine that called CEE3DMP. The dump proceeds up the call chain for the number of routines specified by the STACKFRAME option. Control blocks for files are also dumped if the FILES option was specified. See the FILES option above for more information. If the TRACE runtime option is set to ON, the trace table is dumped when BLOCKS is specified. If the heap storage diagnostics report is requested through the HEAPCHK runtime option, the report is displayed when BLOCKS is specified.
- NOBLOCKs
- Suppresses the dump of control blocks.
NOBLOCKS is the default.
- STORage
- Dumps the storage used by the program. The storage is displayed in hexadecimal and character format. Global storage, as well as storage associated with each routine on the call chain, is printed. Storage is dumped for the routine that called CEE3DMP, which 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 was specified (see above).
- NOSTORage
- Suppresses storage dumps. NOSTORAGE is the default.
- REGSTor
- Controls the amount of storage (
reg_stor_amount
) that is dumped around registers.reg_stor_amount
indicates storage in bytes to be dumped around each register and must be in the range of 0 to 256. The number is rounded up to the nearest multiple of 32. The default is REGSTOR(96).You must specify REGSTor(0) as a CEE3DMP option if a dump storage around registers is not required.
- 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 for CEE3DMP. The first stack frame dumped is the one associated with the routine that called CEE3DMP, followed by its caller, and proceeding backwards up the call chain.
- PAGEsize(n)
- Specifies the number of lines on each page of the dump. This value must be greater than 9. A value of 0 indicates that there should be no page breaks in the dump. The default setting is PAGESIZE(60). Refer to the CEEDUMP runtime option for an optional method of setting the number of lines on each page of the dump.
- FNAME(ddname)
- Specifies the ddname of the file to which the dump report is written. The ddname supplied in this option must be a valid ddname for the system on which the application is running. CEE3DMP does not check the ddname for validity, nor does CEE3DMP translate or modify the ddname. Supplying an invalid ddname can result in unpredictable behavior. The default ddname CEEDUMP is used if this option is not specified.
- CONDition
- Specifies that for each active condition on the call chain, the following information is dumped
from the CIB:
- The address of the CIB.
- The message that is associated with the current condition token.
- The message that is 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 invoked, if an abend or hardware condition occurred.
- The abend code and reason code, if the condition occurred as a result of an abend.
- Language-specific error information.
The information supplied by Language Environment-conforming languages differs. PL/I supplies DATAFIELD, ONCHAR, ONCOUNT, ONFILE, ONKEY, and ONSOURCE built-in function (BIF) values, which are shown in the context of the condition raised.
CONDITION is the default.
This option does not apply to asynchronous signals.
- NOCONDition
- Does not dump condition information for active conditions on the call chain.
- ENTRY
- Includes in the dump a description of the routine that called CEE3DMP and the contents of the
registers on entry to CEE3DMP.
ENTRY is the default.
- NOENTRY
- Does not include in the dump a description of the routine that called CEE3DMP and the contents of the registers on entry to CEE3DMP.
- GENOpts
- Includes in the dump a runtime options report like that generated by the use of the RPTOPTS runtime option.
- NOGENOpts
- Does not include in the dump a runtime options report like that generated by the use of the RPTOPTS runtime option.
- fc (output)
- A 12-byte feedback code, optional in some languages, that indicates the result of this service.
If you choose to omit this parameter, refer to Invoking callable services for the appropriate
syntax to indicate that the feedback code was
omitted.
If specified as an argument, feedback information, in the form of a condition token, is returned to
the calling routine. If not specified, and the requested operation was not successfully completed,
the condition is signaled to the condition manager.
The following feedback codes are possible:
Code Severity Message number Message text CEE000 0 — The service completed successfully. CEE317 1 3111 CEEDUMP was defined as a dummy data set. No Language Environment dump processing was performed. CEE30U 2 3102 Invalid CEE3DMP options or suboptions were found and ignored. CEE30V 3 3103 An error occurred in writing messages to the dump file.
Usage notes
- Language Environment is sensitive to the
national language when it writes dump output.
- When the national language is upper case U.S. English or Japanese, the environment variable _CEE_UPPERCASE_DATA can be used to determine if variable data in the dump output is in uppercase.
- When this environment variable is set to YES, variable data (entry point names, program unit names, variable names, Trace Entry in EBCDIC data, hexadecimal/EBCDIC displays of storage) will be in uppercase.
- When this environment variable is not set or set to a value other than YES, variable data will not be in uppercase. Variable data is never in uppercase when the national language is mixed-case U.S. English.
- CICS® consideration—Only ENCLAVE(CURRENT) and ENCLAVE(1) are supported on CICS.
- MVS™ consideration—On MVS, all values for the ENCLAVE option are supported.
- z/OS UNIX consideration—CEE3DMP applies to the
enclave.
When you call CEE3DMP in a multithread environment, the current thread or all threads might be dumped. Enclave- and process-related storage (along with storage related to threads other than the current thread) might have changed in value from the time the dump request was issued.
If the CEEDUMP DD has a PATH= parameter, the dump is directed to the specified file system.
If your application is running under z/OS UNIX System Services and is either running in an address space that is created by using the
fork()
function or is invoked by one of theexec
family of functions, the dump is written to the file system. Language Environment writes the dump to a file in your current working directory, unless that directory is the root directory, in which case the dump is written to a file in the directory/tmp.
.The name of this file changes with each dump and uses the following format:/path/Fname.Date.Time.Pid
- path
- The current working directory
- Fname
- The name specified in the FNAME parameter on the call to CEE3DMP (default is CEEDUMP)
- Date
- The date the dump is taken, appearing in the format
YYYYMMDD
(such as 19940325 for March 25, 1994) - Time
- The time the dump is taken, appearing in the format
HHMMSS
(such as 175501 for 05:55:01 PM) - Pid
- The process ID the application is running in when the dump is taken
- When nested CEEPIPI main-DP environments are present, the traceback section
includes all nested environments. The first environment contains all the usual sections as
determined by the CEE3DMP options. For the chained parent main-DP environments, the dump output
omits all sections other than the traceback.
The ENCLAVE option controls how many enclaves appear in the output for each CEEPIPI main-DP environment. The STACKFRAME option controls how many stack frames are dumped for each CEEPIPI main-DP environment.
- When multiple CEEPIPI main-DP environments are present, and the chained parent Main-DP environments contain Language Environment member languages that are not present in the current active Main-DP environment (the one that caused the dump), the information dumped out might be incomplete.
- If the assembler CEEPIPI driver program does not follow standard z/OS® linkage conventions, the dumped traceback information might be incomplete or incorrect.
For more information
- See TERMTHDACT for more information about the TERMTHDACT runtime option.
- For more information about generating dumps, see Generating a Language Environment dump with CEE3DMP in z/OS Language Environment Debugging Guide.
Examples
- Following is an example of CEE3DMP called by C/C++.
/*Module/File Name: EDC3DMP */ #include <stdio.h> #include <leawi.h> #include <stdlib.h> #include <string.h> #include <ceeedcct.h> #define OPT_STR "THREAD(CURRENT) TRACEBACK FILES" int main(void) { _CHAR80 title = "This is the title of the dump report"; _CHAR255 options; FILE *f; _FEEDBACK fc; memset(options,' ',sizeof(options)); memcpy(options,OPT_STR,sizeof(OPT_STR)-1); f = fopen("my.file","wb"); fprintf(f,"my file record 1\n"); CEE3DMP(title,options,&fc); if ( _FBCHECK ( fc , CEE000 ) != 0 ) { printf("CEE3DMP failed with msgno %d\n", fc.tok_msgno); exit(2999); } }
- Following is an example of CEE3DMP called by COBOL.
CBL LIB,QUOTE *Module/File Name: IGZT3DMP ************************************************* ** ** ** CBL3DMP - Call CEE3DMP to generate a dump ** ** ** ** In this example, a call to CEE3DMP is made ** ** to request a dump of the runtime ** ** environment. Several options are specified ** ** to customize the dump. ** ************************************************* IDENTIFICATION DIVISION. PROGRAM-ID. CBL3DMP. DATA DIVISION. WORKING-STORAGE SECTION. 01 DMPTITL PIC X(80). 01 OPTIONS PIC X(255). 01 FC. 02 Condition-Token-Value. COPY CEEIGZCT. 03 Case-1-Condition-ID. 04 Severity PIC S9(4) BINARY. 04 Msg-No PIC S9(4) BINARY. 03 Case-2-Condition-ID REDEFINES Case-1-Condition-ID. 04 Class-Code PIC S9(4) BINARY. 04 Cause-Code PIC S9(4) BINARY. 03 Case-Sev-Ctl PIC X. 03 Facility-ID PIC XXX. 02 I-S-Info PIC S9(9) BINARY. PROCEDURE DIVISION. ************************************************* ** Specify title to appear on each page of the ** dump report. ** Specify options that will request that a ** traceback be provided, but no variables, ** stack frames, condition information, or ** registers be dumped. ************************************************* PARA-CBL3DMP. MOVE "This is the dump report title." TO DMPTITL. MOVE "TRACE NOVAR SF(0) NOCOND NOENTRY" TO OPTIONS. CALL "CEE3DMP" USING DMPTITL, OPTIONS, FC. IF NOT CEE000 of FC THEN DISPLAY "CEE3DMP failed with msg " Msg-No of FC UPON CONSOLE STOP RUN END-IF. GOBACK.
- Following is an example of CEE3DMP called by PL/I.
*PROCESS MACRO; /* Module/File Name: IBM3DMP */ /****************************************************/ /** **/ /** Function: CEE3DMP - generate dump **/ /** **/ /** In this example, a call to CEE3DMP is made to **/ /** request a dump of the runtime environment. **/ /** Several options are specified, to customize **/ /** the dump. **/ /****************************************************/ PLI3DMP: PROC OPTIONS(MAIN); %INCLUDE CEEIBMAW; %INCLUDE CEEIBMCT; DCL DMPTITL CHAR(80); DCL OPTIONS CHARACTER ( 255 ); DCL 01 FC, /* Feedback token */ 03 MsgSev REAL FIXED BINARY(15,0), 03 MsgNo REAL FIXED BINARY(15,0), 03 Flags, 05 Case BIT(2), 05 Severity BIT(3), 05 Control BIT(3), 03 FacID CHAR(3), /* Facility ID */ 03 ISI /* Instance-Specific Information */ REAL FIXED BINARY(31,0); /* Specify a string to be printed at the top of */ /* each page of dump */ DMPTITL = 'This is the title for the dump report.'; /* Request that a traceback be provided, but */ /* no variables, stack frames, condition */ /* information, or registers be dumped */ OPTIONS = 'TRACE NOVAR SF(0) NOCOND NOENTRY'; /* Call CEE3DMP with options to customize dump */ CALL CEE3DMP ( DMPTITL, OPTIONS, FC ); IF FBCHECK( FC, CEE000) THEN DO; PUT SKIP LIST( 'Successfully produced dump with' || ' title "' || DMPTITL || '"' ); PUT SKIP LIST( ' and options: ' || OPTIONS ); END; ELSE DO; DISPLAY( 'CEE3DMP failed with msg ' || FC.MsgNo ); STOP; END; END PLI3DMP;