Rational® Developer
for System z® provides a
local include preprocessor that allows you to incorporate external
source files into your programs by using include directives other
than the PL/I directive %INCLUDE or COBOL COPY statement.
Before you begin
Before using the local include preprocessor, you need to have
created a local property group and associated it with a local PL/I
source file or local project.
For PL/I files, Rational Developer for System z does not support local
preprocessors on the Linux platform.
About this task
The local include preprocessor is located in the
bin directory
of the Rational Developer
for System z installation
path. On Windows the file
name is
PPINCL01.EXE. On Linux the file name is
PPINCL01.You
can use the local include preprocessor with an individual PL/I program
or a local z/OS® project containing
one or more 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 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 invoked 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 previous active
preprocessor's Preprocessor Output File Name entry
field. See Using multiple local preprocessors for more information about setting up multiple-preprocessor
operations.
Procedure
To use the local include preprocessor:
- Open the property group editor for the property group associated
with the resource or project and navigate to the PL/I page.
- From the list on the left, click Local Preprocessor to
open the Local Preprocessor page.
- To add a new local preprocessor to the property group,
click New.
- Complete the fields in the Preprocessor Options section
of the Local Preprocessor page.
- Preprocessor Description
- Type a description, such as "Include preprocessor."
- Preprocessor Name (fully qualified)
- Type the full path name for the include preprocessor. You can
use the ${INSTDIR} variable to point to the Rational Developer for System z installation directory. This variable
is used to find the include preprocessor.
- Preprocessor Arguments
- The include preprocessor can take the following arguments:
- TRACE(ON|OFF) On the workstation, this
option provides additional output to the TPF Remote Console. On 390
systems, this option provides additional JES output. This output is
intended for use by an IBM® technical
support representative and should not be used during the regular course
of development because it increases the amount of unwanted output
and can decrease performance. If you need to 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 6 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
perform the replacement of strings in the copy file, nor does it find
the member name 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 quotes 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.
On Linux platforms,
use braces { } instead of parentheses to specify preprocessor options,
such as TRACE{ON} and FORMAT{ON}.
- 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 check box to log errors generated by the preprocessor.
Selecting this check box 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 should change
the value to point to the folder containing your include files. The path length for the SYSLIB environment variable is limited
to 4K. No error message is issued for lengths that exceed 4K, but
SYSLIB statements greater than 4K may cause syntax check operations
to end abnormally in the include preprocessor program.
On Linux, use the export statement
to set environment variables, such as export SYSLIB=/root/project1/includes.