The COPY Statement

The COPY statement incorporates text into a COBOL compilation group.

General Format for Format 1

Syntax for format 1 of the COPY statement

General Formats for Format 2 (Hitachi syntax)

Syntax for format 2 of the COPY statement

General Formats for Format 3 (Fujitsu syntax)

Syntax for format 3 of the COPY statement

General Formats for Format 4 (Fujitsu syntax)

Syntax for format 4 of the COPY statement

Directives

  1. In addition to Compiler directives which provide flagging and modify the reserved word list, the following directives may impact either the syntax or the semantics described in this section.
    • COPYEXT - specifies the filename extension to be used for locating copy files.
    • COPYLBR - specifies that library-names are equivalent to .lbr files.
    • COPYLIST - causes the result of a COPY statement to be included in the listing file.
    • FOLD-COPY-NAME - allows the Compiler to find a copy library member when the library name on disk and the text-name in the COPY statement do not use the same upper-case and lower-case letters for the library member name.
    • OLDCOPY - changes the handling of COPY statements to match the ANS'68 and OS/VS COBOL LANGLVL(1) rules.

Syntax Rules for All Formats

  1. The COPY statement must be preceded by a space and terminated by the separator period.
  2. A COPY statement can occur in the compilation group anywhere a character-string or a separator can occur except that a COPY statement must not occur within another COPY statement.
  3. OSVSVSC2MF The SUPPRESS phrase is used to suppress the printing of the contents of the copy member on the source listing.
  4. ANS85 If the word COPY appears in a comment-entry or in the place where a comment entry can appear, it is considered part of the comment-entry.

    OSVS A COPY statement that appears in a comment-entry is processed.

  5. Library text must conform to the rules for COBOL reference format.

Syntax Rules for Format 1

  1. If more than one COBOL library is available while the source is passed through the COBOL system, text-name must be qualified by the library-name identifying the COBOL library in which the text associated with text-name resides.

    OSVSVSC2MF This restriction is removed.

  2. Pseudo-text-1 must not be null, nor can it consist solely of either the character space(s) or comment lines.
  3. Pseudo-text-2 can be null.
  4. Character-strings within pseudo-text-1 and pseudo-text-2 can be continued. However, both characters of a pseudo-text delimiter must be on the same line. (See the topic Continuation of Lines in the chapter Language Fundamentals.)
  5. Word-1 or word-2 can be any single COBOL word.
  6. Text-name defines a unique external file-name which conforms to the rules for user-defined words.

    OSVSVSC2MFCOB370 External-file-name-literal is an alphanumeric literal that conforms to the operating system rules for file-names. It can be specified with or without enclosing quotation marks.

    Text-names and unquoted external-file-name-literals are always converted to upper case.

  7. MF Library-name-literal is an alphanumeric literal that conforms either to the operating system rules for file-names or to the operating system rules for device identifiers. It can be specified with or without enclosing quotation marks.

    Library-name-literals not inside quotation marks are always converted to upper case.

  8. OSVSMF External-file-name-literal and library-name-literal, when enclosed in quotation marks, may contain the $, #, and @ characters.
  9. ISO2002MF Partial-word-1 must consist of one text-word.
  10. ISO2002MF Partial-word-2 must consist of zero or one text-word.
  11. ISO2002MF Neither a nonnumeric literal nor a national literal can be specified as partial-word-1 or partial-word-2.
  12. Library text must conform to the rules for COBOL reference format.
  13. ISO2002MFXOPEN A concatenation expression must not be specified for external-file-name-literal, library-name-literal, literal-1 or literal-2.

Syntax Rules for Format 2 - 4

  1. word-3, word-4, word-5, word-6 or word-7 can be any single COBOL word.

General Rules for All Formats

  1. The compilation of a compilation group containing COPY statements is logically equivalent to the processing of all COPY statements before the processing of the resultant compilation group.
  2. The effect of processing a COPY statement is that the library text associated with text-name is copied into the source text, logically replacing the entire COPY statement, beginning with the reserved word COPY and ending with the punctuation character period, inclusive.
  3. If the unit identifier is not explicitly specified, the default drive is used. (The default is operating system-dependent.)

General Rules for Format 1

  1. If the REPLACING phrase is not specified, the library text is copied unchanged.

    If the REPLACING phrase is specified, the library text is copied and each properly matched occurrence of pseudo-text-1, identifier-1, literal-1, word-1 and partial-word-1 in the library text is replaced by the corresponding pseudo-text-2, identifier-2, literal-2, word-2 or partial-word-2.

  2. For purposes of matching, identifier-1, literal-1 and word-1 are treated as pseudo-text containing only identifier-1, literal-1 or word-1, respectively.
  3. The comparison operation to determine text replacement occurs in the following manner:
    1. The leftmost library text-word which is not a separator comma or a separator semicolon is the first text-word used for comparison. Any text-word or space preceding this text-word is copied into the source text. Starting with the first text-word for comparison and first pseudo-text-1, identifier-1, word-1, literal-1 or partial-word-1 that was specified in the REPLACING phrase, the entire REPLACING phrase operand that precedes the reserved word BY is compared to an equivalent number of contiguous library text-words.
    2. Pseudo-text-1, identifier-1, word-1, or literal-1 match the library text if, and only if, the ordered sequence of text-words that forms pseudo-text-1, identifier-1, word-1, or literal-1 is equal, character for character, to the ordered sequence of library text-words.
    3. ISO2002MF When the LEADING phrase is specified, partial-word-1 matches the library text only if the contiguous sequence of characters that forms partial-word-1 is equal, character for character, to an equal number of contiguous characters starting with the leftmost character position of a library text-word. When the TRAILING phrase is specified, partial-word-1 matches the library text only if the contiguous sequence of characters that forms partial-word-1 is equal, character for character, to an equal number of contiguous characters, ending with the rightmost character position of a library text-word.
    4. The following rules apply for the purpose of matching:
      1. Each occurrence of a separator comma, semicolon, or space in pseudo-text-1 or in the library text is considered to be a single space. Each sequence of one or more space separators is considered to be a single space.
      2. Except when used in nonnumeric or national literals, each lower-case letter is equivalent to the corresponding upper-case letter as specified for the COBOL character set.
      3. Text-words within a debugging line participate in the matching as if the "D" did not appear in the indicator area.
      4. ISO2002MFXOPEN Each operand and operator of a concatenation expression is a separate text-word.
    5. If no match occurs, the comparison is repeated with each next successive pseudo-text-1, identifier-1, word-1, literal-1, or pseudo-text-1, if any, in the REPLACING phrase until either a match is found or there is no next successive REPLACING operand.
    6. When all the REPLACING phrase operands have been compared and no match has occurred, the leftmost library text-word is copied into the source text. The next successive library text-word is then considered as the leftmost library text-word, and the comparison cycle starts again with the first pseudo-text-1, identifier-1, word-1, literal-1, or partial-word-1 specified in the REPLACING phrase.
    7. Whenever a match occurs between pseudo-text-1, identifier-1, word-1, or literal-1 and the library text, the corresponding pseudo-text-2, identifier-2, word-2, or literal-2 is placed into the source text.

      ISO2002MF When a match occurs between partial-word-1 and the library text-word, the library text-word is placed into the resultant text with the matched characters either replaced by partial-word-1 or deleted when partial-word-2 consists of zero text-words.

      The library text-word immediately following the rightmost text-word that participated in the match is then considered as the leftmost text-word. The comparison cycle starts again with the first pseudo-text-1, identifier-1, word-1, literal-1 or partial-word-1 specified in the REPLACING phrase.

    8. The comparison operation continues until the rightmost text-word in the library text has either participated in a match or been considered as a leftmost library text-word and participated in a complete comparison cycle.
  4. A comment line occurring in either the library text or pseudo-text-1 is interpreted, for purposes of matching, as a single space. Comment lines appearing in either pseudo-text-2 or library text are copied into the source text unchanged.
  5. The text produced as a result of the complete processing of a COPY statement must not contain a COPY statement.

    VSC2 This text can contain a COPY statement provided neither this contained COPY nor the already expanded COPY includes the REPLACING phrase. However, recursive COPY statements (where a library-text is referred to by a COPY statement within it) are not allowed.

    MF COPY statements may be nested in this way to any level. One of the COPY statements in this structure may include the REPLACING phrase, and the replacements specified are in effect for all subsidiary COPY statements.

  6. The syntactic correctness of the library text cannot be independently determined.

    ANS85 Except for COPY statements,

    the syntactic correctness of the entire COBOL compilation group cannot be determined until all COPY statements have been completely processed.

  7. MF If the REPLACING phrase is specified, the library text must not contain an EXEC HTML statement. Violation of this rule may result in unexpected behavior and syntax errors.
  8. Each text-word copied from the library but not replaced, or only partially replaced, is copied so as to start in the same area of the line in the resultant source text as it begins in the line within the library. However, if a text-word copied from the library begins in area A but follows another text-word, which also begins in area A of the same line, and if replacement of a preceding text-word in the line by replacement text of greater length occurs, the following text-word begins in area B if it cannot begin in area A. Each text-word in pseudo-text-2 that is to be placed into the resultant source text begins in the same area of the resultant source text as it appears in pseudo-text-2. Each identifier-2, literal-2, and word-2 that is to be placed into the resultant source text begins in the same area of the resultant source text as the leftmost library text-word that participated in the match would appear if it had not been replaced.

    If additional lines are introduced into the source text as a result of a COPY statement, each text-word introduced appears on a debugging line if the copy statement begins on a debugging line, or if the text-word being introduced appears on a debugging line in library text. When a text-word specified in the BY phrase is introduced, it appears on a debugging line if the first library text-word being replaced is specified on a debugging line. Except in the preceding cases, only those text-words that are specified on debugging lines where the debugging line is within pseudo-text-2 appear on debugging lines in the resultant source text. If any literal specified as literal-2 or within pseudo-text-2 or library text is of too great a length to be accommodated on a single line without continuation to another line in the resultant source text and the literal is not being placed on a debugging line, additional continuation lines are introduced which contain the remainder of the literal. If replacement requires that the continued literal be continued on a debugging line, the compilation group is in error.

  9. For purposes of compilation, text-words after replacement are placed in the source text according to the rules for reference format as described in the section Reference Format in the chapter Language Fundamentals.
  10. OSVS The OLDCOPY Compiler directive causes the entire entry to be replaced by the information identified by text-name, except that the data-name preceding the COPY statement replaces the corresponding data-name in the text-name.
  11. ANS85 If certain conventions are followed in library text, parts of names, for example the prefix portion of data-names, can be changed with the REPLACING phrase. To use this type of "partial word replacement" the portion of the words to be modified must be enclosed in one of the following ways:
    1. In pairs of left and right parentheses. For example, (ABC)
    2. Within colons. For example :XYZ:
    Note: The LEADING and TRAILING phrases can also be used for partial word replacement. The LEADING and TRAILING phrases are supported by the MF dialect and ISO2002, however, they are not included in the ANSI '85 COBOL standard.

General Rules for Format 2

  1. If the PREFIXING phrase is specified, the library text is copied and each of the following data names are prefixed by word-3:
    • data name, condition name and literal name immediately after the level number (except for FILLER)
    • data name right after REDEFINES (except for 01 level)
    • data name right after RENAMES and the qualifier
    • index of OCCURS, data name for KEY IS and the qualifier
    • address name
  2. If the SUFFIXING phrase is specified, the same rule applies as PREFIXING apart from the data names are suffixed by word-4.
Restriction: The replaced text is not shown in list files and in the debugger.

General Rules for Format 3

  1. If the JOINING phrase is specified with PREFIX, the library text is copied and each of the following data names are prefixed by word-5 followed by a single hyphen, "-":
    • data name, condition name and literal name immediately after the level number (except FILLER)
    • data name right after REDEFINES (except 01 level)
  2. If the JOINING phrase is specified with SUFFIX, the same rule applies as PREFIX apart from the data names are suffixed by a single hyphen character, "-", followed by word-5.
Restriction: The replaced text is not shown in list files and in the debugger.

General Rules for Format 4

  1. The phrase DISJOINING word-6 JOINING word-7 AS PREFIX is equivalent to REPLACING LEADING word-6 BY word-7.
  2. The phrase DISJOINING word-6 JOINING word-7 AS SUFFIX is equivalent to REPLACING TRAILING word-6 BY word-7.

Examples

Examples of the following are provided in the chapter Examples in your Language Reference - Additional Topics:

  • Using the OLDCOPY Compiler directive to achieve ANSI'68 or LANGLVL(1) behavior. See the topic COPY (ANSI'68 or LANGLVL(1) Variation)
  • Using the COPY statement with partial word replacement supported by ANSI'85 rules. See the section Example Using ANSI'85 with Special Characters in the topic COPY (Partial Word Replacement)
  • Using the COPY statement with partial word replacement supported by ISO2000 rules. See the section Example Using ISO2002 and MF Dialects in the topic COPY (Partial Word Replacement)
Parent topic: Source Text Manipulation
Related tasks
COPY...REPLACING and REPLACE Literal Restrictions
Related information
Preprocessor Response Codes
COPY (ANSI'68 or LANGLVL(1) Variation)
COPY (Partial Word Replacement)
Continuation of Lines
Reference Format