Chapter Contents |
Previous |
Next |
Using the Debugger from a Remote System |
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
Calling Sequence |
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 |
Dummy Exit Routines |
Note:
There is no dummy exit for CMS.
Assembly Language Implementation |
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
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:
Chapter Contents |
Previous |
Next |
Top of Page |
Copyright © 2001 by SAS Institute Inc., Cary, NC, USA. All rights reserved.