The topics below describe how to use Debug Tool to debug your PL/I programs.
Refer to the following topics for more information related to the material discussed in this topic.
The table below lists the Debug Tool interpretive subset of PL/I commands. This subset is a list of commands recognized by Debug Tool that either closely resemble or duplicate the syntax and action of the corresponding PL/I command. This subset of commands is valid only when the current programming language is PL/I.
| Command | Description |
|---|---|
| Assignment | Scalar and vector assignment |
| BEGIN | Composite command grouping |
| CALL | Debug Tool procedure call |
| DECLARE or DCL | Declaration of session variables |
| DO | Iterative looping and composite command grouping |
| IF | Conditional execution |
| ON | Define an exception handler |
| SELECT | Conditional execution |
PL/I statements are entered as Debug Tool commands. Debug Tool makes it possible to issue commands in a manner similar to each language.
The following types of Debug Tool commands will support the syntax of the PL/I statements:
These commands provide a means of grouping any number of Debug Tool commands into "one" command.
These commands evaluate an expression and control the flow of execution of Debug Tool commands according to the resulting value.
These commands provide a means for declaring session variables.
These commands provide a means to program an iterative or conditional loop as a Debug Tool command.
These commands provide a means to unconditionally alter the flow of execution of a group of commands.
The table below shows the commands that are new or changed for this release of Debug Tool when the current programming language is PL/I.
| Command | Description or changes |
|---|---|
| ANALYZE | Displays the PL/I style of evaluating an expression, and the precision and scale of the final and intermediate results. Debug Tool does not support this command for Enterprise PL/I programs. |
| ON | Performs as the AT OCCURRENCE command except it takes PL/I conditions as operands. |
| BEGIN | BEGIN/END blocks of logic. |
| DECLARE | Session variables can now include COMPLEX (CPLX), POINTER, BIT, BASED, ALIGNED, UNALIGNED, etc. Arrays can be declared to have upper and lower bounds. Variables can have precisions and scales. You cannot declare arrays and structures when you debug Enterprise PL/I programs. |
| DO | The three forms of DO are
added; one is an extension of C’s do.
|
| IF | The IF / ELSE does not require the ENDIF. |
| SELECT | The SELECT / WHEN / OTHERWISE / END programming structure is added. |
The table below shows the possible values for the Debug Tool variable %PATHCODE when the current programming language is PL/I.
| 0 | An attention interrupt occurred. |
| 1 | A block has been entered. |
| 2 | A block is about to be exited. |
| 3 | Control has reached a label constant. |
| 4 | Control is being sent somewhere else as the result of a CALL or a function reference. |
| 5 | Control is returning from a CALL invocation or a function reference. Register 15, if it contains a return code, has not yet been stored. |
| 6 | Some logic contained in a complex DO statement is about to be executed. |
| 7 | The logic following an IF..THEN is about to be executed. |
| 8 | The logic following an ELSE is about to be executed. |
| 9 | The logic following a WHEN within a select-group is about to be executed. |
| 10 | The logic following an OTHERWISE within a select-group is about to be executed. |
All PL/I conditions are recognized by Debug Tool. They are used with the AT OCCURRENCE and ON commands.
When an OCCURRENCE breakpoint is triggered, the Debug Tool %CONDITION variable holds the following values:
| Triggered condition | %CONDITION value |
|---|---|
| AREA | AREA |
| ATTENTION | CEE35J |
| COND ( CC#1 ) | CONDITION |
| CONVERSION | CONVERSION |
| ENDFILE ( MF ) | ENDFILE |
| ENDPAGE ( MF ) | ENDPAGE |
| ERROR | ERROR |
| FINISH | CEE066 |
| FOFL | CEE348 |
| KEY ( MF ) | KEY |
| NAME ( MF ) | NAME |
| OVERFLOW | CEE34C |
| PENDING ( MF ) | PENDING |
| RECORD ( MF ) | RECORD |
| SIZE | SIZE |
| STRG | STRINGRANGE |
| STRINGSIZE | STRINGSIZE |
| SUBRG | SUBSCRIPTRANGE |
| TRANSMIT ( MF ) | TRANSMIT |
| UNDEFINEDFILE ( MF ) | UNDEFINEDFILE |
| UNDERFLOW | CEE34D |
| ZERODIVIDE | CEE349 |
These PL/I language-oriented commands are only a subset of all the commands that are supported by Debug Tool.
Statements can be entered in PL/I’s DBCS freeform. This means that statements can freely use shift codes provided that the statement is not ambiguous.
This will change the description or characteristics of LIST NAMES in that:
LIST NAMES db<.c.skk.w>ord
will search for
<.D.B.C.Skk.W.O.R.D>
This will result in different behavior depending upon the language. For example, the following will find a<kk>b in C and <.Akk.b> in PL/I.
LIST NAMES a<kk>*
where <kk> is shiftout-kanji-shiftin.
Freeform will be added to the parser and will be in effect while the current programming language is PL/I.
With the run-time option, TEST(ERROR, ...) only the following can initialize Debug Tool:
LIST STORAGE address has been enhanced so that the address can be a POINTER, a Px constant, or the ADDR built-in function.
PL/I will support all Debug Tool scalar session variables. In addition, arrays and structures can be declared.
Refer to the following topics for more information related to the material discussed in this topic.
Debug Tool obtains information about a program variable by name using information that is contained in the symbol table built by the compiler. The symbol table is made available to the compiler by compiling with TEST(SYM).
Debug Tool uses the symbol table to obtain information about program variables, controlled variables, automatic variables, and program control constants such as file and entry constants and also CONDITION condition names. Based variables, controlled variables, automatic variables and parameters can be used with Debug Tool only after storage has been allocated for them in the program. An exception to this is DESCRIBE ATTRIBUTES, which can be used to display attributes of a variable.
Variables that are based on any of the following data types must be explicitly qualified when used in expressions:
For example, assume you made the following declaration:
DECLARE P1 POINTER; DECLARE P2 POINTER BASED(P1); DECLARE DX FIXED BIN(31) BASED(P2);
You would not be able to reference the variable directly by name. You can only reference it by specifying either:
P2->DX or P1->P2->DX
The following types of program variables cannot be used with Debug Tool:
Refer to the following topics for more information related to the material discussed in this topic.
You cannot reference elements of arrays of structures. For example, suppose a structure called PAYROLL is declared as follows:
Declare 1 Payroll(100),
2 Name,
4 Last char(20),
4 First char(15),
2 Hours,
4 Regular Fixed Decimal(5,2),
4 Overtime Fixed Decimal(5,2);
Given the way PAYROLL is declared, the following examples of commands are valid in Debug Tool:
LIST ( PAYROLL(1).NAME.LAST, PAYROLL(1).HOURS.REGULAR ); LIST ( ADDR ( PAYROLL) ) ; LIST STORAGE ( PAYROLL.HOURS, 128 );
Given the way PAYROLL is declared, the following examples of commands are invalid in Debug Tool:
LIST ( PAYROLL(1) ); LIST (ADDR ( PAYROLL(5) ) ); LIST STORAGE ( PAYROLL(15).HOURS, 128 ) );
Debug Tool does not support debugging of PL/I typed structures. Declaring a variable as TYPE X, where X comes from a DEFINE STRUCTURE, makes it a typed structure.
When the current programming language is PL/I, expression interpretation is similar to that defined in the PL/I language, except for the PL/I language elements not supported in Debug Tool.
The Debug Tool expression is similar to the PL/I expression. If the source of the command is a variable-length record source (such as your terminal) and if the expression extends across more than one line, a continuation character (an SBCS hyphen) must be specified at the end of all but the last line.
All PL/I constant types are supported, plus the Debug Tool PX constant.
Refer to the following topics for more information related to the material discussed in this topic.
Debug Tool supports the following built-in functions for PL/I for MVS & VM:
|
ABS ACOS ADDR ALL ALLOCATION ANY ASIN ATAN ATAND ATANH BINARYVALUE BINVALUE1 BIT BOOL CHAR COMPLETION COS COSD COSH COUNT |
CSTG2 CURRENTSTORAGE DATAFIELD DATE DATETIME DIM EMPTY ENTRYADDR ERF ERFC EXP GRAPHIC HBOUND HEX HIGH IMAG LBOUND LENGTH LINENO LOG |
LOG1 LOG2 LOW MPSTR NULL OFFSET ONCHAR ONCODE ONCOUNT ONFILE ONKEY ONLOC ONSOURCE PLIRETV POINTER POINTERADD POINTERVALUE PTRADD3 PTRVALUE4 |
REAL REPEAT SAMEKEY SIN SIND SINH SQRT STATUS STORAGE STRING SUBSTR SYSNULL TAN TAND TANH TIME TRANSLATE UNSPEC VERIFY |
Debug Tool supports the following built-in functions for Enterprise PL/I:
|
ACOS ADDR ALLOCATION3 ASIN ATAN ATAND ATANH BIF_DIM BINARYVALUE BINVALUE COPY1 COS COSD COSH COUNT DATAFIELD DATE1 DATETIME1 DIMENSION ENDFILE ENTRYADDR1,2 ERF ERFC EXP FILEOPEN GAMMA HBOUND HEX |
HEXIMAGE HIGH1 IAND IEOR IOR INDEX INOT ISRL ISLL LBOUND LENGTH LINENO LOG LOG10 LOG2 LOGGAMMA LOW1 LOWER2 LOWERCASE1 MAXLENGTH NULL OFFSET OFFSETADD OFFSETSUBTRACT OFFSETDIFF |
OFFSETVALUE ORDINALNAME ORDINALPRED ORDINALSUCC ONCODE ONCONDCOND ONCHAR ONGSOURCE ONSOURCE ONCONDID ONCOUNT ONFILE ONKEY ONLOC PAGENO POINTER PTR POINTERADD PTRADD POINTERSUBTRACT PTRSUBTRACT |
POINTERDIFF PTRDIFF POINTERVALUE PTRVALUE PLIRETV RAISE2 REPEAT1 SAMEKEY SEARCH SEARCHR SIN SIND SINH SQRT SUBSTR1 SYSNULL TAN TAND TANH TALLY TIME1 TRANSLATE1 UNSPEC1 UPPERCASE1 VERIFY VERIFYR |
Debug Tool does not support the following built-in functions for Enterprise PL/I:
|
ABS ALL ANY BIT BOOL CHAR COMPLETION CSTG(2) CURRENTSTORAGE |
EMPTY GRAPHIC IMAG MPSTR REAL STATUS STORAGE STRING |
Refer to the following topics for more information related to the material discussed in this topic.
Certain checks are performed when the Debug Tool SET WARNING command setting is ON and a built-in function (BIF) is evaluated:
These checks are restrictions that can be removed by issuing SET WARNING OFF.
The following list summarizes PL/I functions not available:
There are restrictions on how you can debug OS PL/I programs, which are described in Using CODE/370 with VS COBOL II and OS PL/I, SC09-1862-01.
The OS PL/I compiler does not place the name of the listing data set in the object (load module). Debug Tool tries to find the listing data set in the following location: userid.CUName.LIST. If the listing is in a PDS, direct Debug Tool to the location of the PDS in one of the following ways:
SET DEFAULT LISTINGS my.listing.pds
While debugging Enterprise PL/I programs, you cannot use the following commands:
While debugging Enterprise PL/I programs, the following restrictions apply: