Using the Debugger from a Remote System

Using Remote Debugger User Exits

The remote debugger supports the use of program invocation exits for starting applications with unique start-up requirements or where automatic start-up is unsupported, such as CMS, CICS, or OS/390 batch. A program invocation exit can be written in C or assembly language. It can perform any processing that is necessary in order to start the program that is being debugged. For example, you might use a program invocation exit to

build and submit JCL
initiate a CICS transaction
AUTOLOG a CMS session.

The program invocation exit can use the full SAS/C library and any other operating environment services that are available to normal (unauthorized) SAS/C environments.

Calling Sequence

The remote debugger calls the program invocation exit just before it would normally wait for a TCP/IP or APPC connection request from the program to be debugged. When the exit finishes its processing and returns, the debugger waits for the connection request from the remote program until it continues to initialize.

The program invocation exit is called once per remote debugger session. It is not called at all when the debugger is running in local mode (for example, when the _DB_COMM environment variable equals LOCAL or NONE).

The remote debugger supports the input and output exits L$UDBIN and L$UDBOUT that are described in Debugger I/O Exit Routines. The program invocation exit is independent of the I/O exits. The L$UDBOUT output exit is called for initialization before the program invocation exit is called. The program invocation exit and debugger output exit can exchange information by using the CRAB user words. This allows the output exit to clean up resources that are allocated by the invocation exit during the output exit termination call.

Installation Requirements

The program invocation exit takes the form of a separate load module that is named L$UDBNVK. Under CMS, this load module must be placed in the L$CUSER LOADLIB, which is created by the user. Under OS/390, it may be placed in the transient library data set sasc.LINKLIB, or in a separate library that is concatenated ahead of the transient library to an appropriate DDname (STEPLIB or CTRANS).

Dummy Exit Routines

As installed under OS/390, the SAS/C run-time library contains a dummy L$UDBNVK exit routine in sasc.LINKLIB. This routine does nothing; it only returns control to the caller. You can replace this load module with your own exit or delete it. If you delete the dummy exit, your operating environment might produce error messages when the remote debugger is invoked (for example, OS/390 message CSV003I), but the debugger starts up normally.

Note: There is no dummy exit for CMS. [cautionend]

Assembly Language Implementation

The program invocation exit is invoked under standard IBM linkage conventions. Any registers that are used by the routine should be saved (the standard save area that is addressed by register 13 can be used for this) and restored on exit. Write the exit so that it can be issued in AMODE 31; however, it always starts in the same addressing mode as the remote debugger's first load module.

When the program invocation exit receives control, register 1 points to the following parameter block.

Program Exit Parameter Block
Offset Description

0 Address of the null-terminated string for the _DB_COMM environment variable value. This value indicates the debugger communications access method and is ("APPC", "TCPIP",) or the "TCPIP_xxx" variant.

4 Address of the null-terminated string for the _DB_HOST (TCP/IP) or _DB_LU (APPC) environment variable value.

8 Address of the null-terminated string for the _DB_PORT (TCP/IP) or _DB_TP (APPC) environment variable value.

12 Address of the area that is mapped by C struct RDBG_RUNOPTS or assembler RDBGOPTS DSECT.

16 Address of the value from CRABUSR1 (CRAB user word 1).

20 Address of the value from CRABUSR2 (CRAB user word 2).

24 Address of the value from CRABUSR3 (CRAB user word 3).

28 Address of the value from CRABTUSR (CRAB user word 4).

***Program Exit Parameter Block***
Offset	Description
0	Address of the null-terminated string for the `_DB_COMM` environment variable value. This value indicates the debugger communications access method and is ("APPC", "TCPIP",) or the "TCPIP_xxx" variant.
4	Address of the null-terminated string for the `_DB_HOST` (TCP/IP) or `_DB_LU` (APPC) environment variable value.
8	Address of the null-terminated string for the `_DB_PORT` (TCP/IP) or `_DB_TP` (APPC) environment variable value.
12	Address of the area that is mapped by C `struct RDBG_RUNOPTS` or assembler `RDBGOPTS DSECT`.
16	Address of the value from CRABUSR1 (CRAB user word 1).
20	Address of the value from CRABUSR2 (CRAB user word 2).
24	Address of the value from CRABUSR3 (CRAB user word 3).
28	Address of the value from CRABTUSR (CRAB user word 4).

Offset 12 addresses the area that is mapped by the RDBGOPTS DSECT, as shown in RDBGOPTS DSECT Mapping. This DSECT is created from the run-time options that are specified when SASCDBG is invoked. This DSECT provides access to the name of the program to be debugged, its run-time arguments, and the program invocation method (FORK, OEATTACH, ATTACH, manual).

RDBGOPTS DSECT Mapping
SPACE 3 RDBGOPTS DSECT RDBBPNAM DS A Address of program name to be invoked RDBGARGS DS A Address of runtime arguments passed to program * DS XL2 --Reserved RDBGOPTF DS XL1 Option flag RDBGSUPD EQU X'01' Suppress automatic =D runtime arg insertion RDBGDBTN EQU X'02' Intercept UNIX System Services Terminal I/O * RDBGINVM DS XL1 Request invocation method for program RDBGMANU EQU X'00' Manual invocation RDBGFORK EQU X'01 Via UNIX System Services fork and exec services RDBGOEAT EQU X'02' Via UNIX System Services/TSO OEATTACH service RDBGATTA EQU X'03' Via OS/390 ATTACH * DS 0D RDBGOLEN EQU *-RDBGOPTS Length of DSECT

Offsets 16, 20, 24, and 28 address CRAB user words 1-4, respectively. The CRAB user words are the remote debugger's CRAB, since the program that is being debugged has not yet received control. You can modify the CRAB user words by replacing the values in the parameter block. When the program invocation exit returns, the new values are copied into the debugger's CRAB.

You can also modify other information in the RDBGOPTS DSECT to affect later debugger invocation processing.

The program invocation exit must return one of the values that are described in Return Codes. These return codes are used by exit routines that are written in both assembly language and C.

C Implementation

You can implement the program invocation exit as a C function by using the following syntax:

#include <rdbgnvk.h>
int _dynamn (char *rdbg_comm_method,
             char *rdbg_host_lu,
             char *rdbg_port_tp,
             struct RDBG_RUNOPTS *rdbg_runopts,
             void *crabusr1_copy,
             void *crabusr2_copy,
             void *crabusr3_copy,
             void *crabtusr_copy)
        {
          /* exit code */

All arguments are input arguments and are passed by the remote debugger when it calls the exit. The arguments correspond to the information in Program Exit Parameter Block.

The RDBGOPTS DSECT maps the C struct RDBG_RUNOPTS. This structure is created from the run-time options that are specified when SASCDBG is invoked. This structure provides access to the name of the program that is debugged, its run-time arguments, and the program invocation method (FORK, OEATTACH, ATTACH, manual).

You can modify the information in the struct RDBG_RUNOPTS to affect later debugger invocation processing. You can also modify the copies of the CRAB user words. When the program invocation exit returns, the new values are copied into the debugger's CRAB.

The header file {<rdbgnvk.h>}, shown in Remote Debugger Header File, is stored in sasc.MACLIBC. The header file defines the prototype for the program invocation exit and the RDBG_RUNOPTS structure. It also defines the return code constants RDBG_CONTINUE_RC, RDBG_SUPRESS_MSG_RC, RDBG_SUPRESS_DBGINVOKE_RC, and RDBG_FAIL_RC. The program invocation exit must return one of these values, as described in Return Codes.


Remote Debugger Header File


#ifndef _RDBGNVK
#define _RDBGNVK
/*
 * This header file defines the prototypes and options struct passed
 * to the L$UDBNVK remote debugger user exit which can be used to
 * start the application to be debugged by the remote debugger.
 */
/* Prototype for exit function */
int l$udbnvk(char *rdbg_comm_method, char *rdbg_host_lu,
             char *rdbg_port_tp, struct RDBG_RUNOPTS *rdbg_runopts,
             void *crabusr1, void *crabusr2, void *crabusr3,
             void *crabtusr);
/* Define return codes for l$udbnvk */
#define RDBG_CONTINUE_RC 0
#define RDBG_SUPRESS_MSG_RC 4
#define RDBG_SUPRESS_DBGINVOKE_RC 8
#define RDBG_FAIL_RC 12
/* Define options struct passed to l$udbnvk exit */
struct RDBG_RUNOPTS
{
 char *pgm_name;    /* Name of program to be invoked                */
 char **pgm_args;   /* Runtime arguments to be passed to program    */
 char optresv[2];
 char optflag;
#define RDBG_SUPPRESS_D 1 /* Suppress auto. =D option insertion     */
#define RDBG_DBTERM_NO  2 /* Turn off Posix Terminal I/O Intercepts */
 char invoke_method; /* Requested invocation method for program     */
#define RDBG_MANUAL   0
#define RDBG_FORK     1
#define RDBG_OEATTACH 2
#define RDBG_ATTACH   3
;
#endif

Return Codes

The program invocation exit must return one of the following values:

Return Codes
Value Meaning

0 Continue with debugger normal processing and program invocation, as defined by RDBGOPTS DSECT or C struct RDBG_RUNOPTS. If the program invocation method is manual, issue a message that contains process connection information.

4 Continue with debugger normal processing and program invocation, as defined by RDBGOPTS DSECT or C struct RDBG_RUNOPTS, but suppress the process connection information message.

8 Continue with debugger normal processing, but suppress debugger program invocation processing and the connection information message.

12 Terminate debugger connection processing and remote debugger initialization, and issue a failure message.

***Return Codes***
Value	Meaning
0	Continue with debugger normal processing and program invocation, as defined by `RDBGOPTS DSECT` or C `struct RDBG_RUNOPTS`. If the program invocation method is manual, issue a message that contains process connection information.
4	Continue with debugger normal processing and program invocation, as defined by `RDBGOPTS DSECT` or C `struct RDBG_RUNOPTS`, but suppress the process connection information message.
8	Continue with debugger normal processing, but suppress debugger program invocation processing and the connection information message.
12	Terminate debugger connection processing and remote debugger initialization, and issue a failure message.

Typically, return codes 0 and 12 are used as the standard for success and failure status. Return codes 4 and 8 are intended for special purposes. For example, the exit might return the value 4 after starting a program under OS/390 batch. It might return the value 8 if your site uses a custom program invocation method.

Chapter Contents
Previous
Next
Top of Page