CALLSTK statement

Purpose

Capture a complete representation of the stack frames in the call stack.

Syntax

CALLSTK diskfilename$

Remarks

PowerBASIC creates a stack frame for each call to a Sub or Function, and records each nested call in a call stack.  The stack frame holds the parameters being passed to the routine, and providing space for local variable storage, etc.  Since Subs and Functions can call other Subs and Functions to an almost limitless depth, there may be a substantial number of stack frames present at any given moment.

The CALLSTK statement can help provide answers to the age-old "how did I get here?" question.  When combined with other debugging statements such as CALLSTK$, CALLSTKCOUNT, and TRACE, the programmer has a set of tools that can significantly reduce the amount of effort required to debug an application.

Executing a CALLSTK statement captures a representation of all of the stack frames that exist above the one that includes the CALLSTK statement.  When the CALLSTK statement is executed, a standard sequential file (of the specified file name in diskfilename$) is created.  The resulting disk file contains a list of every call to a Sub/Function, and their associated parameter values, which are currently defined on the call stack.

diskfilename$ must be a legal file spec, may be a Long File Name (LFN), and may include a path.  If the file cannot be created for any reason, the operation will be ignored and no run-time error will be generated.  If present, CALLSTK overwrites the existing file.

If PBMAIN calls the SUB aaa(x&) which then calls the SUB bbb(y&), the CALLSTK from within bbb(y&) might look like this:

PBMAIN()
aaa(77)
bbb(-1)

Later, if bbb(y&) exited, then aaa(x&) called ccc(z&), the updated CALLSTK from within ccc(z&) might then appear as:

PBMAIN()
aaa(77)
ccc(33)

Numeric parameters are displayed in decimal, while pointer and array parameters display a decimal representation of the offset of the target value.

Restrictions

CALLSTK can be invaluable during debugging, but it generates substantial additional code that should be avoided in a final release version of an application.  If the source code contains #TOOLS OFF, all CALLSTK statements which remain in the program are ignored.

The CALLSTK statement is "thread-aware", displaying only stack frame details from the thread in which it was executed.

See also

#TOOLS, CALLSTK$, CALLSTKCOUNT, FUNCNAME$, PROFILE, TRACE

Example

FUNCTION PBMAIN

  CALL Sb1(100)

END FUNCTION

SUB Sb1(x AS LONG)

  CALL Sb2(x + 1)

END SUB

SUB Sb2(y AS LONG)

  CALLSTK "Stack frame test.txt"

END SUB

Result

PBMAIN()
SB1(100)
SB2(101)