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