S-Lang Run-Time Library Reference: Version 2.0.4: Debugging Functions

Next Previous Contents

## 20. Debugging Functions

## 20.1 _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 interpeter 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 value 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
  >                   statements.
  >          2        Same as for 1 with the addition that code will also be
  >                   generated for branching 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`.
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, _debug_info`

## 20.2 _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`

## 20.3 _debug_info

Synopsis

  Configure debugging information

Usage

  `Integer_Type _debug_info`

Description

  The `_debug_info` variable controls whether or not extra code should be generated for additional debugging and traceback information. Currently, if `_debug_info` is zero, no extra code will be generated; otherwise extra code will be inserted into the compiled bytecode for additional debugging data.

  The value of this variable is local to each compilation unit and setting its value in one unit has no effect upon its value in other units.

Example

  > `

  >         _debug_info = 1;   % Enable debugging information

  > `

Notes

  Setting this variable to a non-zero value may slow down the interpreter somewhat.

  The value of this variable is not currently used.

See Also

  `_traceback, _slangtrace`

## 20.4 _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

  > `

  >         static 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`

## 20.5 _set_eos_handler

Synopsis

  Set the beginning 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

  > `

  >        static define eos_handler ()
  >        {
  >          () = fputs ("Done executing the statement\n", stdout);
  >        }
  >        _set_eos_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`

## 20.6 _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`

## 20.7 _traceback

Synopsis

  Generate a traceback upon error

Usage

  `Integer_Type _traceback`

Description

  `_traceback` is an intrinsic integer variable whose value controls whether or not a traceback of the call stack is to be generated upon error. If `_traceback` is greater than zero, a full traceback will be generated, which includes the values of local variables. If the value is less than zero, a traceback will be generated without local variable information, and if `_traceback` is zero the traceback will not be generated.

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

See Also

  `_boseos_info`

## 20.8 _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`

Next Previous Contents