Debug tool event handler

The debug event handler is a DLL with an exported function called one CELQVDBG. The default name of the DLL is also CELQVDBG. The __CEE_DEBUG_FILENAME64 environment variable can be used to specify a different DLL name. Language Environment checks for the environment variable. If the variable exists, Language Environment uses the value specified as the name of the debug event handler DLL and loads it.

You can specify the debug tool to be used at run time by exposing its name to the system for Language Environment to LOAD. A load failure indicates to Language Environment that a debug tool is not available while this program is running. The debug event handler is loaded and initialized when any one of the following occur:
  • An initial command string or PROMPT is discovered and the TEST runtime option is in effect.
  • The error condition is raised for the first time and the TEST runtime option is in effect with the ERROR suboption specified.
  • Any condition is raised for the first time and the TEST runtime option is in effect with the ALL suboption specified.
  • A call to __ctestc is made, regardless of the TEST runtime option setting.

Language Environment notifies the debugger of events by calling the CELQVDBG function. The event handler interface is defined in Table 1 and the bit map descriptions are in Table 2.

Table 1. Debugger Language Environment event handler interface for AMODE 64 applications
Debug Tool Event Debug Tool Event Code Parm 2 Parm 3 Parm 4
Condition raised 101 CIB result code  
Unhandled condition 103 CIB result code  
User handler next 105 CIB

1

2

function pointer
for user handler
function pointer
for member
handler

Goto 111 DSA DSA format  
PIPI Sub Initialization 115      
PIPI Sub Termination 116      
Enclave init 118 creator's EDB    
Enclave term 119      
Thread init 120 creator's CAA    
Debug tool term 121      
Thread term 122      
External entry 123
  • Parm 2 = DSA (see note)
  • Parm 3 = cmd string
  • Parm 4 = INPL
  • Parm 5 = DSA format
Module load 124 DSA module descriptor DSA format
Module delete 125 DSA module name DSA format
Storage free 126 storage storage length  
Condition promote 127 CIB result code  
Condition goto 128 DSA DSA format  
Debug tool program check 130 result code    
Message redirect 131 msg_text ddname  
CALL CEETEST 132 DSA (see note 1) cmd string DSA format
Execute Hook invocation 133
  • Parm 2 = DSA
  • Parm 3 = hook offset
  • Parm 4 = DSA format
  • Parm 5 = A buffer containing general purpose registers
  • Parm 6 = Return address to the routine that was interrupted
  • Parm 7 = Entry point to the routine that was interrupted
mutex_init 140 initializing thread_id mutex (for bit mask descriptions, see Table 2)
mutex_destroy 141 destroying thread_id mutex  
mutex_lock 142 owner thread_id mutex  
mutex_unlock 143 thread_id releasing mutex mutex  
mutex_wait 144 waiting thread_id mutex  
mutex_unwait 145 posted thread_id mutex  
mutex_relock 146 owner thread_id mutex  
mutex_unrelock 147 owner thread_id mutex  
cond_init 150 initializing thread_id condition var cv attr object
cond_destroy 151 destroying thread_id condition var  
cond_wait 152 waiting thread_id condition var mutex
cond_unwait 153 posted thread_id condition var mutex
Initial thread create 160 initial thread_id nil stack_size
Initial thread exit 161 initial thread_id    
Pthread create 162 creating thread_id created thread_id stack_size
Pthread created 163 created thread_id nil stack_size
Pthread exit 164 created thread_id    
Pthread wait 165 joining thread_id joined thread_id  
Pthread unwait 166 joining thread_id joined thread_id  
Imminent CAA Chain Addition 167      
CAA Chain Addition Complete 168      
Imminent CAA Chain Deletion 169      
CAA Chain Deletion Complete 170      
POSIX fork() imminent 171 thread_id    
In child process 172      
POSIX exec() imminent 173      
Process clean up imminent 174      
Spawn is imminent 175      
UNIX file system load module 176 DSA UNIX file system module descriptor DSA format
Delete UNIX file system load module 177 DSA UNIX file system module name DSA format
In parent process 178      
After spawn 179      
rwlock lock for read 181 thread_id rwlock  
rwlock lock for write 182 thread_id rwlock  
rwlock wait for read 183 thread_id rwlock  
rwlock wait for write 184 thread_id rwlock  
Multiple event Execute Hook invocation 189
  • Parm 2 = DSA
  • Parm 3 = hook offset
  • Parm 4 = DSA format
  • Parm 5 = A buffer containing general purpose registers
  • Parm 6 = Return address to the routine that was interrupted
  • Parm 7 = Entry point to the routine that was interrupted
  • Parm 8 = Event mask
Note:
  1. This is the requestor's DSA, which means an HLL library routine DSA is likely the requestor of the Language Environment service or user DSA.
  2. If DSA format is 1 in a 64–bit environment, i.e. XPLink DSA, 64-bit address of 64-bit'ized DSA
Table 2. Debugger Language Environment event handler bit mask descriptions for AMODE 64 applications
Bit mask Description
'00000000'X The object is a private mutex with the non-recursive characteristic.
'00000001'X The object is a private mutex with the recursive characteristic.
'00800000'X The object is a shared mutex with the non-recursive characteristic.
'00800001'X The object is a shared mutex with the recursive characteristic.
'08000001'X The object is a private rwlock with the recursive characteristic.
'08800001'X The object is a shared rwlock with the recursive characteristic.
CAA
A doubleword binary integer that contains the address of the CAA.
CIB
A doubleword binary integer that contains the address of the CIB.
DSA
A doubleword binary integer that contains the address of the DSA.
DSA format
A fullword binary integer set to:
1
The format of the DSA is XPLINK style.
General purpose registers
A 128-byte buffer containing the general purpose registers stored in order 0 to 15 at the time the debug hook was executed. If the debugger changes these register values, the new values will be used when control is returned to the routine that executed the debug hook.
return_address
A doubleword pointer containing the address of the instruction where control will be returned to the routine that executed the debug hook. If the debugger changes this address, control will be returned to the new location.
entry_ptr
A fullword pointer containing the address of the entry point of the routine that contains the debug hook.
EDB
A doubleword binary integer that contains the address of the EDB.
module name
A halfword-prefixed string of the module name being deleted.
UNIX file system module name
A fullword-prefixed string of the module name being deleted.
module descriptor
A structure describing the module that was just loaded. The structure is as follows: 
   dcl 1 module descriptor,
         3  load point  pointer(64),
         3  module size fixed,
                 3  * char(4),
                 3  entry point pointer(64),
         3  name length fixed(15),
         3  module name char(255);
UNIX file system module descriptor
A structure describing the module that was just loaded. The structure is as follows: 
   dcl 1 UNIX file system module descriptor,
         3  load point  pointer(64),
         3  module size fixed,
                 3  * char(4),
                 3  entry point pointer(64),
         3  name length fixed(31),
         3  module name char(255);
result code
A fixed(31) binary value action for condition manager to take. The supported values are:
  • 110 — Resume at the resume cursor
  • 120 — Percolate to next condition handler
storage length
A fixed(31) binary value containing the number of bytes of storage.
cmd string
A halfword-prefixed string containing the debug command.
msg_text
A halfword-prefixed string of the text that is transmitted by Language Environment message services.
ddname
An 8–byte character string, left-justified, padded right with blanks of the target ddname.
INPL
The initialization parameter list. For the format of the INPL, see Figure 1.
start_rtn
A function pointer to the start routine for the pthread.
thread_id
An 8-byte thread identifier.
mutex
A pointer to a mutex object.
recursive
A recursive type mutex.
nonrecurs
A nonrecursive type mutex.
condition var
A pointer to a condition variable object.
cv attr object
A pointer to a condition variable attributes object.
stack_size
A fixed (63) stack size attribute (in bytes) of initial or created thread.
nil
Unused; null pointer.
event mask
a fullword binary value in which each bit represents a different hook event. When the bit is '1'b, the event occurred. The values of the bits are: 
Bit      Event
0-11     Not used
12       Multiple Event Hook
13       Allocate Descriptor Built
14       Block Entry
15       Not used
16       User label
17       Begin of statement
18       Call return
19-20    Not used
21       Start of loop
22       If evaluated TRUE
23       If evaluated FALSE
24       Switch/case/select choice start
25       Switch/case/select default start
26       Multiple flows join
27       Not used
28       Call begin
29       Goto
30       Procedure exit
31       Multiple exit
Usage Notes:
  1. A message is issued if the load fails because the Debug tool is not available.
  2. All parameters are passed by reference.
  3. Return codes (in decimal) are placed in R3
    00
    Success
    16
    Critical error in the debug tool; do not invoke again.
  4. The debugger signals a CEE2F1 condition when it needs to quit from a nested enclave.
Parent topic: Debug tool-provided event handlers