Event code 7 — dump event handler event

Purpose

CEL Dump Processing makes calls to member event handlers for Event Code 7 (Dump). Many of these calls provide a DSA address as input and expect the member to provide information about the routine that owns the stack frame. This event handler code performs several CEEDUMP related functions based upon the function_code passed as the second parameter. There are five function_codes for which the DSA address is passed as input:

2: Dump arguments of a routine.
3: Dump variables of a routine.
4: Dump control blocks associated with a routine.
5: Dump storage for a routine.
18: Dump condition information for DSA/CIB.

Syntax

Calls to dump event handler are made with parameters shown in the following sample procedure statement

Call CEEEVnnn (7, function_code, additional_parms, fc, entry_ptr, dsa_format, call_addr)

INT4      *function_code;
POINTER   *dsaptr;
POINTER   *cibptr;
POINTER   *caaptr;
POINTER   *edbptr;
POINTER   *pcbptr;
FEEDBACK  *fc;
POINTER   *entry_ptr;
INT4      *dsa_format;
POINTER   *call_addr;

function_code (input)

A fullword binary integer that specifies the dump function to be performed. It must contain one of the following values:

1: Dump an informational message to explain why the dump is being taken. This function_code specifies that the exit of the language library that called CEE3DMP print the error message that resulted from the dump being taken in the first place. The informational messages would normally be a copy of the error messages sent to MSGFILE for the error. These messages could contain an ABEND code, the PSW, and register contents at time of the error. If CEE3DMP was not called by a member language library, member language libraries would normally not print any messages in this exit.
2: Dump the arguments of a routine. If the member language cannot distinguish between arguments and local variables for a routine, it should dump the arguments at the same time it is called by dump services to dump variables.
3: Dump the variables of a routine. This includes all local variables and any shared external variables used by the routine. Member language libraries should dump only those variables used or set by the routine if this can be determined.
4: Dump control blocks associated with a routine. This includes the DSA mapped by the member language and any other control blocks associated with the routine that are useful for debugging. This includes compile information, symbol tables, and statement tables.
5: Dump storage for a routine. This includes automatic stack frame storage and static local variable storage. Static data storage shared between this routine and another routine should also be dumped. Only one copy of a shared storage area should be dumped though.
6: Dump control blocks associated with a thread. The CAA for the thread is dumped by Language Environment.
7: Dump storage associated with a thread. Language Environment dumps all stack storage associated with the thread. Member languages can dump any other stack storage that is associated with the thread using this exit. Any stack storage used by the thread is dumped even though it can not be associated with it. Only data storage should be dumped. Storage containing code should not be dumped if possible.
8: Dump control blocks associated with an enclave. The EDB for the enclave is dumped by Language Environment as well as the member list. Member languages should dump communications areas that are linked off of the member list. These are usually the static library communications regions that are part of the application load module.
9: Dump storage associated with an enclave. Language Environment dumps all heap storage associated with the enclave. Member languages can dump any other storage that is associated with the enclave using this exit. This usually includes storage obtained through direct calls to the operating system storage management. Only data storage should be dumped. Storage containing code should not be dumped if possible.
10: Dump status and attributes of files. Language Environment dumps the status and attributes of files used by message services. Member languages should dump status and attributes of their own files. This includes all currently open files as well as any previously open files in the course of running an application.
11: Dump control blocks associated with files. Control blocks and other language-specific control blocks that keep file status are dumped.
12: Dump storage buffers associated with files. These buffers are allocated by the operating system and typically do not use Language Environment heap services. Buffer storage allocated by Language Environment heap services can be dumped.
13: Dump control blocks associated with the process. The PCB for the process is dumped by Language Environment.
14: Dump storage associated with the process. Only data storage should be dumped. Storage containing code should not be dumped.
15: Dump any additional global information. This information appears at the end of the dump report. A list of loaded library modules is an example of additional global information.
16: Dump the variables of the enclave. This includes all static external variables used by the enclave.
17: End of dump call. This indicates that there are no additional calls to the event handler for this instance of dump.
18: Dump condition information associated with the passed DSA/CIB pointer. For example, PL/I displays ONCHAR, ONSOURCE, ONKEY, and ONCOUNT values when applicable.

additional_parms (input)

Parameters specific to a certain function code. Notice that the dump_event_code 7 always precedes the function code. See Figure 1 to view the syntax.

Figure 1. Syntax by function_code

Call CEEEVnnn (7, 1, fc)
Call CEEEVnnn (7, 2, dsaptr, cibptr, caaptr, fc, entry_ptr, dsa_format, call_addr)
Call CEEEVnnn (7, 3, dsaptr, cibptr, caaptr, fc, entry_ptr, dsa_format, call_addr)
Call CEEEVnnn (7, 4, dsaptr, cibptr, caaptr, fc, entry_ptr, dsa_format, call_addr)
Call CEEEVnnn (7, 5, dsaptr, cibptr, caaptr, fc, entry_ptr, dsa_format, call_addr)
Call CEEEVnnn (7, 6, caaptr, fc)
Call CEEEVnnn (7, 7, caaptr, fc)
Call CEEEVnnn (7, 8, edbptr, fc)
Call CEEEVnnn (7, 9, edbptr, fc)
Call CEEEVnnn (7, 10, edbptr, fc, caaptr)
Call CEEEVnnn (7, 11, edbptr, fc, caaptr)
Call CEEEVnnn (7, 12, edbptr, fc, caaptr)
Call CEEEVnnn (7, 13, pcbptr, fc)
Call CEEEVnnn (7, 14, pcbptr, fc)
Call CEEEVnnn (7, 15, edbptr, fc)
Call CEEEVnnn (7, 16, edbptr, fc)
Call CEEEVnnn (7, 17, fc)
Call CEEEVnnn (7, 18, dsaptr, cibptr, caaptr, fc, entry_ptr, dsa_format, call_addr)

dsaptr (input): A fullword binary integer containing the address of a DSA.
cibptr (input): A fullword binary integer containing the address of the CIB for the routine. This parameter is zero if the routine does not have a CIB.
caaptr (input): A fullword binary integer containing the address of a CAA.
edbptr (input): A fullword binary integer containing the address of an EDB.
pcbptr (input): A fullword binary integer containing the address of a PCB.

fc (output)

A 12-byte feedback code passed by reference. The following symbolic conditions might result from this exit:

Condition
CEE000	Severity	0
	Msg_No	N/A
	Message	The service completed successfully.
CEE30V	Severity	3
	Msg_No	3103
	Message	An error occurred in writing messages to the dump file.
CEE311	Severity	3
	Msg_No	3105
	Message	Member language dump exit was unsuccessful.

entry_ptr (input)

A fullword pointer containing the address of the entry point for the routine that owns the stack frame.

dsa_format (input)

A fullword binary integer set to one of the following:

0: The format of the DSA is a Standard OS linkage register save area (with/without Language Environment fields including NAB).
1: The format of the DSA is XPLINK style.

call_addr (input)

A fullword pointer containing the address of the instruction that caused transfer out of the routine that owns the stack frame. If the calling instruction cannot be determined, then the value is zero. This is either the address of the BASR, BALR or BASSM instruction if transfer was made by a subroutine call or the address of the interrupted statement if the transfer was caused by an exception.