Rational Developer for System z

Setting local preprocessor options

This topic describes options you can set for local preprocessors.

Before you begin

You need to have defined a property group on a local or remote system.

About this task

Local preprocessor support is available for the following compilation or syntax check operations:
Tip: When you use local preprocessors with remote files, the output files are generated to the RemoteSystemTempFiles > Build Output folder in the file tree.

Linux icon Rational® Developer for System z® does not support local COBOL or PL/I builds. For PL/I files, Rational Developer for System z does not support local preprocessors, syntax check, or show dependencies on the Linux platform.

Procedure

To define options for local preprocessors:

  1. Open a property group in the property group editor.
  2. Navigate to the Local Preprocessors tab of the Local COBOL Settings or Local PLI Settings page. This page contains two sections: the Preprocessors section shows all preprocessors that have been added the property group. There are two ways to work with this list:
    • Select the check box next to a preprocessor name to enable the preprocessor to execute before a compilation or syntax check operation. This action is called "selecting a preprocessor." The preprocessor is activated for execution only when the check box is selected.
    • Select the preprocessor name in the list to display the options set for it in the Preprocessor Options section. This action is called "highlighting a preprocessor."
    The Preprocessor Options section shows the options for the selected preprocessor.
    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
    Enter any arguments that you are passing to your preprocessor. These arguments would be entered as though you were passing them to your preprocessor from the command prompt. The arguments may include the fully qualified path of the file being preprocessed. If your arguments include the fully qualified name of the XML file, or output file being produced by your preprocessor it is required that the XML file and output file be created in the BuildOutput folder of the local project.
    Preprocessor Output File Name
    Enter the name of the expanded file that your preprocessor will produce. This file name must be unqualified. The Output file must be generated in the BuildOutput folder of the local project.
    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 name of the XML file to be generated for error feedback. This XML file must be unqualified, as it is required that it be created in the BuildOutput folder of the local project.
    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.

    You can also use the following variables in any of the entry fields to help generalize project builds:

    ${project_loc}
    The project location. It can be used to add the location on disk of the project. If you need to pass the name of a folder in your project to your preprocessor, you can specify it as ${project_loc}\folder1. Upon invocation of the preprocessor, ${project_loc} is substituted.
    ${rdz_cache_home}
    When using a local preprocessor with a remote file, it may be necessary to reach the root cache location. This location is the Rational Developer for System z cache location described in the ${rdz_cache_sysn} variable explanation. This variable does not include the "FttRemoteTempFiles"\RSE Connection Name subfolders. The BuildOutput folder for a local syntax check of a remote file is in the ${rdz_cache_home} location. This folder is the one from which the local preprocessor is invoked.
    ${rdz_cache_sysn}
    When using a local preprocessor with a remote file, it may be necessary to be able to point to your file in the Rational Developer for System z download location. This location depends on your workspace location. Rational Developer for System z downloads your compilation dependencies on a local syntax check of a remote file. The download location is the Rational Developer for System z cache location. In performing a local syntax check of a remote file, you need to have your preprocessor running on the remote system. A combination of a preprocess and a compilation is performed on the remote system, and a list of build dependencies is created. This is the same list of files that is displayed when you perform the Show Dependencies operation on the file. This is the same list of files that you see if you click the Dependent Files button on the Check Dependencies dialog from the Syntax Check > Local action. These files are downloaded to the cache location. You may need to point to a file or a folder using the ${rdz_cache_sysn} variable. If a data set member USERID.A001.COPYLIB(MEM1) is one of your dependent files, for example, you may need to point to the cache location of that file for your local preprocessor to consume. One way to do that is to set an environment variable to the folder containing the downloaded member. You can do this in the preprocessor environment variable entry field: SET SYSLIB=${rdz_cache_sysn}\USERID\USERID.A001.COPYLIB. The parent of the folder corresponding to the data set is the high-level qualifier of the data set name containing the member. The variable ${rdz_cache_sysn} is substituted with Rational Developer for System z cache location "FttRemoteTempFiles"\RSE Connection Name.
    ${resource_fn}
    The unqualified file name of the current resource being preprocessed. If you were performing a project build, and there were 3 COBOL files in your project, RED.cbl, WHITE.cbl, and BLUE.cbl, for each preprocess during the project build a value would be assigned to that variable. The value would be either RED, WHITE, or BLUE. This variable is of value when you are specifying preprocessor values on the project. For example, specifying ${resource_fn}_PP1.dek in the Preprocessor Output File Name entry field leads to output files RED_PP1.dek, WHITE_PP1.dek, and BLUE_PP1.dek, in the BuildOutput folder.
    ${resource_loc}
    The location on disk of the resource that is being preprocessed. If the preprocessor requires the exact location of the file on disk to preprocess it, you can use this variable, and upon invocation, the value of the resource location on disk is substituted. When you are performing a local syntax check of a remote file, the value of ${resource_loc} in the local preprocessor options is the location of the file in the Rational Developer for System z cache.
    ${INSTDIR}
    The install directory of Rational Developer for System z.

    When the local preprocessor is invoked by the syntax check, build, or show dependencies action the current directory for this action will be the BuildOutput folder of the local project. The XML file and expanded source file that your preprocessor create should be created in this folder.

  3. Save the property group to save the changes you have made.

Results

If you are using local preprocessors on a remote file, the build output is located in the RemoteSystemTempFiles/Build Output folder. You can find this folder by going to the systems file navigator and navigating to your workspace location. Inside your workspace's folder is the RemoteSystemTempFiles folder.

Feedback