CallStackCaller (System function)

<section begin=dpl_desc/>Get Caller Info<section end=dpl_desc/>

CallStackCaller is a member of the System class.

This shared function returns a string containing information about the caller of the current method or subroutine. The information can extend back to a specific number of call levels.

The CallStackCaller method is available in Sirius Mods 7.2 and later.

Syntax

  %callString = %(system):CallStackCaller(%depth)

Syntax Terms

%callString

A string to receive the information about the current routine's caller.

%(system)

The class name in parentheses denotes a shared method.

%depth

A negative number that indicates the number of call levels to go back. A -1 value requests information about the current routine's immediate caller. A -2 value requests information about the caller's caller; and so on.

Usage Notes

• The CallStackCaller method returns the name of the procedure and the line within the procedure that made the calls of the current method or subroutine. Generally, the returned string has the name of the file containing the calling procedure at positions one through eight, followed by a blank, followed by the name of the calling procedure, followed by a blank, followed by the line number within the calling procedure. Note: The call stack information returned by the CallStackCaller method refers to the (names of and line numbers in) procedures that contain the calls to the current method or subroutine, not to (names of and line numbers in) the current subroutine or method.
• Requesting a call level greater than the call stack depth is a request cancelling error. For example, requesting call level -1 when not inside a method or subroutine results in request cancellation. Similarly, requesting call level -2 in a method invoked directly from level-0 (inside the Begin/End block) code results in request cancellation. A non-negative call level passed to CallStackCaller always results in request cancellation. The current call stack depth can be determined with the CallStackDepth function. The CallStack function can be used to return the same information as returned by CallStackCaller, but for every call level in the call stack.
• For method or subroutine calls that were entered at command level (not inside a procedure), CallStackCaller will return a single asterisk character (*). If CallStackCaller cannot determine the location of the call, the string associated with a call will be null (zero-length).
• For CallStackCaller to determine the location of a method or subroutine call, source line information must be collected at compile time. Either you must set the SIRFACT system parameter's X'01' bit, or the request must be compiled with the DEBUGUL user parameter set to a non-zero value. To use the SIRFACT system parameter, your site must be authorized for SirFact. Using the DEBUGUL user parameter increases the QTBL and (to a lesser degree) VTBL requirements for a compiled request.
• The CallStackCaller method is intended to be used for problem diagnosis and, perhaps, for logging and auditing. Using it to affect method or subroutine behavior by causing a method or subroutine to behave differently depending on its caller is extremely poor technique, and it cannot be discouraged strongly enough.