Name

bstr_trc_trace − Executes a tracing session. 

Syntax

bstr_t_status   bstr_trc_trace (
                               char             ∗tracepoint_set,
                               bstr_t_u_int32   level,
                               void (∗user_routine)(),
                               ...                              );

Description

The bstr_trc_trace procedure executes a tracing session according to the settings specified by the Process_Selector. The indicated tracepoint causes the trace output to be written to the associated device (or devices) if tracepoint_set is added to the Process_Selector and level is enabled for it. 

This procedure is signal safe and can therefore it can be called in a signal handler routine. 

The user_routine argument can be set to NULL, or can specify the address of a user-written routine. 

If the user-written routine is not specified, the variable argument list (...)  must specify the address of a buffer containing a message formatted according to the printf syntax. 

If the user-written routine is specified, it must include a va_list kind variable in its arguments, together with one or more calls to the bstr_trc_trace procedure. The calls to the bstr_trc_trace procedures inside the user routine must have the user_routine argument set to NULL, and inherit date, time, Tracepoint_Set and level from the calling bstr_trc_trace procedure from which the user routine was called. 

Arguments

tracepoint_set
access: read
The name of the Tracepoint_Set the tracepoint belongs to.

level
access: read
Identifies the level associated with the tracepoint to be traced. Permitted values are integers in the range 0 to 255.

user_routine
access: read
The address of an optional  user-written routine that executes actions  other than output (for example, special formatting) and that contains one or more calls to the bstr_trc_trace procedure, as explained in the varargs(3) man pages (DIGITAL UNIX) or the VAX C Run-Time Library Reference Manual (OpenVMS). 

list_of_parameters
access: read
Specifies the user information to be written to the trace output.

If the user routine is set to NULL (that is, user routine not specified), the list_of_parameters must specify the address of a buffer containing a message formatted according to the printf syntax.  (Maximum length 511 characters.) 

If the user-written routine is specified, the list_of_parameters should comply with the explanation in the varargs(3) man pages (DIGITAL UNIX) or the VAX C Run-Time Library Reference Manual (OpenVMS). 

Return Values

Examples

bstr_trc_trace("MESSAGE",15,NULL,"pid %d; str %s0,getpid(),str)

Information on the trace point with the Tracepoint_Set MESSAGE, level of detail 15. No user-written routine is specified. 

The traced parameters are the PID of the process, and the value of the str variable is in the specified printf-like format. The output is as follows:

Fri Jun 7 16:05:03.984197 1991 : MESSAGE; pid 4259; str abcdefgh

The following example shows a call to the bstr_trc_trace procedure where a user-written routine is specified:

bstr_trc_trace("MESSAGE",15,my_routine,"abcdef",124,"ghiml")

The code of the user-written routine can be as follows:

#include <varargs.h>
void trace_format(ap)
va_list ap;
{
   bstr_t_status    status;
   bstr_t_natural   parameter;
   char            ∗routine_name;
   routine_name = va_arg(ap, char ∗);
   parameter    = va_arg(ap ,bstr_t_natural);
   bstr_trc_trace("DEEPER", 0, NULL, "%s%s",
                  "------------------------------------------0,
                  "Phase1: entering in the evaluation routine0);
   bstr_trc_trace("DEEPER", 0, NULL,
                  "Routine name: %s 0,routine_name);
   bstr_trc_trace("DEEPER", 0, NULL,
                  "Parameter value: %d 0, parameter);
   bstr_trc_trace("DEEPER", 0, NULL,
                  "------------------------------------------0);
}

The output is as follows:

Fri Jun 7 16:10:03.932352 1991 : MESSAGE;
START my_routine, the parameters are:
a string: abcdef
an integer: 124
a string: ghiml
END my_routine.

See Also