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.
    • In the first compile stage, in both test and production environments:
      • Specify compiler options PP(COMMENTS,NOLINES) to expand INCLUDEs and macros. The output is SYSUT10 DD, which is the expanded source file and is the input for the second compiler stage.
      • Modify the SYSUT10 DD to enable Debug Tool, by saving it in a expanded source library and specify a member name that is equal to the primary entry point name or CSECT name of your application program.
    • For all programs, such as batch, CICS, and IMS, for the second compiler stage:
      • In test environments:
        • For C++, specify compiler options TEST, ATTRIBUTE(FULL), NOIPA, LIST, NESTINC(255), NOOFFSET, NOOPT, SOURCE, XREF.

          TEST and NOOPT are required by Debug Tool. Debug hooks are inserted, which will adds runtime overhead. Symbolic data required by Debug Tool is stored in the module, which can make it significantly larger.

          The other options format the compiler listing as required by Fault Analyzer for z/OS and Application Performance Analyzer for z/OS.

        • For C, specify compiler options TEST(ALL), AGGREGATE, NOIPA, LIST, NESTINC(255), NOOFFSET, NOOPT, SOURCE, XREF.

          TEST(ALL) and NOOPT are required by Debug Tool. Debug hooks are inserted, which adds runtime overhead. Symbolic data required by Debug Tool is stored in the module, which can make it significantly larger.

          The other options format the compiler listing as required by Fault Analyzer for z/OS and Application Performance Analyzer for z/OS.

      • In production environments:
        • For C++, specify compiler options: NOTEST, ATTRIBUTE(FULL), NOIPA, LIST, NESTINC(255), NOOFFSET, NOOPT, SOURCE, XREF.
        • For C, specify compiler options: NOTEST, AGGREGATE, NOIPA, LIST, NESTINC(255), NOOFFSET, NOOPT, SOURCE, XREF.

        NOTEST disables Debug Tool, but provides the best performance. This produces 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.

        The other options format the compiler listing as required for Fault Analyzer for z/OS and Application Performance Analyzer for z/OS.

  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.