PreviousEmbedded SQL Statements

Appendix E: The CP Preprocessor

E.1 Overview

The CP preprocessor is designed to be used as a stacked preprocessor.

The CP preprocessor:

Therefore, the CP preprocessor removes these quite complex functions from other preprocessors.

E.1.1 Limitations

The CP preprocessor has the following restrictions:

E.2 Copyfile Expansion

When the CP preprocessor encounters a COPY statement, the preprocessor:

  1. Marks the source lines as documented in the section Handling COPY Statements.

  2. Reads through the copyfile.

  3. Locates the copyfiles using the same pathnames and file extensions that the Compiler uses.

  4. Handles any problems as follows:

E.2.1 Handling COPY Statements

If the preprocessor is not interested in the contents of a copyfile, it can pass the COPY statement unmodified through to the Compiler, where it is expanded.

Only valid COBOL constructs can be passed in this way. Any non-COBOL constructs can be commented out and replaced by a valid COPY statement which the Compiler then expands.

In both of these cases, the preprocessor has no opportunity to read and process the copyfile itself.

The Compiler expands all forms of COPY statement that it would expand with no preprocessor present, whether passed back as unchanged or modified lines. The following are supported:

If the preprocessor does want to examine the copyfile contents, it must either expand the copyfile itself, or use the CP preprocessor. The contents of the copyfile itself are returned to the Compiler in the same manner as the lines in the main source file; however, the COPY statement itself receives special handling.

In the simplest case, when the COPY statement is the only statement on one or more lines, and specifies the full filename (including the extension and path if necessary), the first of these lines is passed to the Compiler marked with resp-main set to 3 and resp-more set to the column number of the start of the COPY, and all subsequent lines are passed with resp-main set to 4.

If the location of the file specified in the COPY statement is resolved by adding a filename extension or path, or if the COPY is not unique on the line(s), or is not a regular COBOL COPY statement, it is necessary to comment out (mark with resp-main set to 2) all lines containing the COPY statement and then pass through all other lines as inserted. Inserted COPY statements that the preprocessor is expanding must conform to the normal syntax rules for COBOL, and be marked with:

For example, if the source contains:

01 item-a. copy "cpy-fil.cpy".

This is first returned with resp-main set to 2 to indicate that this is a line that is about to be replaced. On the next call, the preprocessor returns:

01 item-a.

with resp-main set to 1 to indicate that this is a replacement line. On the next call, the preprocessor returns:

copy "copy-fil.cpy".

This time, resp-main is set to 11 to indicate this is a replacement line containing the COPY statement alone. resp-more is set to 20, the position of the word COPY on the original source line.

Note that when a COPY statement is returned to the Compiler, whether to be expanded by the preprocessor or Compiler, the Compiler parses the statement and checks for REPLACING. This REPLACING affects all lines in this and nested copyfiles. The name specified in this COPY statement is read and stored for use by Animator.

Tip: We recommend that you enclose the name in quotes, so that no unwanted case folding occurs when reading the name. On platforms where case is significant, if unwanted case folding does occur, Animator might not be able to locate the file.

If your compiler support is not at base level, where base level indicates the support level of the oldest compiler, refer to the section Compiler Support not at Base Level.

Use value 128 for resp-main only when the preprocessor has finished expanding a copyfile. Otherwise, the Compiler aborts the compilation. At the end of the main source file, use the value 0.

COPY statements in Identification Division comment entries are not always expanded. If a preprocessor signals that it is about to expand a copyfile (resp-main set to 3 or 11) at a point where this is not valid, the Compiler sets response-status to non-zero on the next call to the preprocessor. The preprocessor should abandon the copyfile immediately and send the end-of-copyfile marker (resp-main set to 128) as though the copyfile were empty.

The CP preprocessor expands copyfiles so that other preprocessors do not have to do so. It generates lines as documented above.

E.2.1.1 Compiler Support not at Base Level

resp-main=14 is used when the original word was not a COBOL COPY statement, for example ++INCLUDE or -INC. Some Compiler directives can be specified in $SET statements before any COBOL source but not after. Such statements might follow ++INCLUDE but not COPY. Use of resp-main=14 allows a ++INCLUDE to be expanded whilst at the same time allowing such directives to be set subsequently.

E.3 REPLACE Notification

So that other preprocessors are able to get a view of the source files as the Compiler would, after the effect of REPLACE and REPLACING, the preprocessor returns additional lines as documented here. Note, however, that the Compiler still performs this REPLACING itself except as noted below. The additional lines are passed for information only.

If the preprocessor ever detects that a line will be modified, it adds 32 to the value of resp-main it returns. The line or lines thus marked are followed by one or more lines marked with the value of 8 in resp-main, containing what would be in the line after it was modified. As these changes are for information only, other preprocessors receiving the lines should pass these values back out again for any other preprocessors in the stack; when the Compiler receives lines marked with values in the range 33 to 64 it subtracts 32, and it ignores lines marked with an 8.

If a preprocessor wishes to modify a line affected in this way, it should do so as normal, however it should mark the new line with a 9 rather than a 1 to inform the Compiler that this new, inserted, line does not need to be tested for the effect of REPLACE or REPLACING.

E.4 CP Directives

The CP preprocessor accepts a number of directives. In order to keep the command line short, these exist in an abbreviated form in addition to the full name. After looking at the command line in the usual way, CP also looks at the environment variable CPDIR for directives.

The following directives are available for the CP preprocessor:


Specifies whether directives are to be shown on the screen if accepted.




Limits searches for copyfiles to the directories specified by the COBCPY environment variable. By using this directive, and making a careful choice of both directories in the COBCPY environment variable and file extensions in the COPYEXT directive, the number of file searches can be greatly reduced.




This directive limits searches for copyfiles to the directories specified by the COBCPY environment variable.

This can reduce compilation time.

If the directive is set:


Stacks another preprocessor; that is, specifies that the source input to this preprocessor is to come from another preprocessor rather than the source file itself.

    |                   +-preproc-params-+  |


E.4.4 SQL, S

Specifies whether EXEC SQL INCLUDE is to be treated as a COPY statement.



E.4.5 SY

Reserved for use with COBSQL; this directive should only be used as documented in the section Using the CP Preprocessor to Expand Copyfiles in the chapter COBSQL.

E.4.6 TRACE, T

Specifies whether to create a trace file, and optionally specifies the name of the file to be used. If the filename is omitted, it is created as progname.cpt, where progname is the basename of the main source file.

    |         +-------------+  |



Specifies whether warnings about directive settings are to be shown on screen



E.5 CP Error Messages

All CP error messages have the format:

*CP nnn-x
**	description

where the variables are:

nnn The error number
x The severity level. This can be:

Warning - processing continues
Severe - during initialization causes processing to stop, otherwise non-fatal.
Unrecoverable - causes processing to stop.

The CP preprocessor displays two types of message:

The sections below give descriptions of each error message, together with advice on causes of the error and the action you should take.

E.5.1 Initialization Errors

Illegal command line

One or more directives was rejected.


If explicitly invoking CP, correct the command line and resubmit. If CP is invoked by another preprocessor, inform the appropriate vendor.

Compiler level set to 1; some features disabled

Testing feature enabled (internal use only).


None required.

Open fail: filename

CP was unable to find the source file.


Correct name and resubmit command.

Open fail: filename

CP was unable to create a trace file.


Ensure that the file is not already in use, there is sufficient disk space, the drive is not write-protected.

Call to stacked preprocessor name failed

The preprocessor specified using the CP directive PREPROCESS could not be found.


Ensure that the preprocessor exists and can be invoked. If the name is incorrect then either correct the command line if CP was explicitly invoked or see the appropriate product documentation if CP was invoked by another preprocessor.

Stacked preprocessor returned an error

The stacked preprocessor failed to initialise correctly


For CP, none. Fix the error reported by the stacked preprocessor.

E.5.2 Main processing errors

Undefined technical error - contact technical support

An internal processing error occurred.


Inform MERANT Technical Support.

Internal stack full - contact technical support

An internal processing error occurred.


Inform MERANT Technical Support.

File error - contact technical support

An internal processing error occurred.


Inform MERANT Technical Support.

Copybook filename not found

A COPY statement referenced a file that could not be located.


Correct the program source and resubmit.

Nested REPLACING is not allowed

A COPY REPLACING statement was found while another was still being processed.


Correct the program source and resubmit.

Copyright © 2000 MERANT International Limited. All rights reserved.
This document and the proprietary marks and names used herein are protected by international law.

PreviousEmbedded SQL Statements