Symbolically debugging HLASM applications using Rational Developer for System z and Debug Tool

This article describes how to symbolically debug Language Environment (LE) enabled High Level Assembler (HLASM) applications running on z/OS.

You should have some familiarity with Eclipse, Rational Developer for System z V7.1.1, and High Level Assembler. For links to more information on these products, see Resources. You also need a rudimentary understanding of Job Control Language (JCL) and JCL Procedures.

This article describes how an application programmer can write an assembler program, build the executable, and symbolically debug the assembler application using Rational Developer for System z and Debug Tool V8.1. When symbolically debugging the assembler application, you can view and change the values of the variables within the assembler application using the names of the variables, animate the step-by-step execution of the assembler routine while viewing the assembler listing file, and establish breakpoints within the assembler listing file.

Share:

Laurence England (englandl@us.ibm.com), Senior Technical Staff Member, IBM

Laurence England photoLaurence (Larry) England is a Senior Technical Staff Member at IBM's Silicon Valley Lab in San Jose, California. He has architectural responsibilities for application development tools on System z. When not working at IBM, he can be found running a trail in the California hills.



Vikram Manchala (mailto:vikramm@us.ibm.com), Software Engineer, IBM

Vikram Manchala photoVikram Manchala is a developer in the Debug Tool team responsible for the integration of Rational Developer for System z and Debug Tool.



09 January 2008

Also available in Russian

Introduction

IBM Rational Developer for System z V7.1 (hereafter called Developer for z) provides an Eclipse-based Integrated Development Environment (IDE) that you can use to access applications and resources directly on z/OS. You use the Debugging perspective in Developer for z to leverage Debug Tool for z/OS V8.1 and the Debug Tool Utilities and Advanced Functions V8.1.

Debug Tool and Debug Tool Utilities and Advanced Functions are complimentary products which enable symbolic debugging of COBOL, PL/I, C, C++, and High Level Assembler (HLASM) code. The symbolic information that is made available in the debugging perspective includes entry point names, variable names, labels, and registers including general purpose registers as well as floating point registers.

To support the symbolic information of HLASM applications, Debug Tool Utilities and Advanced Functions supplies a utility to create metadata for the LE-enabled HLASM application needed during the debug session. You do not need to understand the format of the metadata information to enable symbolic debugging of HLASM applications. This article shows you how to implement symbolic HLASM debugging. A simple HLASM application, available as a download, is used to demonstrate these capabilities.

This article assumes you have a valid userid on the z/OS system where you will be running your HLASM application and have properly configured Developer for z to communicate with that z/OS system. For additional information on Developer for z, including how to establish connectivity to a z/OS system, please see IBM Enterprise Modernization Demos in Resources.

After you configure Developer for z to access your z/OS system and authenticate using your userid and password, the Remote Systems view should look similar to this:

Figure 1. Remote Systems view with authentication configured
Remote Systems view with autentication configured

Overview of steps

To symbolically debug an LE-enabled HLASM application using Developer for z you follow these steps, which are described in more detail in the rest of this article:

  1. Customize the JCL Proc that includes the step to create the Debug Tool metadata.
  2. Create an MVS project and subproject, specifying the JCL Proc and the appropriate properties for the JCL Proc.
  3. Create the assembler routine.
  4. Build the application.
  5. Run the application in Debug Mode.
  6. Enable the use of the symbolic information within your HLASM applications.

Customize the ELAXFADT JCL Proc

To debug LE-enabled HLASM applications, you first need to create a file containing metadata. This metadata file contains specially-formatted Debug Tool information with the symbols used in the assembler application. This metadata file is known as an IDILANGX or an EQALANGX file, and it should be a PDS with RECFM= VB, LRECL=1562.

You can use the utility (provided by Debug Tool Utilities and Advanced Functions) to create the IDILANGX file from the assembler ADATA. To invoke the EQALANGX debug utility, use the ELAXFADT JCL Procedure (shown in Listing 1), which is provided by Developer for z and installed by your system programmer.

Listing 1. ELAXFADT JCL Procedure to assemble HLASM source and create metadata debugging information
//ASMDEBUG PROC  LNGPRFX='D94PP.HLASM'                                          
//ASM EXEC PGM=ASMA90,REGION=2048K,                                             
//             PARM=('TEST',                                                    
//             'ADATA',  
//             'SYSPARM(MVS)',  
//             'LIST')                                                          
//STEPLIB DD DSN=&LNGPRFX..LINKLIB,DISP=SHR                                     
//SYSPRINT DD SYSOUT=*                                                          
//SYSLIN   DD  DUMMY                                                            
//SYSUT1   DD  UNIT=SYSALLDA,SPACE=(CYL,(1,1))                                  
//SYSUT2   DD  UNIT=SYSALLDA,SPACE=(CYL,(1,1))                                  
//SYSUT3   DD  UNIT=SYSALLDA,SPACE=(CYL,(1,1))                                  
//SYSUT4   DD  UNIT=SYSALLDA,SPACE=(CYL,(1,1))                                  
//SYSUT5   DD  UNIT=SYSALLDA,SPACE=(CYL,(1,1))                                  
//SYSUT6   DD  UNIT=SYSALLDA,SPACE=(CYL,(1,1))                                  
//SYSUT7   DD  UNIT=SYSALLDA,SPACE=(CYL,(1,1))                                  
//*                                                                             
//SYSTERM  DD SYSOUT=*                                                          
//SYSADATA DD DSNAME=&ADATADS(&MEM),DISP=SHR                                    
//XTRACT  EXEC PGM=EQALANGX,REGION=32M,                                         
//   PARM='&MEM (ASM ERROR OFT IDILANGX FAULT'                                  
//SYSADATA DD DSNAME=&ADATADS(&MEM),DISP=SHR                                    
//IDILANGX DD DSNAME=&LANGXDS(&MEM),DISP=SHR

Your system programmer might need to tailor the JCL Proc to your z/OS environment. For example, you might need to update LNGPREX to match your installation. Make sure the parameters used by the assembler, such as ADATA and TEST, are correct.

Substitution variables used by the JCL Proc are:

  • ADATADS – Specifies the ADATA dataset that will contain the HLASM ADATA information. The JCL Proc assumes this dataset has been allocated and is a PDS/E with RECFM=VB and LRECL=8188.
  • LANGXDS – Specifies the dataset that will contain the Debug Tool formatted metadata needed during debug time. The JCL Proc also assumes this dataset has been allocated and is a PDS/E with RECFM=VB and LRECL=1562. By default, the dataset name is in the form <userid>.EQALANGX. If you choose to specify a dataset with a different name format, you will need to allocate the DDNAME EQADEBUG to reference the EQALANGX PDS/E during the debugging session.
  • MEM – The member name for the ADATA and EQALANGX datasets.

Create a project and subproject

In Developer for z:

  1. Create a project and sub-project. In the example, the project name and the subproject name are PLEX4Bhlasm and HLASMDebug, respectively.
  2. Set the Assembler properties for to use the ELAXFADT JCL proc, and set the JCL Proc substitution variables as appropriate. To specify the JCL Proc, edit the ASM step and specify the JCL proc to create the debug metadata, ELAXFADT, as shown on the next page.
    Figure 2. Specify JCL proc to generate debug metadata
    Figure 2. Specify JCL proc to generate debug metadata
  3. On the Assembler Settings page, click the JCL Substitutions tab, and make sure you specify settings similar to the screenshot shown in Figure 3.

    Figure 3. Verify the JCL substitutions are set correctly
    Figure 3. Verify the JCL substitutions are set correctly

    Specifying MEM as a global variable of is very useful when there are multiple HLASM files in the project because the member name of the source file within the project is used as the substitution variable for each instance in the JCL Proc.

  4. Make sure that the Application Entry Point indicates this is a High Level Assembler entry point.
    Figure 4. Verify the application entry point is set correctly
    Figure 4. Verify the application entry point is set correctly

Create the assembler routine

Next you create the source application on z/OS. For example, to create the sample source on z/OS by using the Developer for z capabilities:

  1. Allocate a Partition Data Set. In the Remote Systems view, highlight MVS Files, right-click, and select Allocate PDS.
  2. In the wizard, provide a dataset name. The sample uses ENGLAND.SOURCE.ASSEMBLE. Make sure the dataset name you provide has a right-most qualifier of ASSEMBLE. Then, click Next.
  3. Select Specify characteristics by usage type, and then select SOURCE and ASM.
  4. Click Finish.
  5. After unzipping the assembler source file to your Microsoft® Windows® system, find the source. In the Remote Systems view under Local system, expand the tree, highlight the source file, right-click, and select Copy.
  6. To copy the assembler source file from your windows system to your z/OS system, still in the Remote System view, find the newly allocated PDS on your z/OS system, highlight it, right-click, and select Paste.
  7. Add the file to the subproject which has the properties you just defined. Expand the newly allocated PDS; look for the source file you just copy-and-pasted; highlight the PDS member; and drag-and-drop it from the Remote Systems view onto the subproject (HLASMDebug in the example).

Listing 2, available in the download, shows the sample source file.

Listing 2. Sample LE-enabled Assembler routine
DBGMAIN  CEEENTRY PPA=MAINPPA,AUTO=WORKSIZE,MAIN=YES                            
         USING    WORKAREA,R13                                           
*                                                                        
         LA     R2,STRT_MSG                                                
         LA     R3,DEST                                                    
         LA     R4,FBCODE                                                  
         STM  R2,R4,PLIST                                                
         LA     R1,PLIST                                                   
         L        R15,MOUT                                                   
         BALR R14,R15                                                    
*                                                                        
         PACK PCKA,ZNA                                                   
         PACK PCKB,ZNB                                                   
         PACK PCKC,ZNC                                                   
         ZAP    PCKSUM,PCKA                                                
         AP      PCKSUM,PCKB                                                
         AP      PCKSUM,PCKC                                                
         MVC  OUTSUM,SUMMSK                                              
         ED      OUTSUM,PCKSUM                                              
         MVC  SUMMSG+1(8),OUTSUM                                         
         MVC  LINE_ST,SUMMSG                                             
*                                                                        
         LA     R2,LINE_MSG                                                
         LA     R3,DEST                                                    
         LA     R4,FBCODE                                                  
         STM  R2,R4,PLIST                                                
         LA     R1,PLIST                                                    
         L        R15,MOUT                                                   
         BALR R14,R15                                                    
*                                                                        
         LA     R2,DONE_MSG                                                
         LA     R3,DEST                                                    
         LA     R4,FBCODE                                                  
         STM  R2,R4,PLIST                                                
         LA     R1,PLIST                                                   
         L        R15,MOUT                                                   
         BALR R14,R15                                                    
*                                                                        
         CEETERM  RC=0                                                   
* ==============================================================         
*  Constants and Variables                                               
* ==============================================================         
ZLEN     EQU 5                                                           
PLEN     EQU ZLEN/2+1                                                    
*                                                                        
SUMMSG   DC  C'(xxxxxxxx) -- The sum    '                                
SUMMSK   DC  X'4020202020202120'                                         
ZNA           DC  ZL5'100'                                                    
ZNB           DC  ZL5'150'                                                    
ZNC           DC  ZL5'50'                                                     
*                                                                        
PCKA        DS  PL(PLEN)                                                    
PCKB        DS  PL(PLEN)                                                    
PCKC        DS  PL(PLEN)                                                    
PCKSUM   DS  PL(PLEN+1)                                                  
OUTSUM   DS  CL(L'SUMMSK)                                                
*                                                                        
MOUT     DC     V(CEEMOUT)        The CEL Message service                
*                                                                        
LINE_MSG DS     0F                                                       
              DC     AL2(LINE_END-LINE_ST)
LINE_ST   DS       CL25                                                       
LINE_END EQU    *                                                        
*                                                                          
STRT_MSG DS     0F                                                       
                DC     AL2(STRT_END-STRT_ST) 
STRT_ST  DC       C'Starting the program.'                                 
STRT_END EQU    *                                                        
*                                                                        
DONE_MSG DS     0F                                                       
                DC     AL2(DONE_END-DONE_ST)
DONE_ST  DC       C'Terminating the program.'                              
DONE_END EQU    *                                                        
*                                                                        
DEST     DC     F'2'              The destination is the MSGFILE         
*                                                                        
MAINPPA  CEEPPA                                                          
* ===================================================================    
*  The Workarea and DSA                                                  
* ===================================================================    
WORKAREA DSECT                                                           
         ORG    *+CEEDSASZ                                               
PLIST    DS     0D                                                       
PARM1    DS     A                                                        
PARM2    DS     A                                                        
PARM3    DS     A                                                        
PARM4    DS     A                                                        
PARM5    DS     A                                                        
*                                                                       
FBCODE   DS     3F                                                       
*                                                                        
         DS         0D                                                       
WORKSIZE EQU    *-WORKAREA                                               
         CEEDSA                   Mapping of the Dynamic Save Area       
         CEECAA                   Mapping of the Common Anchor Area      
*                                                                        
R0       EQU   0                                                         
R1       EQU   1                                                         
R2       EQU   2                                                         
R3       EQU   3                                                         
R4       EQU   4                                                         
R5       EQU   5                                                         
R6       EQU   6                                                         
R7       EQU   7                                                         
R8       EQU   8                                                         
R9       EQU   9                                                         
R10     EQU   10                                                        
R11     EQU   11                                                        
R12     EQU   12                                                        
R13     EQU   13                                                        
R14     EQU   14                                                        
R15     EQU   15                                                        
           END   DBGMAIN            Nominate DBGMAIN as the entry point

Build the application

To build the application:

  1. Ensure all of the datasets you specified in the properties are allocated. These datasets are referenced in JCL that is generated for the build.
  2. Highlight the subproject name (HLASMDebug in the example), right-click, and then select the Rebuild Subproject action.
  3. Check the JES output in the Remote Systems view to verify that the application built correctly. Double-click on the job to open the JES output in the editor.
  4. Fix any errors you find in the JES output or in the Listing file.

If the application builds correctly, you see the dataset member of the load module in the project. In the example on the next page, the load module is ENGLAND.EXEC.LOAD(DBGMAIN).

Important: The file extension (.exe) is artificially added by the Developer for z user interface, and is not truly part of the name.

Figure 5.Project after successful build
Figure 5.Project after successful build

Run the application in Debug Mode

To run the application:

  1. In the sub-project, place focus on the executable load module, in our example, ENGLAND.EXEC.LOAD(DBGMAIN).exe.
  2. Right-click the module and then select the Debug Application action.
  3. The perspective switches to Debug Perspective. If prompted to accept the switch to the Debug Perspective, click Yes to accept the switch.

Enable the generated metadata

Finally, you enable the use of the symbolic information within your HLASM applications by running the LoadDebugData (ldd) command to use the generated Debug Tool metadata.

In the Debug Perspective, make sure that the Debug Console view is open. If not, to open this view:

  1. Use the Windows pull-down and selecting Show View.
  2. Select Other.
  3. Find the Debug Console view in the list and open it. The LoadDebugData command ( ldd) will load the metadata for this debug session.
  4. Type in the command ldd dbgmain, where dbgmain is the name of the EQALANGX member that was created during the build and also specified in the properties. It should look similar to the image below:
    Figure 6. Entering the ldd dbgmain command
    Figure 6. Entering the ldd dbgmain command

If you did not create the member in the <userid>.EQALANGX data set, then you should use the DDNAME EQADEBUG in the JCL to execute the HLASM application. To use this technique, set the properties for the runtime options as shown in Figure 7.

Figure 7. Set the runtime option properties
Figure 7. Set the runtime option properties

Now you can use the debugging actions to step through the source code, establish breakpoints, monitor variable values, view and alter registers (carefully!), and use other Debug Tool activities. The Developer for z window should look similar to Figure 8.

Figure 8. Ready for debugging
Figure 8. Ready for debugging
  1. Using the Step Into button in the Debug View (in the upper left), you can run the assembler application one instruction at a time.
  2. After you have stepped into the application, place the cursor over a variable name for a moment to display a popup containing its current value.
  3. Highlight a variable name and right-click it to select a number of different actions such as Monitor Memory. This is very helpful when the variable holds a machine address!

You can now debug your assembler application using the variable names you coded in your assembler source.

Hints and tips

To maximize the use of real estate on the Debug Perspective in Developer for z, you can move the Register tab to the area on the immediate right of the Listing View by dragging the tab on top of the Outline View. Then you can see the General Purpose Registers (GPRs) simultaneously with the Monitors or Breakpoints view.

Variables are not displayed in the Variables view; however, you can monitor variables by double-clicking on the variable of choice, right-clicking and then selecting the Monitor Expression action. This expression will display in the Monitors view. In the example below, the OUTSUM variable was selected for this action. The Monitors view will display the change in the state of the variable.

Figure 9. Changed variables in Monitors view
Figure 9. Changed variables in Monitors view

You can establish breakpoints by simply double-clicking on the left margin of the source file view on the line where you want the debugger to stop. In the screen capture below, a breakpoint has been established at line 58 of the HLASM source file.

Click the Resume action button Resume action button at the top of the window to run the application until the breakpoint is encountered; the system pauses and waits for further user action.

Figure 10. System pauses when it finds a breakpoint
Figure 10. System pauses when it finds a breakpoint

Finally, use the set automonitor on command in the Debug Console to display the relevant data items for the HLASM statement that will be executed for the next step command.

For the example below, the next HLASM statement to be executed in the source window is the STM assembler instruction:

Figure 11. Step through an application and examine relevant data
Figure 11. Step through an application and examine relevant data

The Monitors view shows the relevant data items. The STM will store general purpose registers 2, 3, and 4 at a displacement (X’80’) off register 13. In addition, the label PLIST value is displayed.

Figure 12. Examine register data
Figure 12. Examine register data

As you step through the program, the Monitors view updates with the relevant data items for the assembler instruction about to be executed.


Conclusion

The ability to debug HLASM applications symbolically, at the source level, greatly enhances productivity. Rational Developer for System z combined with Debug Tool and the Debug Tool Utilities and Advanced Functions makes this possible and provides a consistent, powerful interface for debugging HLASM applications. Establishing the metadata to enable symbolic HLASM debugging is as easy as just described.


Download

DescriptionNameSize
Sample HLASM applicationdbgmain.zip2 KB

Resources

Learn

Get products and technologies

Discuss

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into WebSphere on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=WebSphere, Rational
ArticleID=280988
ArticleTitle=Symbolically debugging HLASM applications using Rational Developer for System z and Debug Tool
publish-date=01092008