Mainframe Pre-compiler Support

Note: The Mainframe Pre-compiler Support is available for COBOL only.

It can only be used in conjunction with an AWM modeled remote edit action. See Edit MVS File and Browse MVS File in the AWM function package for more information. There is no support for COBOL programs opened from MVS Explorer in the Mainframe Systems Explorer view.

The Mainframe Pre-compiler Support enables you to call language pre-compilers (also known as pre-compilers) on the mainframe while editing a source file on the client machine. The source file is taken from the editor and pre-compiled on the mainframe. The result is transferred back to the client machine and used as input to the background parsing process, so the editor does not flag syntax errors due to an unknown pre-compiler. You can use all COBOL variables with the Content Assist.

To use the Mainframe Pre-compiler Support, additional configuration is necessary.

Configuring Mainframe Pre-compiler Support on the Mainframe

A mainframe pre-compiler must be configured on the mainframe to be used with the Mainframe Pre-compiler Support. A pre-compiler specific REXX procedure must be written on the mainframe to connect a pre-compiler. That procedure has to set up the required environment for the pre-compiler. For example, by allocating data sets and then call the pre-compiler.

Configuring Mainframe Pre-compiler Support in the Eclipse Client

The Mainframe Pre-compiler Support needs a server instance to be started in the Eclipse client. By default, the server instance is started when the corresponding plug-in is loaded during Eclipse startup under port 2666.

The default port can be changed by specifying a new value for the Eclipse property variable remotePreprocessorPort in the eclipse.ini file under the vmargs section.

For example, to change the port address to 5555, specify:

-DremotePreprocessorPort=5555

If you do not want to make use of the Mainframe Pre-compiler Support in the Eclipse environment you can configure the server not to start under the Eclipse preferences. To prevent the plug-in from activating on startup:

  1. Click Windows > Preferences > General > Startup and Shutdown.
  2. Click AWM Remote Preprocessor.
  3. Click Apply and Close.

Mainframe Pre-compiler Exit Procedure TAUZCXPP

The pre-compiler exit procedure has to be named TAUZCXPP and must be placed on a library that is in the search path in the user server. TAUZCXPP is called with the following parameters:

Parameter Description
Indsn Data set name of a cataloged mainframe file containing the input source for the pre-compiler. This is the content of the editor on the client machine when the background parse process is started.
Outdsn Data set name of a cataloged mainframe file for the output generated by the pre-compiler. This is the translation of the input file as done by the pre-compiler and must be valid COBOL.
Msgdsn Data set name of a cataloged mainframe file for messages generated by the pre-compiler.
Chgdsn Data set name of a cataloged mainframe file for information about changes done by the pre-compiler.
Parms Additional user supplied parameters for the pre-compiler call.

All data sets exist in the mainframe file system when the procedure is called. The procedure must allocate the input and output data sets to the pre-compiler specific DD names. The message and change data sets are optional and need to have a special format as described in the following sections.

The following return codes of TAUZCXPP are supported:

Return code Description
0 Changes done by the pre-compiler are known and the change data set is filled.
1 Changes done by the pre-compiler are unknown and TAUZCXPP did not fill the change data set.

If return code 1 is received, the mainframe pre-compiler interface attempts to set up a change data set by comparing the input data with the output data. A TAUZCXPP might generate the output data set and issue return code 1. In this case, the comparison of the input and output file is done in the REXX procedure TAUZCCMP via the IBM ISPF tool ISRSUPC.

Note: TAUZCCMP has only been tested with ISPF version 7.2. In another ISPF version the output of ISRSUPC might differ, generating unpredictable results. In this case, the customer has two alternatives:
  • Adapt the REXX procedure TAUZCCMP to the actual output of ISRSUPC.
  • Generating the change data set according to the format described below.

Message Data Set Format

Messages from a pre-compiler must be placed in the message data set. The data set is a fixed block data set with a logical record length of 80. It is already cataloged when TAUZCXPP is called.

There must be one line for each message:

Offset Length Description
0 5 Number of the line in the input source that this message belongs to (right padded filled with 0).
5 1 Message level:
I
Informational
W
Warning
E
Error
S
Severe error
6 74 Message text.

Changes Data Set Format

The local compiler needs to identify which lines of the original source code were changed, inserted, or deleted by the mainframe pre-compiler. This information may be calculated using the Mainframe Pre-compiler Interface by issuing return code 1 from the exit TAUZCXPP, or may be set by TAUZCXPP itself. The data set is a fixed block data set with a logical record length of 80. It is already cataloged when the exit TAUZCXPP is called.

Changes can be grouped into blocks so that, for example, deleting five consecutive lines is a block of five lines.

There must be one line for each change block:

Offset Length Description
0 5 Number of the line in the input source that this change belongs to (right padded filled with 0).
5 1 Reserved (should be blank)
6 1 Type of change
I
Inserted lines
D
Deleted lines
C
Changed (reformatted) lines
7 1 Reserved (should be blank).
8 5 Length of the change block (right padded and filled with 0).
13 67 Reserved (should be blank).

Configuring Mainframe Pre-compiler Integration on the Client Machine

COBOL compiler options can be set in an AWM model by the AWM application specific attribute COMPOPT.

In order to integrate a mainframe pre-compiler, the COMPOPT attribute must contain the call of the local pre-compiler interface:

p(AWMREMPC)  ENDP

After p(AWMREMPC) all parameters can be passed which are needed by the mainframe pre-compiler. The parameters are passed through to the mainframe pre-compiler exit.

The integration of the mainframe pre-compiler is realized on the client side as a stackable preprocessor implementing the integrated preprocessor interface as described under "Writing a Preprocessor". Micro Focus recommends you use the standard CP preprocessor as the first preprocessor in the stack. This is because the CP preprocessor ensures that the contents of unsaved edit buffers is retrieved and passed to the succeeding preprocessors. If you require the mainframe pre-compiler integration gets the source from the edit buffers in an unchanged way the CP preprocessor has to be called with the parameters NOSQL NOCOPY. Otherwise the CP preproessor resolves all COPY and EXEC SQL INCLUDE statements in the source before passing the source to the mainframe pre-compiler integration. The COMPOPT attribute typically has the following format:

p(AWMREMPC)  p(CP) NOCOPY NOSQL ENDP

You need to specify all the parameters to be passed to the mainframe pre-compiler exit between p(AWMREMPC) and p(CP).

Another AWM application-specific attribute AUTO_PARSE controls whether the background parse process of the editor is started automatically or only if explicitly called.

Micro Focus recommends that you set AUTO_PARSE to FALSE if a mainframe pre-compiler is configured. In this case, you should model a tool of type “Reparse with Refresh” from the Micro Focus Editor function package, and add it as a related action to the element type representing COBOL programs and as a global editor action. This action can be used to trigger the start of the pre-compiler interface from the context menu of the COBOL program and the editor context menu. If the file should be parsed when it is opened in the editor, you should also specify the AWM application-specific attribute INITIAL_PARSE and set it to true.

Sample Mainframe Pre-compiler Exits

There are two mainframe pre-compiler exit samples provided in the EXEC library of the z/Server delivery:

  • TAUSADCL
  • TAUSADPC

TAUSADCL

TAUSADCL is a mainframe pre-compiler exit which resolves the DB2 EXEC SQL INCLUDE statements within a COBOL program. TAUSADCL requires the list of libraries where the SQL includes are, separated by semicolon.

TAUSADCL generates an output file where all DB2 EXEC SQL INCLUDE statements with the exception of SQLCA and SQLDA are commented out and replaced by the content of the include. The TAUSADCL exit produces the change data set on its own. This results in an exit with a return code of 0 if successfully executed. If an SQL include can not be resolved from the provided include libraries TAUSADCL returns a corresponding message in the message data set.

Specify the following format for the COMPOPT option used to call the exit TAUSADCL:

 p(AWMREMPC) RESOLVEDCLGEN <list of include libraries> p(CP) NOSQL NOCOPY ENDP ENDP DIALECT(ENTCOBOL) XDB 

TAUSADPC

TAUSADPC is a mainframe pre-compiler exit which calls the IBM DB2 pre-compiler with the source passed by the Mainframe pre-compiler interface. TAUSADPC expects as input the list of libraries separated by semicolon where to look up the SQL includes.

The output file generated by the IBM DB2 pre-compiler is returned to the mainframe pre-compiler interface under the allocation where the pre-compiled source is expected. TAUSADCL exits with the return code 1 on successful execution. This results in the exit leaving it to the mainframe pre-compiler interface to produce the change data set by comparing the input data set with the output data set. There is only a simple error handling implemented in the exit. If the exit is intended to be used in a production environment it has to be extended with adequate error handling.

Specify the following format for the COMPOPT option used to call the exit TAUSADPC:

p(AWMREMPC) DB2PC <list of include libraries> p(CP) NOSQL NOCOPY ENDP ENDP DIALECT(ENTCOBOL)