Rational Developer for System z, Version 7.6

Preparing an assembler program

This chapter describes how to prepare an assembler program that you can debug with Debug Tool's full capabilities. To prepare an assembler program, you must do the following steps:

  1. Assemble your program with the proper options.
  2. Create the EQALANGX file.
  3. Link-edit your program.

If you use Debug Tool Utilities to prepare your assembler program, you can do steps 1 and 2 in one step.

Before you assemble your program

When you debug an assembler program, you can use most of the Debug Tool commands. There are three differences between debugging an assembler program and debugging programs written in other programming languages supported by Debug Tool:

After you verify that your assembler program meets these requirements, prepare your assembler program by doing the following tasks:

  1. Assembling your program.
  2. Creating the EQALANGX file for an assembler program.

Assembling your program and creating EQALANGX describes how to prepare an assembler program by using Debug Tool Utilities.

Assembling your program

If you assemble your program without using Debug Tool Utilities, you must use the High Level Assembler (HLASM) and specify a SYSADATA DD statement and the ADATA option. This causes the assembler to create a SYSADATA file. The SYSADATA file is required to generate the debug information (the EQALANGX file) used by Debug Tool.

Creating the EQALANGX file for an assembler program

To create the EQALANGX file, you use the EQALANGX program. The EQALANGX program shipped as a component of Debug Tool is functionally equivalent to the IDILANGX program shipped as a component of IBM® Fault Analyzer. If you have IBM Fault Analyzer installed, you can use the IDILANGX program to create the EQALANGX file, as long as the version of the IDILANGX program is the same as or newer than the EQALANGX program shipped with Debug Tool. To identify the version of the program, do the following steps:

  1. Create the EQALANGX file as described in the IBM Fault Analyzer documentation.
  2. Look at the first record of the generated EQALANGX file and make a note of the version.
  3. Create the EQALANGX file as described in this section.
  4. Look at the first record of the generated EQALANGX file.

If you choose to use IDILANGX to create the EQALANGX file, you can skip these instructions. See the IBM Fault Analyzer documentation for instructions on creating the EQALANGX file.

To create the EQALANGX files without using Debug Tool Utilities, use JCL similar to the following:

//XTRACT EXEC PGM=EQALANGX,REGION=32M,
//  PARM='(ASM ERROR LOUD'
//STEPLIB DD DISP=SHR,DSN=hlq.SEQAMOD
//SYSADATA DD DISP=SHR,DSN=yourid.sysadata
//IDILANGX DD DISP=OLD,DSN=yourid.EQALANGX

The following list describes the variables used in this example the parameters you can use with the EQALANGX program:

PARM=
(ASM
Indicates that an assembler module is being processed.
ERROR
This parameter is suggested but optional. If you specify it, additional information is displayed when an error is detected.
LOUD
The LOUD parameter is suggested, but optional. If you specify it, additional informational and statistical messages are displayed.

The messages displayed by specifying the ERROR and LOUD parameters are Write To Operator or Write To Programmer (WTO or WTP) messages. See the IBM Fault Analyzer for z/OS® User's Guide and Reference for detailed information about the messages and return codes displayed by the IDILANGX program. The EQALANGX program uses the same messages and return codes.

hlq.SEQAMOD
The name of the data set containing the Debug Tool load modules. If the Debug Tool load modules are in a system linklib data set, you can omit the following line:
//STEPLIB DD DISP=SHR,DSN=hlq.SEQAMOD
yourid.sysadata
The name of the data set containing the SYSADATA output from the assembler. If this is a partitioned data set, the member name must be specified. For information about the characteristics of this data set, see HLASM Programmer’s Guide.
yourid.EQALANGX
The name of the data set where the EQALANGX debug file is to be placed. This data set must have variable block record format (RECFM=VB) and a logical record length of 1562 (LRECL=1562).

Debug Tool searches for the EQALANGX debug file in a partitioned data set with the name yourid.EQALANGX and a member name that matches the name of the first CSECT in the assembly. If you want the member name of the EQALANGX debug file to match the first CSECT in the assembly, you do not need to specify a member name on the DD statement. Otherwise, you must specify a member name on the DD statement. In this case, you must use the SET SOURCE command to direct Debug Tool to the member containing the EQALANGX data.

Debug Tool does not support debugging of Private Code (unnamed CSECT). The EQALANGX will issue error messages if an unnamed CSECT is detected in your assembler program.

Assembling your program and creating EQALANGX

You can assemble your program and create the EQALANGX file at the same time by using Debug Tool Utilities. Do the following:

  1. Start Debug Tool Utilities. The Debug Tool Utilities panel is displayed.
  2. Select option 1, "Program Preparation" . The Debug Tool Program Preparation panel is displayed.
  3. Select option 5, "Assemble". The Debug Tool Program Preparation - High Level Assembler panel is displayed. In this panel, specify the name of the source file and the assemble options that are used by High Level Assembler (HLASM) to assemble the program.

    If option 5 is not available, contact your system administrator.

  4. Press Enter. The High Level Assembler - Verify Selections panel is displayed. Verify that the information on the panel is correct and then press Enter.
  5. If any of the output data sets you specified do not existed, you are asked to verify the options used to create them.
  6. If you specified that the processing be completed by batch, the JCL created to run the batch job is displayed. Verify that the JCL is correct, type Submit in the command line, press Enter and then press PF3.
  7. After the processing is completed, the High Level Assembler - View Outputs panel is displayed. This panel displays the return code of each process completed and enables you to view, edit, or browse the input and output data sets.

To read more information about a field in any panel, place the cursor in the input field and press PF1. To read more information about a panel, place the cursor anywhere on the panel that is not an input field and press PF1.

After you assemble your program and create the EQALANGX file, you can link-edit your program.

Link-editing your program

You can link-edit your program by using your normal link-edit procedures or you can use Debug Tool Utilities by doing the following:

  1. From the Debug Tool Program Preparation panel, select option L, "Link Edit". The Debug Tool Program Preparation - Link Edit panel is displayed. In this panel, specify the input data sets and link edit options that you need the linker to use.
  2. Press Enter. The Link Edit - Verify Selections panel is displayed. Verify that the information on the panel is correct and then press Enter.
  3. If any of the output data sets you specified do not exist, you are asked to verify the options used to create them. Press Enter after you verify the options.
  4. If you specified that the processing be completed by batch, the JCL created to run the batch job is displayed. Verify that the JCL is correct and press PF3.
  5. After the processing is completed, the Link Edit - View Outputs panel is displayed. This panel displays the return code of each process completed and enables you to view, edit, or browse the input and output data sets.

To read more information about a field in any panel, place the cursor in the input field and press PF1. To read more information about a panel, place the cursor anywhere on the panel that is not an input field and press PF1.

After you link-edit your program, you can run your program and start Debug Tool.


Terms of use | Feedback

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