CEETBCK — traceback utility (replaces CEETRCB)

The CEETBCK CWI assists in tracing the call chain backwards. It identifies the language, program unit, entry point, current location, caller's DSA, and other information from the address of a DSA or save area for a program unit. This is essential for creating meaningful traceback messages. The CWI will handle both upward- and downward-growing stacks.

Note: There are several reasons for executing CEETBCK instead of just updating CEETRCB:

For XPLINK, a routine's registers on entry are saved in the routine's own stack frame instead of its caller's stack frame.
For XPLINK, the return address stored in a DSA is the caller's return address and not the return address to the stack frame owner.
Additional parameters which indicate the stack frame format for both the input and the output (caller's) DSA are maintained.
The function of the call_instruction_address parameters has changed and a new parameter callers_call_instruction has been added.

Syntax

void CEETBCK (dsaptr, dsa_format, caaptr, member_id, program_unit_name, program_unit_name_length, program_unit_address, call_instruction_address, entry_name, entry_name_length, entry_address, callers_call_instruction_address, callers_dsaptr, callers_dsa_format, statement_id, statement_id_length, cibptr, main_program, fc)

POINTER   *dsaptr;
INT4      *dsa_format;
POINTER   *caaptr;
INT4      *member_id;
CHARn     *program_unit_name;
INT4      *program_unit_name_length;
INT4      *program_unit_address;
INT4      *call_instruction_address;
CHARn     *entry_name;
INT4      *entry_name_length;
INT4      *entry_address;
INT4      *callers_call_instruction_address;
POINTER   *callers_dsaptr;
INT4      *callers_dsa_format;
CHARn     *statement_id;
INT4      *statement_id_length;
POINTER   *cibptr;
INT4      *main_program;
FEED_BACK *fc;

CEETBCK

Call this CWI interface as follows:

L     R15,CEECAALEOV-CEECAA(,R12)   Address of CAA in R12
L     R15,304(,R15)
BALR  R14,R15

dsaptr (input)

A fullword pointer containing the address of the DSA for the current routine in the traceback. This can also be the address of a standard 18 fullword save area if Language Environment conventions were not used for the routine.

DSA_format (input/output)

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 or without Language Environment fields, including the next available byte).
1: The format of the DSA is XPLINK style.
-1: The format of the DSA is unknown. When multiple calls are made to CEETBCK to scan the call chain, the callers_dsa_format returned from the previous call can be used here.

caaptr (input)

A fullword pointer containing the address of the CAA associated with the DSA or save area pointed to by dsaptr.

member_id (output)

A fullword binary integer containing the member identifier for the routine associated with the DSA. If the member ID cannot be determined, this parameter is set to negative one.

program_unit_name (output)

A fixed-length character string of arbitrary length containing the name of the program unit containing the routine associated with the DSA. If the program unit name cannot be determined, this parameter is set to all blanks. If the program unit name cannot fit within the supplied string, it is truncated. (Truncation of DBCS preserves even byte count and SI/SO pairing.)

program_unit_name_length (input/output)

A fullword binary integer containing the length of the program unit name string on entry, and the actual length of the program unit name placed in the string on exit. If the program unit name cannot be determined, this parameter is set to zero. The maximum length a string can be is 256 bytes. Lengths less than zero are treated as zero. Lengths greater than 256 are treated as 256.

program_unit_address (output)

A fullword binary integer containing the address of the start of the program unit for the routine associated with the DSA. If the program unit address cannot be determined, this parameter is set to zero.

call_instruction_address (input/output)

A fullword binary integer that contains the address of the instruction that caused transfer out of the routine. This is either the address of a BASR, BALR or BASSM instruction if transfer was made by subroutine call, or the address of the interrupted statement if transfer was caused by an exception. When multiple calls are made to CEETBCK to scan the call chain, the callers_call_instruction returned from the previous call can be used here. If the address is not known, this parameter should be set to zero. When this parameter is zero on input and the address can be determined, it will be returned.

entry_name (output)

A fixed-length character string of arbitrary length to contain the name of the entry point into the routine associated with the DSA. If the entry point name cannot be determined, this parameter is set to all blanks. If the entry point name cannot fit within the supplied string, it is truncated. (Truncation of DBCS preserves even byte count and SI/SO pairing.)

entry_name_length (input/output)

A fullword binary integer containing the length of the entry point name string on entry, and the actual length of the entry point name placed in the string on exit. If the entry point name cannot be determined, this parameter is set to zero. The maximum length a string can be is 256 bytes. Lengths less than zero are treated as zero. Lengths greater than 256 are treated as 256.

entry_address (output)

A fullword binary integer that contains the address of the entry point into the routine associated with the DSA. If the entry point address cannot be determined, this parameter is set to zero.

callers_call_instruction_address (output)

A fullword binary integer that contains the address of the instruction that caused transfer out of the caller. This is either the address of a BASR, BALR or BASSM instruction if transfer was made by subroutine call, or the address of the interrupted statement if transfer was caused by an exception. If the address cannot be determined, this parameter is set to zero.

callers_dsaptr (output)

A fullword pointer containing the address of the DSA or save area of the caller. If the address of the caller's DSA cannot be determined or is not valid (points to inaccessible storage), then this parameter is set to zero.

callers_DSA_format (output)

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 or without Language Environment fields, including the next available byte.)
1: The format of the DSA is XPLINK style.

statement_id (output)

A fixed-length character string of arbitrary length that contains the identifier of the statement containing the instruction which caused transfer out of the routine. If the statement cannot be determined, this parameter is set to all blanks. If the statement ID cannot fit within the supplied string, it is truncated. (Truncation of DBCS preserves even byte count and SI/SO pairing.)

statement_id_length (input/output)

A fullword binary integer containing the length of the statement ID string on entry, and the actual length of the statement ID placed in the string on exit. If the statement ID cannot be determined, this parameter is set to zero. The maximum length a string can be is 256 bytes. Lengths less than zero are treated as zero. Lengths greater than 256 are treated as 256.

cibptr (output)

A fullword pointer containing the address of the CEECIB associated with the DSA if an exception occurred. If no exception occurred, this parameter is set to zero. Note that if an exception caused transfer out of the routine, the state of the registers after the last instruction ran in the routine is saved in the CIB, rather than in the DSA.

main_program (output)

A fullword binary integer set to one of the following:

0: The routine associated with the DSA is not the main program.
1: The routine associated with the DSA is the main program.

fc (output)

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

Condition
CEE000	Severity	0
	Msg_No	N/A
	Message	The service completed successfully.
CEE310	Severity	3
	Msg_No	3104
	Message	Information could not be successfully extracted for this DSA. It is likely that the dsaptr parameter does not point to an actual DSA or save area.

Note: CEETBCK uses member event handler utility exits (Event Code 6).