| Embedded SQL Statements |
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.
The CP preprocessor has the following restrictions:
When the CP preprocessor encounters a COPY statement, the preprocessor:
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:
resp-mainresp-more set to nn (where nn is the
position of the start of the COPY statement) for the first line
resp-main set to 12 for all subsequent lines
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.
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.
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.
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.
>>--.----.--CONFIRM--><
+-NO-+
NOCONFIRM
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.
>>--.----.--LIMITED-SEARCH--><
+-NO-+
NOLIMITED-SEARCH
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.
>>--.--PREPROCESS"name"-.----------------.--.--><
| +-preproc-params-+ |
+--NOPREPROCESS-------------------------+
NOPREPROCESS
Specifies whether EXEC SQL INCLUDE is to be treated as a COPY statement.
>>--.----.--SQL--><
+-NO-+
SQL
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.
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.
>>--.--TRACE--.-"filename"--.--.--><
| +-------------+ |
+--NOTRACE-----------------+
NOTRACE
Specifies whether warnings about directive settings are to be shown on screen
>>--.----.--WARNINGS--><
+-NO-+
WARNING
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: | |
| W S U |
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.
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.
Testing feature enabled (internal use only).
None required.
CP was unable to find the source file.
Correct name and resubmit command.
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.
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.
The stacked preprocessor failed to initialise correctly
For CP, none. Fix the error reported by the stacked preprocessor.
An internal processing error occurred.
Inform MERANT Technical Support.
An internal processing error occurred.
Inform MERANT Technical Support.
An internal processing error occurred.
Inform MERANT Technical Support.
A COPY statement referenced a file that could not be located.
Correct the program source and resubmit.
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.
| Embedded SQL Statements |