Appendix C. Quick start guide for compiling and assembling programs for use with IBM Problem Determination Tools products

This chapter describes the minimal steps required to prepare your programs for use with IBM Problem Determination Tools products. For more detailed information, refer to 'Part 2. Preparing your program for debugging' of the Debug Tool for z/OS® User's Guide, 'Part 2. Fault Analyzer Installation and Administration' of the Fault Analyzer for z/OS User's Guide, or 'Appendix B. Creating side files using CAZLANGX' of the Application Performance Analyzer for z/OS User’s Guide.

The purpose of this chapter is to provide instructions for a single compile method for organizations that are using some combination of Debug Tool for z/OS, Fault Analyzer for z/OS, and Application Performance Analyzer for z/OS. If your enterprise is only using Debug Tool for z/OS, you can alternatively refer to 'Part 2. Preparing your program for debugging' of the Debug Tool for z/OS User's Guide. If your enterprise is only using Fault Analyzer for z/OS, alternatively refer to 'Part 2. Fault Analyzer Installation and Administration' of the Fault Analyzer for z/OS User's Guide. If your enterprise is only using Application Performance Analyzer for z/OS, alternatively refer to 'Appendix B. Creating side files using CAZLANGX' of the Application Performance Analyzer for z/OS User’s Guide.

Debug Tool for z/OS, Fault Analyzer for z/OS and Application Performance Analyzer for z/OS are designed to use load modules and other files produced by IBM compilers. You must compile your programs with certain compiler options so that they produce load modules and files that these products can use.

This chapter uses the term ’source information files’ to refer to the types of files that are used by Debug Tool for z/OS, Fault Analyzer for z/OS and Application Performance Analyzer for z/OS. The different kinds of source information files that are the subject of discussion in this chapter include:

Be aware that different compilers generate different kinds of source information files. If you use more than one compiler, you might have more than one type of source information library.

When you compile your programs with the compiler options described in this chapter, you can use the load modules and source information files created by the compilers as follows:

Updating your build process

If someone recently installed one or more of the IBM Problem Determination Tools products on your system, the program build processes might not have been updated yet. Updating the build processes is an important and necessary part of implementing the IBM Problem Determination Tools products.

In many organizations, there is clear ownership of these build processes. In other organizations, it might not be obvious who should make the changes. Many organizations use standard compile processes or PROCs that your system administrators maintain and have updated to prepare programs for the IBM Problem Determination Tools products. If this is the case, find out what processes have been made available and how to use them. In other organizations, each developer maintains their own compile JCL or PROCs to compile programs. If this is the case, update your own compile JCL to prepare your programs for the IBM Problem Determination Tools products as described below.

Start by researching what is required for each compiler individually. For example, the changes required for Enterprise COBOL for z/OS, Enterprise PL/I for z/OS, C/C++ and Assembler are all slightly different.

In general, there are three changes that might be needed to compiler JCL to produce programs that can be used by the IBM Problem Determination Tools:

  1. Specify compiler options required by the IBM Problem Determination Tools. For example, in the case of Enterprise COBOL for z/OS, a TEST options is needed.
  2. Code the JCL to produce and save the source information files that the IBM Problem Determination Tools products need. Newer compilers can generate the required source information files directly. Some older compilers require an additional step in the compile job to run a special utility program that produces the needed file.
  3. In certain environments, it is advantageous to include a special Debug Tool for z/OS module into the application load module during the link edit step. In most cases this is optional, but it can simplify starting Debug Tool for z/OS for certain types of programs. For certain older compilers running in certain environments, you must include a special module to enable Debug Tool for z/OS.

Updating your promotion process

Typically, when a program is tested, program load modules are promoted through different stages before reaching production. For example, when a new program is compiled for the first time, it might be placed into a test load library. After unit testing is completed, perhaps the compiled program is promoted to a quality assurance environment. And eventually, it is promoted into production. On your system, you might know these stages by different names, such as:

Consider whether you want the ability to use Debug Tool for z/OS, Fault Analyzer for z/OS and Application Performance Analyzer for z/OS throughout your programs' life cycle. Even if you do not plan to use Debug Tool for z/OS with production programs, Fault Analyzer for z/OS and Application Performance Analyzer for z/OS are very useful in those stages. To enable the IBM Problem Determination Tools products at each stage, update your promotion processes to retain the source information files. Promotions can be accomplished by performing a recompile, a copy, or a move. Perform the same steps with your source information files that you perform with your load modules or object modules. For each load library or object library, you should have a corresponding set of source information libraries. Whenever you promote a load module or object module, you should promote the source information file as well. This ensures that the source information file is available for Fault Analyzer and Application Performance Analyzer, and you can continue to take advantage of the IBM Problem Determination Tools products at all stages of your program's life cycle.

Preparing your programs

Each compiler produces different kinds of source information files, and each of the IBM Problem Determination Tools products reads different kinds of files. It can be time-consuming to research all the different combinations, but for each compiler, there is a suggested method described below. If you use the suggested methods, then your programs will be ready to take full advantage of the IBM Problem Determination Tools products.

Enterprise COBOL for z/OS Version 4 programs

The following table shows various compiler options that can be used to prepare Enterprise COBOL for z/OS Version 4 programs for use with the IBM Problem Determination Tools products (Debug Tool for z/OS, Fault Analyzer for z/OS and Application Performance Analyzer for z/OS). The methods suggested in the following table indicate if the load module produced is suitable for a production environment. Load modules suitable for a production environments have no significant runtime overhead.

Table 19. Examples of compiler options and source information files supported by IBM Problem Determination Tools products for Enterprise COBOL for z/OS Version 4
Compiler options Source information file type produced Is the load module production ready? Options supported and suggested for Debug Tool for z/OS Options supported and suggested for Fault Analyzer for z/OS Options supported and suggested for Application Performance Analyzer for z/OS
TEST(NOHOOK, SEPARATE, EJPD), LIST, MAP, SOURCE, NONUMBER, XREF(SHORT) SYSDEBUG Yes Suggested for production and test
NOTEST, LIST, MAP, SOURCE, NONUMBER, XREF(SHORT) Compiler listing Yes N/A Supported Supported
NOTEST, LIST, MAP, SOURCE, NUMBER, XREF(SHORT) Yes N/A Supported N/A
LIST, MAP, SOURCE, NONUMBER, XREF(SHORT) LANGX file Yes N/A Supported Supported
Note:
The highlighted row or rows in the table above indicate the suggested compiler options and source information file types for each product.

Preparing Enterprise COBOL for z/OS Version 4 programs

Perform the following steps for compiling your Enterprise COBOL for z/OS Version 4 programs using the compiler options suggested in Table 19:

  1. Create libraries (PDSE is suggested unless PDS is required in your organization) for SYSDEBUG files. Create one or more SYSDEBUG libraries for each environment, such as test, production, and so on.
  2. Create a corresponding SYSDEBUG library for each load library. Specify LRECL=(80 to 1024),RECFM=FB,BLKSIZE=(multiple of lrecl < 32K).
  3. For all programs in both test and production environments, specify the following compiler options: TEST(NOHOOK,SEPARATE,EJPD),LIST,MAP,SOURCE,NONUMBER,XREF(SHORT).

    The TEST compiler option is required if you plan to use Debug Tool for z/OS to debug a program. The TEST option is optional if you plan to use Fault Analyzer for z/OS or Application Performance Analyzer for z/OS.

    The SEPARATE sub-option produces a SYSDEBUG file.

    NOHOOK and SEPARATE produce a production-ready module that can still be debugged.

    If the OPT option is also used, EJPD might reduce optimization but enables the debugger's JUMPTO and GOTO commands. These commands are disabled when OPT and NOEJPD are both used.

  4. When the TEST option is not used, save the compiler listing in a file, or use the xxxLANGX utility program to create a LANGX file. Equivalent xxxLANGX utilities are available in Debug Tool for z/OS as EQALANGX, in Fault Analyzer for z/OS as IDILANGX and in Application Performance Analyzer for z/OS as CAZLANGX. Fault Analyzer for z/OS and Application Performance Analyzer for z/OS can use compiler listings and LANGX files to provide source-level support.
  5. The LIST, MAP, SOURCE, and XREF options are needed only if a compiler listing or a LANGX file will be used to provide source information to Fault Analyzer for z/OS or Application Performance Analyzer for z/OS. If a SYSDEBUG file will be used with these products or if you will not be using Fault Analyzer for z/OS or Application Performance Analyzer for z/OS, the LIST, MAP, SOURCE, and XREF options are optional.
  6. The NONUMBER compiler option is needed only if a compiler listing file will be used to provide source information to Application Performance Analyzer for z/OS. If a SYSDEBUG file will be used with Application Performance Analyzer for z/OS, or if you will not be using Application Performance Analyzer for z/OS, the NONUMBER option is optional.
  7. Code a SYSDEBUG DD in the JCL of the compiler step:
     //SYSDEBUG DD DSN= SYSDEBUG.pds(pgmname),DISP=SHR
    Save the SYSDEBUG file produced by the compiler in the SYSDEBUG library and specify a member name that is equal to the program name of your application program. This is the source information file for Debug Tool for z/OS, Fault Analyzer for z/OS and Application Performance Analyzer for z/OS.
  8. Modify the promotion process to promote SYSDEBUG files. When a load module is promoted, for example from test to production, promote the corresponding SYSDEBUG file or files. A promotion can be a recompile, copy, or move. Perform the same steps with the SYSDEBUG file that you perform with the module during promotion.
  9. Optionally, include a Debug Tool Language Environment® (LE) exit module into the load module during the linkage editor step. This is one way to enable Debug Tool's panel 6 in ISPF, a simple panel-driven method to start the debugger automatically when a program runs, without JCL changes, based on the program name and user ID. Use module EQADBCXT for batch programs (including IMS™ batch), EQADICXT for IMS/TM programs and EQADDCXT for DB2® stored procedures. Do not include the exit module for CICS® programs.

Sample JCL for compiling Enterprise COBOL for z/OS Version 4 programs

Below is a JCL example for compiling an Enterprise COBOL for z/OS Version 4 program for use with the IBM Problem Determination Tools products. This is a generic sample, and might not meet all your requirements to generate your modules.

Notice that the TEST compiler option is specified. Code the correct sub-options of the TEST compiler option for the version of the compiler that you are using. You can also code any other compatible compiler options that are required by your programs.

Also notice that a SYSDEBUG DD statement has been coded. This is the source information file that the compiler produces. It refers to a SYSDEBUG library that is a PDS or PDSE. The member name must be the same as the program name.

For Enterprise COBOL for z/OS, these are the only required changes.

However, there is an optional change in the linkage editor step. The example below shows that a special Language Environment exit module is included in the application load module. Although this is not required, it enables the use of Debug Tool panel 6, which makes the debugger easier to start in some environments. If you prefer to use panel 6 to start Debug Tool, this is one way to enable it. If you do not plan to use Debug Tool panel 6, then do not include an exit module.

//*     - - -  ADD A JOB CARD ABOVE THIS LINE  - - -
//*
//*  SAMPLE JCL TO PREPARE AN ENTERPRISE COBOL PROGRAM
//*  FOR THE IBM ZSERIES PD TOOLS PRODUCTS:
//*     FAULT ANALYZER, DEBUG TOOL, AND APPLICATION PERF. ANALYZER
//*
//*  NOTES:
//*
//*   COMPILER:
//*    1. A TEST COMPILER PARM IS REQUIRED FOR DEBUG TOOL
//*    2. COMPILER PARM TEST(NOHOOK,SEPARATE,EJPD) HAS ADVANTAGES:
//*         - THE MODULE IS READY FOR DEBUG TOOL
//*         - THE MODULE IS PRODUCTION-READY (NO RUN-TIME OVERHEAD)
//*         - A SYSDEBUG FILE IS CREATED THAT CAN BE USED BY DT,FA,APA
//*    3. COMPILER PARMS LIST,MAP,SOURCE,XREF ARE REQUIRED IF YOU PLAN
//*       TO USE THE COMPILER LISTING WITH FA OR APA, OR XXXLANGX
//*
//*   BINDER (LINKAGE EDITOR):
//*    4. THE INCLUDE FOR MODULE EQAD?CXT IS *OPTIONAL*.  IT IS AN
//*       LE EXIT MODULE THAT CAN BE USED TO START DEBUG TOOL.
//*       UNDERSTAND THE METHODS AVAILABLE FOR STARTING DEBUG TOOL,
//*       AND CHOOSE WHETHER YOU WANT TO USE THE LE EXITS.
//*         IF YOU USE THIS METHOD, LOAD THE CORRECT EXIT MODULE:
//*            EQADBCXT: FOR BATCH PROGRAMS
//*            EQADICXT: FOR ONLINE IMS PROGRAMS
//*            EQADDCXT: FOR DB2 STORED PROCEDURES (OF TYPE MAIN AND SUB)
//*           (for SUB this is supported only for invocations through call_sub)
//*            (DO NOT INCLUDE AN EXIT FOR CICS PROGRAMS)
//*
//*  SET PARMS FOR THIS COMPILE:
//*  ---------------------------
//   SET MEM=SAM1                             PROGRAM NAME
//   SET COBOLLIB='IGY.V4R1.SIGYCOMP'         COBOL COMPILER LOADLIB
//   SET DTLIB='EQAW.SEQAMOD'                 DEBUG TOOL LOADLIB
//   SET LELIB='CEE.SCEELKED'                 LE LINKEDIT LIBRARY
//   SET UNITDEV=SYSALLDA                     UNIT FOR TEMP FILES
//*
//*  ****************************
//*        COMPILE STEP
//*  ****************************
//COMPILE  EXEC PGM=IGYCRCTL,REGION=0M,
//   PARM=('TEST(NOHOOK,SEPARATE,EJPD),LIST,MAP,XREF(SHORT),NONUMBER,SOURCE')
//STEPLIB  DD DISP=SHR,DSN=&COBOLLIB
//SYSIN    DD DISP=SHR,DSN=&SYSUID..ADLAB.SOURCE(&MEM)
//SYSLIB   DD DISP=SHR,DSN=&SYSUID..ADLAB.COPYLIB
//SYSPRINT DD DISP=SHR,DSN=&SYSUID..ADLAB.LISTING(&MEM)
//SYSDEBUG DD DISP=SHR,DSN=&SYSUID..ADLAB.SYSDEBUG(&MEM)
//SYSLIN   DD DISP=(MOD,PASS),DSN=&&LOADSET,UNIT=&UNITDEV,
//            SPACE=(80,(10,10))
//SYSUT1   DD SPACE=(80,(10,10),,,ROUND),UNIT=&UNITDEV
//SYSUT2   DD SPACE=(80,(10,10),,,ROUND),UNIT=&UNITDEV
//SYSUT3   DD SPACE=(80,(10,10),,,ROUND),UNIT=&UNITDEV
//SYSUT4   DD SPACE=(80,(10,10),,,ROUND),UNIT=&UNITDEV
//SYSUT5   DD SPACE=(80,(10,10),,,ROUND),UNIT=&UNITDEV
//SYSUT6   DD SPACE=(80,(10,10),,,ROUND),UNIT=&UNITDEV
//SYSUT7   DD SPACE=(80,(10,10),,,ROUND),UNIT=&UNITDEV
//*
//CBLPRINT  EXEC PGM=IEBGENER,REGION=0M
//SYSPRINT  DD SYSOUT=*
//SYSUT1    DD DSN=&SYSUID..ADLAB.LISTING(&MEM),DISP=SHR
//SYSUT2    DD SYSOUT=*
//SYSIN     DD DUMMY
//*  *********************************
//*        LINK-EDIT (BINDER) STEP
//*  *********************************
//LKED EXEC PGM=IEWL,REGION=0M,COND=(5,LT,COMPILE),PARM='LIST,XREF'
//SYSLIB   DD DISP=SHR,DSN=&LELIB
//DTLIB    DD DISP=SHR,DSN=&DTLIB
//SYSLMOD  DD DSN=&SYSUID..ADLAB.LOAD(&MEM),DISP=SHR
//SYSLIN   DD DISP=(OLD,DELETE),DSN=&&LOADSET
//*  INCLUDING A DEBUG TOOL LE EXIT (EQADBCXT, EQADDCXT, OR EQADICXT) IS OPTIONAL.
//*  AN EXIT ENABLES STARTING DEBUG TOOL USING THE USER EXIT DATA SET UTILITY
//*  (ONE OF THE DEBUG TOOL ISPF UTILITIES)
//*  //        DD *
//*   INCLUDE DTLIB(EQADBCXT)
//SYSPRINT DD SYSOUT=*
//SYSUT1   DD UNIT=&UNITDEV,DCB=BLKSIZE=1024,SPACE=(1024,(200,20))

Enterprise COBOL for z/OS Version 3 and COBOL for OS/390 and VM programs

The following table shows various compiler options that can be used to prepare Enterprise COBOL for z/OS Version 3 and COBOL for OS/390® and VM programs for use with the IBM Problem Determination Tools products (Debug Tool for z/OS, Fault Analyzer for z/OS and Application Performance Analyzer for z/OS). The methods suggested in the following table indicate if the load module produced is suitable for a production environment. Load modules suitable for a production environments have no significant runtime overhead.

Table 20. Examples of compiler options and source information files supported by IBM Problem Determination tools products for Enterprise COBOL for z/OS Version 3 and COBOL for OS/390 and VM
Compiler options Source information file type produced Is the load module production ready? Options supported and suggested for Debug Tool for z/OS Options supported and suggested for Fault Analyzer for z/OS Options supported and suggested for Application Performance Analyzer for z/OS
TEST(NONE, SYM, SEPARATE), LIST, MAP, SOURCE, NONUMBER, XREF(SHORT) SYSDEBUG Yes Suggested for production and test
NOTEST, LIST, MAP, SOURCE, NONUMBER, NOOPT, XREF(SHORT) Compiler listing Yes N/A Supported Supported
NOTEST, LIST, MAP, SOURCE, XREF(SHORT), NUMBER Yes N/A Supported N/A
LIST, MAP, SOURCE, NONUMBER, XREF(SHORT) LANGX file Yes N/A Supported Supported
Note:
The highlighted row or rows in the table above indicate the suggested compiler options and source information file types for each product.

Preparing Enterprise COBOL for z/OS Version 3 and COBOL for OS/390 and VM programs

Perform the following steps for compiling your Enterprise COBOL for z/OS Version 3 and COBOL for OS/390 and VM programs using the compiler options suggested in Table 20:

  1. Create libraries (PDSE is suggested unless PDS is required in your organization) for SYSDEBUG files. Allocate one or more SYSDEBUG libraries for each environment, such as test, production, and so on.
  2. Create a corresponding SYSDEBUG library for each load library. Specify LRECL=(80 to 1024),RECFM=FB,BLKSIZE=(multiple of lrecl < 32K).
  3. For all programs in both test and production environments, use TEST(NONE,SYM,SEPARATE),LIST,MAP,SOURCE,NONUMBER,XREF(SHORT).

    TEST is required by Debug Tool for z/OS.

    The SEPARATE sub-option produces a SYSDEBUG file. Specifying NONE with SEPARATE produces a production-ready module that can still be debugged.

    If OPTIMIZE is specified, the debugger JUMPTO and GOTO commands are disabled. These commands are enabled when NOOPTIMIZE is specified.

  4. The LIST, MAP, SOURCE, and XREF options are needed only if a compiler listing or a LANGX file will be used to provide source information to Fault Analyzer for z/OS or Application Performance Analyzer for z/OS. If a SYSDEBUG file will be used with these products, or if you will not be using Fault Analyzer for z/OS or Application Performance Analyzer for z/OS, the LIST, MAP, SOURCE, and XREF options are optional.
  5. The NONUMBER compiler option is needed only if a compiler listing file will be used to provide source information to Application Performance Analyzer for z/OS. If a SYSDEBUG file will be used with Application Performance Analyzer for z/OS, or if you will not be using Application Performance Analyzer for z/OS, the NONUMBER option is optional.
  6. Code a SYSDEBUG DD in the JCL of the compiler step.
    //SYSDEBUG DD DSN= SYSDEBUG.pds(pgmname),DISP=SHR
    Save the SYSDEBUG file produced by the compiler in the SYSDEBUG library and specify a member name that is equal to the program name of your application program. This is the source information file for Debug Tool for z/OS, Fault Analyzer for z/OS and Application Performance Analyzer for z/OS.
  7. Modify the promotion process to promote SYSDEBUG files. When a load module is promoted, for example from test to production, promote the corresponding SYSDEBUG file or files. A promotion can be a recompile, copy, or move. Perform the same steps with the SYSDEBUG file that you perform with the module during promotion.
  8. Optionally, include a Debug Tool Language Environment exit module into the load module during the linkage editor step. This is one way to enable Debug Tool's panel 6 in ISPF, a simple panel-driven method to start the debugger automatically when a program runs, without JCL changes, based on the program name and user ID. Use module EQADBCXT for batch programs (including IMS batch), EQADICXT for IMS/TM programs and EQADDCXT for DB2 stored procedures. Do not include the exit module for CICS programs.

Sample JCL for compiling Enterprise COBOL for z/OS Version 3 programs

Below is a JCL example for compiling an Enterprise COBOL for z/OS Version 3 program for use with the IBM Problem Determination Tools products. This is a generic sample, and might not meet all your requirements.

Notice that a TEST option is specified. Code the correct sub-option of the TEST compiler option for the version of the compiler that you are using. You can also code any other compatible compiler options that are required by your programs.

Also notice that a SYSDEBUG DD statement has been coded. This is the source information file that the compiler produces. It refers to a SYSDEBUG library that is a PDS or PDSE. The member name must be the same as the program name.

For Enterprise COBOL for z/OS, these are the only required changes.

However, there is an optional change in the linkage editor step. The example below shows that a special Language Environment exit module is included in the application load module. Although this is not required, it enables the use of Debug Tool panel 6, which makes the debugger easier to start in some environments. If you prefer to use panel 6 to start Debug Tool, this is one way to enable it. If you do not plan to use Debug Tool panel 6, then do not include an exit module.

//*     - - -  ADD A JOB CARD ABOVE THIS LINE  - - -
//*
//*  SAMPLE JCL TO PREPARE AN ENTERPRISE COBOL PROGRAM
//*  FOR THE IBM ZSERIES PD TOOLS PRODUCTS:
//*     FAULT ANALYZER, DEBUG TOOL, AND APPLICATION PERF. ANALYZER
//*
//*  NOTES:
//*
//*   COMPILER:
//*    1. A TEST COMPILER PARM IS REQUIRED FOR DEBUG TOOL
//*    2. COMPILER PARM TEST(NONE,SYM,SEP) HAS THREE ADVANTAGES:
//*         - THE MODULE IS READY FOR DEBUG TOOL
//*         - THE MODULE IS PRODUCTION-READY (NO RUN-TIME OVERHEAD)
//*         - A SYSDEBUG FILE IS CREATED THAT CAN BE USED BY DT,FA,APA
//*    3. COMPILER PARMS LIST,MAP,SOURCE,XREF ARE REQUIRED IF YOU PLAN
//*       TO USE THE COMPILER LISTING WITH FA OR APA, OR XXXLANGX
//*    4. COMPILER PARM NOOPT IS OPTIONAL.  HOWEVER, THE DEBUG TOOL
//*       COMMANDS JUMPTO AND GOTO WILL NOT BE AVAILABLE IF
//*       THE OPT PARM IS USED
//*
//*   BINDER (LINKAGE EDITOR):
//*    5. THE INCLUDE FOR MODULE EQAD?CXT IS *OPTIONAL*.  IT IS AN
//*       LE EXIT MODULE THAT CAN BE USED TO START DEBUG TOOL.
//*       UNDERSTAND THE METHODS AVAILABLE FOR STARTING DEBUG TOOL,
//*       AND CHOOSE WHETHER YOU WANT TO USE THE LE EXITS.
//*         IF YOU USE THIS METHOD, LOAD THE CORRECT EXIT MODULE:
//*            EQADBCXT: FOR BATCH PROGRAMS
//*            EQADICXT: FOR ONLINE IMS PROGRAMS
//*            EQADDCXT: FOR DB2 STORED PROCEDURES (OF TYPE MAIN AND SUB)
//*           (for SUB this is supported only for invocations through call_sub)
//*            (DO NOT INCLUDE AN EXIT FOR CICS PROGRAMS)
//*
//*  SET PARMS FOR THIS COMPILE:
//*  ---------------------------
//   SET MEM=SAM1                             PROGRAM NAME
//   SET COBOLLIB='IGY.V3R4.SIGYCOMP'         COBOL COMPILER LOADLIB
//   SET DTLIB='EQAW.SEQAMOD'                 DEBUG TOOL LOADLIB
//   SET LELIB='CEE.SCEELKED'                 LE LINKEDIT LIBRARY
//   SET UNITDEV=SYSALLDA                     UNIT FOR TEMP FILES
//*
//*  ****************************
//*        COMPILE STEP
//*  ****************************
//COMPILE  EXEC PGM=IGYCRCTL,REGION=0M,
//   PARM=('TEST(NONE,SYM,SEPARATE),LIST,MAP,SOURCE,NONUMBER,XREF(SHORT)')
//STEPLIB  DD DISP=SHR,DSN=&COBOLLIB
//SYSIN    DD DISP=SHR,DSN=&SYSUID..ADLAB.SOURCE(&MEM)
//SYSLIB   DD DISP=SHR,DSN=&SYSUID..ADLAB.COPYLIB
//SYSPRINT DD DISP=SHR,DSN=&SYSUID..ADLAB.LISTING(&MEM)
//SYSDEBUG DD DISP=SHR,DSN=&SYSUID..ADLAB.SYSDEBUG(&MEM)
//SYSLIN   DD DISP=(MOD,PASS),DSN=&&LOADSET,UNIT=&UNITDEV,
//            SPACE=(80,(10,10))
//SYSUT1   DD SPACE=(80,(10,10),,,ROUND),UNIT=&UNITDEV
//SYSUT2   DD SPACE=(80,(10,10),,,ROUND),UNIT=&UNITDEV
//SYSUT3   DD SPACE=(80,(10,10),,,ROUND),UNIT=&UNITDEV
//SYSUT4   DD SPACE=(80,(10,10),,,ROUND),UNIT=&UNITDEV
//SYSUT5   DD SPACE=(80,(10,10),,,ROUND),UNIT=&UNITDEV
//SYSUT6   DD SPACE=(80,(10,10),,,ROUND),UNIT=&UNITDEV
//SYSUT7   DD SPACE=(80,(10,10),,,ROUND),UNIT=&UNITDEV
//*
//CBLPRINT  EXEC PGM=IEBGENER,REGION=0M
//SYSPRINT  DD SYSOUT=*
//SYSUT1    DD DSN=&SYSUID..ADLAB.LISTING(&MEM),DISP=SHR
//SYSUT2    DD SYSOUT=*
//SYSIN     DD DUMMY
//*  *********************************
//*        LINK-EDIT (BINDER) STEP
//*  *********************************
//LKED EXEC PGM=IEWL,REGION=0M,COND=(5,LT,COMPILE),PARM='LIST,XREF'
//SYSLIB   DD DISP=SHR,DSN=&LELIB
//DTLIB    DD DISP=SHR,DSN=&DTLIB
//SYSLMOD  DD DSN=&SYSUID..ADLAB.LOAD(&MEM),DISP=SHR
//SYSLIN   DD DISP=(OLD,DELETE),DSN=&&LOADSET
//*  INCLUDING A DEBUG TOOL LE EXIT (EQADBCXT, EQADDCXT, OR EQADICXT) IS OPTIONAL.
//*  AN EXIT ENABLES STARTING DEBUG TOOL USING THE USER EXIT DATA SET UTILITY
//*  (ONE OF THE DEBUG TOOL ISPF UTILITIES)
//*  //        DD *
//*   INCLUDE DTLIB(EQADBCXT)
//SYSPRINT DD SYSOUT=*
//SYSUT1   DD UNIT=&UNITDEV,DCB=BLKSIZE=1024,SPACE=(1024,(200,20))

COBOL for MVS and VM programs

The following table shows various compiler options that can be used to prepare COBOL for MVS™ and VM programs for use with the IBM Problem Determination Tools products (Debug Tool for z/OS, Fault Analyzer for z/OS and Application Performance Analyzer for z/OS). The methods suggested in the following table indicate if the load module produced is suitable for a production environment. Load modules suitable for a production environments have no significant run-time overhead.

Table 21. Examples of compiler options and source information files supported by IBM Problem Determination tools products for COBOL for MVS and VM
Compiler options Source information file type produced Is the load module production ready? Options supported and suggested for Debug Tool for z/OS Options supported and suggested for Fault Analyzer for z/OS Options supported and suggested for Application Performance Analyzer for z/OS
TEST(ALL, SYM), LIST, MAP, SOURCE, NOOPT, NONUMBER, XREF(SHORT) Compiler listing No Suggested for test. (Using Debug Tool in production for this compiler is not suggested.)
NOTEST, LIST, MAP, SOURCE, NONUMBER, XREF(SHORT) Yes N/A Suggested for production
NOTEST, LIST, MAP, SOURCE, NONUMBER, XREF(SHORT) LANGX file Yes N/A Supported Supported
Note:
The highlighted row or rows in the table above indicate the suggested compiler options and source information file types for each product.

Preparing COBOL for MVS and VM programs

Perform the following steps for compiling your COBOL for MVS and VM programs:

  1. Create libraries (PDSE is suggested unless PDS is required in your organization) for compiler listing files. Allocate one or more compiler listing libraries for each environment, such as test and production.
  2. Create a corresponding listing library for each load library. Specify LRECL=133,RECFM=FBA,BLKSIZE=(multiple of lrecl < 32K).
  3. For all programs, such as batch, CICS, and IMS:
  4. Modify the SYSPRINT DD in the JCL of the compiler step to refer to a file.
    //SYSPRINT DD DSN= compiler.listing.pds(pgmname),DISP=SHR
    Save the compiler listing in a file in the compiler listing library and specify a member name that is equal to the program name of your application program. This is the source information file for Debug Tool for z/OS, Fault Analyzer for z/OS and Application Performance Analyzer for z/OS.
  5. Modify the promotion process to promote compiler listing files. When a load module is promoted, for example, from test to production, promote the corresponding compiler listing file or files. A promotion can be a recompile, a copy, or a move. Perform the same steps with the compiler listing file that you perform with the module during promotion.
  6. Optionally, include a Debug Tool Language Environment exit module into the load module during the linkage editor step. This is one way to enable Debug Tool's panel 6 in ISPF, a simple panel-driven method to start the debugger automatically when a program runs, without JCL changes, based on the program name and user ID. Use module EQADBCXT for batch programs (including IMS batch), EQADICXT for IMS/TM programs and EQADDCXT for DB2 stored procedures. Do not include the exit module for CICS programs.

Sample JCL for compiling COBOL for MVS and VM programs

Below is a JCL example for compiling an COBOL for MVS and VM program for use with the IBM Problem Determination Tools products. This is a generic sample, and might not meet all your requirements.

Notice that a TEST option is specified. Code the correct sub-options of the TEST compiler option for the version of the compiler that you are using. You can also code any other compatible compiler options that are required by your programs.

Also notice that the SYSPRINT DD refers to a permanent file. This is the source information file that the compiler produces. It refers to a listing library that is a PDS or PDSE. The member name must be the same as the program name. For COBOL for MVS and VM, these are the only required changes.

However, there is an optional change in the linkage editor step. The example below shows that a special Language Environment exit module is included in the application load module. Although this is not required, it enables the use of Debug Tool panel 6, which makes the debugger easier to start in some environments. If you prefer to use panel 6 to start Debug Tool, this is one way to enable it. If you do not plan to use Debug Tool panel 6, then do not include an exit module.

//*     - - -  ADD A JOB CARD ABOVE THIS LINE  - - -
//*
//*  SAMPLE JCL TO PREPARE A COBOL FOR MVS AND VM PROGRAM
//*  FOR THE IBM ZSERIES PD TOOLS PRODUCTS:
//*     FAULT ANALYZER, DEBUG TOOL, AND APPLICATION PERF. ANALYZER
//*
//*  NOTES:
//*
//*   COMPILER:
//*    1. A TEST COMPILER PARM IS REQUIRED FOR DEBUG TOOL
//*    2. COMPILER PARMS LIST,MAP,SOURCE,XREF ARE REQUIRED IF YOU PLAN
//*       TO USE THE COMPILER LISTING WITH FA OR APA, OR XXXLANGX
//*    3. COMPILER PARM NOOPT IS OPTIONAL.  HOWEVER, THE DEBUG TOOL
//*       COMMANDS JUMPTO AND GOTO WILL NOT BE AVAILABLE IF
//*       THE OPT PARM IS USED
//*
//*   BINDER (LINKAGE EDITOR):
//*    4. THE INCLUDE FOR MODULE EQAD?CXT IS *OPTIONAL*.  IT IS AN
//*       LE EXIT MODULE THAT CAN BE USED TO START DEBUG TOOL.
//*       UNDERSTAND THE METHODS AVAILABLE FOR STARTING DEBUG TOOL,
//*       AND CHOOSE WHETHER YOU WANT TO USE THE LE EXITS.
//*         IF YOU USE THIS METHOD, LOAD THE CORRECT EXIT MODULE:
//*            EQADBCXT: FOR BATCH PROGRAMS
//*            EQADICXT: FOR ONLINE IMS PROGRAMS
//*            EQADDCXT: FOR DB2 STORED PROCEDURES (OF TYPE MAIN AND SUB)
//*           (for SUB this is supported only for invocations through call_sub)
//*            (DO NOT INCLUDE AN EXIT FOR CICS PROGRAMS)
//*
//*  SET PARMS FOR THIS COMPILE:
//*  ---------------------------
//   SET MEM=SAM1                             PROGRAM NAME
//   SET COBOLLIB='IGY.SIGYCOMP'              COBOL COMPILER LOADLIB
//   SET DTLIB='EQAW.SEQAMOD'                 DEBUG TOOL LOADLIB
//   SET LELIB='CEE.SCEELKED'                 LE LINKEDIT LIBRARY
//   SET UNITDEV=SYSALLDA                     UNIT FOR TEMP FILES
//*
//*  ****************************
//*        COMPILE STEP
//*  ****************************
////COMPILE  EXEC PGM=IGYCRCTL,REGION=0M,
//   PARM=(NOTEST,LIST,MAP,SOURCE,NONUMBER,XREF(SHORT)')
//STEPLIB  DD DISP=SHR,DSN=&COBOLLIB
//SYSIN    DD DISP=SHR,DSN=&SYSUID..ADLAB.SOURCE(&MEM)
//SYSLIB   DD DISP=SHR,DSN=&SYSUID..ADLAB.COPYLIB
//SYSPRINT DD DISP=SHR,DSN=&SYSUID..ADLAB.LISTING(&MEM)
//SYSDEBUG DD DISP=SHR,DSN=&SYSUID..ADLAB.SYSDEBUG(&MEM)
//SYSLIN   DD DISP=(MOD,PASS),DSN=&&LOADSET,UNIT=&UNITDEV,
//            SPACE=(80,(10,10))
//SYSUT1   DD SPACE=(80,(10,10),,,ROUND),UNIT=&UNITDEV
//SYSUT2   DD SPACE=(80,(10,10),,,ROUND),UNIT=&UNITDEV
//SYSUT3   DD SPACE=(80,(10,10),,,ROUND),UNIT=&UNITDEV
//SYSUT4   DD SPACE=(80,(10,10),,,ROUND),UNIT=&UNITDEV
//SYSUT5   DD SPACE=(80,(10,10),,,ROUND),UNIT=&UNITDEV
//SYSUT6   DD SPACE=(80,(10,10),,,ROUND),UNIT=&UNITDEV
//SYSUT7   DD SPACE=(80,(10,10),,,ROUND),UNIT=&UNITDEV
//*
//CBLPRINT  EXEC PGM=IEBGENER,REGION=0M
//SYSPRINT  DD SYSOUT=*
//SYSUT1    DD DSN=&SYSUID..ADLAB.LISTING(&MEM),DISP=SHR
//SYSUT2    DD SYSOUT=*
//SYSIN     DD DUMMY
//*  *********************************
//*        LINK-EDIT (BINDER) STEP
//*  *********************************
//LKED EXEC PGM=IEWL,REGION=0M,COND=(5,LT,COMPILE),PARM='LIST,XREF'
//SYSLIB   DD DISP=SHR,DSN=&LELIB
//*** DTLIB    DD DISP=SHR,DSN=&DTLIB
//SYSLMOD  DD DSN=&SYSUID..ADLAB.LOAD(&MEM),DISP=SHR
//SYSLIN   DD DISP=(OLD,DELETE),DSN=&&LOADSET
//*  INCLUDING A DEBUG TOOL LE EXIT (EQADBCXT, EQADDCXT, OR EQADICXT) IS OPTIONAL.
//*  AN EXIT ENABLES STARTING DEBUG TOOL USING THE USER EXIT DATA SET UTILITY
//*  (ONE OF THE DEBUG TOOL ISPF UTILITIES)
//*  //        DD *
//*   INCLUDE DTLIB(EQADBCXT)
//SYSPRINT DD SYSOUT=*
//SYSUT1   DD UNIT=&UNITDEV,DCB=BLKSIZE=1024,SPACE=(1024,(200,20))

VS COBOL II programs

If you are currently using the TEST option to compile your programs, consider using NOTEST. Using NOTEST allows you to take advantage of Debug Tool for z/OS functionality that is not available when compiling with the TEST option. Examples of Debug Tool for z/OS functions that are available when compiling with the NOTEST option include the automonitor feature and using AT ENTRY program name breakpoints. Compiling with NOTEST also allows you to generate a module that can be debugged but does not incur additional overhead when running without the debugger.

The following table shows various compiler options that can be used to prepare VS COBOL II programs for use with the IBM Problem Determination Tools products (Debug Tool for z/OS, Fault Analyzer for z/OS and Application Performance Analyzer for z/OS). The methods suggested in the following table indicate if the load module produced is suitable for a production environment. Load modules suitable for a production environments have no significant run-time overhead.

Table 22. Examples of compiler options and source information files supported by Problem Determination tools products for VS COBOL II
Compiler options Source information file type produced Is the load module production ready? Options supported and suggested for Debug Tool for z/OS Options supported and suggested for Fault Analyzer for z/OS Options supported and suggested for Application Performance Analyzer for z/OS
NOTEST, LIST, MAP, SOURCE, XREF, NONUMBER, NOOFFSET Compiler listing Yes N/A Supported Supported
NOTEST, LIST, MAP, SOURCE, XREF, NUMBER Yes N/A Supported N/A
NOTEST, LIST, MAP, NOOPT, SOURCE, XREF, NONUMBER LANGX file Yes Suggested for production and test
Note:
The highlighted row or rows in the table above indicate the suggested compiler options and source information file types for each product.

Preparing VS COBOL II programs

Perform the following steps for compiling your VS COBOL II programs using the compiler options suggested in Table 22:

  1. Allocate libraries (PDSE is suggested unless PDS is required for your organization) for LANGX files. Allocate one or more LANGX libraries for each environment, such as test and production.
  2. Create a corresponding LANGX library for each load library. Specify LRECL=1562 or greater,RECFM=VB,BLKSIZE= lrecl+4 to 32k.
  3. For all programs, such as batch, CICS, and IMS, in both test and production environments, compile with NOTEST,LIST,MAP,NOOPT,SOURCE,XREF,NONUMBER compiler options.
  4. Modify the SYSPRINT DD in the compiler step to refer to a file. It can be either a permanent or temporary file. This will be the input to the xxxLANGX utility.
  5. Add a step after the compiler step to run the Problem Determination tools xxxLANGX utility. This utility program reads the compiler listing and generates a LANGX file. This is the source information file for Debug Tool for z/OS, Fault Analyzer for z/OS and Application Performance Analyzer for z/OS. Save the LANGX file in the LANGX file library and specify a member name that is equal to the program name of your application program. Equivalent xxxLANGX utilities are available in Debug Tool for z/OS as EQALANGX, in Fault Analyzer for z/OS as IDILANGX and in Application Performance Analyzer for z/OS as CAZLANGX.
  6. If the module is linked with Language Environment services, optionally include a Debug Tool Language Environment exit module into the load module during the linkage editor step. This is one way to enable the Debug Tool panel 6 in ISPF, a simple panel-driven method to start the debugger automatically when a program runs, without JCL changes, based on the program name and user ID. Use module EQADBCXT for batch programs (including IMS batch), EQADICXT for IMS/TM programs and EQADDCXT for DB2 stored procedures. Do not include the exit module for CICS programs or if the module is not linked with Language Environment services (it is linked with COBOL II runtime services).
  7. Modify the promotion process to promote LANGX files. When a load module is promoted, for example, from test to production, promote the corresponding LANGX file or files. A promotion can be a recompile, copy, or move. Perform the same steps with the LANGX file that you perform with the module during promotion.

Sample JCL for compiling VS COBOL II programs

Below is an example of JCL for compiling a VS COBOL II program for use with IBM Problem Determination Tools products. This is a generic sample, and might not meet all your requirements.

Notice the compiler options used and notice that the compiler listing is passed to an added step that generates a LANGX file. The compiler listing can be stored in a permanent file or can be passed in a temporary file. For VS COBOL II, these are the only required changes.

However, there is an optional change in the linkage editor step. The following example includes a special Language Environment exit module in the application load module. Although this is not required, it enables the use of Debug Tool panel 6, which makes the debugger easier to start in some environments. If you prefer to use panel 6 to start Debug Tool, this is one way to enable it. If you do not plan to use Debug Tool panel 6, then do not include an exit module. Do not include the exit module for CICS programs or if the module is not linked with Language Environment services (it is linked with COBOL II runtime services).

//*     - - -  ADD A JOB CARD ABOVE THIS LINE  - - -                
//*                                                                 
//*  SAMPLE JCL TO PREPARE A VS COBOL II PROGRAM                    
//*  FOR THE IBM ZSERIES PD TOOLS PRODUCTS:                         
//*     FAULT ANALYZER, DEBUG TOOL, AND APPLICATION PERF. ANALYZER  
//*                                                                 
//*  NOTES:                                                         
//*                                                                 
//*   COMPILER:                                                     
//*    1. COMPILER OPTIONS LIST,MAP,SOURCE,XREF ARE REQUIRED IF YOU 
//*       PLAN TO USE THE LISTING WITH A PD TOOLS PRODUCT, OR TO    
//*       PROCESS THE LISTING WITH AN XXXLANGX UTILITY              
//*    2. COMPILER OPTION NOTEST IS SUGGESTED FOR ALL COBOL II      
//*       PROGRAMS, EVEN IF IBM DEBUG TOOL FOR Z/OS WILL BE USED    
//*                                                                 
//*   BINDER (LINKAGE EDITOR):                                      
//*    3. IN THIS EXAMPLE, THE MODULE IS LINKED WITH LANGUAGE       
//*       ENVIRONMENT RUNTIME SERVICES. THIS IS CONTROLLED BY THE   
//*       LIBRARY OR LIBRARIES SPECIFIED IN THE SYSLIB DD IN THE    
//*       BINDER STEP.                                              
//*    4. THE INCLUDE FOR MODULE EQAD?CXT IS *OPTIONAL*.  IT IS AN  
//*       LE EXIT MODULE THAT CAN BE USED TO START DEBUG TOOL.      
//*       UNDERSTAND THE METHODS AVAILABLE FOR STARTING DEBUG TOOL, 
//*       AND CHOOSE WHETHER YOU WANT TO USE THE LE EXITS.          
//*         IF YOU USE THIS METHOD, LOAD THE CORRECT EXIT MODULE:   
//*            EQADBCXT: FOR BATCH PROGRAMS                         
//*            EQADICXT: FOR ONLINE IMS PROGRAMS                    
//*            EQADDCXT: FOR DB2 STORED PROCEDURES (OF TYPE MAIN AND SUB)
//*           (for SUB this is supported only for invocations through call_sub)
//*         (DO NOT INCLUDE AN EXIT FOR CICS PROGRAMS, OR FOR       
//*          PROGRAMS LINKED WITH THE COBOL II RUNTIME SERVICES     
//*          INSTEAD OF LANGUAGE ENVIRONMENT RUNTIME SERVICES)      
//*                                                                 
//*  SET OPTIONS FOR THIS COMPILE:                                  
//*  ---------------------------                                    
//   SET MEM=SAMII1                          PROGRAM NAME           
//   SET COB2COMP='IGY.V1R4M0.COB2COMP'      COBOL II COMPILER LIB  
//   SET DTLIB='EQAW.SEQAMOD'                DEBUG TOOL LOADLIB       
//   SET LELKED='CEE.SCEELKED'               LE LINK LIBRARY          
//   SET LELIB='CEE.SCEERUN'                 LE RUNTIME LIBRARY       
//   SET UNITDEV=SYSALLDA                    TEMP DATASET UNIT        
//   SET LANGX='EQALANGX'                    XXXLANGX UTILITY PROGRAM 
//   SET LANGXLIB='EQAW.SEQAMOD'             LIB FOR XXXLANGX UTILITY 
//*                                                                   
//*  ****************************                                     
//*        COMPILE STEP                                               
//*  ****************************                                     
//COMPILE  EXEC PGM=IGYCRCTL,REGION=4M,                               
//   PARM=('NOTEST,LIST,MAP,NOOPT,SOURCE,XREF,NONUMBER',              
//         'RES,APOST,LIB,DYNAM,NORENT,NOSSRANGE')                    
//STEPLIB  DD DISP=SHR,DSN=&COB2COMP                                  
//SYSIN    DD DISP=SHR,DSN=&SYSUID..ADLAB.SOURCE(&MEM)                
//SYSLIB   DD DISP=SHR,DSN=&SYSUID..ADLAB.COPYLIB                     
//SYSPRINT DD DISP=SHR,DSN=&SYSUID..ADLAB.LISTING(&MEM)               
//SYSLIN   DD DISP=(MOD,PASS),DSN=&&LOADSET,UNIT=&UNITDEV,            
//            SPACE=(80,(10,10))                           
//SYSUT1   DD SPACE=(80,(10,10),,,ROUND),UNIT=&UNITDEV     
//SYSUT2   DD SPACE=(80,(10,10),,,ROUND),UNIT=&UNITDEV     
//SYSUT3   DD SPACE=(80,(10,10),,,ROUND),UNIT=&UNITDEV     
//SYSUT4   DD SPACE=(80,(10,10),,,ROUND),UNIT=&UNITDEV     
//SYSUT5   DD SPACE=(80,(10,10),,,ROUND),UNIT=&UNITDEV     
//SYSUT6   DD SPACE=(80,(10,10),,,ROUND),UNIT=&UNITDEV     
//SYSUT7   DD SPACE=(80,(10,10),,,ROUND),UNIT=&UNITDEV     
//*                                                        
//CBLPRINT  EXEC PGM=IEBGENER,REGION=0M                    
//SYSPRINT  DD SYSOUT=*                                    
//SYSUT1    DD DSN=&SYSUID..ADLAB.LISTING(&MEM),DISP=SHR   
//SYSUT2    DD SYSOUT=*                                    
//SYSIN     DD DUMMY                                       
//*                                                        
//* *********************************                      
//* STEP TO GENERATE A LANGX FILE                          
//* *********************************                      
//LANGX EXEC PGM=&LANGX,REGION=32M,                                  
//   PARM='(COBOL ERROR 64K CREF'                                    
//STEPLIB  DD DISP=SHR,DSN=&LANGXLIB                                 
//         DD DISP=SHR,DSN=&LELIB                                    
//LISTING  DD DSN=&SYSUID..ADLAB.LISTING(&MEM),DISP=SHR              
//IDILANGX DD DISP=SHR,DSN=&SYSUID..ADLAB.EQALANGX(&MEM)             
//*                                                                  
//*  *********************************                               
//*        LINK-EDIT (BINDER) STEP                                   
//*  *********************************                               
//LKED EXEC PGM=IEWL,REGION=0M,COND=(5,LT,COMPILE),PARM='LIST,XREF'  
//SYSLIB   DD DISP=SHR,DSN=&LELKED                                   
//DTLIB    DD DISP=SHR,DSN=&DTLIB                                    
//SYSLMOD  DD DSN=&SYSUID..ADLAB.LOAD(&MEM),DISP=SHR                 
//SYSLIN   DD DISP=(OLD,DELETE),DSN=&&LOADSET                        
//*  INCLUDING A DEBUG TOOL LE EXIT (EQADBCXT, EQADDCXT, OR EQADICXT) IS OPTIONAL.
//*  AN EXIT ENABLES STARTING DEBUG TOOL USING THE USER EXIT DATA SET UTILITY
//*  (ONE OF THE DEBUG TOOL ISPF UTILITIES)                          
//*  //        DD *                                                  
//*   INCLUDE DTLIB(EQADBCXT)                                        
//SYSPRINT DD SYSOUT=*                                               
//SYSUT1   DD UNIT=&UNITDEV,DCB=BLKSIZE=1024,SPACE=(1024,(200,20))   

OS/VS COBOL programs

The following table shows various compiler options that can be used to prepare OS/VS COBOL programs for use with the IBM Problem Determination Tools products (Debug Tool for z/OS, Fault Analyzer for z/OS and Application Performance Analyzer for z/OS). The methods suggested in the following table indicate if the load module produced is suitable for a production environment. Load modules suitable for a production environments have no significant run-time overhead.

Table 23. Examples of compiler options and source information files supported by Problem Determination tools products for OS/VS COBOL
Compiler options Source information file type produced Is the load module production ready? Options supported and suggested for Debug Tool for z/OS Options supported and suggested for Fault Analyzer for z/OS Options supported and suggested for Application Performance Analyzer for z/OS
DMAP, NOCLIST, NOLST, PMAP, SOURCE, VERB, XREF(SHORT) Compiler listing Yes N/A Supported Supported
(LIST,NOPMAP) or (CLIST,NOPMAP) or (CLIST,PMAP) Yes N/A N/A N/A
NOBATCH, NOCLIST, NOCOUNT, DMAP, NOLST, PMAP, SOURCE, NOSYMDMP, NOTEST, NOOPT, VERB, XREF(SHORT) LANGX file Yes Suggested for production and test
Note:
The highlighted row or rows in the table above indicate the suggested compiler options and source information file types for each product.

Preparing OS/VS COBOL programs

Perform the following steps for compiling your OS/VS COBOL programs:

  1. Allocate libraries (PDSE is suggested unless PDS is required for your organization) for LANGX files. Allocate one or more LANGX libraries for each environment, such as test and production.
  2. Create a corresponding LANGX library for each load library. Specify LRECL=1562 or greater,RECFM=VB,BLKSIZE= lrecl+4 to 32k.
  3. For all programs, such as batch, CICS, and IMS, in both test and production environments, compile with the NOBATCH, NOCLIST, NOCOUNT, DMAP, NOLST, PMAP, SOURCE, NOSYMDMP, NOTEST, NOOPT, VERB, XREF(SHORT) compiler options. The module is production-ready and can be debugged using Debug Tool for z/OS.
  4. Modify the SYSPRINT DD in the compiler step to refer to a file. It can be either a permanent or temporary file. This will be the input to the xxxLANGX utility.
  5. Add a step after the compiler step to run the Problem Determination tools xxxLANGX utility. This utility program reads the compiler listing and generates a LANGX file, which is the source information file for Debug Tool for z/OS, Fault Analyzer for z/OS and Application Performance Analyzer for z/OS. Save the LANGX file in the LANGX file library, and specify a member name that is equal to the program name of your application program. Equivalent xxxLANGX utilities are available in Debug Tool for z/OS as EQALANGX, in Fault Analyzer for z/OS as IDILANGX and in Application Performance Analyzer for z/OS as CAZLANGX.
  6. Modify the promotion process to promote LANGX files. When a load module is promoted, for example, from test to production, promote the corresponding LANGX file or files. A promotion can be a recompile, copy, or move. Perform the same steps with the LANGX file that you perform with the module during promotion.

Sample JCL for compiling OS/VS COBOL programs

Below is a JCL example for compiling an OS/VS program for use with the IBM Problem Determination Tools products:

//*     - - -  ADD A JOB CARD ABOVE THIS LINE  - - -
//*
//*  SAMPLE JCL TO PREPARE AN OS VS COBOL PROGRAM
//*  FOR THE IBM ZSERIES PD TOOLS PRODUCTS:
//*     FAULT ANALYZER, DEBUG TOOL, AND APPLICATION PERF. ANALYZER
//*
//*  NOTES:
//*
//*   COMPILER:
//*    -  COMPILER PARMS DMAP,NOCLIST,NOLST,PMAP,SOURCE,VERB,XREF
//*       ARE REQUIRED IF YOU PLAN TO USE THE COMPILER LISTING WITH
//*       PD TOOLS AND/OR PROCESS IT WITH XXXLANGX
//*
//*   A STEP THAT PROCESSES THE SYSADATA FILE,
//*   AND CREATES A LANGX FILE IS NEEDED.
//*
//*  SET PARMS FOR THIS COMPILE:
//*  ---------------------------
// SET MEM=SAMOS1                       PROGRAM NAME
// SET OSVSCOMP='IGY.VSCOLIB'           OS VS COBOL COMPILER LIBRARY
// SET LELIB='CEE.SCEELKED'             LE LINKEDIT LIBRARY
// SET UNITDEV=SYSALLDA                 UNIT FOR TEMP FILES
// SET SCEERUN='CEE.SCEERUN'            LANGUAGE ENVIRON SCEERUN LIB
// SET LANGX='EQALANGX'                 XXXLANGX UTILITY PROGRAM
// SET LANGXLIB='EQAW.SEQAMOD'          LIBRARY FOR XXXLANGX UTILITY
//*    NOTE: THE XXXLANGX UTILITY IS AVAILABLE WITH DEBUG TOOL,
//*          FAULT ANALYZER, AND APA WITH DIFFERENT NAMES.  YOU CAN
//*          USE ANY OF THEM... THEY ALL PRODUCE THE SAME RESULTS.
//*      IF YOU HAVE DEBUG TOOL, YOU CAN SET:
//*         LANGX='EQALANGX'  LANGXLIB=(THE DT SEQAMOD LIBRARY)
//*      IF YOU HAVE FAULT ANALYZER YOU CAN SET:
//*         LANGX='IDILANGX'  LANGXLIB=(THE FA SIDIAUTH LIBRARY)
//*      IF YOU HAVE APA (APP. PERFORMANCE ANALYZER) YOU CAN SET:
//*         LANGX='CAZLANGX'  LANGXLIB=(THE APA SCAZAUTH LIBRARY)
//*
//*  ****************************
//*        COMPILE STEP
//*  ****************************
//COMPILE  EXEC PGM=IKFCBL00,REGION=4M,
//   PARM=('DMAP,NOCLIST,NOLST,NOOPT,SOURCE,VERB,XREF(SHORT)')
//*   FOR DT (CHECK DEFAULTS): NOBATCH,NOCOUNT,PMAP,NOSYMDMP,NOTEST
//STEPLIB  DD DISP=SHR,DSN=&OSVSCOMP
//SYSIN    DD DISP=SHR,DSN=&SYSUID..ADLAB.SOURCE(&MEM)
//SYSLIB   DD DISP=SHR,DSN=&SYSUID..ADLAB.COPYLIB
//SYSPRINT DD DISP=SHR,DSN=&SYSUID..ADLAB.OSVSCOB.LISTING(&MEM)
//SYSLIN   DD DISP=(MOD,PASS),DSN=&&LOADSET,UNIT=&UNITDEV,
//            SPACE=(80,(10,10))
//SYSUT1   DD SPACE=(80,(10,10),,,ROUND),UNIT=&UNITDEV
//SYSUT2   DD SPACE=(80,(10,10),,,ROUND),UNIT=&UNITDEV
//SYSUT3   DD SPACE=(80,(10,10),,,ROUND),UNIT=&UNITDEV
//SYSUT4   DD SPACE=(80,(10,10),,,ROUND),UNIT=&UNITDEV
//SYSUT5   DD SPACE=(80,(10,10),,,ROUND),UNIT=&UNITDEV
//SYSUT6   DD SPACE=(80,(10,10),,,ROUND),UNIT=&UNITDEV
//SYSUT7   DD SPACE=(80,(10,10),,,ROUND),UNIT=&UNITDEV
//*
//CBLPRINT  EXEC PGM=IEBGENER,REGION=0M
//SYSPRINT  DD SYSOUT=*
//SYSUT1    DD DSN=&SYSUID..ADLAB.OSVSCOB.LISTING(&MEM),DISP=SHR
//SYSUT2    DD SYSOUT=*
//SYSIN     DD DUMMY
//*
//*  *********************************
//*     STEP TO GENERATE LANGX FILE
//*  *********************************
//LANGX    EXEC PGM=&LANGX,REGION=32M,
//  PARM='(COBOL ERROR 64K CREF'
//STEPLIB  DD DISP=SHR,DSN=&LANGXLIB
//         DD DISP=SHR,DSN=&SCEERUN
//LISTING  DD DSN=&SYSUID..ADLAB.OSVSCOB.LISTING(&MEM),DISP=SHR
//IDILANGX DD DISP=SHR,DSN=&SYSUID..ADLAB.EQALANGX(&MEM)
//*
//*  *********************************
//*        LINK-EDIT (BINDER) STEP
//*  *********************************
//LKED EXEC PGM=IEWL,REGION=0M,COND=(5,LT,COMPILE),PARM='LIST,XREF'
//SYSLIB   DD DISP=SHR,DSN=&LELIB
//SYSLMOD  DD DSN=&SYSUID..ADLAB.LOAD(&MEM),DISP=SHR
//SYSLIN   DD DISP=(OLD,DELETE),DSN=&&LOADSET
//SYSPRINT DD SYSOUT=*
//SYSUT1   DD UNIT=&UNITDEV,DCB=BLKSIZE=1024,SPACE=(1024,(200,20))

Enterprise PL/I Version 3.7 and later programs

The following table shows various compiler options that can be used to prepare Enterprise PL/I Version 3.7 and later programs for use with the IBM Problem Determination Tools products (IBM Debug Tool for z/OS, IBM Fault Analyzer for z/OS and IBM Application Performance Analyzer for z/OS). The methods suggested in the following table indicate if the load module produced is suitable for a production environment. Load modules suitable for production environments have no significant run-time overhead.

Table 24. Examples of compiler options and source information files supported by IBM Problem Determination Tools products for Enterprise PL/I Version 3.7 and later
Compiler options Source information file type produced Is the load module production ready? Options supported and suggested for Debug Tool for z/OS Options supported and suggested for Fault Analyzer for z/OS Options supported and suggested for Application Performance Analyzer for z/OS
For Enterprise PL/I Version 3.7: TEST(ALL, SYM, NOHOOK, SEPARATE, SEPNAME, AALL), NOPT, AGGREGATE, ATTRIBUTES (FULL), NOBLKOFF, LIST, MAP, NEST, NONUMBER, OFFSET, OPTIONS, SOURCE, STMT, XREF(FULL)

For Enterprise PL/I Version 3.8 and later: TEST(ALL, SYM, NOHOOK, SEPARATE, SEPNAME), LISTVIEW(AALL), NOPT, AGGREGATE, ATTRIBUTES (FULL), NOBLKOFF, LIST, MAP, NEST, NONUMBER, OFFSET, OPTIONS, SOURCE, STMT, XREF(FULL)

SYSDEBUG file used by Debug Tool for z/OS and Fault Analyzer for z/OS. LANGX file used by Application Performance Analyzer for z/OS Although the module is larger than a module compiled with the NOTEST option, you can use the module in production if needed. Suggested for test. You can also use these options in a production environment if the increased load module size is not an issue.
AGGREGATE, ATTRIBUTES (FULL), NOBLKOFF, LIST, MAP, NEST, NOTEST, NONUMBER, OFFSET, OPTIONS, SOURCE, STMT, XREF(FULL) Compiler listing Yes N/A Supported N/A
LANGX file Yes N/A Suggested for production and test
Note:
The highlighted row or rows in the table above indicate the suggested compiler options and source information file types for each product.

Preparing Enterprise PL/I Version 3.7 and later programs

Perform the following steps for compiling your Enterprise PL/I Version 3.7 and later programs:

  1. Create a library (PDSE is suggested unless PDS is required for your organization) for SYSDEBUG files. This is only needed in test environments where debugging will be performed using LRECL=(80 to 1024),RECFM=FB,BLKSIZE=(multiple of lrecl < 32K).
  2. Allocate one or more LANGX libraries for each environment, such as test and production.
  3. Create a corresponding LANGX library for each load library. Specify LRECL=1562 or greater,RECFM=VB,BLKSIZE= lrecl+4 to 32k.
  4. For all programs, such as batch, CICS, and IMS:
  5. When a TEST(...SEPARATE) option is used, code a SYSDEBUG DD in the second compiler step as follows:

     //SYSDEBUG DD DSN= sysdebug.pds(pgmname),DISP=SHR

    This is the source information file for IBM Debug Tool for z/OS, and optionally, IBM Fault Analyzer for z/OS. Save it in the SYSDEBUG library, and specify a member name that is equal to the primary entry point name or CSECT name of your application program.

  6. Modify the SYSPRINT DD in the compiler step. This is the compiler listing. Write the listing to either a permanent or temporary file. This is the input to the xxxLANGX utility.
    Note:
    This compiler typically renames CSECTs according to an internal compiler algorithm. Therefore, it is not recommended to store PL/I compiler listings or side files using CSECT names as they might not be found by IBM Application Performance Analyzer for z/OS or IBM Fault Analyzer for z/OS. Instead, use the primary entry point name.
  7. Add a step after the compile step to run the xxxLANGX utility. This utility reads the compiler listing and generates a LANGX file. This is the source information file for IBM Fault Analyzer for z/OS and IBM Application Performance Analyzer for z/OS. Equivalent xxxLANGX utilities are available in IBM Debug Tool for z/OS as EQALANGX, in IBM Fault Analyzer for z/OS as IDILANGX and in IBM Application Performance Analyzer for z/OS as CAZLANGX. Save the LANGX file in the LANGX file library, and specify a member name that is equal to the primary entry point name of your application program.
  8. Modify the promotion process to promote LANGX files. When a load module is promoted, for example, from test to production, promote the corresponding LANGX file or files. A promotion can be a recompile, copy, or move. Perform the same steps with the LANGX file that you perform with the module during promotion.
  9. If you compile with the TEST option and will promote these modules into production, promote the SYSDEBUG file for your production environment.
  10. Optionally, include a Debug Tool Language Environment exit module into the load module during the linkage editor step. This is one way to enable Debug Tool's panel 6 in ISPF, a simple panel-driven method to start the debugger automatically when a program runs, without JCL changes, based on the program name and user ID. Use module EQADBCXT for batch programs (including IMS batch), EQADICXT for IMS/TM programs and EQADDCXT for DB2 stored procedures. Do not include the exit module for CICS programs.

Sample JCL for compiling Enterprise PL/I for z/OS Version 3.7 or later programs

Below is a JCL example for compiling an Enterprise PL/I for z/OS Version 3.7 or later program for use with the IBM Problem Determination Tools products.

//* - - - ADD A JOB CARD ABOVE THIS LINE - - -
//*
//* SAMPLE JCL TO PREPARE AN ENTERPRISE PL/I V3.7 OR LATER
//* PROGRAM FOR THE IBM ZSERIES PD TOOLS PRODUCTS:
//* FAULT ANALYZER, DEBUG TOOL, AND APPLICATION PERF. ANALYZER
//*
//* NOTES:
//*
//* COMPILER:
//* 1. COMPILER PARMS TEST IS REQUIRED FOR DEBUG TOOL
//* 2. COMPILER PARM NOPT IS RECOMMENDED FOR DEBUG TOOL
//* 3. COMPILER PARM:
//*     TEST(ALL,SYM,NOHOOK,SEPARATE,SEPNAME,AALL) (V3.7)
//*     TEST(ALL,SYM,NOHOOK,SEPARATE,SEPNAME),LISTVIEW(AALL), (V3.8+)
//*    IS USED BECAUSE:
//*    - THE MODULE IS READY FOR DEBUG TOOL
//*    - NOHOOK DOES NOT HAVE RUN-TIME CPU OVERHEAD. HOWEVER, THE
//*      MODULE IS LARGER BECAUSE OF STATEMENT TABLE
//*    - A SYSDEBUG FILE IS CREATED THAT CAN BE USED BY DT,FA,APA
//* 4. COMPILER PARMS AGGREGATE,ATTRIBUTES(FULL),NOBLKOFF,LIST,
//*    MAP,NEST,NONUMBER,OPTIONS,SOURCE,STMT,XREF(FULL) ARE NEEDED
//*    TO PROCESS THE COMPILER LISTING WITH XXXLANGX
//*
//* BINDER (LINKAGE EDITOR):
//* 5. THE INCLUDE FOR MODULE EQAD?CXT IS OPTIONAL. IT IS AN
//*    LE EXIT MODULE THAT CAN BE USED TO START DEBUG TOOL.
//*    UNDERSTAND THE METHODS AVAILABLE FOR STARTING DEBUG TOOL,
//*    AND CHOOSE WHETHER YOU WANT TO USE THE LE EXITS.
//*    IF YOU USE THIS METHOD, LOAD THE CORRECT EXIT MODULE:
//*      EQADBCXT: FOR BATCH PROGRAMS
//*      EQADICXT: FOR ONLINE IMS PROGRAMS
//*      EQADDCXT: FOR DB2 STORED PROCEDURES (OF TYPE MAIN AND SUB)
//*           (for SUB this is supported only for invocations through call_sub)
//*    (DO NOT INCLUDE AN EXIT FOR CICS PROGRAMS)
//*
//* SET PARMS FOR THIS COMPILE:
//* ---------------------------
//  SET MEM=PADSTAT                   PROGRAM NAME
//  SET PLICOMP='IBMZ.V3R7.SIBMZCMP'  PLI COMPILER LOADLIB
//  SET DTLIB='EQAW.SEQAMOD'          DEBUG TOOL LOADLIB
//  SET LEHLQ='CEE'                   LE HIGH LVL QUALIFIER
//  SET UNITDEV=SYSALLDA              UNIT FOR TEMP FILES
//  SET LANGX='EQALANGX'              XXXLANGX UTILITY PROGRAM
//  SET LANGXLIB='EQAW.SEQAMOD'       LIBRARY FOR XXXLANGX UTILITY
//*   NOTE: YOU CAN USE THE XXXLANGX UTILITY SHIPPED WITH DT, FA,
//*         OR APA. THE NAMES ARE DIFFERENT, BUT RESULTS ARE THE SAME.
//*         USE ANY OF THEM... THEY ALL PRODUCE THE SAME RESULTS.
//* IF YOU HAVE:     SET LANGX TO:    SET LANGXLIB TO:
//* DEBUG TOOL       EQALANGX         THE DT SEQAMOD LIBRARY
//* FAULT ANALYZER   IDILANGX         THE FA SIDIAUTH LIBRARY
//* APA              CAZLANGX         THE APA SCAZAUTH LIBRARY
//*
//ALLOCOBJ EXEC PGM=IEFBR14 ALLOC OBJ LIB IF NEEDED
//OBJ DD DSN=&SYSUID..ADLAB.OBJ,SPACE=(CYL,(3,1,15)), 
// DSORG=PO,RECFM=FB,LRECL=80,BLKSIZE=8000,DISP=(MOD,CATLG) 
//* 
//* *************************************** 
//* COMPILE STEP  
//* *************************************** 
//COMPILE EXEC PGM=IBMZPLI,REGION=0M, 
// PARM=('TEST(ALL,SYM,NOHOOK,SEPARATE,SEPNAME,AALL),LIST,MAP,SOURCE,', 
// 'XREF(FULL),NOBLKOFF,AGGREGATE,ATTRIBUTES(FULL),NEST,OPTIONS,NOPT,', 
// 'STMT,NONUMBER,OFFSET') 
//*  Note: The above options are for Enterprise PL/I Version 3.7 
//*        For Enterprise PL/I Version 3.8+, change the TEST option 
//*        to  TEST(ALL,SYM,NOHOOK,SEPARATE,SEPNAME), and add the 
//*        LISTVIEW(AALL) option 
//STEPLIB  DD DSN=&PLICOMP,DISP=SHR 
//         DD DSN=&LEHLQ..SCEERUN,DISP=SHR 
//SYSIN    DD DISP=SHR,DSN=&SYSUID..ADLAB.SOURCE(&MEM) 
//SYSLIB   DD DISP=SHR,DSN=&SYSUID..ADLAB.COPYLIB
//SYSPRINT DD DISP=SHR,DSN=&SYSUID..ADLAB.ENTPLI.LISTING(&MEM) 
//SYSDEBUG DD DISP=SHR,DSN=&SYSUID..ADLAB.SYSDEBUG(&MEM) 
//SYSUT1   DD SPACE=(CYL,(5,2),,CONTIG),DCB=BLKSIZE=1024,UNIT=&UNITDEV
//SYSLIN   DD DSN=&SYSUID..ADLAB.OBJ(&MEM),DISP=SHR 
//* 
//PLIPRINT EXEC PGM=IEBGENER,REGION=0M 
//SYSPRINT DD SYSOUT=* 
//SYSUT1   DD DSN=&SYSUID..ADLAB.ENTPLI.LISTING(&MEM),DISP=SHR 
//SYSUT2   DD SYSOUT=* 
//SYSIN    DD DUMMY 
//* 
//* ********************************* 
//* STEP TO GENERATE LANGX FILE 
//* ********************************* 
//LANGX EXEC PGM=&LANGX,REGION=32M, 
// PARM='(PLI ERROR 64K CREF' 
//STEPLIB  DD DISP=SHR,DSN=&LANGXLIB
//         DD DISP=SHR,DSN=&LEHLQ..SCEERUN
//LISTING  DD DSN=&SYSUID..ADLAB.ENTPLI.LISTING(&MEM),DISP=SHR 
//IDILANGX DD DISP=SHR,DSN=&SYSUID..ADLAB.EQALANGX(&MEM) 
//* 
//* ********************************* 
//* LINK-EDIT (BINDER) STEP 
//* ********************************* 
//LINK EXEC PGM=IEWL,PARM=(LET,MAP,LIST),REGION=0M 
//SYSLIB   DD DSN=&LEHLQ..SCEELKED,DISP=SHR 
//DTLIB    DD DSN=&DTLIB,DISP=SHR 
//SYSPRINT DD SYSOUT=* 
//SYSLMOD  DD DISP=SHR,DSN=&SYSUID..ADLAB.LOAD(&MEM) 
//SYSUT1   DD UNIT=SYSDA,SPACE=(TRK,(10,10)) 
//SYSLIN   DD DSN=&SYSUID..ADLAB.OBJ(&MEM),DISP=(OLD,PASS) 
//* INCLUDING A DEBUG TOOL LE EXIT (EQADBCXT, EQADDCXT, OR EQADICXT) 
//* IS OPTIONAL. THE EXIT ENABLES STARTING DEBUG TOOL WITH THE 
//* USER EXIT DATA SET UTILITY (ONE OF THE DEBUG TOOL ISPF UTILITIES) 
//* 
//* //  DD * 
//* INCLUDE DTLIB(EQADBCXT)

Enterprise PL/I Version 3.5 and Version 3.6 programs

The following table shows various compiler options that can be used to prepare Enterprise PL/I Version 3.5 and Version 3.6 programs for use with the IBM Problem Determination Tools products (IBM Debug Tool for z/OS, IBM Fault Analyzer for z/OS and IBM Application Performance Analyzer for z/OS). The methods suggested in the following table indicate if the load module produced is suitable for a production environment. Load modules suitable for a production environments have no significant run-time overhead.

Table 25. Examples of compiler options and source information files supported by IBM Problem Determination Tools products for Enterprise PL/I Version 3.5 and Version 3.6
Compiler options Source information file type produced Is the load module production ready? Options supported and suggested for Debug Tool for z/OS Options supported and suggested for Fault Analyzer for z/OS Options supported and suggested for Application Performance Analyzer for z/OS
Preprocess (1st stage) to expand source, In compile (2nd stage):

For Enterprise PL/I Version 3.5: TEST(ALL, SYM, NOHOOK, SEPARATE), NOPT, AGGREGATE, ATTRIBUTES (FULL), NOBLKOFF, LIST, MAP, NEST, NONUMBER, OFFSET, OPTIONS, SOURCE, STMT, XREF(FULL)

For Enterprise PL/I Version 3.6: TEST(ALL, SYM, NOHOOK, SEPARATE, SEPNAME), NOPT, AGGREGATE, ATTRIBUTES (FULL), NOBLKOFF, LIST, MAP, NEST, NONUMBER, OFFSET, OPTIONS, SOURCE, STMT, XREF(FULL)

SYSDEBUG file used by Debug Tool for z/OS and Fault Analyzer for z/OS. LANGX file used by Application Performance Analyzer for z/OS Although the module is larger than a module compiled with the NOTEST option, you can use the module in production if needed. Suggested for test. You can also use these options in a production environment if the increased load module size is not an issue.
AGGREGATE, ATTRIBUTES (FULL), NOBLKOFF, LIST, MAP, NEST, NOTEST, NONUMBER, OFFSET, OPTIONS, SOURCE, STMT, XREF(FULL) Compiler listing Yes N/A Supported N/A
LANGX file Yes N/A Suggested for production and test
Note:
The highlighted row or rows in the table above indicate the suggested compiler options and source information file types for each product.

Preparing Enterprise PL/I Version 3.5 and Version 3.6 programs

Perform the following steps for compiling your Enterprise PL/I Version 3.5 and Version 3.6 programs:

  1. Create a library (PDSE is suggested unless PDS is required for your organization) for SYSDEBUG files. This is only needed in test environments where debugging will be performed using LRECL=(80 to 1024),RECFM=FB,BLKSIZE=(multiple of lrecl < 32K).
  2. Allocate one or more LANGX libraries for each environment, such as test and production.
  3. Create a corresponding LANGX library for each load library. Specify LRECL=1562 or greater,RECFM=VB,BLKSIZE= lrecl+4 to 32k.
  4. Run a two-stage compile. The first stage preprocesses the program, so the IBM Problem Determination Tools products have access to fully expanded source code with INCLUDEs and macros. The second stage compiles the program. For all programs, such as batch, CICS, and IMS:

    NOTEST disables Debug Tool, but produces a smaller load module.

    The other options format the compiler listing as required for the xxxLANGX utility to produce a production-ready module that can be used with Fault Analyzer for z/OS and Application Performance Analyzer for z/OS (but not Debug Tool for z/OS).

  5. When a TEST(...SEPARATE) parm is used, code a SYSDEBUG DD in the second compiler step as follows:

     //SYSDEBUG DD DSN= sysdebug.pds(pgmname),DISP=SHR

    This is the source information file for IBM Debug Tool for z/OS, IBM Application Performance Analyzer for z/OS and optionally, IBM Fault Analyzer for z/OS. Save it in the SYSDEBUG library, and specify a member name that is equal to the primary entry point name or CSECT name of your application program.

  6. Modify the SYSPRINT DD in the second compiler stage. This is the compiler listing. Write the listing to either a permanent or temporary file. This is the input to the xxxLANGX utility.
    Note:
    This compiler typically renames CSECTs according to an internal compiler algorithm. Therefore, it is not recommended to store PL/I compiler listings or side files using CSECT names as they might not be found by IBM Application Performance Analyzer for z/OS or IBM Fault Analyzer for z/OS. Instead, use the primary entry point name.
  7. Add a step after the compile step to run the xxxLANGX utility. This utility reads the compiler listing and generates a LANGX file. This is the source information file for IBM Fault Analyzer for z/OS and IBM Application Performance Analyzer for z/OS. Equivalent xxxLANGX utilities are available in IBM Debug Tool for z/OS as EQALANGX, in IBM Fault Analyzer for z/OS as IDILANGX and in IBM Application Performance Analyzer for z/OS as CAZLANGX. Save the LANGX file in the LANGX file library, and specify a member name that is equal to the primary entry point name of your application program.
  8. Modify the promotion process to promote LANGX files. When a load module is promoted, for example, from test to production, promote the corresponding LANGX file or files. A promotion can be a recompile, copy, or move. Perform the same steps with the LANGX file that you perform with the module during promotion.
  9. If you compile with the TEST option and will promote these modules into production, promote the SYSDEBUG file for your production environment.
  10. Optionally, include a Debug Tool Language Environment exit module into the load module during the linkage editor step. This is one way to enable Debug Tool's panel 6 in ISPF, a simple panel-driven method to start the debugger automatically when a program runs, without JCL changes, based on the program name and user ID. Use module EQADBCXT for batch programs (including IMS batch), EQADICXT for IMS/TM programs and EQADDCXT for DB2 stored procedures. Do not include the exit module for CICS programs.

Sample JCL for compiling Enterprise PL/I Version 3.5 or Version 3.6 programs

Below is a JCL example for compiling an Enterprise PL/I for z/OS Version 3.5 or Version 3.6 program for use with the IBM Problem Determination Tools products.

//*     - - -  ADD A JOB CARD ABOVE THIS LINE  - - -
//*
//* SAMPLE JCL TO PREPARE AN ENTERPRISE PL/I V3.5 OR
//* ENTERPRISE PL/I V3.6 PROGRAM FOR THE IBM ZSERIES
//* FOR THE IBM ZSERIES PD TOOLS PRODUCTS:
//* FAULT ANALYZER, DEBUG TOOL, AND APPLICATION PERF. ANALYZER
//*
//* NOTES:
//*
//* COMPILER:
//* 1. A 2-STAGE COMPILE IS PERFORMED. STAGE 1 (PREPROCESS) IS
//*    DONE TO EXPAND INCLUDES AND MACROS IN THE PROGRAM, SO THAT
//*    THE SYSDEBUG FILE CREATED IN STAGE 2 (COMPILE) HAS ALL STMTS.
//* 2. COMPILER PARMS TEST AND NOPT ARE REQUIRED FOR DEBUG TOOL
//* 3. COMPILER PARM TEST(ALL,SYM,NOHOOK,SEP) (V3.5) OR
//*    TEST(ALL,SYM,NOHOOK,SEP,SEPNAME) (V3.6) IS USED BECAUSE:
//*    - THE MODULE IS READY FOR DEBUG TOOL
//*         - NOHOOK DOES NOT HAVE RUN-TIME CPU OVERHEAD. HOWEVER, THE
//*           MODULE IS LARGER BECAUSE OF STATEMENT TABLE
//*         - A SYSDEBUG FILE IS CREATED THAT CAN BE USED BY DT,FA,APA
//*    4. COMPILER PARMS AGGREGATE,ATTRIBUTES(FULL),NOBLKOFF,LIST,
//*       MAP,NEST,NONUMBER,OPTIONS,SOURCE,STMT,XREF(FULL) ARE NEEDED
//*       TO PROCESS THE COMPILER LISTING WITH XXXLANGX
//*
//*   BINDER (LINKAGE EDITOR):
//*    5. THE INCLUDE FOR MODULE EQAD?CXT IS OPTIONAL.  IT IS AN
//*       LE EXIT MODULE THAT CAN BE USED TO START DEBUG TOOL.
//*       UNDERSTAND THE METHODS AVAILABLE FOR STARTING DEBUG TOOL,
//*       AND CHOOSE WHETHER YOU WANT TO USE THE LE EXITS.
//*         IF YOU USE THIS METHOD, LOAD THE CORRECT EXIT MODULE:
//*            EQADBCXT: FOR BATCH PROGRAMS
//*            EQADICXT: FOR ONLINE IMS PROGRAMS
//*            EQADDCXT: FOR DB2 STORED PROCEDURES (OF TYPE MAIN AND SUB)
//*           (for SUB this is supported only for invocations through call_sub)
//*            (DO NOT INCLUDE AN EXIT FOR CICS PROGRAMS)
//*
//*  SET PARMS FOR THIS COMPILE:
//*  ---------------------------
//   SET MEM=PADSTAT                      PROGRAM NAME
//   SET PLICOMP='IBMZ.V3R5.SIBMZCMP'     PLI COMPILER LOADLIB
//   SET DTLIB='EQAW.SEQAMOD'             DEBUG TOOL LOADLIB
//   SET LEHLQ='CEE'                      LE HIGH LVL QUALIFIER
//   SET UNITDEV=SYSALLDA                 UNIT FOR TEMP FILES
//   SET LANGX='EQALANGX'                 XXXLANGX UTILITY PROGRAM
//   SET LANGXLIB='EQAW.SEQAMOD'          LIBRARY FOR XXXLANGX UTILITY
//*    NOTE: YOU CAN USE THE XXXLANGX UTILITY SHIPPED WITH DT, FA,
//*          OR APA. THE NAMES ARE DIFFERENT, BUT RESULTS ARE THE SAME
//*          USE ANY OF THEM... THEY ALL PRODUCE THE SAME RESULTS.
//*      IF YOU HAVE:     SET LANGX TO:    SET LANGXLIB TO:
//*      DEBUG TOOL       EQALANGX         THE DT SEQAMOD LIBRARY
//*      FAULT ANALYZER   IDILANGX         THE FA SIDIAUTH LIBRARY
//*      APA              CAZLANGX         THE APA SCAZAUTH LIBRARY
//*
//ALLOCOBJ EXEC PGM=IEFBR14              ALLOC OBJ LIB IF NEEDED
//OBJ   DD DSN=&SYSUID..ADLAB.OBJ,SPACE=(CYL,(3,1,15)),
//  DSORG=PO,RECFM=FB,LRECL=80,BLKSIZE=8000,DISP=(MOD,CATLG)
//*  ***************************************
//*     PREPROCESS STEP (COMPILE STAGE 1)
//*  ***************************************
//PRECOMP  EXEC PGM=IBMZPLI,REGION=0M,
//   PARM=('MACRO,MDECK,NOCOMPILE,NOSYNTAX,INSOURCE')
//STEPLIB  DD   DSN=&PLICOMP,DISP=SHR
//         DD   DSN=&LEHLQ..SCEERUN,DISP=SHR
//SYSIN    DD   DISP=SHR,DSN=&SYSUID..ADLAB.SOURCE(&MEM)
//SYSLIB   DD   DISP=SHR,DSN=&SYSUID..ADLAB.COPYLIB
//SYSPRINT DD   SYSOUT=*
//SYSUT1   DD   SPACE=(1024,(200,50),,CONTIG,ROUND),DCB=BLKSIZE=1024,
//             UNIT=&UNITDEV
//SYSPUNCH DD DISP=(MOD,PASS),DSN=&&SRC1,UNIT=&UNITDEV,
//            SPACE=(80,(10,10))
//*
//*  ***************************************
//* COMPILE STEP (COMPILE STAGE 2)
//* ***************************************
//COMPILE EXEC PGM=IBMZPLI,REGION=0M,
// PARM=('TEST(ALL,SYM,NOHOOK,SEPARATE),LIST,MAP,SOURCE,XREF(FULL),',
// 'NOBLKOFF,AGGREGATE,ATTRIBUTES(FULL),NEST,OPTIONS,NOPT,',
// 'STMT,NONUMBER,OFFSET')
//*  Note: The above options are for Enterprise PL/I Version 3.5
//*        For Enterprise PL/I Version 3.6, change the TEST option
//*        to:  TEST(ALL,SYM,NOHOOK,SEPARATE,SEPNAME)
//STEPLIB  DD DSN=&PLICOMP,DISP=SHR
//         DD DSN=&LEHLQ..SCEERUN,DISP=SHR
//SYSIN    DD DSN=&&SRC1,DISP=(OLD,PASS)
//SYSLIB   DD DISP=SHR,DSN=&SYSUID..ADLAB.COPYLIB
//SYSPRINT DD DISP=SHR,DSN=&SYSUID..ADLAB.ENTPLI.LISTING(&MEM)
//SYSDEBUG DD DISP=SHR,DSN=&SYSUID..ADLAB.SYSDEBUG(&MEM)
//SYSUT1   DD SPACE=(CYL,(5,2),,CONTIG),DCB=BLKSIZE=1024,UNIT=&UNITDEV
//SYSLIN   DD DSN=&SYSUID..ADLAB.OBJ(&MEM),DISP=SHR
//*
//PLIPRINT  EXEC PGM=IEBGENER,REGION=0M
//SYSPRINT  DD SYSOUT=*
//SYSUT1    DD DSN=&SYSUID..ADLAB.ENTPLI.LISTING(&MEM),DISP=SHR
//SYSUT2    DD SYSOUT=*
//SYSIN     DD DUMMY
//*
//*  *********************************
//*     STEP TO GENERATE LANGX FILE
//*  *********************************
//LANGX    EXEC PGM=&LANGX,REGION=32M,
//  PARM='(PLI ERROR 64K CREF'
//STEPLIB  DD DISP=SHR,DSN=&LANGXLIB
//         DD DISP=SHR,DSN=&LEHLQ..SCEERUN
//LISTING  DD DSN=&SYSUID..ADLAB.ENTPLI.LISTING(&MEM),DISP=SHR
//IDILANGX DD DISP=SHR,DSN=&SYSUID..ADLAB.EQALANGX(&MEM)
//*
//* *********************************
//* LINK-EDIT (BINDER) STEP
//* *********************************
//LINK EXEC PGM=IEWL,PARM=(LET,MAP,LIST),REGION=0M
//SYSLIB DD DSN=&LEHLQ..SCEELKED,DISP=SHR
//DTLIB DD DSN=&DTLIB,DISP=SHR
//SYSPRINT DD SYSOUT=*
//SYSLMOD DD DISP=SHR,DSN=&SYSUID..ADLAB.LOAD(&MEM)
//SYSUT1 DD UNIT=SYSDA,SPACE=(TRK,(10,10))
//SYSLIN DD DSN=&SYSUID..ADLAB.OBJ(&MEM),DISP=(OLD,PASS)
//*  INCLUDING A DEBUG TOOL LE EXIT (EQADBCXT, EQADDCXT, OR EQADICXT)
//*  IS OPTIONAL.  THE EXIT ENABLES STARTING DEBUG TOOL WITH THE
//*  USER EXIT DATA SET UTILITY (ONE OF THE DEBUG TOOL ISPF UTILITIES)
//*  //        DD *
//*   INCLUDE DTLIB(EQADBCXT)

Enterprise PL/I Version 3.4 and earlier programs

The following table shows various compiler options that can be used to prepare Enterprise PL/I Version 3.4 and earlier programs for use with the IBM Problem Determination Tools products (Debug Tool for z/OS, Fault Analyzer for z/OS and Application Performance Analyzer for z/OS). The methods suggested in the following table indicate if the load module produced is suitable for a production environment. Load modules suitable for a production environments have no significant run-time overhead.

Table 26. Examples of compiler options and source information files supported by IBM Problem Determination Tools products for Enterprise PL/I Version 3.4 and earlier
Compiler options Source information file type produced Is the load module production ready? Options supported and suggested for Debug Tool for z/OS Options supported and suggested for Fault Analyzer for z/OS Options supported and suggested for Application Performance Analyzer for z/OS
Preprocess (1st stage) to expand source, In compile (2nd stage): TEST(ALL), NOPT, AGGREGATE, ATTRIBUTES (FULL), NOBLKOFF, LIST, MAP, NEST, NONUMBER, OFFSET, OPTIONS, SOURCE, STMT, XREF(FULL)) Expanded source file used by Debug Tool for z/OS, LANGX file used by Fault Analyzer for z/OS and Application Performance Analyzer for z/OS No Suggested for test. (Using Debug Tool in production for this compiler is not recommended.)
AGGREGATE, ATTRIBUTES (FULL), NOBLKOFF, LIST, MAP, NEST, NOTEST, NONUMBER, OFFSET, OPTIONS, SOURCE, STMT, XREF(FULL)) Compiler listing Yes N/A Supported N/A
LANGX file Yes N/A Suggested for production and test
Note:
The highlighted row or rows in the table above indicate the suggested compiler options and source information file types for each product.

Preparing Enterprise PL/I Version 3.4 and earlier programs

Perform the following steps for compiling your Enterprise PL/I Version 3.4 and earlier programs:

  1. Create a library (PDSE is suggested unless PDS is required for your organization) for expanded source files. This is only needed in test environments where debugging will be performed. The library can be any RECFM / LRECL / BLKSIZE supported as input by the compiler.
  2. Allocate libraries (PDSE is suggested unless PDS is required for your organization) for LANGX files. Allocate one or more LANGX libraries for each environment, such as test or production.
  3. Create a corresponding LANGX library for each load library. Specify LRECL=1562 or greater,RECFM=VB,BLKSIZE= lrecl+4 to 32k.
  4. Run a 2-stage compile. The first stage preprocesses the program, so the IBM Problem Determination Tools have access to fully expanded source code with INCLUDEs and macros. The second stage compiles the program.
  5. Modify the SYSPRINT DD in the second compiler stage. This is the compiler listing. Save the compiler listing to either a permanent or temporary file. This will be the input to the xxxLANGX utility.
    Note:
    This compiler typically renames CSECTs according to an internal compiler algorithm. Therefore, it is not recommended to store PL/I compiler listings or side files using CSECT names as they might not be found by Application Performance Analyzer for z/OS or Fault Analyzer for z/OS. Instead, use the primary entry point name.
  6. Add a step after the compiler step to run the xxxLANGX utility. The xxxLANGX utility reads the compiler listing and generates a LANGX file, which is the source information file for Fault Analyzer for z/OS and Application Performance Analyzer for z/OS. Equivalent xxxLANGX utilities are available in Debug Tool for z/OS as EQALANGX, in Fault Analyzer for z/OS as IDILANGX and in Application Performance Analyzer for z/OS as CAZLANGX. Save the LANGX file in the LANGX file library, and specify a member name that is equal to the primary entry point name or CSECT name of your application program.
  7. Modify the promotion process to promote LANGX files. When a load module is promoted, for example, from test to production, promote the corresponding LANGX file or files. A promotion can be a recompile, copy, or move. Perform the same steps with the LANGX file that you perform with the module during promotion.
  8. Optionally, include a Debug Tool Language Environment exit module into the load module during the linkage editor step. This is one way to enable Debug Tool's panel 6 in ISPF, a simple panel-driven method to start the debugger automatically when a program runs, without JCL changes, based on the program name and user ID. Use module EQADBCXT for batch programs (including IMS batch), EQADICXT for IMS/TM programs and EQADDCXT for DB2 stored procedures. Do not include the exit module for CICS programs.
  9. For CICS applications only, if the Debug Tool DTCN transaction will be used to start Debug Tool, link edit the Debug Tool CICS startup exit module EQADCCXT into the application load module to enable Debug Tool in CICS. This is not needed if using the CADP transaction instead of DTCN.

Sample JCL for compiling Enterprise PL/I for z/OS Version 3.4 or earlier programs

Below is a JCL example for compiling an Enterprise PL/I for z/OS Version 3.4 or earlier program for use with the IBM Problem Determination Tools products.

//*     - - -  ADD A JOB CARD ABOVE THIS LINE  - - -
//*
//*  SAMPLE JCL TO COMPILE WITH ENTERPRISE PLI V3.4 AND PREVIOUS
//*  FOR THE IBM ZSERIES PD TOOLS PRODUCTS:
//*     FAULT ANALYZER, DEBUG TOOL, AND APPLICATION PERF. ANALYZER
//*
//*  NOTES:
//*
//*   COMPILER:
//*    1. A 2-STAGE COMPILE IS PERFORMED.  STAGE 1 (PREPROCESS) IS
//*       DONE TO EXPAND INCLUDES AND MACROS IN THE PROGRAM, SO THAT
//*       A SOURCE FILE IS CREATED FOR DEBUG TOOL THAT HAS ALL STMTS.
//*    2. COMPILER PARM TEST AND NOPT ARE REQUIRED FOR DEBUG TOOL
//*    3. COMPILER PARMS AGGREGATE,ATTRIBUTES(FULL),NOBLKOFF,LIST,
//*       MAP,NEST,NONUMBER,OPTIONS,SOURCE,STMT,XREF(FULL) ARE NEEDED
//*       TO PROCESS THE COMPILER LISTING WITH XXXLANGX
//*
//*   BINDER (LINKAGE EDITOR):
//*    4. THE INCLUDE FOR MODULE EQAD?CXT IS OPTIONAL.  IT IS AN
//*       LE EXIT MODULE THAT CAN BE USED TO START DEBUG TOOL.
//*       UNDERSTAND THE METHODS AVAILABLE FOR STARTING DEBUG TOOL,
//*       AND CHOOSE WHETHER YOU WANT TO USE THE LE EXITS.
//*         IF YOU USE THIS METHOD, LOAD THE CORRECT EXIT MODULE:
//*            EQADBCXT: FOR BATCH PROGRAMS
//*            EQADICXT: FOR ONLINE IMS PROGRAMS
//*            EQADDCXT: FOR DB2 STORED PROCEDURES (OF TYPE MAIN AND SUB)
//*           (for SUB this is supported only for invocations through call_sub)
//*            (DO NOT INCLUDE AN EXIT FOR CICS PROGRAMS)
//*
//*  SET PARMS FOR THIS COMPILE:
//*  ---------------------------
//   SET MEM=PTEST                        PROGRAM NAME
//   SET PLICOMP='IBMZ.V3R4.SIBMZCMP'     PLI COMPILER LOADLIB
//   SET DTLIB='EQAW.SEQAMOD'             DEBUG TOOL LOADLIB
//   SET LEHLQ='CEE'                      LE HIGH LVL QUALIFIER
//   SET UNITDEV=SYSALLDA                 UNIT FOR TEMP FILES
//   SET LANGX='EQALANGX'                 XXXLANGX UTILITY PROGRAM
//   SET LANGXLIB='EQAW.SEQAMOD'          LIBRARY FOR XXXLANGX UTILITY
//*    NOTE: YOU CAN USE THE XXXLANGX UTILITY SHIPPED WITH DT, FA,
//*          OR APA. THEY NAMES ARE DIFFERENT, BUT RESULTS ARE THE SAME
//*          USE ANY OF THEM... THEY ALL PRODUCE THE SAME RESULTS.
//*      IF YOU HAVE:     SET LANGX TO:    SET LANGXLIB TO:
//*      DEBUG TOOL       EQALANGX         THE DT SEQAMOD LIBRARY
//*      FAULT ANALYZER   IDILANGX         THE FA SIDIAUTH LIBRARY
//*      APA              CAZLANGX         THE APA SCAZAUTH LIBRARY
//*
//ALLOCOBJ EXEC PGM=IEFBR14              ALLOC OBJ LIB IF NEEDED
//XSOURCE DD DSN=&SYSUID..ADLAB.EXPANDED.SOURCE,SPACE=(CYL,(3,1,15)),
//  DSORG=PO,RECFM=FB,LRECL=80,BLKSIZE=8000,DISP=(MOD,CATLG)
//OBJ   DD DSN=&SYSUID..ADLAB.OBJ,SPACE=(CYL,(3,1,15)),
//  DSORG=PO,RECFM=FB,LRECL=80,BLKSIZE=8000,DISP=(MOD,CATLG)
//*  ***************************************
//*     PREPROCESS STEP (COMPILE STAGE 1)
//*  ***************************************
//PRECOMP  EXEC PGM=IBMZPLI,REGION=0M,
//   PARM=('MACRO,MDECK,NOCOMPILE,NOSYNTAX,INSOURCE')
//STEPLIB  DD   DSN=&PLICOMP,DISP=SHR
//         DD   DSN=&LEHLQ..SCEERUN,DISP=SHR
//SYSIN    DD   DISP=SHR,DSN=&SYSUID..ADLAB.SOURCE(&MEM)
//SYSLIB   DD   DISP=SHR,DSN=&SYSUID..ADLAB.COPYLIB
//SYSPRINT DD   SYSOUT=*
//SYSUT1   DD   SPACE=(1024,(200,50),,CONTIG,ROUND),DCB=BLKSIZE=1024,
//             UNIT=&UNITDEV
//SYSPUNCH DD DISP=SHR,DSN=&SYSUID..ADLAB.EXPANDED.SOURCE(&MEM)
//*
//*  ***************************************
//*     COMPILE STEP (COMPILE STAGE 2)
//*  ***************************************
//COMPILE  EXEC PGM=IBMZPLI,REGION=0M,
// PARM=('TEST(ALL),LIST,MAP,SOURCE,XREF(FULL),',
//       'NOBLKOFF,AGGREGATE, ATTRIBUTES(FULL),NEST,OPTIONS,NOPT,',
//       'STMT,NONUMBER,OFFSET')
//STEPLIB  DD DSN=&PLICOMP,DISP=SHR
//         DD DSN=&LEHLQ..SCEERUN,DISP=SHR
//SYSIN    DD DISP=SHR,DSN=&SYSUID..ADLAB.EXPANDED.SOURCE(&MEM)
//SYSLIB   DD DISP=SHR,DSN=&SYSUID..ADLAB.COPYLIB
//SYSPRINT DD DISP=SHR,DSN=&SYSUID..ADLAB.ENTPLI.LISTING(&MEM)
//SYSUT1   DD SPACE=(CYL,(5,2),,CONTIG),DCB=BLKSIZE=1024,UNIT=&UNITDEV
//SYSLIN   DD DSN=&SYSUID..ADLAB.OBJ(&MEM),DISP=SHR
//*
//PLIPRINT  EXEC PGM=IEBGENER,REGION=0M
//SYSPRINT  DD SYSOUT=*
//SYSUT1    DD DSN=&SYSUID..ADLAB.ENTPLI.LISTING(&MEM),DISP=SHR
//SYSUT2    DD SYSOUT=*
//SYSIN     DD DUMMY
//*
//*  *********************************
//*     STEP TO GENERATE LANGX FILE
//*  *********************************
//LANGX    EXEC PGM=&LANGX,REGION=32M,
//  PARM='(PLI ERROR 64K CREF'
//STEPLIB  DD DISP=SHR,DSN=&LANGXLIB
//         DD DISP=SHR,DSN=&LEHLQ..SCEERUN
//LISTING  DD DSN=&SYSUID..ADLAB.ENTPLI.LISTING(&MEM),DISP=SHR
//IDILANGX DD DISP=SHR,DSN=&SYSUID..ADLAB.EQALANGX(&MEM)
//*
//* *********************************
//* LINK-EDIT (BINDER) STEP
//* *********************************
//LINK EXEC PGM=IEWL,PARM=(LET,MAP,LIST),REGION=0M
//SYSLIB DD DSN=&LEHLQ..SCEELKED,DISP=SHR
//DTLIB DD DSN=&DTLIB,DISP=SHR
//SYSPRINT DD SYSOUT=*
//SYSLMOD DD DISP=SHR,DSN=&SYSUID..ADLAB.LOAD(&MEM)
//SYSUT1 DD UNIT=SYSDA,SPACE=(TRK,(10,10))
//SYSLIN DD DSN=&SYSUID..ADLAB.OBJ(&MEM),DISP=(OLD,PASS)
//*  INCLUDING A DEBUG TOOL LE EXIT (EQADBCXT, EQADDCXT, OR EQADICXT)
//*  IS OPTIONAL.  THE EXIT ENABLES STARTING DEBUG TOOL WITH THE
//*  USER EXIT DATA SET UTILITY (ONE OF THE DEBUG TOOL ISPF UTILITIES)
//*  //        DD *
//*   INCLUDE DTLIB(EQADBCXT)

PL/I for MVS and VM and OS PL/I programs

The following table shows various compiler options that can be used to prepare Enterprise COBOL for z/OS Version 4 programs for use with the IBM Problem Determination Tools products (Debug Tool for z/OS, Fault Analyzer for z/OS and Application Performance Analyzer for z/OS). The methods suggested in the following table indicate if the load module produced is suitable for a production environment. Load modules suitable for a production environments have no significant run-time overhead.

For the test environment, you need both the listing and the LANGX file (for Fault Analyzer for z/OS and Application Performance Analyzer for z/OS). In production, only the LANGX file is suggested.

Table 27. Examples of compiler options and source information files supported by IBM Problem Determination Tools products for PL/I for MVS and VM and OS PLI
Compiler options Source information file type produced Is the load module production ready? Options supported and suggested for Debug Tool for z/OS Options supported and suggested for Fault Analyzer for z/OS Options supported and suggested for Application Performance Analyzer for z/OS
TEST(ALL), AGGREGATE, ATTRIBUTES (FULL), ESD, LIST, MAP, NEST, NOPT, OPTIONS, SOURCE, STMT, XREF(FULL) Compiler listing No Suggested for test. (Using Debug Tool in production for this compiler is not recommended.) Supported Supported
LANGX file No N/A Supported N/A
NOTEST, AGGREGATE, ATTRIBUTES (FULL), ESD, LIST, MAP, NEST, OPTIONS, SOURCE, STMT, XREF(FULL) Compiler listing Yes N/A Supported Suggested for production and test
LANGX file Yes N/A Suggested for production and test N/A
Note:
The highlighted row or rows in the table above indicate the suggested compiler options and source information file types for each product.

Preparing PL/I for MVS and VM and OS PL/I programs

Perform the following steps for compiling your PL/I for MVS and VM and OS PL/I programs:

  1. Create a library (PDSE is suggested unless PDS is required for your organization) for compiler listing files. This is only needed in test environments where debugging will be performed. Specify LRECL=125 minimum,RECFM=VBA,BLKSIZE= lrecl+4 to 32k.
  2. Allocate libraries (PDSE is suggested unless PDS is required for your organization) for LANGX files. Allocate one or more LANGX libraries for each environment, such as test and production.
  3. Create a corresponding LANGX library for each load library. Specify LRECL=1562 or greater,RECFM=VB,BLKSIZE= lrecl+4 to 32k.
  4. For all programs, such as batch, CICS, and IMS:
  5. Modify the SYSPRINT DD in the compiler step. This is the compiler listing. Save this to a permanent file. The compiler listing is the input to the xxxLANGX utility and is the source information file for Debug Tool for z/OS
    Note:
    This compiler typically renames CSECTs according to an internal compiler algorithm. Therefore, it is not recommended to store PL/I compiler listings or side files using CSECT names as they might not be found by Application Performance Analyzer for z/OS or Fault Analyzer for z/OS. Instead, use the primary entry point name.
  6. Add a step after the compiler step to run the xxxLANGX utility. This utility reads the compiler listing and saves a LANGX file. This is the source information file for Fault Analyzer for z/OS and Application Performance Analyzer for z/OS. Equivalent xxxLANGX utilities are available in Debug Tool for z/OS as EQALANGX, in Fault Analyzer for z/OS as IDILANGX and in Application Performance Analyzer for z/OS as CAZLANGX. Save it in the LANGX file library and specify a member name that is equal to the primary entry point name of your application program.
  7. Modify the promotion process to promote LANGX files. When a load module is promoted, for example, from test to production, promote the corresponding LANGX file or files. A promotion can be a recompile, copy, or move. Perform the same steps with the LANGX file that you perform with the module during promotion.
  8. Optionally, include a Debug Tool Language Environment exit module into the load module during the linkage editor step. This is one way to enable Debug Tool's panel 6 in ISPF, a simple panel-driven method to start the debugger automatically when a program runs, without JCL changes, based on the program name and user ID. Use module EQADBCXT for batch programs (including IMS batch), EQADICXT for IMS/TM programs and EQADDCXT for DB2 stored procedures. Do not include the exit module for CICS programs.
  9. For CICS applications only, if the Debug Tool DTCN transaction will be used to start Debug Tool, link-edit the Debug Tool CICS startup exit module EQADCCXT into the application load module to enable Debug Tool in CICS. This is not needed if using the CADP transaction instead of DTCN.

Sample JCL for compiling PL/I for MVS and VM programs

Below is a JCL example for compiling an PL/I for MVS and VM program for use with the IBM Problem Determination Tools products.

//*     - - -  ADD A JOB CARD ABOVE THIS LINE  - - -
//*
//*  SAMPLE JCL TO PREPARE A PLI FOR MVS AND VM PROGRAM
//*  FOR THE IBM ZSERIES PD TOOLS PRODUCTS:
//*     FAULT ANALYZER, DEBUG TOOL, AND APPLICATION PERF. ANALYZER
//*
//*  NOTES:
//*
//*   COMPILER:
//*    1. COMPILER PARM TEST IS REQUIRED FOR DEBUG TOOL
//*    2. COMPILER PARMS AGGREGATE,ATTRIBUTES(FULL),ESD,LIST,
//*       MAP,NEST,OPTIONS,SOURCE,STMT,XREF(FULL) ARE NEEDED
//*       FOR PD TOOLS TO PROCESS THE COMPILER LISTING
//*
//*   BINDER (LINKAGE EDITOR):
//*    3. THE INCLUDE FOR MODULE EQAD?CXT IS OPTIONAL.  IT IS AN
//*       LE EXIT MODULE THAT CAN BE USED TO START DEBUG TOOL.
//*       UNDERSTAND THE METHODS AVAILABLE FOR STARTING DEBUG TOOL,
//*       AND CHOOSE WHETHER YOU WANT TO USE THE LE EXITS.
//*         IF YOU USE THIS METHOD, LOAD THE CORRECT EXIT MODULE:
//*            EQADBCXT: FOR BATCH PROGRAMS
//*            EQADICXT: FOR ONLINE IMS PROGRAMS
//*            EQADDCXT: FOR DB2 STORED PROCEDURES (OF TYPE MAIN AND SUB)
//*           (for SUB this is supported only for invocations through call_sub)
//*            (DO NOT INCLUDE AN EXIT FOR CICS PROGRAMS)
//*
//*  SET PARMS FOR THIS COMPILE:
//*  ---------------------------
//   SET MEM=PADSTAT                      PROGRAM NAME
//   SET PLICOMP='IEL.V1R1M1.SIELCOMP'    PLI COMPILER LOADLIB
//   SET DTLIB='EQAW.SEQAMOD'             DEBUG TOOL LOADLIB
//   SET LEHLQ='CEE'                      LE HIGH LVL QUALIFIER
//   SET UNITDEV=SYSALLDA                 UNIT FOR TEMP FILES
//   SET LANGX='EQALANGX'                 XXXLANGX UTILITY PROGRAM
//   SET LANGXLIB='EQAW.SEQAMOD'          LIBRARY FOR XXXLANGX UTILITY
//*    NOTE: YOU CAN USE THE XXXLANGX UTILITY SHIPPED WITH DT, FA,
//*          OR APA. THE NAMES ARE DIFFERENT, BUT RESULTS ARE THE SAME
//*          USE ANY OF THEM... THEY ALL PRODUCE THE SAME RESULTS.
//*      IF YOU HAVE:     SET LANGX TO:    SET LANGXLIB TO:
//*      DEBUG TOOL       EQALANGX         THE DT SEQAMOD LIBRARY
//*      FAULT ANALYZER   IDILANGX         THE FA SIDIAUTH LIBRARY
//*      APA              CAZLANGX         THE APA SCAZAUTH LIBRARY
//*
//ALLOCOBJ EXEC PGM=IEFBR14              ALLOC OBJ LIB IF NEEDED
//OBJ   DD DSN=&SYSUID..ADLAB.OBJ,SPACE=(CYL,(3,1,15)),
//  DSORG=PO,RECFM=FB,LRECL=80,BLKSIZE=8000,DISP=(MOD,CATLG)
//*
//*  ***************************************
//*     COMPILE STEP
//*  ***************************************
//*
//COMPILE  EXEC PGM=IEL1AA,REGION=6M,
// PARM=('TEST(ALL),NOPT,AGGREGATE,ATTRIBUTES(FULL),ESD,LIST,MAP,',
//       'NEST,OPTIONS,SOURCE,STMT,XREF(FULL)')
//STEPLIB  DD   DSN=&PLICOMP,DISP=SHR
//SYSIN    DD   DISP=SHR,DSN=&SYSUID..ADLAB.SOURCE(&MEM)
//SYSLIB   DD   DISP=SHR,DSN=&SYSUID..ADLAB.COPYLIB
//SYSPRINT DD   DISP=SHR,DSN=&SYSUID..ADLAB.PLIMVS.LISTING(&MEM)
//SYSUT1   DD   SPACE=(CYL,(1,1)),UNIT=SYSDA
//SYSLIN   DD DSN=&SYSUID..ADLAB.OBJ(&MEM),DISP=SHR
//*
//PLIPRINT  EXEC PGM=IEBGENER,REGION=0M
//SYSPRINT  DD SYSOUT=*
//SYSUT1    DD DSN=&SYSUID..ADLAB.PLIMVS.LISTING(&MEM),DISP=SHR
//SYSUT2    DD SYSOUT=*
//SYSIN     DD DUMMY
//*
//*  *********************************
//*     STEP TO GENERATE LANGX FILE
//*  *********************************
//LANGX    EXEC PGM=&LANGX,REGION=32M,
//  PARM='(PLI ERROR 64K CREF'
//STEPLIB  DD DISP=SHR,DSN=&LANGXLIB
//         DD DISP=SHR,DSN=&LEHLQ..SCEERUN
//LISTING  DD DSN=&SYSUID..ADLAB.PLIMVS.LISTING(&MEM),DISP=SHR
//IDILANGX DD DISP=SHR,DSN=&SYSUID..ADLAB.EQALANGX(&MEM)
//*
//* *********************************
//* LINK-EDIT (BINDER) STEP
//* *********************************
//LINK EXEC PGM=IEWL,PARM=(LET,MAP,LIST),REGION=0M
//SYSLIB DD DSN=&LEHLQ..SCEELKED,DISP=SHR
//DTLIB DD DSN=&DTLIB,DISP=SHR
//SYSPRINT DD SYSOUT=*
//SYSLMOD DD DISP=SHR,DSN=&SYSUID..ADLAB.LOAD(&MEM)
//SYSUT1 DD UNIT=SYSDA,SPACE=(TRK,(10,10))
//SYSLIN DD DSN=&SYSUID..ADLAB.OBJ(&MEM),DISP=(OLD,PASS)
//*  INCLUDING A DEBUG TOOL LE EXIT (EQADBCXT, EQADDCXT, OR EQADICXT)
//*  IS OPTIONAL.  THE EXIT ENABLES STARTING DEBUG TOOL WITH THE
//*  USER EXIT DATA SET UTILITY (ONE OF THE DEBUG TOOL ISPF UTILITIES)
//*  //        DD *
//*   INCLUDE DTLIB(EQADBCXT)

z/OS XL C and C++ programs

The following table shows various compiler options that can be used to prepare z/OS XL C and C++ programs for use with the IBM Problem Determination Tools products (Debug Tool for z/OS, Fault Analyzer for z/OS and Application Performance Analyzer for z/OS). The methods suggested in the following table indicate if the load module produced is suitable for a production environment. Load modules suitable for a production environments have no significant run-time overhead.

Table 28. Examples of compiler options and source information files supported by IBM Problem Determination Tools products for C++
Compiler options Output produced Is the load module production ready? Options supported and suggested for Debug Tool for z/OS Options supported and suggested for Fault Analyzer for z/OS Options supported and suggested for Application Performance Analyzer for z/OS
Preprocess (1st stage) to expand source, In compile (2nd stage): TEST, ATTRIBUTE(FULL), NOIPA, LIST, NESTINC(255), NOOFFSET, NOOPT, SOURCE, XREF Expanded source file used by Debug Tool for z/OS, compiler listing used by Fault Analyzer for z/OS and Application Performance Analyzer for z/OS No Suggested for test. (Using Debug Tool in production for this compiler is not recommended.) Supported Supported
Expanded source file used by Debug Tool for z/OS, LANGX file used by Fault Analyzer for z/OS and Application Performance Analyzer for z/OS No Supported Supported Supported
NOTEST, ATTRIBUTE(FULL), NOIPA, LIST, NESTINC(255), NOOFFSET, NOOPT, SOURCE, XREF Compiler listing Yes N/A Suggested for production and test Suggested for production and test
LANGX file Yes N/A Supported Supported
Preprocess (1st stage) to expand source. In compile (2nd stage): DEBUG(FORMAT (DWARF), HOOK(LINE, NOBLOCK, PATH), SYMBOL, FILE(location)) Expanded source file and DWARF file No Supported. (Using Debug Tool in production for this compiler is not recommended.) N/A N/A
Notes:
  1. The highlighted row or rows in the table above indicate the suggested compiler options and source information file types for each product.
  2. The FORMAT(DWARF) option is supported for z/OS Version 1.6 and higher.
Table 29. Examples of compiler options and source information files supported by IBM Problem Determination Tools products for C
Compiler options Output produced Is the load module production ready? Options supported and suggested for Debug Tool for z/OS Options supported and suggested for Fault Analyzer for z/OS Options supported and suggested for Application Performance Analyzer for z/OS
Preprocess (1st stage) to expand source, In compile (2nd stage): TEST(ALL), AGGREGATE, NOIPA, LIST, NESTINC(255), NOOFFSET, NOOPT, SOURCE, XREF Expanded source file used by Debug Tool for z/OS, compiler listing used by Fault Analyzer for z/OS and Application Performance Analyzer for z/OS No Suggested for test. (Using Debug Tool in production for this compiler is not recommended.) Supported Supported
Expanded source file used by Debug Tool for z/OS, LANGX file used by Fault Analyzer for z/OS and Application Performance Analyzer for z/OS No Supported Supported Supported
NOTEST, AGGREGATE, NOIPA, LIST, NESTINC(255), NOOFFSET, NOOPT, SOURCE, XREF Compiler listing Yes N/A Suggested for production and test Suggested for production and test
LANGX file Yes N/A Supported Supported
Preprocess (1st stage) to expand source. In compile (2nd stage): DEBUG(FORMAT (DWARF), HOOK(LINE, NOBLOCK, PATH), SYMBOL, FILE(location)) Expanded source file and DWARF file No Supported. (Using Debug Tool in production for this compiler is not recommended.) N/A N/A
Notes:
  1. The highlighted row or rows in the table above indicate the suggested compiler options and source information file types for each product.
  2. The FORMAT(DWARF) option is supported for z/OS Version 1.6 and higher.

Preparing z/OS XL C and C++ programs

Perform the following steps for compiling your z/OS XL C and C++ programs:

  1. Create a library (PDSE is suggested unless PDS is required for your organization) for expanded source files. This is only needed in test environments where debugging will be performed. This can be any RECFM / LRECL / BLKSIZE supported as input by the compiler.
  2. Allocate libraries (PDSE is suggested unless PDS is required for your organization) for compiler listing files. Allocate one or more compiler listing libraries for each environment, such as test and production.
  3. Create a corresponding listing library for each load library. Specify LRECL=133,RECFM=FBA,BLKSIZE=(multiple of lrecl up to 32k) or LRECL=137 or greater, RECFM=VBA,BLKSIZE= lrecl+4 to 32k.
  4. Run a 2-stage compile. The first stage preprocesses the program, so the IBM Problem Determination Tools products have access to fully expanded source code. The second stage compiles the program.
  5. Modify the SYSCPRT DD in the second compiler stage to refer to a file. This is the compiler listing and is the source information file for Fault Analyzer for z/OS and Application Performance Analyzer for z/OS. Save it in the compiler listing library and specify a member that is equal to the CSECT name of your application program.
    //SYSCPRT DD DSN=compiler.listing.pds(csect-name),DISP=SHR
    Note:
    To enable source support in Fault Analyzer, it is a requirement that CSECTs in C programs are named using:
    #pragma csect(code, "csect_name")
    where, if using a PDS(E), csect_name matches the compiler listing or LANGX file member name.
  6. Modify the promotion process to promote compiler listing files. When a load module is promoted, for example, from test to production, promote the corresponding compiler listing file or files. A promotion can be a recompile, copy, or move. Perform the same steps with the compiler listing file that you perform with the module during promotion.
  7. Optionally, include a Debug Tool Language Environment exit module into the load module during the linkage editor step. This is one way to enable Debug Tool's panel 6 in ISPF, a simple panel-driven method to start the debugger automatically when a program runs, without JCL changes, based on the program name and user ID. Use module EQADBCXT for batch programs (including IMS batch), EQADICXT for IMS/TM programs and EQADDCXT for DB2 stored procedures. Do not include the exit module for CICS programs.
  8. For CICS applications only: if the Debug Tool DTCN transaction will be used to start Debug Tool, link edit the Debug Tool CICS startup exit module EQADCCXT into the application load module to enable Debug Tool in CICS. This is not needed if using the CADP transaction instead of DTCN.

Sample JCL for compiling z/OS C++ programs

Below is a JCL example for compiling an z/OS C/C++ program for use with the IBM Problem Determination Tools products.

//* ADD A JOB CARD HERE
//*
//*
//*  SAMPLE JCL TO PREPARE A Z/OS C PROGRAM PROGRAM
//*  FOR THE IBM ZSERIES PD TOOLS PRODUCTS:
//*     FAULT ANALYZER, DEBUG TOOL, AND APPLICATION PERF. ANALYZER
//*
//*  NOTES:
//*
//*   COMPILER:
//*    1. A 2-STAGE COMPILE IS PERFORMED.  STAGE 1 (PREPROCESS) IS
//*       DONE TO EXPAND INCLUDES AND MACROS IN THE PROGRAM AND TO
//*       PRODUCE AN EXPANDED SOURCE FILE.
//*    2. THE EXPANDED SOURCE FILE IS RETAINED.  IT IS USED BY
//*       DEBUG TOOL.
//*    2. COMPILER PARMS TEST AND NOOPT ARE REQUIRED FOR DEBUG TOOL.
//*    3. COMPILER PARMS AGGREGATE, NOIPA, LIST, NOOFFSET, SOURCE,
//*       AND XREF(FULL) ARE NEEDED TO FORMAT THE COMPILER LISTING
//*       SO THAT IT CAN BE PROCESSED WITH XXXLANGX
//*
//*   A STEP RUNS TO PRODUCE A LANGX FILE FOR FAULT ANALYZER AND APA.
//*    NOTE: YOU CAN USE THE XXXLANGX UTILITY SHIPPED WITH DT, FA,
//*          OR APA. THE NAMES ARE DIFFERENT, BUT THE RESULTS ARE THE SAME.
//*          USE ANY OF THEM... THEY ALL PRODUCE THE SAME RESULTS.
//*      IF YOU HAVE:     THEN EXECUTE MODULE:
//*      DEBUG TOOL       EQALANGX, AND ENSURE THAT THE DT SEQAMOD LIBRARY
//*                         IS AVAILABLE (VIA STEPLIB, JOBLIB, OR LINKLIST)
//*      FAULT ANALYZER   IDILANGX, AND ENSURE THAT THE FA SIDIAUTH LIBRARY
//*                         IS AVAILABLE (VIA STEPLIB, JOBLIB, OR LINKLIST)
//*      APA              CAZLANGX, AND ENSURE THAT THE APA SCAZAUTH LIBRARY
//*                         IS AVAILABLE (VIA STEPLIB, JOBLIB, OR LINKLIST)
//*
//*   BINDER (LINKAGE EDITOR):
//*    1. AN INCLUDE FOR MODULE EQAD?CXT IS OPTIONAL.  IT IS AN
//*       LE EXIT MODULE THAT CAN BE USED TO START DEBUG TOOL.
//*       UNDERSTAND THE METHODS AVAILABLE FOR STARTING DEBUG TOOL,
//*       AND CHOOSE WHETHER YOU WANT TO USE THE LE EXITS.
//*         IF YOU USE THIS METHOD, INCLUDE THE CORRECT EXIT MODULE:
//*            EQADBCXT: FOR BATCH PROGRAMS
//*            EQADICXT: FOR ONLINE IMS PROGRAMS
//*            EQADDCXT: FOR DB2 STORED PROCEDURES (OF TYPE MAIN AND SUB)
//*           (for SUB this is supported only for invocations through call_sub)
//*            (DO NOT INCLUDE AN EXIT FOR CICS PROGRAMS)
//*
//*  SET PARMS FOR THIS COMPILE:
//*  ---------------------------
//*       CPRFX: THE PREFIX THE C/C++ COMPILE IS INSTALLED UNDER
//*       LEPRFX: THE PREFIX FOR THE LE RUNTIME AND LINK LIBS
//*       DTPRFX: THE PREFIX OF THE DEBUG TOOL SEQAMOD LIBRARY
//*
//    SET CPRFX=CBC
//    SET LEPRFX=CEE
//    SET DTPRFX=EQAW
//*
//*******************************************************************/
//* CREATE C/C++ COMPILER LISTING SYSPRINT, EXPANDED SOURCE DEBUG,  */
//* AND EQALANGX FILES                                              */
//*******************************************************************/
//ALLOC EXEC PGM=IEFBR14
//LISTING DD DSN=&SYSUID..ADLAB.CLST,
//           DISP=(MOD,CATLG),
//           DCB=(DSORG=PO,RECFM=VBA,LRECL=137,BLKSIZE=0),
//           SPACE=(TRK,(20,20,50)),UNIT=SYSDA
//DBGSRC  DD DSN=&SYSUID..ADLAB.CDBG,
//           DISP=(MOD,CATLG),
//           DCB=(DSORG=PO,RECFM=FB,LRECL=80,BLKSIZE=0),
//           SPACE=(TRK,(20,20,50)),UNIT=SYSDA
//LANGX   DD DSN=&SYSUID..ADLAB.EQALANGX,
//           DISP=(MOD,CATLG),
//           DCB=(DSORG=PO,RECFM=VB,LRECL=1562,BLKSIZE=0),
//           SPACE=(TRK,(40,40,50)),UNIT=SYSDA
//*                                                                 *
//****************************************************************
//*-------------------------------------------------------------------
//*  COMPILE STEP1: GENERATE EXPANDED C/C++ SOURCE FILE IN THE DD
//*                 SYSUT10
//*-------------------------------------------------------------------
//COMP1   EXEC PGM=CCNDRVR,REGION=0M,
// PARM=('PP(COMMENTS,NOLINES)')
//STEPLIB  DD  DSNAME=&LEPRFX..SCEERUN2,DISP=SHR
//         DD  DSNAME=&CPRFX..SCCNCMP,DISP=SHR
//SYSMSGS  DD  DUMMY,DSN=&CPRFX..SCBC3MSG(EDCMSGE),DISP=SHR
//SYSLIB   DD  DSNAME=&LEPRFX..SCEEH.H,DISP=SHR
//         DD  DSNAME=&LEPRFX..SCEEH.SYS.H,DISP=SHR
//         DD  DSNAME=&SYSUID..ADLAB.COPYLIB,DISP=SHR
//SYSPRINT DD  SYSOUT=*
//SYSOUT   DD  SYSOUT=*
//SYSCPRT  DD  SYSOUT=*
//SYSUT1   DD  UNIT=SYSDA,SPACE=(32000,(30,30)),
//   DCB=(RECFM=FB,LRECL=80,BLKSIZE=3200)
//SYSUT5   DD  UNIT=SYSDA,SPACE=(32000,(30,30)),
//   DCB=(RECFM=FB,LRECL=3200,BLKSIZE=12800)
//SYSUT6   DD  UNIT=SYSDA,SPACE=(32000,(30,30)),
//   DCB=(RECFM=FB,LRECL=3200,BLKSIZE=12800)
//SYSUT7   DD  UNIT=SYSDA,SPACE=(32000,(30,30)),
//   DCB=(RECFM=FB,LRECL=3200,BLKSIZE=12800)
//SYSUT8   DD  UNIT=SYSDA,SPACE=(32000,(30,30)),
//   DCB=(RECFM=FB,LRECL=3200,BLKSIZE=12800)
//SYSUT9   DD  UNIT=SYSDA,SPACE=(32000,(30,30)),
//   DCB=(RECFM=VB,LRECL=137,BLKSIZE=882)
//SYSUT10  DD  DISP=SHR,DSN=&SYSUID..ADLAB.CDBG(TMC01A)
//SYSUT14  DD  UNIT=SYSDA,SPACE=(32000,(30,30)),
//             DCB=(RECFM=FB,LRECL=3200,BLKSIZE=12800)
//SYSUT16  DD  UNIT=SYSDA,SPACE=(32000,(30,30)),
//             DCB=(RECFM=FB,LRECL=3200,BLKSIZE=12800)
//SYSUT17  DD  UNIT=SYSDA,SPACE=(32000,(30,30)),
//             DCB=(RECFM=FB,LRECL=3200,BLKSIZE=12800)
//SYSLIN   DD  DUMMY
//SYSIN    DD  DSNAME=&SYSUID..ADLAB.SOURCE(TMC01A),DISP=SHR
//*
//*-------------------------------------------------------------------
//*  COMPILE STEP2: COMPILE THE EXPANDED SOURCE FILE WITH THE DEBUG
//*                 COMPILER OPTION TEST(ALL)
//*-------------------------------------------------------------------
//COMP2   EXEC PGM=CCNDRVR,REGION=0M,
//  PARM=('TEST(ALL), AGGREGATE, NOIPA, LIST, NESTINC(255),',
//    ' NOOFFSET, NOOPT, SOURCE, XREF')
//STEPLIB  DD  DSNAME=&LEPRFX..SCEERUN2,DISP=SHR
//         DD  DSNAME=&CPRFX..SCCNCMP,DISP=SHR
//         DD  DSNAME=&LEPRFX..SCEERUN,DISP=SHR
//SYSMSGS  DD  DUMMY,DSN=&CPRFX..SCBC3MSG(EDCMSGE),DISP=SHR
//SYSLIB   DD  DSNAME=&LEPRFX..SCEEH.H,DISP=SHR
//         DD  DSNAME=&LEPRFX..SCEEH.SYS.H,DISP=SHR
//SYSCPRT  DD  DISP=SHR,DSN=&SYSUID..ADLAB.CLST(TMC01A)
//SYSOUT   DD  SYSOUT=*
//SYSPRINT DD  SYSOUT=*
//SYSUT1   DD  UNIT=SYSDA,SPACE=(32000,(30,30)),
//   DCB=(RECFM=FB,LRECL=80,BLKSIZE=3200)
//SYSUT5   DD  UNIT=SYSDA,SPACE=(32000,(30,30)),
//   DCB=(RECFM=FB,LRECL=3200,BLKSIZE=12800)
//SYSUT6   DD  UNIT=SYSDA,SPACE=(32000,(30,30)),
//   DCB=(RECFM=FB,LRECL=3200,BLKSIZE=12800)
//SYSUT7   DD  UNIT=SYSDA,SPACE=(32000,(30,30)),
//   DCB=(RECFM=FB,LRECL=3200,BLKSIZE=12800)
//SYSUT8   DD  UNIT=SYSDA,SPACE=(32000,(30,30)),
//   DCB=(RECFM=FB,LRECL=3200,BLKSIZE=12800)
//SYSUT9   DD  UNIT=SYSDA,SPACE=(32000,(30,30)),
//   DCB=(RECFM=VB,LRECL=137,BLKSIZE=882)
//SYSUT10  DD  SYSOUT=*
//SYSUT14  DD  UNIT=SYSDA,SPACE=(32000,(30,30)),
//             DCB=(RECFM=FB,LRECL=3200,BLKSIZE=12800)
//SYSUT16  DD  UNIT=SYSDA,SPACE=(32000,(30,30)),
//             DCB=(RECFM=FB,LRECL=3200,BLKSIZE=12800)
//SYSUT17  DD  UNIT=SYSDA,SPACE=(32000,(30,30)),
//             DCB=(RECFM=FB,LRECL=3200,BLKSIZE=12800)
//SYSLIN   DD DSN=&&TEMOBJ1(TMC01A),DISP=(,PASS),UNIT=SYSDA,
// SPACE=(TRK,(20,20,20)),DCB=(RECFM=FB,BLKSIZE=3120,LRECL=80,DSORG=PO)
//SYSIN    DD  DSNAME=&SYSUID..ADLAB.CDBG(TMC01A),DISP=SHR
//*
//*-------------------------------------------------------------------
//* LINK STEP: LINK THE COMPILED OBJECT DECK
//*-------------------------------------------------------------------
//LKED EXEC PGM=IEWL,PARM=(LET,MAP,LIST)
//SYSLIB DD DSN=&LEPRFX..SCEELKED,DISP=SHR
//SYSPRINT DD SYSOUT=*
//SYSLMOD DD DISP=SHR,DSN=&SYSUID..ADLAB.LOAD
//SYSUT1 DD SPACE=(TRK,(10,10)),UNIT=SYSDA
//OBJECT DD DISP=(OLD,PASS),DSN=&&TEMOBJ1
//* DTLIB DD DSN=&DTPRFX..SEQAMOD,DISP=SHR
//SYSLIN DD *
INCLUDE OBJECT(TMC01A)
ENTRY CEESTART
NAME TMC01(R)
/*
//*  INCLUDING A DEBUG TOOL LE EXIT (EQADBCXT, EQADDCXT, OR EQADICXT)
//*  IS OPTIONAL.  THE EXIT ENABLES STARTING DEBUG TOOL WITH THE
//*  USER EXIT DATA SET UTILITY (ONE OF THE DEBUG TOOL ISPF UTILITIES).
//*  AN INCLUDE CAN BE ADDED TO SYSLIN IN THE APPRORIATE SEQUENCE:
//*   INCLUDE DTLIB(EQADBCXT)
//**************************************************************
//* GENERATE THE TMC01A EQALANGX FILE
//**************************************************************
//LANGX1   EXEC PGM=EQALANGX,REGION=32M,
//  PARM='(C ERROR'
//STEPLIB  DD DISP=SHR,DSN=&DTPRFX..SEQAMOD
           DD DISP=SHR,DSN=&LEPRFX..SCEERUN
//LISTING  DD DSN=&SYSUID..ADLAB.CLST(TMC01A),DISP=SHR
//IDILANGX DD DSN=&SYSUID..ADLAB.EQALANGX(TMC01AX),DISP=(OLD)

Assembler programs

The following table shows various assembler options that can be used to prepare programs for use with the IBM Problem Determination Tools products (Debug Tool for z/OS, Fault Analyzer for z/OS and Application Performance Analyzer for z/OS). The methods suggested in the following table indicate if the load module produced is suitable for a production environment. Load modules suitable for a production environments have no significant run-time overhead.

Table 30. Examples of assembler options and source information files supported by IBM Problem Determination Tools products for Assembler
Assembler options Source information file type produced Is the load module production ready? Options supported and suggested for Debug Tool for z/OS Options supported and suggested for Fault Analyzer for z/OS Options supported and suggested for Application Performance Analyzer for z/OS
ADATA SYSADATA file Yes N/A Supported Supported
ADATA LANGX file Yes Suggested for production and test
Note:
The highlighted row or rows in the table above indicate the suggested compiler options and source information file types for each product.

Preparing Assembler programs

Perform the following steps for assembling your programs:

  1. Allocate libraries (PDSE is suggested unless PDS is required for your organization) for LANGX files. Allocate one or more LANGX libraries for each environment, such as test and production.
  2. Create a corresponding LANGX library for each load library. Specify LRECL=1562 or greater,RECFM=VB,BLKSIZE= lrecl+4 to 32k.
  3. For all programs, such as batch, CICS, and IMS, in both test and production environments, specify ADATA.

    ADATA instructs the assembler to produce a SYSADATA file, which contains source and symbolic data about the program. This produces a production-ready module that can be debugged using Debug Tool for z/OS. ADATA does not affect the contents of the assembled module.

  4. Add a SYSADATA DD in the assembler step. This file is created by the assembler and it can be a permanent or temporary file. Specify LRECL=8188 or greater,RECFM=VB,BLKSIZE= lrecl+4 to 32k. This file is the input to the xxxLANGX utility.
  5. Add a step after the assembler step to run the xxxLANGX utility. The xxxLANGX utility reads the SYSADATA file and creates a LANGX file. The LANGX file is the source information file for Debug Tool for z/OS, Fault Analyzer for z/OS and Application Performance Analyzer for z/OS. Equivalent xxxLANGX utilities are available in Debug Tool for z/OS as EQALANGX, in Fault Analyzer for z/OS as IDILANGX and in Application Performance Analyzer for z/OS as CAZLANGX.
  6. Save the LANGX file in the LANGX file library, and specify a member name that is equal to the CSECT name.
  7. Modify the promotion process to promote LANGX files. When a load module is promoted, for example, from test to production, promote the corresponding LANGX file or files. A promotion can be a recompile, copy, or move. Perform the same steps with the LANGX file that you perform with the module during promotion.
  8. If the assembler program is Language Environment-enabled, optionally include a Debug Tool Language Environment exit module into the load module during the linkage editor step. This is one way to enable Debug Tool's panel 6 in ISPF, a simple panel-driven method to start the debugger automatically when a program runs, without JCL changes, based on the program name and user ID. Use module EQADBCXT for batch programs (including IMS batch), EQADICXT for IMS/TM programs and EQADDCXT for DB2 stored procedures. Do not include the exit module for CICS programs.
  9. For CICS programs only: If the program is a CICS main program, is enabled for Language Environment, and the Debug Tool DTCN transaction will be used to start Debug Tool, then supplied module EQADCCXT must be included in the load module during the linkage editor step.

Sample JCL for assembling a program

Below is a JCL example for assembling a program for use with the IBM Problem Determination Tools products.

//*     - - -  ADD A JOB CARD ABOVE THIS LINE  - - -
//*
//*  SAMPLE JCL TO PREPARE AN ASSEMBLER PROGRAM
//*  FOR THE IBM ZSERIES PD TOOLS PRODUCTS:
//*     FAULT ANALYZER, DEBUG TOOL, AND APPLICATION PERF. ANALYZER
//*
//*  NOTES:
//*
//*   ASSEMBLER:
//*    1. AN ADATA PARM IS REQUIRED TO PRODUCE A SYSADATA FILE
//*
//*   A STEP THAT PROCESSES THE SYSADATA FILE,
//*   AND CREATES A LANGX FILE IS NEEDED.
//*
//*   BINDER (LINKAGE EDITOR):
//*    1. AMODE / RMODE CAN BE CODED AS NEEDED BY THE PROGRAM.  THEY ARE
//*       NOT REQUIRED FOR PD TOOLS.
//*
//*  SET PARMS FOR THIS COMPILE:
//*  ---------------------------
//   SET MEM=ASAM1                        PROGRAM NAME
//   SET Language EnvironmentHLQ='CEE'    Language Environment HIGH LVL QUALIFIER
//   SET UNITDEV=SYSALLDA                 UNIT FOR TEMP FILES
//   SET LANGX='EQALANGX'                 XXXLANGX UTILITY PROGRAM
//   SET LANGXLIB='EQAW.SEQAMOD'          LIBRARY FOR XXXLANGX UTILITY
//*    NOTE: YOU CAN USE THE XXXLANGX UTILITY SHIPPED WITH DT, FA,
//*          OR APA. THE NAMES ARE DIFFERENT, BUT RESULTS ARE THE SAME
//*          USE ANY OF THEM... THEY ALL PRODUCE THE SAME RESULTS.
//*      IF YOU HAVE:     SET LANGX TO:    SET LANGXLIB TO:
//*      DEBUG TOOL       EQALANGX         THE DT SEQAMOD LIBRARY
//*      FAULT ANALYZER   IDILANGX         THE FA SIDIAUTH LIBRARY
//*      APA              CAZLANGX         THE APA SCAZAUTH LIBRARY
//*
//*  *********************************
//*      ASSEMBLER STEP
//*  *********************************
//ASM1 EXEC  PGM=ASMA90,COND=(4,LT),REGION=32M,
//      PARM='ADATA,OBJECT'
//SYSIN    DD DISP=SHR,DSN=&SYSUID..ADLAB.SOURCE(&MEM)
//SYSPRINT DD SYSOUT=*
//SYSLIN   DD DISP=SHR,DSN=&SYSUID..ADLAB.OBJ(&MEM)
//SYSADATA DD DISP=SHR,DSN=&SYSUID..ADLAB.SYSADATA(&MEM)
//SYSLIB  DD  DSN=SYS1.MODGEN,DISP=SHR
//        DD  DSN=SYS1.MACLIB,DISP=SHR
//        DD  DSN=&LEHLQ..SCEEMAC,DISP=SHR
//SYSUT1  DD  DISP=(NEW,DELETE),DSN=&&SYSUT1,SPACE=(1700,(900,450)),
//     UNIT=&UNITDEV
//SYSUT2  DD  DISP=(NEW,DELETE),DSN=&&SYSUT2,SPACE=(1700,(600,300)),
//     UNIT=&UNITDEV
//SYSUT3  DD  DISP=(NEW,DELETE),DSN=&&SYSUT3,SPACE=(1700,(600,300)),
//     UNIT=&UNITDEV
//*
//*  *********************************
//*     STEP TO GENERATE LANGX FILE
//*  *********************************
//LANGX    EXEC PGM=&LANGX,REGION=32M,
//  PARM='(ASM ERROR'
//STEPLIB  DD DISP=SHR,DSN=&LANGXLIB
//         DD DISP=SHR,DSN=&LEHLQ..SCEERUN
//SYSADATA DD DSN=&SYSUID..ADLAB.SYSADATA(&MEM),DISP=SHR
//IDILANGX DD DSN=&SYSUID..ADLAB.EQALANGX(&MEM),DISP=SHR
//*
//*  *********************************
//*        LINK-EDIT (BINDER) STEP
//*  *********************************
//LINK     EXEC PGM=IEWL,PARM='MAP',REGION=0M
//SYSLIB   DD DSN=&LEHLQ..SCEELKED,DISP=SHR
//SYSPRINT DD SYSOUT=*
//SYSLMOD  DD DISP=SHR,DSN=&SYSUID..ADLAB.LOAD(&MEM)
//SYSUT1   DD UNIT=SYSDA,SPACE=(TRK,(10,10))
//SYSLIN   DD DSN=&SYSUID..ADLAB.OBJ(&MEM),DISP=SHR
//         DD *
     MODE AMODE(31),RMODE(24)
     ENTRY ASAM1
//*