CallStackCaller (System function): Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (1 revision)
m (guess subtitle, syntax and footer template names, match syntax terms to template, lots of tags and edits.)
Line 1: Line 1:
<span style="font-size:120%; color:black"><b><section begin=dpl_desc/>Get Caller Info<section end=dpl_desc/></b></span>
{{Template:System:CallStackCaller subtitle}}
[[Category:System methods|CallStackCaller function]]
The <var>CallStackCaller</var> 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.
[[Category:System/Subsystem methods]]
<!--DPL?? Category:System methods|CallStackCaller function: Get Caller Info-->
<p>
CallStackCaller is a member of the [[System class]].
</p>


This shared function returns a string containing information about the caller
==Syntax==
of the current method or subroutine.
{{Template:System:CallStackCaller syntax}}
The information can extend back to a specific number of call levels.
===Syntax Terms===
<table class="syntaxTable">
<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>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.
<li>A <code>-2</code> value requests information about the caller's caller; and so on.</ul></td></tr>
</table>


The CallStackCaller method is available in ''Sirius Mods'' 7.2 and later.
==Usage Notes==
===Syntax===
  %callString = %(system):CallStackCaller(%depth)
====Syntax Terms====
<dl>
<dt><i><b>%callString</b></i>
<dd>A string to receive the information about the current routine's caller.
<dt>%(system)
<dd>The class name in parentheses denotes a shared method.
<dt><i><b>%depth</b></i>
<dd>A negative number that indicates the number of call levels to go back.
A <tt>-1</tt> value requests information about the current routine's immediate
caller.
A <tt>-2</tt> value requests information about the caller's caller; and so on.
 
</dl>
===Usage Notes===
<ul>
<ul>
<li>The CallStackCaller method returns the name of the
<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.
procedure and the line within the procedure that made the calls of the current
<p><b><i>Note:</i></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>
method or subroutine.
<li>Requesting a call level greater than the call stack depth is a request canceling error.
Generally, the returned string has the name of the file containing the calling
<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>
procedure at positions one through eight, followed by a blank, followed by the
<li>A non-negative call level passed to <var>CallStackCaller</var> always results in request cancellation.
name of the calling procedure, followed by a blank, followed by the line number
<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 (<code>*</code>). 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).  
within the calling procedure.
<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>[[DEBUGUL]]</var> user parameter set to a non-zero value.
'''Note:'''
<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>
The call stack information returned by the CallStackCaller method refers to the
<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.
(names of and line numbers in)
<li><var>CallStackCaller</var> is available in <var class="product">[[Sirius Mods|"Sirius Mods"]]</var> Version 7.2 and later.
procedures that contain the calls to the current method or subroutine,
</ul>
''not'' to (names of and line numbers in) the current
subroutine or method.
<li>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 (System function)|CallStackDepth]] function.
The [[CallStack (System function)|CallStack]] function can be used to return the same
information as returned by CallStackCaller, but for every call level in the call
stack.
<li>For method or subroutine calls that were entered at command level (not inside a
procedure), CallStackCaller will return a single asterisk character (<tt>*</tt>).
If CallStackCaller cannot determine the location of the call, the string
associated with a call will be null (zero-length).
<li>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]].
==See also==
Using the DEBUGUL user parameter
<ul><li>The current call stack depth can be determined with the <var>[[CallStackDepth (System function)|CallStackDepth]]</var> function.
increases the QTBL and (to a lesser degree) VTBL requirements for a compiled
<li><var>[[CallStack (System function)|CallStack]]</var> can be used to return the same information as returned by <var>CallStackCaller</var>, but for every call level in the call stack.  
request.
<li>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.
</ul>
</ul>
{{Template:System:CallStackCaller footer}}

Revision as of 09:46, 19 March 2011

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

%stringA string to receive the information about the current routine's caller.
%(system)The class name in parentheses denotes a shared method.
numberA 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

  • 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 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.
Retrieved from "https://m204wiki.rocketsoftware.com/index.php?title=CallStackCaller_(System_function)&oldid=13856"