To debug programs that have been assembled with debug information, you can use most of the Debug Tool commands. Any exceptions are noted in Debug Tool Reference and Messages. Before debugging an assembler program, prepare your program as described in Preparing an assembler program.
The SET ASSEMBLER ON and SET DISASSEMBLY ON commands enable some of the same functions. However, you must consider which type of CUs that you will be debugging (assembler, disassembly, or both) before deciding which command to use. The following guidelines can help you decide which command to use:
If you are debugging an assembler CU and later decide you want to debug a disassembly CU, you can enter the SET DISASSEMBLY ON command after you enter the SET ASSEMBLER ON command.
Use the LOADDEBUGDATA (or LDD) command to indicate to Debug Tool that a compile unit is an assembler compile unit and to load the debug information associated with that compile unit. The LDD command can be issued only for compile units which have no debug information and are, therefore, considered disassembly compile units. In the following example, mypgm is the compile unit (CSECT) name of an assembler program:
LDD mypgm
Debug Tool locates the debug information in a data set with the following name: yourid.EQALANGX(mypgm). If Debug Tool finds this data set, you can begin to debug your assembler program. Otherwise, enter the SET SOURCE or SET DEFAULT LISTINGS command to indicate to Debug Tool where to find the debug information. In remote debug mode, the remote debugger prompts you for the data set information when the program is stepped into.
Normally, compile units without debug information are not listed when you enter the DESCRIBE CUS or LIST NAMES CUS commands. To include these compile units, enter the SET ASSEMBLER ON command. The next time you enter the DESCRIBE CUS or LIST NAMES CUS command, these compile units are listed.
The Debug Tool session panel below shows the information displayed in the Source window while you debug an assembler program.
Assemble LOCATION: PUBS :> 34.1 Command ===> Scroll ===> CSR MONITOR --+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+---10----+--- LINE: 0 OF 0 ******************************************************* TOP OF MONITOR ******************************************************** ****************************************************** BOTTOM OF MONITOR ****************************************************** SOURCE: PUBS +----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+---10-- LINE: 60 OF 513 1 34 2 3 * 7 . 34 00000078 OPENIT EQU * . 34 00000078 + OPEN ((2),INPUT) . 34 4 + CNOP 0,4 ALIGN LIST TO FULLWORD . 34 00000078 4510 B080 + BAL 1,*+8 LOAD REG1 W/LIST ADDR. @L2A . 35 0000007C + DC A(0) OPT BYTE AND DCB ADDR. . 36 00000080 5021 0000 + ST 2,0(1,0) STORE INTO LIST @L1C. . 37 00000084 9280 1000 + MVI 0(1),128 MOVE IN OPTION BYTE . 38 00000088 0A13 + SVC 19 ISSUE OPEN SVC . 39 5 6 CALL CEEMOUT,(STRING,DEST,0),VL Omitted feedback code . 39 + SYSSTATE TEST @L3A . 39 + CNOP 0,4 . LOG 0----+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8----+----9----+---10----+---1 LINE: 1 OF 9 ********************************************************* TOP OF LOG ********************************************************** 0001 IBM Debug Tool Version 9 Release 1 Mod 0 0002 10/30/2008 4:11:41 PM 0003 5655-U27: Copyright IBM Corp. 1992, 2008 0004 EQA1872E An error occurred while opening file: INSPPREF. The file may not exist, or is not accessible. 0005 Source or Listing data is not available, or the CU was not compiled with the correct compile options. 0006 LDD PUBS ; 0007 SET DEFAULT SCROLL CSR ; 0008 AT 34 ; 0009 GO ; ******************************************************** BOTTOM OF LOG ******************************************************** PF 1:? 2:STEP 3:QUIT 4:LIST 5:FIND 6:AT/CLEAR PF 7:UP 8:DOWN 9:GO 10:ZOOM 11:ZOOM LOG 12:RETRIEVE
The information displayed in the Source window is similar to the listing generated by the assembler. The Source window displays the following information:
The same statement number can sometimes be assigned to more than one line. Comments, labels and macro invocations are assigned the same statement number as the machine instruction that follows these statements. All of these statements have the same offset within the CSECT, which allows you to put the cursor on any of these lines and press PF6 to set a breakpoint. When the statement is reached, the focus is set on the first line within the statement that contains either a macro invocation or a machine instruction.
Refer to the following topics for more information related to the material discussed in this topic.
This table shows the possible values for the Debug Tool %PATHCODE variable when the current programming language is Assembler:
| %PATHCODE | Entry type | Instruction | Additional requirements or comments |
|---|---|---|---|
| 1 | A block has been entered. | Any | External symbol whose offset corresponds to an instruction |
| 2 | A block is about to be exited. |
BR R14 (07FE) |
|
BALR R14,R15 (05EF) |
These instructions are considered an Exit only if this instruction is not followed by an valid instruction. | ||
BASR R14,R15 (0DEF) |
|||
BASSM R14,R15 (0CEF) |
|||
BCR 15,x (07Fx) |
|||
| 3 | Control has reached a label coded in the program. | Any | Label whose offset corresponds to an instruction. |
| 4 | Control is being transferred as a result of a CALL. |
BALR R14,R15 (05EF) |
|
BASR R14,R15 (0DEF) |
|||
BASSM R14,R15 (0CEF) |
|||
| SVC (0A) | |||
| PC (B218) | |||
| BAL (45) | Except BAL 1,xxx is not considered a CALL | ||
| BAS (4D) | |||
BALR x,y (05) |
|||
BASR x,y (0D) |
|||
BASSM x,y (0C) |
|||
| BRAS (A7x5) | |||
| BRASL (C0x5) | |||
| 5 | Control is returning from a CALL. | Statement after CALL | If the statement after a CALL is an instruction, it gets an entry here. |
| 6 | A conditional branch is about to be executed. | BC x (47x) | x^=15 & X^=0 |
| BCR x (07x) | x^=15 & X^=0 | ||
| BCT (46) | |||
| BCTR (06) | |||
| BCTGR (B946) | |||
| BXH (86) | |||
| BXHG (EB44) | |||
| BXLE (87) | |||
| BXLEG (EB45) | |||
| BRC x (A7x4) | x^=15 & X^=0 | ||
| BRCL (C0x4) | |||
| BRCT (A7x6) | |||
| BRCTG (A7x7) | |||
| BRXH (84) | |||
| BRXHG (EC44) | |||
| BRXLE (85) | |||
| BRXLG (EC45) | |||
| 7 | A conditional branch was not executed and control has "fallen-through" to the next instruction. | Statement after Conditional Branch | |
| 8 | An unconditional branch is about to be executed. |
BC 15,x (47Fx) |
|
BRC 15,x (A7F4) |
|||
BRCL 15,x (C0F4) |
|||
| BSM (0B) |
The information displayed in the Source window for an assembler program can be viewed in either of two views. The STANDARD view shows all lines in the assembler listing including lines generated through macro expansion. The NOMACGEN view omits lines generated by macro expansion and, therefore, is similar to the assembler listing generated when PRINT NOGEN is in effect.
You can use the following commands to control the view that you see in the Source window for an assembler program:
When you debug assembler programs the following general restrictions apply:
When you debug a Language Environment-enabled assembler main program, the following restrictions apply:
The following restrictions apply when you attempt to set explicit or implicit breakpoints in the prologue of a Language Environment assembler program:
If you specify the TEST run-time option with the NOPROMPT suboption when you start your program and Debug Tool is subsequently started by CALL CEETEST or the raising of an Language Environment condition, you can debug both Language Environment and non-Language Environment programs and detect both Language Environment and non-Language Environment events in the enclave that started Debug Tool and in subsequent enclaves. You cannot debug non-Language Environment programs or detect non-Language Environment events in higher-level enclaves. After control has returned from the enclave in which Debug Tool was started, you can no longer debug non-Language Environment programs or detect non-Language Environment events.
Debug Tool cannot debug code that uses instructions as data. If your program references one or more instructions as data, the result can be unpredictable, including an abnormal termination (ABEND) of Debug Tool. This is because Debug Tool sometimes replaces instructions with SVCs in order to create breakpoints.
For example, Debug Tool cannot process the following code correctly:
Entry1 BRAS 15,0
NOPR 0
B Common
Entry2 BRAS 15,0
NOPR 4
Common DS 0H
IC 15,1(15)
In this code, the IC is used to examine the second byte of the NOPR instructions. However, if the NOPR instructions are replaced by an SVC to create a breakpoint, a value that is neither 0 nor 4 might be obtained, which causes unexpected results in the user program.
You can use the following coding techniques can be used to eliminate this problem:
Using Method 1, you can change the above example to the following code:
Entry1 BAL 15,*+L'*+2
DC H'0'
B Common
Entry2 BAL 15,*+L'*+2
DC H'4'
Common DS 0H
IC 15,1(15)
Using Method 2, you can change the above example to the following code:
Entry1 BRAS 15,0
DC X'0700'
B Common
Entry2 BRAS 15,0
DC X'0704'
Common DS 0H
IC 15,1(15)
Debug Tool defines two types of self-modifying code: detectable and non-detectable. Detectable self-modifying code is code that either:
Inst1 NOP Label1
MVI Inst1+1,X'F0' EQAModIn Inst1
Inst1 NOP Label1
LA R3,Inst1
MVI 0(R3),X'F0'Any self-modifying code that does not meet one of these criteria is classified as non-detectable.
When Debug Tool identifies detectable, self-modifying code, it indicates the situation in the Source window by putting an "X" in the column immediately before the column indicating a macro-generated instruction. A breakpoint cannot be set on such an instruction nor will STEP stop on such an instruction.
The EQAMODIN macro in shipped in the Debug Tool sample library (hlq.SEQASAMP). This macro can be used to make non-detectable, self-modifying code detectable. It generates no executable code. Instead it simply adds information to the SYSADATA file to identify the specified operand as modified. The operand can be specified either as a label name or as "*" to indicate that the immediately following instruction is modified.
If your program contains non-detectable, self-modifying code that modifies an instruction while the containing compilation unit is being debugged, the result can be unpredictable, including an abnormal termination (ABEND) of Debug Tool. If your program contains self-modifying code that completely replaces an instruction while the containing compilation unit is being debugged, the result might not be an ABEND. However, Debug Tool might miss a breakpoint on that instruction or display a message indicating an invalid hook address at delete.
The following coding techniques can be used to minimize problems debugging non-detectable, self-modifying code:
| Coding that modifies an instructions | Coding that replaces an instruction |
|---|---|
ModInst BC 0,Target ... MVI ModInst+1,X'F0' |
ModInst BC 0,Target ... MVC ModInst(4),NewInst ... NewInst BC 15,Target |