CallStackCaller (System function): Difference between revisions
Jump to navigation
Jump to search
m (→Syntax Terms) |
(Automatically generated page update) |
||
| (16 intermediate revisions by 3 users not shown) | |||
| Line 4: | Line 4: | ||
==Syntax== | ==Syntax== | ||
{{Template:System:CallStackCaller syntax}} | {{Template:System:CallStackCaller syntax}} | ||
===Syntax | ===Syntax terms=== | ||
<table class="syntaxTable"> | <table class="syntaxTable"> | ||
<tr><th>%string</th><td>A string to receive the information about the current routine's caller.</td></tr> | <tr><th>%string</th><td>A string to receive the information about the current routine's caller.</td></tr> | ||
<tr><th>%(System)</th><td>The class name in parentheses denotes a shared method.</td></tr> | <tr><th><var class="nobr">%(System)</var></th><td>The class name in parentheses denotes a [[Notation conventions for methods#Shared methods|shared]] method.</td></tr> | ||
<tr><th>number</th><td>A negative number that indicates the number of call levels to go back. | <tr><th>number</th><td>A negative number that indicates the number of call levels to go back. | ||
<ul><li>A <code>-1</code> value requests information about the current routine's immediate caller. | <ul><li>A <code>-1</code> value requests information about the current routine's immediate caller. | ||
| Line 16: | Line 16: | ||
<ul> | <ul> | ||
<li><var>CallStackCaller</var> 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 <var class="term">string</var> 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. | <li><var>CallStackCaller</var> 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 <var class="term">string</var> 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. | ||
<p><b | <p><b>Note:</b> The call stack information returned by the <var>CallStackCaller</var> method refers to the (names of and line numbers in) procedures that contain the calls to the current method or subroutine, <b><i>not</i></b> to (names of and line numbers in) the current subroutine or method.</p> | ||
<li>Requesting a call level greater than the call stack depth is a request canceling error. | <li>Requesting a call level greater than the call stack depth is a request canceling error. | ||
<p>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.</p> | <p>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 <var>Begin/End</var> block) code results in request cancellation.</p> | ||
<li>A non-negative call level passed to <var>CallStackCaller</var> always results in request cancellation. | <li>A non-negative call level passed to <var>CallStackCaller</var> always results in request cancellation. | ||
<li>For method or subroutine calls that were entered at command level (not inside a procedure), <var>CallStackCaller</var> will return a single asterisk character (< | |||
<li>For <var>CallStackCaller</var> to determine the location of a method or subroutine call, source line information must be collected at compile time. Either you must set the <var>[[SIRFACT_parameter|SIRFACT]]</var> system parameter's X'01' bit, or the request must be compiled with the <var> | <li>For method or subroutine calls that were entered at command level (not inside a procedure), <var>CallStackCaller</var> will return a single asterisk character (<tt>*</tt>). If <var>CallStackCaller</var> cannot determine the location of the call, the <var class="term">string</var> associated with a call will be null (zero-length). | ||
<li>For <var>CallStackCaller</var> to determine the location of a method or subroutine call, source line information must be collected at compile time. Either you must set the <var>[[SIRFACT_parameter|SIRFACT]]</var> system parameter's X'01' bit, or the request must be compiled with the <var class="product">Model 204</var> <var>DEBUGUL</var> user parameter set to a non-zero value. | |||
<p>To use the <var>SIRFACT</var> system parameter, your site must be authorized for <var class="product">[[SirFact]]</var>. Using the <var>DEBUGUL</var> user parameter increases the <var>QTBL</var> and (to a lesser degree) <var>VTBL</var> requirements for a compiled request.</p> | <p>To use the <var>SIRFACT</var> system parameter, your site must be authorized for <var class="product">[[SirFact]]</var>. Using the <var>DEBUGUL</var> user parameter increases the <var>QTBL</var> and (to a lesser degree) <var>VTBL</var> requirements for a compiled request.</p> | ||
<li><var>CallStackCaller</var> 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 <b><i>extremely</i></b> poor technique, and it cannot be discouraged strongly enough. | <li><var>CallStackCaller</var> 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 <b><i>extremely</i></b> poor technique, and it cannot be discouraged strongly enough. | ||
<li><var>CallStackCaller</var> is available in <var class="product">[[Sirius Mods| | |||
<li><var>CallStackCaller</var> is available in <var class="product">[[Sirius Mods|Sirius Mods]]</var> Version 7.2 and later. | |||
</ul> | </ul> | ||
Latest revision as of 00:19, 16 February 2014
Current caller information (System class)
The CallStackCaller 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.
Syntax
%string = %(System):CallStackCaller( number)
Syntax terms
| %string | A string to receive the information about the current routine's caller. |
|---|---|
| %(System) | The class name in parentheses denotes a shared method. |
| number | A negative number that indicates the number of call levels to go back.
|
Usage Notes
- CallStackCaller 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 canceling 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.
- 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 Model 204 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.
- CallStackCaller 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.
- CallStackCaller is available in Sirius Mods Version 7.2 and later.
See also
- The current call stack depth can be determined with the CallStackDepth function.
- CallStack can be used to return the same information as returned by CallStackCaller, but for every call level in the call stack.