1\variable{_bofeof_info}
2\synopsis{Control the generation of function callback code}
3\usage{Int_Type _bofeof_info}
4\description
5 This value of this variable dictates whether or not the \slang
6 interpreter will generate code to call the beginning and end of
7 function callback handlers.  The value of this variable is local to
8 the compilation unit, but is inherited by other units loaded by the
9 current unit.
10
11 If the value of this variable is 1 when a function is defined, then
12 when the function is executed, the callback handlers defined via
13 \ifun{_set_bof_handler} and \ifun{_set_eof_handler} will be called.
14\seealso{_set_bof_handler, _set_eof_handler, _boseos_info}
15\done
16
17\variable{_boseos_info}
18\synopsis{Control the generation of BOS/EOS callback code}
19\usage{Int_Type _boseos_info}
20\description
21 This value of this variable dictates whether or not the \slang
22 interpreter will generate code to call the beginning and end of
23 statement callback handlers.  The value of this variable is local to
24 the compilation unit, but is inherited by other units loaded by the
25 current unit.
26
27 The lower 8 bits of \ivar{_boseos_info} controls the generation of code for
28 callbacks as follows:
29#v+
30   Value      Description
31   -----------------------------------------------------------------
32     0        No code for making callbacks will be produced.
33     1        Callback generation will take place for all non-branching
34              and looping statements.
35     2        Same as for 1 with the addition that code will also be
36              generated for branching statements (if, !if, loop, ...)
37     3        Same as 2, but also including break and continue
38              statements.
39#v-
40 A non-branching statement is one that does not effect chain of
41 execution.  Branching statements include all looping statements,
42 conditional statement, \exmp{break}, \exmp{continue}, and \exmp{return}.
43
44 If bit 0x100 is set, callbacks will be generated for preprocessor
45 statements.
46\example
47 Consider the following:
48#v+
49   _boseos_info = 1;
50   define foo ()
51   {
52      if (some_expression)
53        some_statement;
54   }
55   _boseos_info = 2;
56   define bar ()
57   {
58      if (some_expression)
59        some_statement;
60   }
61#v-
62 The function \exmp{foo} will be compiled with code generated to call the
63 BOS and EOS handlers when \exmp{some_statement} is executed.  The
64 function \exmp{bar} will be compiled with code to call the handlers
65 for both \exmp{some_expression} and \exmp{some_statement}.
66\notes
67 The \sldb debugger and \slsh's \exmp{stkcheck.sl} make use of this
68 facility.
69\seealso{_set_bos_handler, _set_eos_handler, _bofeof_info}
70\done
71
72\function{_clear_error}
73\synopsis{Clear an error condition (deprecated)}
74\usage{_clear_error ()}
75\description
76  This function has been deprecated.  New code should make use of
77  try-catch exception handling.
78
79  This function may be used in error-blocks to clear the error that
80  triggered execution of the error block.  Execution resumes following
81  the statement, in the scope of the error-block, that triggered the
82  error.
83\example
84  Consider the following wrapper around the \ifun{putenv} function:
85#v+
86    define try_putenv (name, value)
87    {
88       variable status;
89       ERROR_BLOCK
90        {
91          _clear_error ();
92          status = -1;
93        }
94       status = 0;
95       putenv (sprintf ("%s=%s", name, value);
96       return status;
97    }
98#v-
99  If \ifun{putenv} fails, it generates an error condition, which the
100  \exmp{try_putenv} function catches and clears.  Thus \exmp{try_putenv}
101  is a function that returns -1 upon failure and 0 upon
102  success.
103\seealso{_trace_function, _slangtrace, _traceback}
104\done
105
106\function{_get_frame_info}
107\synopsis{Get information about a stack frame}
108\usage{Struct_Type _get_frame_info (Integer_Type depth)}
109\description
110  \ifun{_get_frame_info} returns a structure with information about
111  the function call stack from of depth \svar{depth}. The structure
112  contains the following fields:
113#v+
114    file: The file that contains the code of the stack frame.
115    line: The line number the file the stack frame is in.
116    function: the name of the function containing the code of the stack
117      frame; it might be NULL if the code isn't inside a function.
118    locals: Array of String_Type containing the names of variables local
119      to the stack frame; it might be NULL if the stack frame doesn't
120      belong to a function.
121    namespace: The namespace the code of this stack frame is in.
122#v-
123\seealso{_get_frame_variable, _use_frame_namespace}
124\done
125
126\function{_get_frame_variable}
127\synopsis{Get the value of a variable local to a stack frame}
128\usage{Any_Type _get_frame_variable (Integer_Type depth, String_Type name)}
129\description
130  This function returns value of the variable \exmp{name} in the stack
131  frame at depth \exmp{depth}.  This might not only be a local variable but
132  also variables from outer scopes, e.g., a variable private to the
133  namespace.
134
135  If no variable with this name is found an \exc{UndefinedNameError}
136  will be thrown.  An \exc{VariableUninitializedError} will be
137  generated if the variable has no value.
138\seealso{_get_frame_info, _use_frame_namespace}
139\done
140
141\function{_set_bof_handler}
142\synopsis{Set the beginning of function callback handler}
143\usage{_set_bof_handler (Ref_Type func)}
144\description
145 This function is used to set the function to be called prior to the
146 execution of the body \slang function but after its arguments have
147 been evaluated, provided that function was defined
148 with \ivar{_bofeof_info} set appropriately.  The callback function
149 must be defined to take two parameters, the function name and the
150 filename and must return nothing.
151\example
152#v+
153    private define bof_handler (fun, file)
154    {
155      () = fputs ("About to execute function $fun from file $file"$, stdout);
156    }
157    _set_bof_handler (&bof_handler);
158#v-
159\seealso{_set_eof_handler, _boseos_info, _set_bos_handler}
160\done
161
162\function{_set_bos_handler}
163\synopsis{Set the beginning of statement callback handler}
164\usage{_set_bos_handler (Ref_Type func)}
165\description
166 This function is used to set the function to be called prior to the
167 beginning of a statement.  The function will be passed two
168 parameters: the name of the file and the line number of the statement
169 to be executed.  It should return nothing.
170\example
171#v+
172    private define bos_handler (file, line)
173    {
174      () = fputs ("About to execute $file:$line\n"$, stdout);
175    }
176    _set_bos_handler (&bos_handler);
177#v-
178\notes
179 The beginning and end of statement handlers will be called for
180 statements in a file only if that file was compiled with the variable
181 \ivar{_boseos_info} set to a non-zero value.
182\seealso{_set_eos_handler, _boseos_info, _bofeof_info}
183\done
184
185\function{_set_eof_handler}
186\synopsis{Set the beginning of function callback handler}
187\usage{_set_eof_handler (Ref_Type func)}
188\description
189 This function is used to set the function to be called at the end of
190 execution of a \slang function, provided that function was compiled with
191 \ivar{_bofeof_info} set accordingly.
192
193 The callback function will be passed no parameters and it must return
194 nothing.
195\example
196#v+
197   private define eof_handler ()
198   {
199     () = fputs ("Done executing the function\n", stdout);
200   }
201   _set_eof_handler (&eof_handler);
202#v-
203\seealso{_set_bof_handler, _bofeof_info, _boseos_info}
204\done
205
206\function{_set_eos_handler}
207\synopsis{Set the end of statement callback handler}
208\usage{_set_eos_handler (Ref_Type func)}
209\description
210 This function is used to set the function to be called at the end of
211 a statement.  The function will be passed no parameters and it should
212 return nothing.
213\example
214#v+
215   private define eos_handler ()
216   {
217     () = fputs ("Done executing the statement\n", stdout);
218   }
219   _set_eos_handler (&eos_handler);
220#v-
221\notes
222 The beginning and end of statement handlers will be called for
223 statements in a file only if that file was compiled with the variable
224 \ivar{_boseos_info} set to a non-zero value.
225\seealso{_set_bos_handler, _boseos_info, _bofeof_info}
226\done
227
228\variable{_slangtrace}
229\synopsis{Turn function tracing on or off}
230\usage{Integer_Type _slangtrace}
231\description
232  The \ivar{_slangtrace} variable is a debugging aid that when set to a
233  non-zero value enables tracing when function declared by
234  \ifun{_trace_function} is entered.  If the value is greater than
235  zero, both intrinsic and user defined functions will get traced.
236  However, if set to a value less than zero, intrinsic functions will
237  not get traced.
238\seealso{_trace_function, _traceback, _print_stack}
239\done
240
241\variable{_traceback}
242\synopsis{Generate a traceback upon error}
243\usage{Integer_Type _traceback}
244\description
245  \ivar{_traceback} is an intrinsic integer variable whose bitmapped value
246  controls the generation of the call-stack traceback upon error.
247  When set to 0, no traceback will be generated.  Otherwise its value
248  is the bitwise-or of the following integers:
249#v+
250       1        Create a full traceback
251       2        Omit local variable information
252       4        Generate just one line of traceback
253#v-
254  The default value of this variable is 4.
255\notes
256  Running \slsh with the \exmp{-g} option causes this variable to be
257  set to 1.
258\seealso{_boseos_info}
259\done
260
261\function{_trace_function}
262\synopsis{Set the function to trace}
263\usage{_trace_function (String_Type f)}
264\description
265  \ifun{_trace_function} declares that the \slang function with name
266  \exmp{f} is to be traced when it is called.  Calling
267  \ifun{_trace_function} does not in itself turn tracing on.  Tracing
268  is turned on only when the variable \ivar{_slangtrace} is non-zero.
269\seealso{_slangtrace, _traceback}
270\done
271
272\function{_use_frame_namespace}
273\synopsis{Selects the namespace of a stack frame}
274\usage{_use_frame_namespace (Integer_Type depth)}
275\description
276  This function sets the current namespace to the one belonging to the
277  call stack frame at depth \svar{depth}.
278\seealso{_get_frame_info, _get_frame_variable}
279\done
280
281