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

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 12. 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 13. 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)


Rate this page

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