Note: The Integrated Preprocessor is supported for native COBOL only.
Preprocessor Parameters
Three parameters are passed across the interface:
| mode-flag | Used to pass control information |
| buffer | Used for text information (source lines and filenames) |
| response | Used to indicate the type of source line in the buffer |
Use the following data structure to pass these parameters:
01 mode-flag pic 9(2) comp-x. 01 buffer pic x(n). 01 response. 03 response-status pic 9(2) comp-x. 03 response-code-1 pic 9(4) comp-x. 03 filler redefines response-code-1. 05 filler pic x. 05 resp-main pic 9(2) comp-x. 03 response-code-2 pic 9(4) comp-x. 03 filler redefines response-code-2. 05 filler pic x. 05 resp-more pic 9(2) comp-x.
The Initial Call
The initial call is made to the preprocessor at the point where the Compiler would normally open the source file. The mode-flag parameter is set to 0 and the name of the source file is placed in buffer. If the Compiler was able to locate the source file, the filename contains the full path and file extension. If it was not able to do so, the name is as specified on the command line. The preprocessor preserves the contents of the buffer in this initial call.
In addition, the initial call initiates a handshaking process so that the Compiler and preprocessor can determine their respective levels of support. This enables new functionality to be built into the preprocessor interface while at the same time ensuring that this new functionality is not made use of unless both the Compiler and preprocessor support it. The Compiler does not pass any information to the preprocessor unless it has been told that the preprocessor is able to process it; similarly the preprocessor should not make any requests of the Compiler unless it has been told that it can do so. The process has been designed so that older Compilers and preprocessors continue to work even though they do not take account of the handshaking process.
When the Compiler calls the preprocessor, response-code-2 is used to inform the preprocessor of its support level. When the preprocessor returns to the Compiler, it uses the same parameter for its support level. As features are added the support levels are incremented; each level includes the support in the levels before it. To ensure that old Compilers are supported, the value 8224 is a special case - it indicates that the parameter was not initialized and represents the "base level". Similarly, an old preprocessor that does not set a support level does not change the parameter value, so all values of 32767 or lower are treated as the "base level".
Features in the base levels are explained in the following sections. Features not in the base level are highlighted with a warning. The following is a summary:
Compiler support levels
| response-code-2 | Feature |
|---|---|
| 8224 | Base level |
| 0 | response-code-1 contains length of buffer |
| 1 | resp-main of 14 supported |
| 2 | Compiler understands preprocessor support level; and tells the preprocessor to abort |
| 3 | resp-main of 17 supported |
| 4 | resp-main of 18 supported |
Preprocessor support levels
| response-code-2 | Feature |
|---|---|
| 32767 or less | Base level |
| 32768 | Compiler might tell the preprocessor to abort |
| 32769 | Support for conditional compilation. Note: The preprocessor must accept and act on a MODE-FLAG value of 3 by returning source lines untouched and marked as original source lines. It must continue to do this while MODE-FLAG has this value. |
| Not base level: | The Compiler puts the length of buffer in response-code-1. The preprocessor can return source lines up to this length. If response-code-2 is 8224 then the preprocessor should assume the length is 80 bytes. |
The preprocessor should open the file and return zero in response-status to indicate success, or 255 to indicate a failure.
The operating system command line contains any directives to the preprocessor, terminated by spaces. These directives are specified in the Compiler command line, directives files or $SET statements and follow the PREPROCESS directive itself.
The directives are used to pass information from the command line to the integrated preprocessor and are defined by the designer of the preprocessor. The preprocessor should not expect the directives it receives to be separated by only one space character. The command line format matches that of the PREPROCESS directive and each preprocessor directive (including the first) can be preceded by one or more spaces.
Subsequent Calls
Subsequent calls request a line of source code until the preprocessor indicates that the last line has been reached.
In these calls, the Compiler sets mode-flag to 1 and response-status to 0, except as documented in the topic Handling COPY Statements. The preprocessor returns information in buffer, resp-main and resp-more as defined in the next section.
If there is an error, response-status should be set to a nonzero value (the remaining fields might be left undefined).
The first byte of response-code-1 and response-code-2 are reserved for future use and must always be set to zero on return.
The simplest way to achieve this is to set response-code-1 and response-code-2 to zero before setting resp-main and resp-more.
If you wish to modify the source code, you should note that the original source code lines should always be passed back before their replacement line(s). In addition, lines that are continued over several lines of source code must be treated as one block; it is not possible to modify part of the logical line.
| Not base level: | If the Compiler sets mode-flag to 2 then it is about to terminate before the preprocessor indicates that the end of the source has been reached. On this call the preprocessor should perform any clean-up operations it needs to do (such as deleting temporary work files). If the preprocessor is stacked, that is it invokes other preprocessors, it should also call the next preprocessor with the same parameter values and then CANCEL that preprocessor. |
