CallStack (System function): Difference between revisions

From m204wiki
Jump to navigation Jump to search
mNo edit summary
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 Call Stack<section end=dpl_desc/></b></span>
{{Template:System:CallStack subtitle}}
[[Category:System methods|CallStack function]]
The <var>CallStack</var> shared function returns a <var>[[Stringlist_class|Stringlist]]</var> containing information about the current call stack: information about the caller of the current method or subroutine, the caller of that caller, and so on.
[[Category:System/Subsystem methods]]
 
<!--DPL?? Category:System methods|CallStack function: Get Call Stack-->
==Syntax==
<p>
{{Template:System:CallStack syntax}}
CallStack is a member of the [[System class]].
===Syntax Terms===
</p>
<table class="syntaxTable">
<tr><th>%sl</th><td>A <var>[[Stringlist_class|Stringlist]]</var> object to be set to reference the object that contains information about the current call stack. The first item in the <var>Stringlist</var> refers to the immediate caller of the current method or subroutine; a second item refers to the caller of that caller, if any; and so on.</td></tr>
This shared function returns a Stringlist containing information about the current
<tr><th>%(system)</th><td>The class name in parentheses denotes a shared method.</td></tr>
call stack: information about the caller of the current method or subroutine,
</table>
the caller of that caller, and so on.
 
==Usage Notes==
The CallStack method is available in ''Sirius Mods'' 7.2 and later.
===Syntax===
  %callList = %(system):CallStack
====Syntax Terms====
<dl>
<dt><i><b>%callList</b></i>
<dd>A Stringlist object to be set to reference the object that contains information
about the current call stack.
The first item in the Stringlist refers to the immediate caller of
the current method or subroutine; a second item refers to the caller of that caller,
if any; and so on.
<dt>%(system)
<dd>The class name in parentheses denotes a shared method.
</dl>
===Usage Notes===
<ul>
<ul>
<li>The CallStack method returns the name of the
<li><var>CallStack</var> returns the name of the procedure and the line within the procedure that made the calls of the current method or subroutine. Generally, each returned <var>Stringlist</var> item 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 <var>CallStack</var> 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.</p>
method or subroutine.
<li>For method or subroutine calls that were entered at command level (not inside a procedure), the <var class="term">%sl</var> item will contain a single asterisk character (<code>*</code>).
Generally, each returned Stringlist item has the name of the file containing
If <var>CallStack</var> cannot determine the location of the call, the <var class="term">%sl</var> item associated with a call will be null (zero-length). If not issued from within a method or subroutine, <var>CallStack</var> will return an empty (zero-item) Stringlist.
the calling procedure at positions one through eight, followed by a blank,
<li>For <var>CallStack</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.
followed by the name of the calling procedure, followed by a blank, followed
<p>To use the <var>SIRFACT</var> system parameter, your site must be authorized for <var>[[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>
by the line number within the calling procedure.
<li>The <var>CallStack</var> 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 <b><i>extremely</i></b> poor technique, and it cannot be discouraged strongly enough.
'''Note:'''
<li><var>CallStack</var> method is available in <var class="product">[[Sirius Mods|"Sirius Mods"]]</var> Version 7.2 and later.
The call stack information returned by the CallStack 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>For method or subroutine calls that were entered at command level (not inside a
procedure), the ''%callList'' item will contain a single asterisk
character (<tt>*</tt>).
If CallStack cannot determine the location of the call, the ''%callList''
item associated with a call will be null (zero-length).
If not issued from within a method or subroutine, CallStack will
return an empty (zero-item) Stringlist.
<li>For CallStack 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.
<li>The CallStack 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>
===Example===
 
==Examples==
In the MYTAX.UL procedure,
<ol><li>In the MYTAX.UL procedure, the computeTax1 subroutine is called by the computeTax2 subroutine at line 146. If you issue the following statements from within computeTax1:
the computeTax1 subroutine is called by the computeTax2 subroutine
<p class="code">%callList is object stringList
at line 146.
%callList = %(system):callStack
If you issue the following statements from within computeTax1:
%callList:[[Print_(Stringlist_function)|print]]
<p class="code"><nowiki>%callList is object Stringlist
</p>
%callList = %(system):CallStack
%callList:Print
</nowiki></p>
The result is something like the following:
The result is something like the following:
<p class="code"><nowiki>MYPROC  MYTAX.UL 193
<p class="output">MYPROC  MYTAX.UL 193
MYPROC  MYTAX.UL 146
MYPROC  MYTAX.UL 146
</nowiki></p>
</p></ol>
 
==See Also==
{{Template:System:CallStack footer}}

Revision as of 02:17, 19 March 2011

Current call stack description (System class)

The CallStack shared function returns a Stringlist containing information about the current call stack: information about the caller of the current method or subroutine, the caller of that caller, and so on.

Syntax

%sl = %(System):CallStack

Syntax Terms

%slA Stringlist object to be set to reference the object that contains information about the current call stack. The first item in the Stringlist refers to the immediate caller of the current method or subroutine; a second item refers to the caller of that caller, if any; and so on.
%(system)The class name in parentheses denotes a shared method.

Usage Notes

  • CallStack returns the name of the procedure and the line within the procedure that made the calls of the current method or subroutine. Generally, each returned Stringlist item 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 CallStack 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.

  • For method or subroutine calls that were entered at command level (not inside a procedure), the %sl item will contain a single asterisk character (*). If CallStack cannot determine the location of the call, the %sl item associated with a call will be null (zero-length). If not issued from within a method or subroutine, CallStack will return an empty (zero-item) Stringlist.
  • For CallStack 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 CallStack 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.
  • CallStack method is available in "Sirius Mods" Version 7.2 and later.

Examples

  1. In the MYTAX.UL procedure, the computeTax1 subroutine is called by the computeTax2 subroutine at line 146. If you issue the following statements from within computeTax1:

    %callList is object stringList %callList = %(system):callStack %callList:print

    The result is something like the following:

    MYPROC MYTAX.UL 193 MYPROC MYTAX.UL 146

See Also

Retrieved from "https://m204wiki.rocketsoftware.com/index.php?title=CallStack_(System_function)&oldid=13834"