IPA | NOIPA

Pragma equivalent

None.

Purpose

Enables or customizes a class of optimizations known as interprocedural analysis (IPA).

Syntax


   .-NOIPA-.   
>>-+-IPA---+---------------------------------------------------->

>--+------------------------------------------------------------------------------+-><
   | .-,------------------------------------------------------------------------. |   
   | V                                                                          | |   
   '---(--+-NOLINK | LINK-----------------------------------------------------+-+-'   
          +-OBJ | NOOBJ-------------------------------------------------------+       
          +-ATTR | NOATTR-----------------------------------------------------+       
          +-COM|NOCOM---------------------------------------------------------+       
          +-GONUM | NOGONUM---------------------------------------------------+       
          +-LIS | NOLIS-------------------------------------------------------+       
          +-OPT | NOOPT-------------------------------------------------------+       
          +-XR | NOXR---------------------------------------------------------+       
          +-LEVEL--+-(0)-+----------------------------------------------------+       
          |        +-(1)-+                                                    |       
          |        '-(2)-'                                                    |       
          +-CONTROL | NOCONTROL--+--------------+-----------------------------+       
          |                      '-(--fileid--)-'                             |       
          +-DUP | NODUP-------------------------------------------------------+       
          +-ER | NOER---------------------------------------------------------+       
          +-MAP | NOMAP-------------------------------------------------------+       
          +-NCAL | NONCAL-----------------------------------------------------+       
          +-UPCASE | NOUPCASE-------------------------------------------------+       
          +-PDF1 | NOPDF1-----------------------------------------------------+       
          +-PDF2 | NOPDF2-----------------------------------------------------+       
          '-PDFNAME | NOPDFNAME--(--+-//data set name--------------------+--)-'       
                                    '-z/OS UNIX System Services filename-'

Defaults

NOIPA

The default for the c99, c89, cc, c++ z/OS® UNIX System Services utilities is:

NOIPA(NOCONTROL(ipa.ctl),DUP,NOER,NOMAP,NOUPCASE,NONCAL)IPA(LINK,LEVEL(1)).

Parameters

IPA compile and link step suboptions

LEVEL(0|1|2)

Indicates the level of IPA optimization that the IPA link step should perform after it links the object files into the call graph.

If you specify LEVEL(0), IPA performs subprogram pruning and program partitioning only.

If you specify LEVEL(1), IPA performs all of the optimizations that it does at LEVEL(0), as well as subprogram inlining and global variable coalescing. IPA performs more precise alias analysis for pointer dereferences and subprogram calls.

Under IPA Level 1, many optimizations such as constant propagation and pointer analysis are performed at the intraprocedural (subprogram) level. If you specify LEVEL(2), IPA performs specific optimizations across the entire program, which can lead to significant improvement in the generated code.

The compiler option OPTIMIZE that you specify on the IPA link step controls subsequent optimization for each partition during code generation. Regardless of the optimization level you specified during the IPA compile step, you can modify the level of IPA optimization, regular code generation optimization, or both, on the IPA link step.

The default is IPA(LEVEL(1)).

IPA compile step suboptions

NOLINK

IPA(NOLINK) invokes the IPA compile step. (NOLINK is the default.)

ATTRIBUTE | NOATTRIBUTE

Indicates whether the compiler saves information about symbols in the IPA object file. The IPA link step uses this information if you specify the ATTR or XREF option on that step.

The difference between specifying IPA(ATTR) and specifying ATTR or XREF is that IPA(ATTR) does not generate a Cross Reference or Static Map listing sections after IPA compile step source analysis is complete. It also does not generate a Storage Offset, Static Map, or External Symbol Cross Reference listing section during IPA compile step code generation.

The default is IPA(NOATTRIBUTE). The abbreviations are IPA(ATTR|NOATTR). If you specify the ATTR or XREF option, it overrides the IPA(NOATTRIBUTE) option.

IPA(ATTR|NOATTR) is not supported with the METAL option.

COMPRESS | NOCOMPRESS

Indicates that the IPA object information is compressed to significantly reduce the size of the IPA object file.

The default is IPA(COMPRESS). The abbreviations are IPA(COM|NOCOM).

GONUMBER | NOGONUMBER

Indicates whether the compiler saves information about source file line numbers in the IPA object file. The difference between specifying IPA(GONUMBER) and GONUMBER is that IPA(GONUMBER) does not cause GONUMBER tables to be built during IPA compile step code generation. If the compiler does not build GONUMBER tables, the size of the object module is smaller.

Refer to GONUMBER | NOGONUMBER for information about the effect of this suboption on the IPA link step. Refer also to Interactions between compiler options and IPA suboptions.

The default is IPA(NOGONUMBER). The abbreviations are IPA(GONUM|NOGONUM). If you specify the GONUMBER or LIST option, it overrides the IPA(NOGONUMBER) option.

IPA(GONUM|NOGONUM) is not supported with the METAL option.

LIST | NOLIST

Indicates whether the compiler saves information about source line numbers in the IPA object file. The difference between specifying IPA(LIST) and LIST is that IPA(LIST) does not cause the IPA compile step to generate a Pseudo Assembly listing.

Refer to LIST | NOLIST for information about the effect of this suboption on the IPA link step. Refer also to Interactions between compiler options and IPA suboptions.

The default is IPA(NOLIST). The abbreviations are IPA(LIS|NOLIS). If you specify the GONUMBER or LIST option, it overrides the IPA(NOLIST) option.

OBJECT | NOOBJECT

Controls the content of the object file.

OBJECT
The compiler performs IPA compile-time optimizations and generates IPA object information for the resulting program, in addition to generating optimized object code. See z/OS XL C/C++ Programming Guide for a list of optimizations.

The object file can be used by an IPA link step, a prelink/link step, or a bind step.
NOOBJECT
The compiler performs IPA compile-time optimizations and generates IPA object information for the resulting program. No object code is generated.

The object file can be used by an IPA link step only.

The default is IPA(OBJECT). The abbreviations are IPA(OBJ|NOOBJ).

Note: When the METAL option is specified, IPA(OBJECT) is not supported.

OPTIMIZE | NOOPTIMIZE

The default is IPA(OPTIMIZE) If you specify IPA(NOOPTIMIZE), the compiler issues an informational message and turns on IPA(OPTIMIZE). The abbreviations are IPA(OPT|NOOPT).

IPA(OPTIMIZE) generates information (in the IPA object file) that will be needed by the OPT compiler option during IPA Link processing.

If you specify the IPA(OBJECT), the IPA(OPTIMIZE), and the NOOPTIMIZE option during the IPA compile step, the compiler creates a non-optimized object module for debugging. If you specify the OPT(2) option on a subsequent IPA link step, you can create an optimized object module without first rerunning the IPA compile step.

XREF | NOXREF

Indicates whether the compiler saves information about symbols in the IPA object file that will be used in the IPA link step if you specify ATTR or XREF on that step.

The difference between specifying IPA(XREF) and specifying ATTR or XREF is that IPA(XREF) does not cause the compiler to generate a Cross Reference or Static Map listing sections after IPA compile step source analysis is complete. It also does not cause the compiler to generate a Storage Offset, Static Map, or External Symbol Cross Reference listing section during IPA compile step code generation.

Refer to XREF | NOXREF for information about the effects of this suboption on the IPA link step.

The default is IPA(NOXREF). The abbreviations are IPA(XR|NOXR). If you specify the ATTR or XREF option, it overrides the IPA(NOXREF) option.

IPA link step suboptions

LINK

IPA(LINK) invokes the IPA link step.

Only the following IPA suboptions affect the IPA link step. If you specify other IPA suboptions, they are ignored.

CONTROL[(fileid)] | NOCONTROL[(fileid)]

Specifies whether a file that contains IPA directives is available for processing. You can specify an optional fileid. If you specify both IPA(NOCONTROL(fileid)) and IPA(CONTROL), in that order, the IPA link step resolves the option to IPA(CONTROL(fileid)).

The default fileid is DD:IPACNTL if you specify the IPA(CONTROL) option. The default is IPA(NOCONTROL).

For more information about the IPA link step control file, see IPA link step control file.

DUP | NODUP

Indicates whether the IPA link step writes a message and a list of duplicate symbols to the console.

The default is IPA(DUP).

ER | NOER

Indicates whether the IPA link step writes a message and a list of unresolved symbols to the console.

The default is IPA(NOER).

MAP | NOMAP

Specifies that the IPA link step will produce a listing. The listing contains a Prolog and the following sections:

Object File Map
Compiler Options Map
Global Symbols Map (which may or may not appear, depending on how much global coalescence was done during optimization)
Partition Map for each partition
Source File Map

The default is IPA(NOMAP).

See Using the IPA link step listing for more information.

NCAL | NONCAL

Indicates whether the IPA link step performs an automatic library search to resolve references in files that the IPA compile step produces. Also indicates whether the IPA link step performs library searches to locate an object file or files that satisfy unresolved symbol references within the current set of object information.

This suboption controls both explicit searches triggered by the LIBRARY IPA Link control statement, and the implicit SYSLIB search that occurs at the end of IPA Link input processing.

To help you remember the difference between NCAL and NONCAL, you may think of NCAL as "nocall" and NONCAL as "no nocall", (or "call").

The default is IPA(NONCAL).

UPCASE | NOUPCASE

Determines whether the IPA link step makes an additional automatic library call pass for SYSLIB if unresolved references remain at the end of standard IPA Link processing. Symbol matching is not case sensitive in this pass.

This suboption provides support for linking assembly language object routines, without forcing you to make source changes. The preferred approach is to add #pragma map definitions for these symbols, so that the correct symbols are found during normal IPA Link automatic library call processing.

The default is IPA(NOUPCASE). The abbreviations are IPA(UPC|NOUPC).

IPA PDF suboptions

PDF1 | NOPDF1, PDF2 | NOPDF2, PDFNAME | NOPDFNAME

The default is IPA(NOPDF1, NOPDF2, NOPDFNAME).

Notes:

When the METAL option is specified, all PDF suboptions are not supported.
IPA(PDF) applies to both the IPA compile and IPA link steps. IPA(PDF) requires that the RENT (C only) compiler option is active. This requirement has no effect on C++ because C++ code behaves as if RENT was specified.

PDF (profile-directed feedback) is a suboption of IPA that enables you to use the results from sample program execution to improve optimization near conditional branches and in frequently executed code sections. PDF allows you to gather information about the critical paths and the usage of various parts of the application. PDF passes this information to the compiler so that the optimizer can work to make these critical paths faster. This is a three stage process that involves:

Performing a full IPA build with the PDF1 and PDFNAME suboptions
Running the trial application with representative data
Performing another full IPA build with the PDF2 suboption (the file indicated by PDFNAME holds the profile generated when the code was run in step 2)

Note: The trial application built from the IPA(PDF1) compiler option can only be run on the current system.

The following list describes each of the IPA PDF suboptions:

PDF1: An IPA suboption specified during IPA Compile and Link steps. It tells IPA to prepare the application to collect profiling information.
PDF2: An IPA suboption specified during IPA Compile and Link steps. It tells IPA to use the profiling information that is provided when optimizing the application.
PDFNAME: This IPA suboption should be used with PDF1 and PDF2 to provide the name of the file that contains the profiling information.
PDFDIR: This environment variable can be used when using IPA(PDF) in the z/OS UNIX System Services shell. It is used to specify the directory for the file that contains the profiling information.

Usage

The following information describes how to use PDF.

Before you begin: PDF requires that you compile the entire application twice and is intended to be used after other debugging and tuning is finished. PDF compiles should be performed during one of the last steps before putting the application into production. The following list describes restrictions that applies to the procedures that follow:

You must compile the main program with IPA for profiling information to be collected at run time.
Do not compile or run two different applications that use the same PDFDIR directory at the same time, unless you have used the PDFNAME(filename) suboption to distinguish the sets of profiling information.
To get the most optimization from the collected profiling information, use the same set of source files and identical compiler options when you compile with PDF1 as with PDF2.
You must ensure the profiling information that is provided to the compiler during the PDF2 step is for the application you are tuning.
- If a non-qualified data set name is provided, the same userid that runs the application to collect the profiling information must perform the PDF2 step.
- If PDFDIR is set for the PDF2 step, it must name a directory where the actual profiling information can be found.
The profiling information is placed in the file specified by the PDFNAME(filename) suboption, where filename can be a z/OS UNIX System Services file name or a z/OS data set name (physical sequential data set or a member of a partitioned data set). For a data set name, it can be fully qualified such as PDFNAME="//'HLQ.PDF'" or non-qualified such as PDFNAME=//PDF, in which case the actual data set name will be userid.PDF, where the userid identifies the user who is executing the application built with PDF1 and building the application with PDF2. The key DCB attributes are RECFM=U and LRECL=0. In the z/OS UNIX environment, the profile is placed in the current working directory or in the directory that the PDFDIR environment variable names, if that variable is set. If PDFNAME(filename) is not specified, the default file name is PDFNAME(@@PDF). This file is referred to as the PDF file.
If PDFNAME is not provided, then you need to ensure that the same environment (z/OS UNIX System Services, batch/TSO, POSIX mode) is used to collect the profiling information and to perform the PDF1 or PDF2 steps. This is because PDFNAME will default to @@PDF and thus the actual location of the file is based on the environment. For example, when the POSIX(ON) runtime option is used, the PDF file will be ./@@PDF and when the POSIX(OFF) runtime option is used, the PDF file will be in data set userid.@@PDF. In order to eliminate unnecessary confusion, it is recommended that an explicit PDF file name always be provided.
The compiler makes an attempt to delete the PDF file during PDF1 IPA(LINK) processing.
If PDFNAME names a data set, it is strongly recommended that the data set physically exist and be allocated with sufficient space before step 2 in the process. Since the actual space required is based on the complexity of the application and the amount of the test data, you may run into a situation where the pre-allocated space is insufficient and you need to re-allocate the data set with larger space. The recommended attributes for the PDF data set are: RECFM=U LRECL=0.
If you do compile a program with PDF1, it will generate profiling information when it runs, which involves some performance overhead. This overhead goes away when you recompile with PDF2 or with no PDF (NOPDF1 and NOPDF2).
The CCNXPD1B, CCNPD1B, CCNPD1B, and CCNQPD1B PROCs have been created to help the batch user link with the libraries required for IPA(PDF1). Unlike the default link PROCs, these PROCs will statically bind the libraries to support correct operation of the information capture runs.
Applications built with IPA(PDF1) should not be put into production because the application will be slower due to the instrumented code. The application will lose its natural reentrancy due to the sharing of the global data between the application and the statically bound PDF runtime code.

Perform the following steps to use PDF:

Compile your program with the IPA(PDF1) suboption. You also need to specify the OPTIMIZE(2) option, or preferably the OPTIMIZE(3) option. Pay special attention to the compiler options that you use to compile the program, because you will need to use the same options later. Link the program using CCNPD1B, CCNXPD1B, or CCNQPD1B in batch, or the -Wl,PDF option in the z/OS UNIX System Services shell.
Run the program built from step 1 all the way through using a typical data set. The program records profiling information when it finishes. You can run the program multiple times with different input data sets, and the profiling information is accumulated to provide a count of how often branches are taken and blocks of code are executed, based on the input data sets used.
Note: Use data that is representative of the data that will be used during a normal run of your finished program.
It is recommended that you rebuild your program using the identical set of source files with the identical compiler options that you used in step 1, but change PDF1 to PDF2. This must be done with the same compiler release you use in step 1. In this second stage, the accumulated profiling information is used to fine-tune the optimizations. The resulting program does not contain profiling overhead. During the PDF2 phase, the compiler issues an information message with a number in the range of 0 to 100. If you have not changed your program between the PDF1 and PDF2 phases, the number is 100, which means that all the profiling data can be used to optimize the program. If the number is 0, it means that the profiling data is completely outdated, and the compiler cannot take advantage of any information. When the number is less than 100, you can choose to recompile your program with the PDF1 option and regenerate the profiling data.
If you modify the source files, compiler options, or both that are used in step 1, you might see a list of warnings and the benefits from PDF might not apply for the changes from step 1.

Note: If you specify the PDF1 or PDF2 option on the IPA Link step but not on the Compile step, the compiler issues a warning message. The message indicates that you must recompile your program to get all the profiling information.

PDF1 at IPA compile step causes IPA to place an indicator in the IPA object so the functions in the compilation unit are instrumented during the IPA link step.

PDF2 at IPA compile step causes IPA to place an indicator in the IPA object so the functions in the compilation unit are optimized based on the profiling information.

PDF1 at IPA link step causes IPA to insert instrumentation in the application code.

PDF2 at IPA link step causes IPA to optimize the application based on the profiling information collected in the file specified by PDFNAME.

Predefined macros