CallStackCaller (System function): Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (1 revision)
(Automatically generated page update)
 
(18 intermediate revisions by 4 users not shown)
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><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.
<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===
<ul>
  %callString = %(system):CallStackCaller(%depth)
<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.
====Syntax Terms====
<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>
<dl>
 
<dt><i><b>%callString</b></i>
<li>Requesting a call level greater than the call stack depth is a request canceling error.
<dd>A string to receive the information about the current routine's caller.
<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>
<dt>%(system)
 
<dd>The class name in parentheses denotes a shared method.
<li>A non-negative call level passed to <var>CallStackCaller</var> always results in request cancellation.
<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>
<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).  
===Usage Notes===
 
<ul>
<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.
<li>The CallStackCaller method returns the name of the
<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>
procedure and the line within the procedure that made the calls of the current
 
method or subroutine.
<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.
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.
<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
<li><var>CallStackCaller</var> is available in <var class="product">[[Sirius Mods|Sirius Mods]]</var> Version 7.2 and later.
[[CallStackDepth (System function)|CallStackDepth]] function.
</ul>
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}}

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

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