Go to the first, previous, next, last section, table of contents.

5. Syntax of COBOL programs

5.2 Preprocessor

Intro... not done yet... what it does, how it fits in.

5.2.1 COPY Verb

5.2.1.1 COPY Verb Examples

COPY a.

reads file A.CPY from current directory into program at compile time
name is converted to upper case
if SYSLIB environment variable exists, its value replaces the current directory name

COPY a OF b.

reads file A.CPY from directory B into program at compile time
if environment variable B exists, its value replaces the directory name
a and B converted to upper case

COPY "a" of "b".

reads file a from directory b into program at compile time
no case conversion is done

COPY A replacing
        X by Y
        P of Q of R (1 2 a + 1 b - 2 c) (3: 4*4+1)
        FUNCTION MAXIMUM (A) by ====
        1.0 by 2.0
        ==Gumby people "abc"== by 
          ==Brumby people 'XYZ'==.

copies from A.CPY as above but replaces text as shown
rules for matching and replacing are complex - keep this simple
I recommend you use the delimited version - the delimiters are "==", ie "replacing ==from== by ==to=="
matching is case insensitive

5.2.1.2 COPY Verb Syntax

As per the COBOL 85 standard with extensions.

COPY text-name-1 | non-numeric-literal-1 
     [{OF|IN} library-name-1|non-numeric-literal-2]
[       
 REPLACING 
 {
        { ==pseudo-text-1== | identifier-1 | literal-1 | word-1 } BY
        { ==pseudo-text-2== | identifier-2 | literal-2 | word-2 }
 } ...
] .

pseudo-text 0 or more text-words. In the case of the pseudo text before the BY, there must be at least one text word that is not space, comment, ", " or "; ". For definitions of text word, identifier, literal and word, see ???. I recommend using the pseudo text form as it is much better and more reliable - the definition of identifier etc is rather vague. The COPY verb should start in area b.
Spaces Matching ignores spaces. This includes "," ";" and " ". Thus ==a(b)== will match the same things as == a ( b ) ==. They will both match ==a(b)== and == a( b )= etc.
Library Name In COBOL for GCC, the library consists of a directory in the file system. The member consists of a file within that directory. For library-name-1, the library name is converted to upper case before use. The library name may be a non-numeric literal eg "a/b". In this case it is used as is, with no conversion to upper case. (Extension). Leading and trailing '"' and "'" are removed from the non-numeric literals before use. If the library name matches an environment variable name, the value of the environment variable is substituted for the library name. If no library name is specified, then the current directory is used. However, if there is an environemt variable called SYSLIB, its value is used as the library (directory) name.
Member Name For text-name-1, the member name is converted to upper case before use, and ".CPY" is added to the end. The member name may be a non-numeric literal eg "a/b". In this case it is used as is, with no conversion to upper case and no added ".CPY". Leading and trailing '"' and "'" are removed from the non-numeric literals before use.
File name used for copy library The file name for the COPY using text-name-1 and library-name-1 is library-name-1/text-name-1.CPY. A COPY using non-numeric-literal-1 and non-numeric-literal-2 would use non-numeric-literal-2/non-numeric-literal-1 Environment variable substitution of the library namae is performed before use for either form.

5.2.1.3 COPY Verb Restrictions

Up to 10 levels of nested copy is allowed. This limit can be changed via a compile time option. All COPY verbs can have REPLACING clauses within them.

A COPY verb can appear anywhere in the source program or in a library, except in a comment, literal or comment-entry. It can even appear within a REPLACE verb for example.

If REPLACING is not specified, the file is copied into the source program without change. The copied file starts on a new line and after it ends, the next text from the source file that contained the COPY verb will be on a new line.

If REPLACING is specified, the file is copied into the source program with replacements specified (see below).

Match process for REPLACING Ignore leading spaces in file. Compare words one at a time, looking for a match of the one or more words. One or more spaces comments and newlines count as one space which must then match. On a match the replace is done, then compare resumes with the word after the matched set. "D/d" debug lines are treated as normal lines for the match process.
Replace Process
- remove tokens and comments and lines that matched
- copy in tokens comments and blank lines within replacement text
Location of Replacement Text If replacement is pseudo text, the pseudo text is put in the column number that the pseudo text was in. This may require a new line. However, spaces or new lines do not get added where they do not already exist (so you can do token pasting). Other replacement text words (ie not pseudo text) go in the same area (A or B) as the first replaced word. Words can get pushed across to the right because of prior replaces on same line. Always, where two words are seperated by spaces, they will stay seperated by spaces, and where not seperated by spaces, the will stay not seperated by spaces. A given item is only replaced once per COPY verb or REPLACE verb (unlike in C)
Debug Attribute of Replacement Text Replacement text is on a debug line if - the copy verb was on a debug line OR - the first replaced word was on a debug line OR - the replacement word was on a debugging line However, the decision to make a line debug is only made when a new line is created, so if there is no space before a word, you cannot put it on a debug line if the preceding word is not on a debug line. Debug indicators within the COPY verb have no effect on the decision to do the COPY. They are ignored, except as above to determine the debug indicator of added lines.

5.2.2 REPLACE Verb

5.2.2.1 REPLACE Verb Examples

 REPLACE ==forward-verb-buffer-size== by 1000.

  01 FVB-ARRAY.
    02  FVB-ENTRY PIC 9(3) OCCURS forward-verb-buffer-size. 

  PERFORM VARYING IX FROM 1 BY 1 UNTIL IX GT forward-verb-buffer-size
    blah blah blah
  END-PERFORM.

Gives

  01 FVB-ARRAY.
    02  FVB-ENTRY PIC 9(3) OCCURS 1000.

  PERFORM VARYING IX FROM 1 BY 1 UNTIL IX GT 1000
    blah blah blah
  END-PERFORM.

5.2.2.2 REPLACE Verb Syntax

REPLACE {== pseudo-text-1 == by == pseudo-text-2 == ...} .

REPLACE OFF.

This verb replaces text within the program with other text. It is a good way to define array sizes etc and have all the relevant variables set up.

After all the COPY verbs are processed, producing a single conceptual output file, the REPLACE verbs are processed. Only one or no replace is active at a given point in the code.

REPLACE OFF turns off replacing. Only the last REPLACE verb is in effect at any time. So each REPLACE turns off the previous REPLACE.

The REPLACE verb should start in area b.

5.2.2.3 REPLACE Verb Processing

Matching rules
1. same as for COPY
2. no ignoring of leading comments and blanks
Replacment rules As for copy with replacing pseudo-text (from and to).
Location of Replacement Text Determined the same as for COPY verb (as the standard is basically silent on the matter, it just says 'in accordance with the rules of reference format).
Debug Attrinute of Replacement Text Lines introduced into the program have the same debug indicator as the first word being replaced. The debug attributes of the words in the pseudo text have no effect. Debug indicators within the REPLACE verb have no effect. They are ignored - sometimes you will get a warning about this.
A replace verb can be within COPYed code.

5.3 Definitions of syntactic elements and terms.

array_expression

identifier
OR
integer
OR
identifier + integer
OR
identifier - integer

expression

identifier
OR
numeric_literal
OR
expression + expression
OR
expression - expression
OR
expression / expression
OR
expression * expression
OR
expression ** expression
OR
( expression )

identifier
```
word {[of/in word] ...} [(array_expression ...)] [([expression]:expression)]
#end example
```
That is...
1. a name...
2. possibly qualified...
3. possibly with array references (any expression is allowed per array dimension)...
4. possibly with reference modification
May also be a function reference...
```
FUNCTION function-name1 [([expression or identifier ...])]
```
integer a sequence of digits, no sign eg 44, 101, 0. Not +1, -1.
literal A numeric literal of a non-numeric literal.
non-numeric-literal
1. basically a character string eg "abc123"
2. can be enclosed in single quotes eg '123abc'
3. can include quotes as follows
```
"abc""123" -> abc"123
'abc''123' -> abc'123
'abc"123' -> abc"123
"abc'123" -> abc'123
```
  In the main compiler, hex strings are allowed (x"hhhh...") but not in the preprocessor. Non-numeric literals are case sensitive.
numeric literal
```
[+-][99][.][99]
```
1. Must have at least one digit
2. Sign is optional and must be leftmost if present. One decimal point max.
3. Decimal point can be a comma to accommodate 'decimal point is comma' possibility.
text word
1. a literal
2. OR a separator (", " ". " "==" or one or more spaces)
3. or any other sequence of contiguous characters except COPY.
token This refers to any word or literal or other element of a COBOL program, such as "=".
word A COBOL name. Rules are
1. consists of 0-9a-zA-Z plus "-".
2. "-" must not be first or last character.
3. must not all be 0-9.
4. length <= 30 characters (extension - can be > 30 characters, a warning will be given).
5. May also be an arithmetic operator: + - < > <= >= ** *