Rational Developer for System z, Version 7.6

Starting Debug Tool from a program

The instructions in this section apply to programs that run in Language Environment. For programs that do not run in Language Environment, refer to the instructions in Starting Debug Tool for programs that start outside of Language Environment.

Debug Tool can also be started directly from within your program using one of the following methods:

However, you cannot use these methods in DB2® stored procedures with the PROGRAM TYPE of SUB.

If you use these methods to start Debug Tool, you can debug non-Language Environment programs and detect non-Language Environment events only in the enclave in which Debug Tool first appeared and in subsequent enclaves. You cannot debug non-Language Environment programs or detect non-Language Environment events in higher-level enclaves.

To start Debug Tool using these alternatives, you still need to be aware of the TEST suboptions specified using NOTEST, CEEUOPT, or other "indirect" settings.

Refer to the following topics for more information related to the material discussed in this topic.

Starting Debug Tool with CEETEST

Using CEETEST, you can start Debug Tool from within your program and send it a string of commands. If no command string is specified, or the command string is insufficient, Debug Tool 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 Debug Tool 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 Debug Tool 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++

Syntax diagram for the C and C++ CEETEST compiler option

For COBOL

Syntax diagram for the COBOL CEETEST compiler option

For PL/I

Syntax diagram for the PL/I CEETEST compiler option
string_of_commands (input)
Halfword-length prefixed string containing a Debug Tool command list. The command string string_of_commands is optional.

If Debug Tool is available, the commands in the list are passed to the debugger and carried out.

If string_of_commands is omitted, Debug Tool prompts for commands in interactive mode.

For Debug Tool, 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 Debug Tool in one of the following debug modes:

To indicate that you want to start Debug Tool in full-screen mode through a VTAM terminal without the Debug Tool Terminal Interface Manager, specify the MFI suboption of the TEST runtime option with the LU name of the VTAM® 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 Debug Tool in full-screen mode through a VTAM terminal with the Debug Tool 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 Debug Tool 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 Debug Tool in remote debug mode, specify the TCPIP suboption of the TEST runtime option with the IP address and port number that the remote debugger is listening to:

For example, you can code the following call in your PL/I program:

Call CEETEST('TCPIP&your.company.com%8001:*;',*);

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 Debug Tool 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 Debug Tool was started through CALL CEETEST, the GOTO command is only allowed after Debug Tool has returned control to your program via STEP or GO.

Additional notes about starting Debug Tool with CEETEST

C and C++
Include leawi.h header file.
COBOL
Include CEEIGZCT. CEEIGZCT is in the Language Environment SCEESAMP data set.
PL/I
Include CEEIBMAW and CEEIBMCT. CEEIBMAW is in the Language Environment SCEESAMP data set.
Batch and CICS nonterminal processes
We strongly recommend that you use feedback codes (fc) when using CEETEST to initiate Debug Tool from a batch process or a CICS nonterminal task; otherwise, results are unpredictable.

Example: using CEETEST to start Debug Tool from C/C++

The following examples show how to use the Language Environment callable service CEETEST to start Debug Tool from C or C++ programs.

Example 1
In this example, an empty command string is passed to Debug Tool and a pointer to the Language Environment feedback code is returned. If no other TEST run-time options have been compiled into the program, the call to CEETEST starts Debug Tool with all defaults in effect. After it gains control, Debug Tool prompts you for commands.
#include <leawi.h>
#include <string.h>
#include <stdio.h>

int main(void) {
  _VSTRING  commands;
  _FEEDBACK fc;

  strcpy(commands.string, "");
  commands.length = strlen(commands.string);

  CEETEST(&commands, &fc);

}
Example 2
In this example, a string of valid Debug Tool commands is passed to Debug Tool and a pointer to Language Environment feedback code is returned. The call to CEETEST starts Debug Tool and the command string is processed. At statement 23, the values of x and y are displayed in the Log, and execution of the program resumes. Barring further interrupts, the behavior at program termination depends on whether you have set AT TERMINATION: The command LIST(z) is discarded when the command GO is executed.
Note:
If you include a STEP or GO in your command string, all commands after that are not processed. The command string operates like a commands file.
#include <leawi.h>
#include <string.h>
#include <stdio.h>

int main(void) {
  _VSTRING  commands;
  _FEEDBACK fc;

  strcpy(commands.string, "AT LINE 23; {LIST(x); LIST(y);} GO; LIST(z)");
  commands.length = strlen(commands.string);

  ·
  ·
  ·
CEETEST(&commands, &fc);
  ·
  ·
  ·
}
Example 3
In this example, a string of valid Debug Tool commands is passed to Debug Tool and a pointer to the feedback code is returned. If the call to CEETEST fails, an informational message is printed.

If the call to CEETEST succeeds, Debug Tool is started and the command string is processed. At statement 30, the values of x and y are displayed in the Log, and execution of the program resumes. Barring further interrupts, the behavior at program termination depends on whether you have set AT TERMINATION:

#include <leawi.h>
#include <string.h>
#include <stdio.h>

#define SUCCESS "\0\0\0\0"

int main (void) {

   int x,y,z;
   _VSTRING commands;
   _FEEDBACK fc;

   strcpy(commands.string,"AT LINE 30 { LIST(x); LIST(y); } GO;");
   commands.length = strlen(commands.string);

  ·
  ·
  ·
CEETEST(&commands,&fc);
  ·
  ·
  ·
if (memcmp(&fc,SUCCESS,4) != 0) { printf("CEETEST failed with message number %d\n",fc.tok_msgno); return(2999); } }

Example: using CEETEST to start Debug Tool from COBOL

The following examples show how to use the Language Environment callable service CEETEST to start Debug Tool from COBOL programs.

Example 1
A command string is passed to Debug Tool at its invocation and the feedback code is returned. After it gains control, Debug Tool becomes active and prompts you for commands or reads them from a commands file.
01  FC.
    02  CONDITION-TOKEN-VALUE.
    COPY CEEIGZCT.
        03  CASE-1-CONDITION-ID.
            04  SEVERITY    PIC S9(4) BINARY.
            04  MSG-NO      PIC S9(4) BINARY.
        03  CASE-2-CONDITION-ID
                  REDEFINES CASE-1-CONDITION-ID.
            04  CLASS-CODE  PIC S9(4) BINARY.
            04  CAUSE-CODE  PIC S9(4) BINARY.
        03  CASE-SEV-CTL    PIC X.
        03  FACILITY-ID     PIC XXX.
    02  I-S-INFO            PIC S9(9) BINARY.
77  Debugger                PIC x(7)  Value 'CEETEST'.

01  Parms.
    05  AA                  PIC S9(4) BINARY   Value 14.
    05  BB                  PIC x(14)   Value 'SET SCREEN ON;'.

CALL Debugger USING Parms FC.
Example 2
A string of commands is passed to Debug Tool when it is started. After it gains control, Debug Tool sets a breakpoint at statement 23, runs the LIST commands and returns control to the program by running the GO command. The command string is already defined and assigned to the variable COMMAND-STRING by the following declaration in the DATA DIVISION of your program:
01 COMMAND-STRING.
   05 AA     PIC 99    Value 60 USAGE IS COMPUTATIONAL.
   05 BB     PIC x(60) Value 'AT STATEMENT 23; LIST (x); LIST (y); GO;'.
The result of the call is returned in the feedback code, using a variable defined as:
01  FC.
    02  CONDITION-TOKEN-VALUE.
    COPY CEEIGZCT.
        03  CASE-1-CONDITION-ID.
            04  SEVERITY    PIC S9(4) BINARY.
            04  MSG-NO      PIC S9(4) BINARY.
        03  CASE-2-CONDITION-ID
                  REDEFINES CASE-1-CONDITION-ID.
            04  CLASS-CODE  PIC S9(4) BINARY.
            04  CAUSE-CODE  PIC S9(4) BINARY.
        03  CASE-SEV-CTL    PIC X.
        03  FACILITY-ID     PIC XXX.
    02  I-S-INFO            PIC S9(9) BINARY.
in the DATA DIVISION of your program. You are not prompted for commands.
CALL "CEETEST" USING COMMAND-STRING FC.

Example: using CEETEST to start Debug Tool from PL/I

The following examples show how to use the Language Environment callable service CEETEST to start Debug Tool from PL/I programs.

Example 1
No command string is passed to Debug Tool at its invocation and no feedback code is returned. After it gains control, Debug Tool becomes active and prompts you for commands or reads them from a commands file.
CALL  CEETEST(*,*);    /*  omit arguments   */
Example 2
A command string is passed to Debug Tool at its invocation and the feedback code is returned. After it gains control, Debug Tool becomes active and executes the command string. Barring any further interruptions, the program runs to completion, where Debug Tool prompts for further commands.
DCL   ch  char(50)
      init('AT STATEMENT 10 DO; LIST(x); LIST(y); END; GO;');

DCL   1  fb,
         5  Severity  Fixed bin(15),
         5  MsgNo     Fixed bin(15),
         5  flags,
            8  Case   bit(2),
            8  Sev    bit(3),
            8  Ctrl   bit(3),
         5  FacID     Char(3),
         5  I_S_info  Fixed bin(31);


DCL   CEETEST  ENTRY  ( CHAR(*)  VAR  OPTIONAL,
         1   optional ,
           254 real fixed bin(15),     /* MsgSev     */
           254 real fixed bin(15),     /* MSGNUM     */
           254                         /* Flags      */,
             255 bit(2),               /* Flags_Case     */
             255 bit(3),               /* Flags_Severity */
             255 bit(3),               /* Flags_Control  */
           254 char(3),                /* Facility_ID    */
           254 fixed bin(31) )         /* I_S_Info    */
                 options(assembler) ;

CALL  CEETEST(ch, fb);
Example 3
This example assumes that you use predefined function prototypes and macros by including CEEIBMAW, and predefined feedback code constants and macros by including CEEIBMCT.

A command string is passed to Debug Tool that sets a breakpoint on every tenth executed statement. Once a breakpoint is reached, Debug Tool displays the current location information and continues the execution. After the CEETEST call, the feedback code is checked for proper execution.

Note:
The feedback code returned is either CEE000 or CEE2F2. There is no way to check the result of the execution of the command passed.
%INCLUDE CEEIBMAW;
%INCLUDE CEEIBMCT;
DCL 01 FC FEEDBACK;

/* if CEEIBMCT is NOT included, the following DECLARES need to be
   provided:          ---------- comment start -------------

Declare CEEIBMCT  Character(8) Based;
Declare ADDR      Builtin;
%DCL FBCHECK ENTRY;
%FBCHECK:  PROC( fbtoken, condition ) RETURNS( CHAR );
   DECLARE
      fbtoken    CHAR;
      condition  CHAR;
RETURN('(ADDR('||fbtoken||')->CEEIBMCT = '||condition||')');
%END FBCHECK;
%ACT FBCHECK;
                      ---------- comment end --------------- */

Call CEETEST('AT Every 10 STATEMENT * Do; Q Loc; Go; End;'||
             'List AT;', FC);

If ¬FBCHECK(FC, CEE000)
   Then Put Skip List('----> ERROR! in CEETEST call', FC.MsgNo);

Starting Debug Tool with PLITEST

For PL/I programs, the preferred method of Starting Debug Tool is to use the built-in subroutine PLITEST. It can be used in exactly the same way as CEETEST, except that you do not need to include CEEIBMAW or CEEIBMCT, or perform declarations.

The syntax is:

Syntax diagram for the PL/I PLITEST built-in subroutine
character_string_expression
Specifies a list of Debug Tool commands. If necessary, this is converted to a fixed-length string.
Notes:
  1. If Debug Tool executes a command in a CALL PLITEST command string that causes control to return to the program (GO for example), any commands remaining to be executed in the command string are discarded.
  2. If you don't want to compile your program with hooks, you can use CALL PLITEST statements as hooks and insert them 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.

The following examples show how to use PLITEST to start Debug Tool for PL/I.

Example 1
No argument is passed to Debug Tool when it is started. After gaining control, Debug Tool prompts you for commands.
CALL PLITEST;
Example 2
A string of commands is passed to Debug Tool when it is started. After gaining control, Debug Tool sets a breakpoint at statement 23, and returns control to the program. You are not prompted for commands. In addition, the List Y; command is discarded because of the execution of the GO command.
CALL PLITEST('At statement 23 Do; List X; End; Go; List Y;');
Example 3
Variable ch is declared as a character string and initialized as a string of commands. The string of commands is passed to Debug Tool when it is started. After it runs the commands, Debug Tool prompts you for more commands.
DCL  ch   Char(45) Init('At Statement 23 Do; List x; End;');

CALL PLITEST(ch);

Starting Debug Tool with the __ctest() function

You can also use the C and C++ library routine __ctest() or ctest() to start Debug Tool. Add:

#include <ctest.h>

to your program to use the ctest() function.

Note:
If you do not include ctest.h in your source or if you compile using the option LANGLVL(ANSI), you must use __ctest() function. The __ctest() function is not supported in CICS.

When a list of commands is specified with __ctest(), Debug Tool runs the commands in that list. If you specify a null argument, Debug Tool gets commands by reading from the supplied commands file or by prompting you. If control returns to your application before all commands in the command list are run, the remainder of the command list is ignored. Debug Tool will continue reading from the specified commands file or prompt for more input.

If you do not want to compile your program with hooks, you can use __ctest() function calls to start Debug Tool 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 __ctest() when Debug Tool is already initialized results in a reentry that is similar to a breakpoint.

The syntax for this option is:

Syntax diagram for the C and C++ __ctest() function
char_str_exp
Specifies a list of Debug Tool commands.

The following examples show how to use the __ctest() function for C and C++.

Example 1
A null argument is passed to Debug Tool when it is started. After it gains control, Debug Tool prompts you for commands (or reads commands from the primary commands file, if specified).
__ctest(NULL);
Example 2
A string of commands is passed to Debug Tool when it is started. At statement 23, Debug Tool lists x and y, then returns control to the program. You are not prompted for commands. In this case, the command list z; is never executed because of the execution of the command GO.
__ctest("at line 23 {"
         "  list x;"
         "  list y;"
         "}"
         "go;"
         "list z;");
Example 3
Variable ch is declared as a pointer to character string and initialized as a string of commands. The string of commands is passed to Debug Tool when it is started. After it runs the string of commands, Debug Tool prompts you for more commands.
char *ch = "at line 23 list x;";

·
·
·
__ctest(ch);
Example 4
A string of commands is passed to Debug Tool when it is started. After Debug Tool gains control, you are not prompted for commands. Debug Tool runs the commands in the command string and returns control to the program by way of the GO command.
#include <stdio.h>
#include <string.h>

char *ch = "at line 23 printf(\"x.y is %d\n\", x.y); go;";
char buffer[35.132];

strcpy(buffer, "at change x.y;");

__ctest(strcat(buffer, ch));

Terms of use | Feedback

This information center is powered by Eclipse technology. (http://www.eclipse.org)