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
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:
- Customize the JCL Proc that includes the step to create the Debug Tool metadata.
- Create an MVS project and subproject, specifying the JCL Proc and the appropriate properties for the JCL Proc.
- Create the assembler routine.
- Build the application.
- Run the application in Debug Mode.
- 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 theADATAdataset that will contain the HLASM ADATA information. The JCL Proc assumes this dataset has been allocated and is a PDS/E with RECFM=VBand 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=VBand 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 theDDNAME EQADEBUGto reference theEQALANGX PDS/Eduring the debugging session. -
MEM– The member name for theADATAandEQALANGXdatasets.
Create a project and subproject
In Developer for z:
- Create a project and sub-project. In the example, the project name and the subproject name are
PLEX4BhlasmandHLASMDebug, respectively. - 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
ASMstep 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
-
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
Specifying
MEMas 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. - 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
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:
- Allocate a Partition Data Set. In the Remote Systems view, highlight MVS Files, right-click, and select Allocate PDS.
- 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 ofASSEMBLE. Then, click Next. - Select Specify characteristics by usage type, and then select SOURCE and ASM.
- Click Finish.
- 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.
- 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.
- 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
|
To build the application:
- Ensure all of the datasets you specified in the properties are allocated. These datasets are referenced in JCL that is generated for the build.
- Highlight the subproject name (HLASMDebug in the example), right-click, and then select the Rebuild Subproject action.
- 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.
- 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
Run the application in Debug Mode
To run the application:
- In the sub-project, place focus on the executable load module, in our example,
ENGLAND.EXEC.LOAD(DBGMAIN).exe. - Right-click the module and then select the Debug Application action.
- The perspective switches to Debug Perspective. If prompted to accept the switch to the Debug Perspective, click Yes to accept the switch.
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:
- Use the Windows pull-down and selecting Show View.
- Select Other.
- Find the Debug Console view in the list and open it. The LoadDebugData command (
ldd) will load the metadata for this debug session. - Type in the command
ldd dbgmain, wheredbgmainis 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 theldd dbgmaincommand
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
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
- Using the Step Into button in the Debug View (in the upper left), you can run the assembler application one instruction at a time.
- 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.
- 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.
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
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 
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
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
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
As you step through the program, the Monitors view updates with the relevant data items for the assembler instruction about to be executed.
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.
| Description | Name | Size | Download method |
|---|---|---|---|
| Sample HLASM application | dbgmain.zip | 2 KB | HTTP |
Information about download methods
Learn
-
developerWorks WebSphere on System z zone
-
Debug Tool for z/OS
-
Debug Tool Utilities and Advanced Functions
-
High Level Assembler and Toolkit Feature
-
InfoCenter: IBM System z Enterprise Development Tools & Compilers, including information for both Debug Tool Utilities and Advanced Functions and Debug Tool.
-
IBM Rational Developer for System z Installation Guide (GI11-8297-00)
-
Rational Developer for System z technical resources
-
Techdocs: Managing Language Environment Options in WebSphere for z/OS Servers
Get products and technologies
-
Download a demo of Rational Developer for System z in use with a variety of scenarios from
IBM Enterprise Modernization Demos.
-
Download a free trial of Rational Developer for System z.
Discuss
Table of contents
Local resources
My developerWorks community
Tags
Use the slider bar to see more or fewer tags.
Popular tags shows the top tags for this particular content zone (for example, Java technology, Linux, WebSphere).
My tags shows your tags for this particular content zone (for example, Java technology, Linux, WebSphere).
Popular article tags |
My article tagsSkip to tags list
Popular article tags |
My article tags
