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
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:
- 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=
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
TEST, are correct.
Substitution variables used by the JCL Proc are:
ADATADS– Specifies the
ADATAdataset that will contain the HLASM ADATA information. The JCL Proc assumes this dataset has been allocated and is a PDS/E with RECFM=
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=
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 EQADEBUGto reference the
EQALANGX PDS/Eduring the debugging session.
MEM– The member name for the
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
- 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
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
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:
- 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 of
ASSEMBLE. 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
Build the application
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
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,
- 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.
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:
- 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, where
dbgmainis 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
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.
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
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
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.
|Sample HLASM application||dbgmain.zip||2 KB|
- 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.
Dig deeper into WebSphere on developerWorks
Get samples, articles, product docs, and community resources to help build, deploy, and manage your cloud apps.
Experiment with new directions in software development.
Software development in the cloud. Register today to create a project.
Evaluate IBM software and solutions, and transform challenges into opportunities.