Using the Debugger from a Remote System

General Instructions

The remote debugger allows you to run the debugger display in one process and the program that is being debugged in another. The processes can be run on the same system or on different systems.

Under TSO and CMS, the remote debugger takes the form of a REXX EXEC that is named SASCDBG. Under the OS/390 UNIX System Services shell, it takes the form of an executable that is named SASCDBG.

The remote debugger is intended for use in the following situations:

when you want to debug a Customer Information Control System (CICS) application
when you want to debug a UNIX System Services application
when you want to run the debugger and application on different terminals or systems
when you need to debug a full-screen program
when you need to debug a multitasking application.

We recommend using the local debugger for most other debugging tasks. For example, when debugging an application under TSO that is not a UNIX System Services application, the local debugger is considerably more efficient, since it is not subject to context-switching or communication delays.

How the Remote Debugger Works

The remote debugger is similar to the local debugger in its appearance and operation. The main difference is in the program architecture and start-up procedure.

When you are running the remote debugger under TSO or CMS, the remote debugger provides the same full-screen debugging capabilities as the local debugger. When you are running the remote debugger in the UNIX System Services shell or under OS/390 batch, the remote debugger is limited to line-mode operation only.

If you are familiar with the local debugger, you should have no problem using the remote debugger, once you understand the environment and start-up procedures that are described here.

Architecture

The SAS/C Debugger client/server architecture allows debugging of remote applications. There are two components in a remote debugging session:

the debugger display and program control logic
the program being debugged and an interface to the debugger (ITD).

The debugger display, along with the program control logic, act as the server. It provides the debugger services, under user control, to the client program. Each debugger component runs in a separate process. Depending on your operating environment, this may mean a different address space, task, virtual machine, or UNIX System Services process. In addition, the client program may be running on a physically different host.

As shown in Remote Debugger Architecture, the debugger processes communicate with each other through a communications layer, which can use either the TCP/IP or APPC communications access method.

Remote Debugger Architecture

[IMAGE]

For maximum productivity, typically the debugger display component is run in a full-screen session under TSO or CMS. You can run the client program in any environment that supports the SAS/C library. CICS and UNIX System Services processes are the most typical environments. You can also run the client program in environments such as TSO, CMS, OS/390 APPC address spaces, or OS/390 batch.

Start-Up Methods

From the user's point of view, the most significant difference between the local debugger and remote debugger is the start-up procedure. To use the local debugger, you compile your program in debug mode and include the =debug run-time option when you run the executable. The remote debugger has two start-up methods:

independent start-up
automatic start-up.

With the independent start-up method, you start the debugger display process first, by using the SASCDBG debugger interface. When the process starts, the terminal displays the communications access method and other information that is needed by the client program in order to connect to the debugger display. For example, under TSO, you might see the following message after starting the remote debugger display:

SASCDBG DBCOMM(TCPIP)

SAS/C Remote Debugger can be reached via:
_DB_COMM=TCPIP connect to _DB_HOST=10.1.1.1
  (OS/390), at _DB_PORT=13227

Then, in a separate step, you start the program to be debugged in the normal way for your environment, and you specify the =debug run-time option on the command line. You can specify the connection information with environment variables before starting the program, or you can issue the equivalent command-line options. For example, you might call a TSO load module in the following manner:

CALL ABC.LOAD(MYPGM) '=D =_DB_COMM=TCPIP
  =_DB_HOST=OS/390 =_DB_PORT=13227'

With the automatic start-up method, you start both processes in a single step by including the program name in the SASCDBG command line. For example, in the UNIX System Services shell, you might start the remote debugger with the following command:

sascdbg -tcpip mypgm

For more information about environment variables, See Debugger Environment Variables. For a complete description of SASCDBG syntax, see Using the SASCDBG Debugger Interface.

CICS applications are a special case. Since CICS does not support a command line, you must use the remote debugger's CICS front-end transaction in order to set the environment variables and to launch the program that is being debugged. Debugging CICS Applications describes this procedure.

PUTENV _DB_COMM=TCPIP EXTERNAL

CMS environment:

GLOBALV SELECT CENVSETS _DB_COMM TCPIP

UNIX System Services Shell

export _DB_COMM=TCPIP

For details about the PUTENV command, see the SAS/C Compiler and Library User's Guide. For details about the GLOBALV command, see the IBM publication SC24-5776 VM/ESA V2R4.0 CMS Command Reference.

Optionally, you can set the environment variables on the command line during independent start-up of the program that is being debugged. This is equivalent to setting the environment variables with a program scope. For example, under CMS, the following command starts MYPGM in debug mode and sets the _DB_COMM environment variable to TCPIP:

MYPGM =d =_DB_COMM=TCPIP

Under OS/390 batch, you must set the environment variables in an EXEC PARM string. There is a 100-character limit on EXEC PARM strings. If this limit presents a problem, you can use another method for setting the environment variables. For example, you could use argument redirection in order to obtain the environment variables from a file. For details about argument redirection, see the SAS/C Compiler and Library User's Guide.

Because CICS does not enable you to specify program-scope variables on the command line, you should use the remote debugger's CICS front-end transaction in order to set the environment variables for the remote debugging session. See Debugging CICS Applications for details.

Using the SASCDBG Debugger Interface

The SASCDBG debugger interface has three forms: TSO, CMS , and UNIX System Services shell. In addition, for TSO and UNIX System Services, there is a form for the independent start-up method and a form for the automatic start-up method. The start-up method depends on the presence or absence of a program name. CMS supports the independent start-up method only. The independent start-up method does not require the program name when you run the SASCDBG debugger interface.

Process Invocation

When you start the remote debugger under TSO or the UNIX System Services shell, you can specify the method that invokes the program that is being debugged. Your choices are

FORK
OEATTACH
ATTACH

The FORK method is similar to a UNIX fork. It is the standard method in the UNIX System Services environment for creating a child process with its own address space. Typically, you will use the FORK method when debugging a UNIX System Services application under TSO.

The OEATTACH method provides an alternative for debugging UNIX System Services applications under TSO or the UNIX System Services shell. File handling, signal handling, and so forth, is like UNIX System Services but the address space is the same as the debugger. Typically, you will use the OEATTACH method for improved performance over FORK.

The ATTACH method starts the debugger processes by using the assembler ATTACH macro. You can use the ATTACH method for debugging applications under TSO that are not UNIX System Services applications. However, we do not recommend using this method, because the local debugger is considerably more efficient than the remote debugger in this environment.

When debugging a UNIX System Services application under TSO by using the FORK or OEATTACH method, a UNIX System Services terminal ( tty ) is not defined for the program. Instead, the debugger intercepts program I/O to the standard UNIX System Services file descriptors 0, 1, and 2, and processes it according to the specifications in the Termin and Termout windows (if the debugger is running in full-screen mode). Any attempt by the program to open /dev/tty fails. If you invoke the program with OEATTACH, the program can open the file //ddn:* in order to access the TSO terminal.

You can disable program I/O intercepts with the SASCDBG DBTERM parameter. This causes the program output to the UNIX System Services file descriptors to be discarded. In addition, file 0 input requests receive an immediate end-of-file indicator. For more information about DBTERM, see sascdbg Arguments.

sascdbg Syntax

This section describes the syntax for the SASCDBG debugger interface. The syntax is different in each environment, but the arguments have the same meaning.

Note: You can abbreviate command keywords to four or fewer characters in most cases: PARMS and RESTART can be abbreviated to a single character; DBCOMM, DBPORT, and DBINVK can be abbreviated to three characters; DEBUG can be abbreviated to two characters; and DBTERM can be abbreviated to four characters. YES and NO values can be abbreviated to one character. All intermediate abbreviations are accepted. DBLU and DBTP cannot be abbreviated [cautionend]

TSO forms:

SASCDBG pgm_name

[ PARMS( pgm_args...) ]

[ DBCOMM(TCPIP | TCPIP_ xxx) ]

[ DBPORT(port_num) ]

[ RESTART(YES | NO) ]

[ DBTERM(YES | NO) ]

[ DBINVK(FORK | OEATTACH | ATTACH) ]

[ DEBUG(YES | NO) ]

SASCDBG

[ DBCOMM(TCPIP | TCPIP_ xxx | APPC) ]

[ DBPORT(port_num) ]

[ RESTART(YES | NO) ]

[ DBLU(lu_name) ]

[ DBTP(tp_name) ]

CMS form:

SASCDBG (TCPIP | TCPIP_ xxx

[ PORT=port_num ]

[ RESTART ])

UNIX System Services Shell forms:

sascdbg

[ -tcpip | -tcpip_ xxx ]

[ -port=port_num ]

[ -nod ]

[ -fork | -oeattach ]

pgm_name [ pgm_args... ]

sascdbg

[ -tcpip | -tcpip_ xxx ]

[ -port= port_num ]

sascdbg Arguments

No arguments except pgm_name and pgm_args are case sensitive.

FORK

requests program invocation with a FORK function call and then an EXEC of the program to be debugged in the child process of the FORK. This is the default program invocation method when you debug a UNIX System Services application under TSO or the UNIX System Services shell.

OEATTACH

requests program invocation with an OEATTACH function call for improved performance over the FORK method when you debug a UNIX System Services application under TSO or the UNIX System Services shell.

ATTACH

requests program invocation with the OS/390 ATTACH macro. You can use this option to debug applications under TSO that are not UNIX System Services applications. However, because the local debugger does not have to communicate over a network to debug and is therefore more efficient, using the local debugger instead of the ATTACH option is recommended.

DEBUG

determines whether the =debug run-time option is added during program invocation; the default is YES. Normally, the =debug option must be passed by SASCDBG in order to cause the client program to invoke the debugger interface. However, if the program uses the _nlibopt external variable in order to suppress run-time option handling, =debug is interpreted as a program argument. If your program sets _nlibopt, it must initialize the library external variable _options to specify _DEBUG in order to allow the program to be debugged. For more information about the _nlibopt and _options variables, see the SAS/C Compiler and Library User's Guide.

NOD

suppresses insertion of the =debug run-time option during program invocation. -nod is the equivalent of DEBUG(NO) for the UNIX System Services.

DBTERM

determines whether the debugger intercepts terminal I/O when you are debugging a UNIX System Services application under TSO by using the FORK or OEATTACH method; the default is YES.

Note: This option has no effect when you debug a program that is not a UNIX System Services program. Terminal I/O is controlled by the initial configuration file settings and the I/O window intercept settings of the debugger's terminal. [cautionend]

TCPIP TCPIP_xxx APPC

determines the communication method between the debugger processes, either TCP/IP or APPC. For SAS/C Releases prior to Release 7.00, when TCPIP is specified, the debugger uses your site's default TCP/IP implementation of nonintegrated sockets. For SAS/C Release Release 7.00, when TCPIP is specified, the debugger uses your site's default TCP/IP implementation of integrated sockets. When TCPIP_xxx is specified, the debugger uses the TCP/IP implementation that is specified by the setsockimp("xxx") function call. For example, TCPIP_OE requests UNIX System Services integrated sockets. You can specify any TCP/IP implementation that is installed and available on your system. For more information, see the description of the setsockimp function in SAS/C Library Reference, Volume 2.

Specifying the communications access method on the command line sets the program scope _DB_COMM environment variable. If this variable is already defined with an external or permanent scope, the command line specification takes precedence. If you do not specify the communications access method, the _DB_COMM environment variable is used.

RESTART

determines whether the debugger display process is restarted after program termination or loss of communication with the client program (TSO and CMS only). The default is NO. Use this option with the independent start-up method in the event that you need to restart the debugger processes, for example, when you debug a pseudo-conversational CICS transaction. See Debugging CICS Applications for details. Also see the port_num option.

If you specify the RESTART option, you must use attention (PA1) on TSO or the HX command on CMS in order to terminate SASCDBG. Otherwise, it continues to try to reconnect with the client program.

Note: This option does not preserve breakpoints or other debugger session parameters. It recreates the debugger's entire C environment and reloads the debugger load modules. [cautionend]

port_num

specifies the TCP/IP port number that is used by the remote debugger (TCP/IP communications access method only). If the debugger cannot use the specified port, for example, because it is in use by another process, it displays a warning message and allows the system to assign a port number. Port numbers can be in the range of 0-65535. If port_num is 0, the system assigns a port number from 1 to 65535.

If the operating environment supports external scope environment variables, the debugger saves the port number from the current session in an external scope _DB_PORT variable. (See the note below for information about environments that do not support external scope variables.) By default, the debugger tries to reuse the port in the _DB_PORT variable if you do not set port_num explicitly. This behavior is especially useful when you specify the RESTART option, for example, when debugging a pseudo-conversational CICS transaction. This allows the client program to automatically reestablish communication with the debugger on subsequent invocations.

The system always assigns the port number if this is the first debugging session since logging in, if the _DB_PORT environment variable is cleared, or if the debugger is unable to reuse the previous port number.

Note: Environments such as OS/390 batch and the UNIX System Services shell do not support external class environment variables. In these environments, the debugger uses the specified port_num for the current debugging session, but does not retain it for future sessions. [cautionend]

lu_name

specifies the name of the APPC Logical Unit (LU) where the debugger display is run (APPC communications access method only). The LU name consists of 1-8 nonblank uppercase letters or numbers (A-Z, 0-9). During independent start-up, the LU name is displayed at the terminal and is used by the client program in order to request an APPC connection to the debugger display. The default value is 8 blanks, which indicates the system base LU.

Note: The default value may or may not work, depending on the APPC definitions for your system. [cautionend]

tp_name

specifies the name of the APPC Transaction Program (TP) that is registered with the APPC LU (APPC communications access method only). The TP name consists of 1-64 upper- or lowercase alphabetic characters, numbers, or special characters, except $, #, and @. During independent start-up, the TP name is displayed at the terminal and is used by the client program in order to request an APPC connection to the debugger display. The default value is SASCDBG.

pgm_name

specifies the name of the program that is debugged. This program automatically connects with the remote debugger display. Under TSO, specify the program name as the first argument. Under the UNIX System Services shell, specify the program name last. For details about how the debugger locates programs in the UNIX System Services hierarchical file system (HFS), see Pathname Resolution under UNIX System Services.

pgm_args

specifies one or more run-time arguments that are passed to the program that is debugged. The remote debugger adds the =debug run-time option automatically unless you specify -nod (UNIX System Services) or DEBUG(NO) (TSO/CMS).

Pathname Resolution under UNIX System Services

When you are debugging a UNIX System Services program, pgm_name takes the form of a pathname in the UNIX System Services hierarchical file system. If pgm_name does not begin with a / (slash), the debugger searches for the program in the following way:

If you run the debugger display in the UNIX System Services shell, it first checks your current working directory.
Otherwise, it checks your home directory.
Finally, it checks the directories on your search path, as defined in the PATH environment variable.

If pgm_name begins with a / (an absolute pathname), the debugger looks for the program at the specified pathname.

Restrictions

The remote debugger has the following restrictions on its use and operation:

When debugging a UNIX System Services program under TSO, you must use the TCP/IP communications access method if you launch the program with ATTACH or OEATTACH.
Under CMS and UNIX System Services, the debugger display component supports only the TCP/IP communications access method.
When using the ATTACH method of program invocation, the debugger environment variables are appended to the program run-time arguments in the form of =name=value. This may cause problems for programs that are compiled with the _nlibopts variable, because the environment variables are interpreted as program arguments and are not set as environment variables.

Debugging CICS Applications

CICS does not support a command line. When you start a CICS program, you specify only the program's transaction name; you cannot specify run-time options, environment variables, or command parameters. Since the remote debugger uses environment variables to exchange information with the client program, you must use the remote debugger's CICS front-end transaction to set these variables and launch the program that is debugged.

To use the remote debugger with a CICS application, follow these steps:

Start the remote debugger on the system where you do your development, for example:

SASCDBG DBCOMM(TCPIP)

SAS/C Remote Debugger can be reached via:
_DB_COMM=TCPIP connect to _DB_HOST=10.1.1.1
  (OS/390), at _DB_PORT=13227

On your CICS system, start the remote debugger's front-end transaction. The transaction name, as distributed with the SAS/C product, is DBUG. Its format is
```
DBUG trans_name
```
Where trans_name is the 4-character transaction name that is associated with the program to be debugged. For example:
```
DBUG ctim
```
Note: Your CICS systems administrator can change the name of the DBUG transaction, if desired. Check with your administrator if you have any questions about the name of the transaction at your site.

DBUG Transaction Screen shows the screen that is displayed by the DBUG transaction. You can tab from field to field and specify values for the debugger environment variables. You can also specify run-time options; the =debug option is specified by default.

DBUG Transaction Screen

[IMAGE]

Once you type the appropriate values, press the ENTER key to in order start your application. The DBUG transaction verifies that the named transaction exists, that the specified program name is associated with the transaction, and that the program can be loaded into memory. If any of these checks fail, the DBUG transaction displays an error message and exits. Otherwise, it starts the application, and it produces the remote debugger display with your application's source code in the Source window.

If you specify the wrong value for any debugger environment variable (for example, the wrong TCP/IP port number), the application exits with an ABEND 1219 error message. You can rerun the DBUG transaction and correct the value without restarting the debugger. The DBUG transaction saves the latest value of each field in an external scope environment variable. You see this value when the transaction screen reappears. Replace the value with a new one and press ENTER when you are finished.

If you debug a pseudo-conversational CICS application, you start the remote debugger with the RESTART parameter under TSO or CMS. The RESTART parameter causes the debugger to restart with the same connection parameters. If you use the TCP/IP communications access method, do not set the DBPORT parameter to 0, since this forces the system to select a new port number when the debugger is restarted. If this occurs, the CICS application terminates with an ABEND 1219 error message. Otherwise, your pseudo-conversational program reestablishes communication with the debugger automatically, and you can continue to debug your program without interruption.

If the debugger cannot reuse the previous TCP/IP port, for example, because it is in use by another process, it displays its normal connection message, and the CICS application terminates with an ABEND 1219 error message.

Note: CICS applications cannot communicate with the remote debugger over TCP/IP until you start TCP/IP for your CICS region. For IBM TCP/IP, if the start-up transaction has not been executed, your CICS application terminates with an ABEND AEY9 error message. The CICS administrator can start IBM TCP/IP with the IBM CSKE transaction. Other TCP/IP vendors may have different start-up requirements and procedures. [cautionend]

Start-Up Scenarios

The following examples show how you can start the remote debugger in different environments.

TSO Independent Start-Up (TCP/IP)

TSO session 1:
SASCDBG DBCOMM(TCPIP)

TSO session 2:
CALL XYZ.LOAD(MYPGM) '=D =_DB_COMM=TCPIP =_DB_HOST=OS/390 =_DB_PORT=1234'

Start the remote debugger by using the TCP/IP communications access method. Then, by using the information that is displayed at debugger start-up, call the program load module MYPGM in debug mode. On the command line, specify the environment variables for the communications access method.

TSO Independent Start-Up (APPC)

TSO session 1:
SASCDBG DBCOMM(APPC) DBLU(C02SESS) DBTP(SASCDBG)

TSO session 2:
CALL XYZ.LOAD(MYPGM) '=D =_DB_COMM=APPC =_DB_LU=C02SESS =_DB_TP=SASCDBG'

Start the remote debugger by using the APPC communications access method. On the command line, specify the Logical Unit name and Transaction Program name (this is required if the corresponding environment variables are undefined). Then call the program load module MYPGM in debug mode. On the command line, specify the APPC communications access method environment variables.

Note: The _DB_TP environment variable defaults to SASCDBG and is shown in this example for illustration only. [cautionend]

CMS Independent Start-Up

CMS session 1:
SASCDBG (TCPIP

CMS session 2:
MYPGM =D =DB_COMM=TCPIP =_DB_HOST=VM =_DB_PORT=1234

Start the remote debugger by using the TCP/IP communications access method. Then, by using the information displayed at debugger start-up, run MYPGM in debug mode. On the command line, specify the environment variables for the communications access method.

OS/390 Batch Independent Start-Up

TSO session:
SASCDBG DBCOMM(TCPIP)

OS/390 batch JCL:
//STEP1 EXEC PGM=MYPGM, // PARM='=D =_DB_COMM=TCPIP =_DB_HOST=OS/390=_DB_PORT=1234' //STEPLIB DD DSN=pgm.load,DISP=SHR //CTRANS DD DSN=SASC.LOAD,DISP=SHR //SYSPRINT DD SYSOUT=A

Start the remote debugger by using the TCP/IP communications access method. Then submit a batch job that runs MYPGM in debug mode. In a PARM string, specify the values of the environment variables for the communications access method.

TSO automatic start-up

SASCDBG mypgm DBCOMM(TCPIP) DBINVK(FORK)

Start the remote debugger by using the TCP/IP communications access method. Debug the UNIX System Services program MYPGM by using the FORK method.

Note: The program name is case sensitive and is the first argument in the command line. [cautionend]

UNIX System Services Shell Automatic Start-Up

sascdbg -tcpip -fork /devel/r6/mypgm

Start the remote debugger by using the TCP/IP communications access method. Debug the program /dev/r6/mypgm by using the FORK method.

Note: The FORK method is the default for invoking a program under the UNIX System Services shell and is included in this example for illustration only. [cautionend]

Chapter Contents
Previous
Next
Top of Page