Preparing z/OS® XL C and C++ programs

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

Create a library (PDSE is suggested unless PDS is required for your organization) for expanded source files. This library is only needed in test environments where debugging is performed. This can be any RECFM / LRECL / BLKSIZE supported as input by the compiler.
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.
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.
Run a 2-stage compilation. The first stage preprocesses the program, so that ADFz products have access to fully expanded source code. The second stage compiles the program.
- In the first compilation 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. Note that DB2® programs containing SQL statements cannot use the PP option directly. If used, the behavior is undefined. Follow z/OS® Debugger instructions to Processing SQL Statements first. See z/OS® Debugger V14.1 User's Guide, Chapter 8. "Preparing a DB2® program", section "Processing SQL statements".
  Modify the SYSUT10 DD to enable z/OS® Debugger, by saving it in an expanded source library and specify a member name that is equal to the primary entry point name or CSECT name of your application program.
- You can prepare your program with a one-stage compilation, skipping the expanding source preprocessing step recommended above. If you do this, you need to be aware of the following:
  - Case 1: If there are no executable statements in the header file, the header file is not included in the captured source that is saved in the mdbg file and is not available for browsing during a z/OS® Debugger session. All other z/OS® Debugger functionality is still available.
  - Case 2: If there are executable statements in the header file, the header file is included in the captured source that is saved in the mdbg file and is available for browsing during a z/OS® Debugger session.
- For all programs, such as batch, CICS®, and IMS™, for the second compilation stage, refer to Examples of compiler options and source information files that are supported by ADFz products for C and C++ for the appropriate options.
Modify the SYSCPRT DD in the second compiler stage to refer to a file. This file is the compiler listing and is the source information file for 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 facilitate source support in Fault Analyzer, CSECTs in C programs should be named using the following statement:
```
#pragma csect(code, "csect_name")
```
where, if using a PDS(E), csect_name matches the compiler listing or LANGX file member name. This enables the side file search to automatically locate compiler listings. Without named CSECTs, C compiler listings can only be located by using the compiler listing read user exit or the compiler listing prompt. For details see the Compiler Listing Read user exit and Prompting for compiler listing or side file topics in the IBM Fault Analyzer for z/OS User’s Guide.
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. You also need to promote any file that is related to the compilation, not just the listing. So you need to promote, for example, dbg and mdbg files.
Optionally, include a z/OS® Debugger Language Environment® exit module into the load module during the linkage editor step. This approach is one way to enable z/OS® Debugger 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 EQAD3CXT for batch programs, IMS/TM, IMS™ BTS programs, and DB2® type MAIN stored procedures.
For CICS® applications only: if the z/OS® Debugger DTCN transaction is used to start z/OS® Debugger, link edit the z/OS® Debugger CICS® startup exit module EQADCCXT into the application load module to enable z/OS® Debugger in CICS®. This link edit is not needed if using the CADP transaction instead of DTCN.