Local preprocessor support

Z Open Editor provides the advanced capability to integrate parsing of COBOL programs with a custom preprocessor to allow editing programs that contain such preprocessor statements without causing the editor to show syntax errors. The preprocessor would be executed on a developer machine by Z Open Editor in the background, taking COBOL with custom code and transforming it to valid COBOL. Users can then edit such programs by using the preprocessor output to still provide full language support such as code completion, syntax error highlighting, and outline view. The editor would not learn the preprocessor language, but rather ensure the the resulting preprocessed output is still valid COBOL.

Example workflow

The following workflow is written from the perspective of COBOL developer, Deb.

1. Deb installs a command-line centric preprocessor program on her local development machine.
2. Deb creates a zapp.yaml file with a preprocessor profile type. The profile specifies the command-line for running the preprocessor on the currently edited program file as well as the output path for the preprocessed program files.
3. Deb edits a program file with preprocessor statements in Z Open Editor.
4. Deb either manually starts preprocessing the program via a right-click menu command or she created a user setting to automatically run the preprocessor on Save.
5. Z Open Editor starts the preprocessor command in the background and sends the resulting output file to its COBOL parser.
6. Z Open Editor's COBOL parser will compare the program in the editor with the output of the preprocessor command.
7. Deb hovers over processor statements in Z Open Editor, which displays the resulting COBOL.
8. Deb continues editing the program in Z Open Editor. Z Open Editor continues to provide full language support for all the parts of the program that are not preprocessor statements.

To learn and explore this sample workflow, we have provided a example preprocessor and code samples in our Github repository at https://github.com/ibm/zopeneditor-sample/tree/wazi-main/preprocessor. Review the Readme file in this folder with detailed instructions for building and running the sample.

Requirements for the preprocessor

To be able to integrate your preprocessor with Z Open Editor, it must fulfill these requirements:

• It needs to run locally on your development machine where Z Open Editor is running.
• You need to be able to run the processor via command-line.
• The command-line operation needs to create an output file that contains valid cobol.
• The output path can be computed by specifying a new file extension to be used with the program file name.

ZAPP profile

The integration of the preprocessor with the editor is handled via a ZAPP file profile. Such a profile could look like this:

- name: extended-cobol
  type: preprocessor
  location: local
  settings:
    command: ${JAVA_HOME}/bin/java -jar ${WORKSPACE}/preprocessor/my-preprocessor/target/my-preprocessor-1.0-SNAPSHOT.jar ${input_file} ${output_file}
    outputPath: ./preprocessor/output
    fileExtension: cee
    environmentVariables:
      VARIABLE1: value1

In the settings object the following properties can be used:

Property	Description
command	The command line to be executed. You can mix the command line with ZAPP Variables as well as use the predefined variables ${input_file} and ${output_file}. You need to define ${JAVA_HOME} and ${WORKSPACE} in the example above as ZAPP variables. Environment variables can only be used by specifying them with the below environmentVariables property.
outputPath	The base path in which the output file should be created. This path must be inside the current VS Code workspace so that the editor can see and process the files.
fileExtension	The file extension to be used for the output files.
environmentVariables	An optional sub-object to specify the environment variables that should be created before executing the command.

Running the preprocessor

After you specify the ZAPP profile, you can run the preprocessor in the following ways:

1. Right-click and choose Execute local preprocessor command to manually run the preprocessor in the program file editor.
2. Automatically run the preprocessor via the VS Code user setting zopeneditor.cobol.autoPreprocessor. The setting can have one of the values:
   • off: disables the automatic preprocessor execution.
   • open: when a program file is opened in the editor.
   • save: when a program file is saved in the editor.
   • both: when opening and saving a program file in the editor.

When the preprocessor command runs, a progress bar is displayed. When the preprocessor finishes, it refreshes the editor and any syntax errors that were caused by preprocessor statements should go away or, if they contained problems, will show those instead.

If the processor command execution failed and produced errors, a dialog will be shown with a button to open the Z Open Editor log file viewer which lists the detailed error message produced by the preprocessor command.

Using the preprocessor output in the editor

After the preprocessor is executed, you can hover the mouse of preprocessor statements in their program file to see the COBOL code that was generated for the statement. You can edit these statements and all other COBOL code in the program.

Syntax errors for preprocessor statements will not be available until the preprocessor runs again. Syntax errors for other regular COBOL will be shown while typing as usual in Z Open Editor.

To get a side-by-side view of the program before and after preprocessing, you can use the right-click menu option Compare preprocessor input and output files.

Limitations

Restriction: Several limitations are associated with using a preprocessor within Z Open Editor:

• Code formatting will be disabled for files that contain preprocessor statements.
• Not all preprocessor statements within an EXEC block might be identified.
• All preprocessor statements might not be identified if the code is reorganized.
• Preprocessor statements that modify text in another location of a program might not be identified.
• Real-time syntax checking of programs that contain preprocessor statements that contain only the beginning or ending of a language comment might not be identified.