# MX\_CALLSTACK

> [HTML Version](mx_callstack.htm)

_Added November 2016_

**xcall MIAMEX, MX\_CALLSTACK, maxdepth, csarray(1), mainprog\}**

MX\_CALLSTACK (MIAMEX 189) returns information about the call stack. The motivation here is to allow application routines to identify the context in which they were called. For example, the file hook subroutine, or an error trapping routine, might want to identify not just the location where the file operation or error occurred, but if that location was within a callable routine, the routine(s) that called it. 

**Parameters**

_maxdepth_  ([Num](num.htm.md))  \[in/out\]

should be set to the number of elements in the _csarray()_, i.e. the maximum number of stack levels—working backwards from the current stack frame context—to retrieve. On return, it will be set to the number of levels in the current stack. If greater than the number you originally specified, it indicates that not all of the levels were returned.

_csarray(1)  _(array of ST\_CALLSTACK)  \[out\]

the first element of an array of structures defined in ASHINC:[CALLSTACK.DEF](https://bitbucket.org/microsabio/soslib/src/master/907016/callstack.def) as follows:

defstruct ST\_CALLSTACK

    map2 calltype,b,2    \! type of call (see CSTF\_xxx)

    map2 src'lno,b,2     \! line # at or prior to call

    map2 src'loc,b,4     \! location counter at call

    map2 dst'loc,b,4     \! target location (for call, fn, proc)

    map2 dst'name,s,52   \! name of sbx or AMOS command line

endstruct



Typically _csarray()_ would be defined via:

dimx callstack(MAX\_CALLSTACK), ST\_CALLSTACK

MAX\_CALLSTACK should be set to the maximum number of levels you want to retrieve.

_mainprog _ ([String](string.htm.md))  \[out\] 

returns the main program at the top of the call stack.

**Example**

\++include ashinc:ashell.def

\++include ashinc:callstack.bsi



define MAX\_CALLSTACK = 10



map1 misc

    map2 program\$,s,10

    map2 stackdepth,i,2



dimx callstack(MAX\_CALLSTACK), ST\_CALLSTACK



stackdepth = MAX\_CALLSTACK   \! max # levels we can handle

xcall MIAMEX, MX\_CALLSTACK, stackdepth, callstack(1), program\$



for i = 1 to stackdepth min MAX\_CALLSTACK

    ? Fn'Call'Stack'Descr\$(callstack(i))

next i



The Fn'Call'Stack'Descr\$() function referenced above is in the [SOSLIB module SOSFUNC:callstack.bsi](https://bitbucket.org/microsabio/soslib/src/master/907010/callstack.bsi). It creates a one line description of a call (gosub, procedure, function, subroutine, amos statement, etc.) from one location/context to another. An example showing a context six levels deep looks like this:

from loc 3B7 call proc() @3DF

from loc 38C fn'() @393

from loc 32B call proc() @331

from loc 4F1 xcall callstack1

from loc 47C fn'() @483

from loc 323 call proc() @41A



**Notes**

•	In the above example, the program had no line numbers, so they weren't listed in the output. 

•	To match up the location counter values to source code lines, see the [LSX file](lsxfilescompil.htm.md) created by the compiler /L switch.

•	The entry in the array (shown at the top) describes the level that called the code that executed the MX\_CALLSTACK function. So in the above case, the current code is within a procedure that starts at location 3DF (hex) and was called from location 3B7. Location 3B7 is within a function that starts at location 393, which in turn was called from location 38C, etc.

**History**

2016 November, A-Shell 6.3.1538:  Function added to A-Shell.