Using the local include preprocessor

Edit online

The local include preprocessor allows for the incorporation of external source files into programs by using include directives other than the PL/I directive %INCLUDE or COBOL COPY statement.

Before you begin

Create a local property group and associated it with a local COBOL or PL/I source file or local project.
Limitation: The local include preprocessor is not supported on macOS clients.

You can set content type associations for the include preprocessor to define which file extensions the preprocessor searches when it looks for copy and include files. For instructions for defining content type associations, see the related topics. When you define content type associations for the include preprocessor, the product passes an EXT( ) parameter to the include preprocessor that contains a list of allowable file extensions, such as EXT("cpy","inc","mac").

About this task

The local include preprocessor is in the com.ibm.systemz.preprocessor.include plug-in that is unpacked when you install the product. You can use the local include preprocessor with an individual COBOL or PL/I program or a local z/OS® project that contains one or more COBOL or PL/I programs. You can also use it alone or as part of a multi-preprocessor build operation.
  • When the include preprocessor is the only preprocessor that is called before a compilation, the input file is the COBOL or PL/I program that was selected for a Syntax Check or Show Dependencies operation.
  • When the include processor is called for a project build, each COBOL or PL/I program in the project is processed and then compiled. The input file in this case is the current COBOL or PL/I source that is being processed.
  • When the include preprocessor is called as part of a multiple-preprocessor operation and is started after a previous preprocessor, the input file to the include preprocessor is the output file from the previous active preprocessor. This file is the one listed in the Preprocessor Output File Name entry field of previous active preprocessors. For more information about setting up multiple-preprocessor operations, see Using multiple local preprocessors.

Procedure

To use the local include preprocessor:

  1. Open the property group editor for the property group that is associated with the resource or project and open to the PL/I page.
  2. From the list on the left, click Local Preprocessor to open the Local Preprocessor page.
  3. Click New.
  4. Complete the fields in the Preprocessor Options section of the Local Preprocessor page.
    Preprocessor Description
    Type a description, such as Include preprocessor.
    Preprocessor Name
    Type the name for the include preprocessor. The default value is ${bundle:com.ibm.systemz.preprocessor.include}/bin/operatingSystem/PPINCL01, where operatingSystem is macos or win32. The ${bundle} variable points to an unpacked bundle or plug-in. This variable is used to find the include preprocessor.
    Note: If you are using a property group created in V14.1.4 or an earlier release, then a Preprocessor Name that uses the ${INSTDIR} variable to point to the installation directory remains valid. For version 14.1.5, the PPINCL01 preprocessor is included both in the product installation path and in the com.ibm.systemz.preprocessor.include plug-in.
    Preprocessor Arguments
    The include preprocessor can take the following arguments:
    • TRACE(ON|OFF) On the workstation, this option provides more output to the TPF Remote Console. On 390 systems, this option provides more JES output. This output is intended for use by an IBM® technical support representative and must not be used during the regular course of development because it increases the amount of unwanted output and can decrease performance. If you must contact your IBM technical support representative for problem determination, you can copy this output it into your correspondence. The default for this option is TRACE(OFF). If the option is not specified, the default value is used.
    • FORMAT(ON|OFF) On the workstation and on 390 systems, this option changes the readability of the XML generated for error messages. FORMAT(ON) causes the statement table to be written in six columns, making the XML file more readable. Setting this option significantly decreases the performance of parsing the XML file, causing operations to take longer. The default for this option is FORMAT(OFF). If the option is not specified, the default value is used.
    • NOCOPY(ON|OFF) If your source contains COPY REPLACE statements, the include preprocessor does not support processing the COPY REPLACE statement. The preprocessor does not replace strings in the copy file, nor does it find the member name that is specified in the COPY REPLACE statement. To avoid this problem, use the NOCOPY(ON) preprocessor option. This option allows the -INC and ++INCLUDE statements to be processed, but the COPY statements and the %INCLUDE statements are not processed by the include preprocessor. The compiler processes those statements after the preprocessor.

      If your source contains COPY statements with the member name enclosed in quotation marks or apostrophes, the include preprocessor does not support processing these statements. To avoid this problem, use the NOCOPY(ON) preprocessor option. This option allows the -INC and ++INCLUDE statements to be processed, but the COPY statements and the %INCLUDE statements are not processed by the include preprocessor. The compiler processes those statements after the preprocessor.

    • CMT(ON|OFF) When you specify CMT(ON) and open an expanded source file, the include preprocessor comments the original COPY or INCLUDE statement, places the copybook or include file into the source file, and then places another comment to indicate the end of the copybook or include file. The expanded copybook or include file and the comments look like this example:
      * COPY ABC
01  XYZ     PIC X
01  FIRST  PIC 9
    • For more information about showing expanded source, see the related topics.
    Restriction: By default, this field is empty. If you define content types for the include preprocessor and you specify any preprocessor arguments in this field, then you must manually add any file extensions that you want the preprocessor to recognize by using the EXT( ) argument, such as EXT("cpy","inc"," ").
    Preprocessor Output File Name
    Specify a file name to be used for preprocessor output. If you omit this option, an output file name is generated.
    Support Error Feedback
    Select this checkbox to log errors that are generated by the preprocessor. Selecting this checkbox enables the Error Feedback XML File Name field. This option is enabled by default.
    Error Feedback XML File Name
    Specify the unqualified name of the XML file to be generated for error feedback. If you omit this option, an error feedback XML file name is generated.
    Environment Variables (Set Statements)
    Specify any environment variables to be passed to the preprocessor. This field contains a value for the SYSLIB, but you must change the value to point to the folder that contains your include files. The path length for the SYSLIB environment variable is limited to 4 K. No error message is issued for lengths that exceed 4 K, but SYSLIB statements greater than 4 K might cause syntax check operations to end abnormally in the include preprocessor program.