Rational Developer for System z, Version 7.6

Debugging an assembler program

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 and SET DISASSEMBLY commands

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.

Loading an assembler program's debug information

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.

Debug Tool session panel while debugging an assembler program

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:

 1  statement number
The statement number is a number assigned by the EQALANGX program. Use this column to set breakpoints and identify statements.

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.

 2 
An asterisk in the column preceding the offset indicates that the line is contained in a compile unit to which you are not currently qualified. Before you attempt to set a line or statement breakpoint on that a line, you must enter the SET QUALIFY CU compile_unit and specify the name of the containing compile unit for the compile_unit parameter.
 3  offset
The offset from the start of the CSECT. This column matches the left-most column in the assembler listing.
 4  object
The object code for instructions. This column matches the "Object Code" column in the assembler listing. Object code for data fields is not displayed.
 5  modified instruction
An "X" in this column indicates an executable instruction that is modified by the program at some point. You cannot set a breakpoint on such an instruction nor can you STEP into such an instruction.
 6  macro generated
A "+" in this column indicates that the line is generated by macro expansion. Lines generated by macro expansion appear only in the standard view. These lines are suppressed when the NOMACGEN view is in effect.
 7  source statement
The original source statement. This column corresponds to the "Source Statement" column in the assembler listing.

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

%PATHCODE values for assembler programs

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)

Using the STANDARD and NOMACGEN view

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:

Restrictions for debugging an assembler program

When you debug assembler programs the following general restrictions apply:

Restrictions for debugging a Language Environment assembler MAIN program

When you debug a Language Environment-enabled assembler main program, the following restrictions apply:

Restrictions on setting breakpoints in the prologue of Language Environment assembler programs

The following restrictions apply when you attempt to set explicit or implicit breakpoints in the prologue of a Language Environment assembler program:

Restrictions for debugging non-Language Environment programs

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.

Restrictions for debugging assembler code that uses instructions as data

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)

Restrictions for debugging self-modifying assembler code

Debug Tool defines two types of self-modifying code: detectable and non-detectable. Detectable self-modifying code is code that either:

Any self-modifying code that does not meet one of these criteria is classified as non-detectable.

Handling of detectable self-modifying assembler code

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.

Non-detectable self-modifying assembler code

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:


Terms of use | Feedback

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