CEE3DMP—Generate dump

CEE3DMP generates a dump of Language Environment and the member language libraries. Sections of the dump are selectively included, depending on options specified with the options parameter. When an error occurs that would cause a CEEDUMP to be taken, and this is a POSIX application, Language Environment writes this dump to the current directory. Output from CEE3DMP is written to one of the following (in top-down order):

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 pathname (made up of the cwd pathname 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

(See the Fname suboption of CEE3DMP in Fname for more information about the dump output filename.)

If 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.

CEE3DMP establishes a condition handler that captures all conditions that occur during dump processing. It terminates the section of the dump in progress when a condition occurs and inserts the following line into the dump (nnnnnnnn is the instruction address at the time of the exception). After this line is inserted in the report, dump processing continues for other member languages until CEE3DMP is complete.

Exception occurred during dump processing at nnnnnnnn

If an abend occurs, or if any other condition occurs or is raised, the condition manager attempts to handle it. If the condition remains unhandled, and it is of sufficient severity, the condition manager might, based on if the TERMTHDACT TRACE or DUMP suboption is specified, invoke dump services and then terminate the program. You do not have to call CEE3DMP to use the dump services. Any routine can use them. To support this case, dump services are invoked as follows:

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.

Reprinting of section title and control block name at the top of each page is suppressed. Only the main title CEE3DMP: ... is reprinted.


Syntax

>>-CEE3DMP--(--title--,--options--,--fc--)---------------------><

title (input)

An 80-byte fixed-length character string containing a title printed at the top of each page of the dump.

options

A 255-byte fixed-length character string enclosed in single quotes containing options describing the type, format, and destination of dump information. 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 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.

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.

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.

NOTRACEback

Does not include a traceback.

FILEs

Includes attributes of all open files and the buffer contents 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.

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 shown below for each HLL, except for PL/I, which does not support the VARIABLE option.

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 specified by the STACKFRAME option. See below for a description of 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 (see below). 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.

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.

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).

Restriction: 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 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 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.

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.

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 can result from this service:

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 created by using the fork() function or is invoked by one of the exec 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 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;