Debug event handler

The debug event handler is loadable by Language Environment with the following:
  • If the __CEE_DEBUG_FILENAME31 environment variable is not defined, the name CEEEVDBG is used to load the debug event handler from the MVS load library search order.
  • If the __CEE_DEBUG_FILENAME31 environment variable is defined and the value specified is acceptable, Language Environment uses the value as the name of the debug event handler and loads it from the z/OS UNIX file system. This name, combined with the path name (in the z/OS UNIX file system) that is specified in the LIBPATH environment variable, provides the fully qualified path name for the debug event handler.

By default, Language Environment will only accept the value /bin/dbx31vdbg, which is used by dbx.

To allow other values, a list of allowed values must be created in a file named _CEE_DEBUG_FILENAME31.list in the directory /etc. Add each allowable value exactly as it will be returned by the getenv() function (excluding the NULL character at the end) to the file. Each value must be on a line by itself, with no comments, no leading blanks and no trailing blanks. Lines are terminated with the newline character.

When the value is not /bin/dbx31vdbg, Language Environment will open the file /etc/_CEE_DEBUG_FILENAME31.list and read each line. If a line is found that matches the value for the environment variable _CEE_DEBUG_FILENAME31, the value will be accepted. When the value is not accepted, Language Environment will issue a message, the debug event handler will not be loaded and the application will continue.

The attempt to load the debug event handler is performed from either the z/OS UNIX file system or the MVS load library search order, but not both.

For additional information on invoking the debug event handler, see Event code 16 — z/OS Debugger event. Specification of which debug tool to be used is made 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 CEETEST is made, regardless of the TEST runtime option setting.
Language Environment notifies the debugger of events through the address of the debug tool event handler contained in the CEEPCBDBGEH. The event handler interface is defined in Table 1 and the bit map descriptions are in Table 2. The CWI CEE3CBTS event handler interface is defined in Table 3.
Table 1. Debugger Language Environment event handler interface
Debug Event Debug 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
  • user handler address
  • member event handler address
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  
Attention 129      
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      
CALL CEE3CBTS 180 (for parameter descriptions, see Table 3)    
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
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.
Note:
  1. Indicators are available for objects that are shared and separate events for each type of lock.This information indicates the shared object has two copies of DBX that run in different address spaces for applications that use a shared mutex or rwlock. The first occurrence of a lock event, and the fact the object is shared, causes a new control structure for this object. That is, when the following unique events occur and the high order bit of the mutex_object content is ON, a control structure with a lock count of one will be created. This makes the view of a shared mutex or rwlock available in the using address space after the originating address space has initialized the shared object.
    142
    mutex object
    181
    rwlock object, locking for read
    183
    rwlock object, locking for write
  2. Shared mutex and rwlock objects will always be presented even if the NODEBUG option is one of the object's attributes.
  3. If a shared object acquire event is reported and there is no entry for the lock object, an entry will be created for the object with a lock count of one. Then when an unlock event happens which sets the lock count to zero, the entry for the shared object will be removed.
Table 3. CWI CEE3CBTS event handler interface parameters
Number Name Description
1 Function Code Integer values passed to CEE3CBTS by the invoker of the CWI.
1
Attach Debug
2
Start Debug
3
Suspend Debug
4
Resume Debug
5
Stop Debug
6
Attach Debug_Thread
2 TCP/IP address inout A fullword binary integer containing the TCP/IP address of the debugger GUI.
3 Debugger port ID inout A fullword binary integer containing the port ID of the debugger daemon.
4 Client Process IDinout A fullword binary integer containing the Process ID of the client.
5 Client Thread ID inout A fullword binary integer containing the Thread ID of the client.
6 Client IP address inout A fullword binary integer containing the IP address of the client.
7 Debug Flow inout A fullword binary integer containing debug flow information as provided by CBC.
CAA
A fullword binary integer that contains the address of the CAA.
CIB
A fullword binary integer that contains the address of the CIB.
DSA
A fullword binary integer that contains the address of the DSA.
DSA format
A fullword binary integer set to one of the following:
0
The format of the DSA is a standard OS linkage register save area (with/without Language Environment® fields including NAB).
1
The format of the DSA is XPLINK style.
General purpose registers
A 64-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 fullword 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 fullword 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,
      3  module size fixed,
      3  entry point pointer,
      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,
      3  module size fixed,
      3  entry point pointer,
      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 as passed to CEEINT. 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 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
Note:
  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 R15
    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.