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