Application Performance Analyzer for z/OS, Version 11.1, User's Guide

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 8. 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)



Rate this page

[ Top of Page | Previous Page | Next Page | Contents | Index ]