Guardian Procedure Calls Reference Manual

context to be displayed. A double loop of HIST_FORMAT_ and HIST_GETPRIOR_ procedure
calls then displays a history of context transitions: HIST_FORMAT_ provides the text for display,
and HIST_PRIOR_ establishes the next context (for the previous procedure).
The HO_Init_Address option of HIST_INIT_ does not start a stack trace. It generates only one
context. However, the same loop of calls still works; the loop simply terminates after one
iteration. When this option is specified, the only effective workspace.FormatSelect
options are HF_Name, HF_Parent, HF_Offset, or HF_CodeSpace. These are all selected by
default. The user can assign a subset. For a description of workspace.FormatSelect
options, see the HIST_FORMAT_ Procedure (page 698).
• Protected contexts
When a run-time event that requires immediate attention, such as a hardware trap, causes a
signal to be generated, the uContext structure presented to the signal handler contains either
one or two contexts. The primary context is a complete record of the procedure context at the
site of the event. If that site was in protected code, a secondary context contains part of the
state at the site of transition into protected code.
For example, if a user program invokes a CALLABLE procedure (switching into privileged
mode) and an attempt to access an invalid address occurs within the privileged code, the
primary context is that of the invalid operation and the secondary context is that of the user
procedure at the site of the call to the CALLABLE procedure.
The secondary context is limited to those registers that, by convention, are saved and restored
by all subsequent callers. Registers used as temporary values (including procedure parameters
and return values) are not available.
For a sample display of primary and secondary context, see the HIST_FORMAT_ Procedure
(page 698).
• TNS process support
The HIST_INIT_ procedure can be called from a TNS process. However, HO_Init_Here and
HO_Init_Address are the only supported context option for TNS callers. For native callers, the
trace begins with the caller of HIST_INIT_, because the activation records for HIST_INIT_ and
its shell ($HIST_INIT_) are suppressed, regardless of the setting of the HO_NoSuppress option.
TNS stack frames can also be encountered if a trace is begun within native procedures and
proceeds through TNS frames in a TNS process.
• The workspace structure (HISTWORKSPACE_TEMPLATE) has two formats. The HistVersion1
format is the default format for 32-bit callers, while the HistVersion3 format is the default for
64-bit callers. 32-bit callers may specify the HistVersion3 format by defining the _HIST32_64BIT
toggle for pTAL programs, or adding #define _HIST32_64BIT for C/C++ programs. Note
that the version defines how information is stored within the structure, but does not restrict
where the structure may be allocated. In other words, a workspace structure may be allocated
from 32-bit addressable memory or 64-bit addressable memory, regardless of its version
format.
Example
error := HIST_INIT_ ( hws, vers, options, context );
720 Guardian Procedure Calls (H-K)