Starting z/OS Debugger with CEETEST

Using CEETEST, you can start z/OS® Debugger from within your program and send it a string of commands. If no command string is specified, or the command string is insufficient, z/OS Debugger prompts you for commands from your terminal or reads them from the commands file. In addition, you have the option of receiving a feedback code that tells you whether the invocation procedure was successful.

If you don't want to compile your program with hooks, you can use CEETEST calls to start z/OS Debugger at strategic points in your program. If you decide to use this method, you still need to compile your application so that symbolic information is created.

Using CEETEST when z/OS Debugger is already initialized results in a reentry that is similar to a breakpoint.

The following diagrams describe the syntax for CEETEST:

For C and C++

For COBOL

For PL/I

string_of_commands (input)

Halfword-length prefixed string containing a z/OS Debugger command list. The command string string_of_commands is optional.

If z/OS Debugger is available, the commands in the list are passed to the debugger and carried out.

If string_of_commands is omitted, z/OS Debugger prompts for commands in interactive mode.

For z/OS Debugger, remember to use the continuation character if your command exceeds 72 characters.

The first command in the command string can indicate that you want to start z/OS Debugger in one of the following debug modes:

• full-screen mode using the Terminal Interface Manager
• remote debug mode

To indicate that you want to start z/OS Debugger in full-screen mode using a dedicated terminal without Terminal Interface Manager, specify the MFI suboption of the TEST runtime option with the LU name of the dedicated terminal. For example, you can code the following call in your PL/I program:

Call CEETEST('MFI%TRMLU001:*;Query Location;Describe CUS;',*);

For a COBOL program, you can code the following call:

01 PARMS.
05 LEN PIC S9(4) BINARY Value 43.
05 PARM PIC X(43) Value 'MFI%TRMLU001:*;Query Location;Describe CUS;'.

CALL "CEETEST" USING PARMS FC.

To indicate that you want to start z/OS Debugger in full-screen mode using the Terminal Interface Manager, specify the VTAM® suboption of the TEST runtime option with the User ID that you supplied to the Terminal Interface Manager. For example, you can code the following call in your PL/I program:

Call CEETEST(VTAM%USERABCD:*;Query Location;Describe CUS;,*);

In these examples, the suboption :* can be replaced with the name of a preferences file. If you started z/OS Debugger the TEST runtime option and specified a preferences file and you specify another preferences file in the CEETEST call, the preferences file in the CEETEST call replaces the preferences file specified with the TEST runtime option.

To indicate that you want to start z/OS Debugger in remote debug mode, specify the DBMDT or TCPIP suboptions of the TEST runtime option with the userid you logged on RSE with (DBMDT) or the IP address and port number that the remote debugger is listening to (TCPIP).

• To start z/OS Debugger by using Debug Manager with the user ID that you logged on RSE with, code the following call:

  Call CEETEST(’DBMDT%userid:*;’,*);

• To start z/OS Debugger with the TCP/IP address of your workstation, code the following call:

  Call CEETEST(’DBMDT%userid:*;’,*);

These calls must include the trailing semicolon (;).

fc (output)

A 12-byte feedback code, optional in some languages, that indicates the result of this service.

CEE000

Severity = 0
Msg_No = Not Applicable
Message = Service completed successfully

CEE2F2

Severity = 3
Msg_No = 2530
Message = A debugger was not available

Note: The CEE2F2 feedback code can also be obtained by MVS/JES batch applications. For example, either the z/OS Debugger environment was corrupted or the debug event handler could not be loaded.

Language Environment® provides a callable service called CEEDCOD to help you decode the fields in the feedback code. Requesting the return of the feedback code is recommended.

For C and C++ and COBOL, if z/OS Debugger was started through CALL CEETEST, the GOTO command is only allowed after z/OS Debugger has returned control to your program via STEP or GO.