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.
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++

For COBOL

For PL/I

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 (;).
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.
The following examples show how to use the Language Environment callable service CEETEST to start Debug Tool from C or C++ programs.
#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);
}
#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);
·
·
·
}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);
}
}
The following examples show how to use the Language Environment callable service CEETEST to start Debug Tool from COBOL programs.
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.
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.
The following examples show how to use the Language Environment callable service CEETEST to start Debug Tool from PL/I programs.
CALL CEETEST(*,*); /* omit arguments */
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);
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.
%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);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:

The following examples show how to use PLITEST to start Debug Tool for PL/I.
CALL PLITEST;
CALL PLITEST('At statement 23 Do; List X; End; Go; List Y;');
DCL ch Char(45) Init('At Statement 23 Do; List x; End;');
CALL PLITEST(ch);
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.
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:

The following examples show how to use the __ctest() function for C and C++.
__ctest(NULL);
__ctest("at line 23 {"
" list x;"
" list y;"
"}"
"go;"
"list z;");
char *ch = "at line 23 list x;";
·
·
·
__ctest(ch);
#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));