Next Previous Contents

23. Debugging Functions

23.1 _bofeof_info

Synopsis

Control the generation of function callback code

Usage

Int_Type _bofeof_info

Description

This value of this variable dictates whether or not the S-Lang interpreter will generate code to call the beginning and end of function callback handlers. The value of this variable is local to the compilation unit, but is inherited by other units loaded by the current unit.

If the value of this variable is 1 when a function is defined, then when the function is executed, the callback handlers defined via _set_bof_handler and _set_eof_handler will be called.

See Also

_set_bof_handler, _set_eof_handler, _boseos_info

23.2 _boseos_info

Synopsis

Control the generation of BOS/EOS callback code

Usage

Int_Type _boseos_info

Description

This value of this variable dictates whether or not the S-Lang interpreter will generate code to call the beginning and end of statement callback handlers. The value of this variable is local to the compilation unit, but is inherited by other units loaded by the current unit.

The lower 8 bits of _boseos_info controls the generation of code for callbacks as follows:

   Value      Description
   -----------------------------------------------------------------
     0        No code for making callbacks will be produced.
     1        Callback generation will take place for all non-branching
              and looping statements.
     2        Same as for 1 with the addition that code will also be
              generated for branching statements (if, !if, loop, ...)
     3        Same as 2, but also including break and continue
              statements.
A non-branching statement is one that does not effect chain of execution. Branching statements include all looping statements, conditional statement, break, continue, and return.

If bit 0x100 is set, callbacks will be generated for preprocessor statements.

Example

Consider the following:

   _boseos_info = 1;
   define foo ()
   {
      if (some_expression)
        some_statement;
   }
   _boseos_info = 2;
   define bar ()
   {
      if (some_expression)
        some_statement;
   }
The function foo will be compiled with code generated to call the BOS and EOS handlers when some_statement is executed. The function bar will be compiled with code to call the handlers for both some_expression and some_statement.

Notes

The sldb debugger and slsh's stkcheck.sl make use of this facility.

See Also

_set_bos_handler, _set_eos_handler, _bofeof_info

23.3 _clear_error

Synopsis

Clear an error condition (deprecated)

Usage

_clear_error ()

Description

This function has been deprecated. New code should make use of try-catch exception handling.

This function may be used in error-blocks to clear the error that triggered execution of the error block. Execution resumes following the statement, in the scope of the error-block, that triggered the error.

Example

Consider the following wrapper around the putenv function:

    define try_putenv (name, value)
    {
       variable status;
       ERROR_BLOCK
        {
          _clear_error ();
          status = -1;
        }
       status = 0;
       putenv (sprintf ("%s=%s", name, value);
       return status;
    }
If putenv fails, it generates an error condition, which the try_putenv function catches and clears. Thus try_putenv is a function that returns -1 upon failure and 0 upon success.

See Also

_trace_function, _slangtrace, _traceback

23.4 _get_frame_info

Synopsis

Get information about a stack frame

Usage

Struct_Type _get_frame_info (Integer_Type depth)

Description

_get_frame_info returns a structure with information about the function call stack from of depth depth. The structure contains the following fields:

    file: The file that contains the code of the stack frame.
    line: The line number the file the stack frame is in.
    function: the name of the function containing the code of the stack
      frame; it might be NULL if the code isn't inside a function.
    locals: Array of String_Type containing the names of variables local
      to the stack frame; it might be NULL if the stack frame doesn't
      belong to a function.
    namespace: The namespace the code of this stack frame is in.

See Also

_get_frame_variable, _use_frame_namespace

23.5 _get_frame_variable

Synopsis

Get the value of a variable local to a stack frame

Usage

Any_Type _get_frame_variable (Integer_Type depth, String_Type name)

Description

This function returns value of the variable name in the stack frame at depth depth. This might not only be a local variable but also variables from outer scopes, e.g., a variable private to the namespace.

If no variable with this name is found an UndefinedNameError will be thrown. An VariableUninitializedError will be generated if the variable has no value.

See Also

_get_frame_info, _use_frame_namespace

23.6 _set_bof_handler

Synopsis

Set the beginning of function callback handler

Usage

_set_bof_handler (Ref_Type func)

Description

This function is used to set the function to be called prior to the execution of the body S-Lang function but after its arguments have been evaluated, provided that function was defined with _bofeof_info set appropriately. The callback function must be defined to take a single parameter representing the name of the function and must return nothing.

Example

    private define bof_handler (fun)
    {
      () = fputs ("About to execute $fun"$, stdout);
    }
    _set_bos_handler (&bof_handler);

See Also

_set_eof_handler, _boseos_info, _set_bos_handler

23.7 _set_bos_handler

Synopsis

Set the beginning of statement callback handler

Usage

_set_bos_handler (Ref_Type func)

Description

This function is used to set the function to be called prior to the beginning of a statement. The function will be passed two parameters: the name of the file and the line number of the statement to be executed. It should return nothing.

Example

    private define bos_handler (file, line)
    {
      () = fputs ("About to execute $file:$line\n"$, stdout);
    }
    _set_bos_handler (&bos_handler);

Notes

The beginning and end of statement handlers will be called for statements in a file only if that file was compiled with the variable _boseos_info set to a non-zero value.

See Also

_set_eos_handler, _boseos_info, _bofeof_info

23.8 _set_eof_handler

Synopsis

Set the beginning of function callback handler

Usage

_set_eof_handler (Ref_Type func)

Description

This function is used to set the function to be called at the end of execution of a S-Lang function, provided that function was compiled with _bofeof_info set accordingly.

The callback function will be passed no parameters and it must return nothing.

Example

   private define eof_handler ()
   {
     () = fputs ("Done executing the function\n", stdout);
   }
   _set_eof_handler (&eof_handler);

See Also

_set_bof_handler, _bofeof_info, _boseos_info

23.9 _set_eos_handler

Synopsis

Set the end of statement callback handler

Usage

_set_eos_handler (Ref_Type func)

Description

This function is used to set the function to be called at the end of a statement. The function will be passed no parameters and it should return nothing.

Example

   private define eos_handler ()
   {
     () = fputs ("Done executing the statement\n", stdout);
   }
   _set_eos_handler (&eos_handler);

Notes

The beginning and end of statement handlers will be called for statements in a file only if that file was compiled with the variable _boseos_info set to a non-zero value.

See Also

_set_bos_handler, _boseos_info, _bofeof_info

23.10 _slangtrace

Synopsis

Turn function tracing on or off

Usage

Integer_Type _slangtrace

Description

The _slangtrace variable is a debugging aid that when set to a non-zero value enables tracing when function declared by _trace_function is entered. If the value is greater than zero, both intrinsic and user defined functions will get traced. However, if set to a value less than zero, intrinsic functions will not get traced.

See Also

_trace_function, _traceback, _print_stack

23.11 _traceback

Synopsis

Generate a traceback upon error

Usage

Integer_Type _traceback

Description

_traceback is an intrinsic integer variable whose bitmapped value controls the generation of the call-stack traceback upon error. When set to 0, no traceback will be generated. Otherwise its value is the bitwise-or of the following integers:

       1        Create a full traceback
       2        Omit local variable information
       4        Generate just one line of traceback
The default value of this variable is 4.

Notes

Running slsh with the -g option causes this variable to be set to 1.

See Also

_boseos_info

23.12 _trace_function

Synopsis

Set the function to trace

Usage

_trace_function (String_Type f)

Description

_trace_function declares that the S-Lang function with name f is to be traced when it is called. Calling _trace_function does not in itself turn tracing on. Tracing is turned on only when the variable _slangtrace is non-zero.

See Also

_slangtrace, _traceback

23.13 _use_frame_namespace

Synopsis

Selects the namespace of a stack frame

Usage

_use_frame_namespace (Integer_Type depth)

Description

This function sets the current namespace to the one belonging to the call stack frame at depth depth.

See Also

_get_frame_info, _get_frame_variable


Next Previous Contents