COBOL - COPY statement - www.cadcobol.com.br



Desenvolvido por DORNELLES Carlos Alberto - Analista de Sistemas - Brasília DF. - cad_cobol@hotmail.com

COBOL - COPY statement - Em português

Enterprise COBOL for z/OS, V4.2, Language Reference


We use COPY in the COBOL simple program and INCLUDE in the COBOL-DB2 program.

COPY statements are executed at compile time and INCLUDE statements are executed at run time.

The COPY statement is a library statement that places prewritten text in a COBOL compilation unit.

Prewritten source code entries can be included in a compilation unit at compile time.
Thus, an installation can use standard file descriptions, record descriptions, or procedures without recoding them.
These entries and procedures can then be saved in user-created libraries;
they can then be included in programs and class definitions by means of the COPY statement.

Compilation of the source code containing COPY statements is logically equivalent to processing all COPY statements before processing the resulting source text.

The effect of processing a COPY statement is that the library text associated with text-name is copied into the compilation unit, logically replacing the entire COPY statement, beginning with the word COPY and ending with the period, inclusive.
When the REPLACING phrase is not specified, the library text is copied unchanged.

text-name, library-name
text-name identifies the copy text. library-name identifies where the copy text exists.
  • Can be from 1-30 characters in length
  • Can contain the following characters: Latin uppercase letters A-Z, Latin lowercase letters a-z, digits 0-9, and hyphen
  • Thefirst or last character must not be a hyphen
  • Cannot contain an underscore

Neither text-name nor library-name need to be unique within a program.
They can be identical to other user-defined words in the program.

text-name need not be qualified. If text-name is not qualified, a library-name of SYSLIB is assumed.

When compiling from JCL or TSO, only the first eight characters are used as the identifying name.
When compiling with the cob2 command and processing COPY text residing in the Hierarchical File System (HFS), all characters are significant.

literal-1, literal-2
Must be alphanumeric literals. literal-1 identifies the copy text. literal-2 identifies where the copy text exists.

When compiling from JCL or TSO:

  • Literals can be from 1-30 characters in length.
  • Literals can contain characters: A-Z, a-z, 0-9, hyphen,@, #, or $.
  • Thefirst or last character must not be a hyphen.
  • Literals cannot contain an underscore.
  • Only the first eight characters are used as the identifying name.

When compiling with the cob2 command and processing COPY text residing in the HFS, the literal can be from 1 to 160 characters in length.

The uniqueness of text-name and library-name is determined after the formation and conversion rules for a system-dependent name have been applied.

For information about the mapping of characters in the text-name, library-name, and literals, see in the Enterprise COBOL Programming Guide.

operand-1, operand-2
Can be either pseudo-text, an identifier, a function-identifier, a literal, or a COBOL word (except the word COPY).

Library text and pseudo-text can consist of or include any words (except COPY), identifiers, or literals that can be written in the source text.
This includesDBCS user-defined words,DBCS literals, and national literals.

DBCS user-defined words must be wholly formed; that is, there is no partial-word replacement forDBCS words.

Words or literals containingDBCS characters cannot be continued across lines.

Each COPY statement must be preceded by a space and ended with a separator period.

A COPY statement can appear in the source text anywhere a character string or a separator can appear.

COPY statements can be nested.
However, nested COPY statements cannot contain the REPLACING phrase, and a COPY statement with the REPLACING phrase cannot contain nested COPY statements.

A nested COPY statement cannot cause recursion.
That is, a COPY member can be named only once in a set of nested COPY statements until the end-of-file for that COPY member is reached.
For example, assume that the source text contains the statement: COPY X. and library text X contains the statement: COPY Y..

In this case, library text Y must not have a COPY X or a COPY Y statement.

Debugging lines are permitted within library text and pseudo-text.
Text words within a debugging line participate in the matching rules as if the "D" did not appear in the indicator area.
A debugging line is specified within pseudo-text if the debugging line begins in the source text after the opening pseudo-text delimiter but before the matching closing pseudo-text delimiter.

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.

When a COPY statement is specified on a debugging line, the copied text is treated as though it appeared on a debugging line, except that comment lines in the text appear as comment lines in the resulting source text.

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.

After all COPY and REPLACE statements have been processed, a debugging line will be considered to have all the characteristics of a comment line, if the WITH DEBUGGING MODE clause is not specified in the SOURCE-COMPUTER paragraph.

Comment lines or blank lines can occur in library text.
Comment lines or blank lines appearing in library text are copied into the resultant source text unchanged with the following exception: a comment line or blank line in library text is not copied if that comment line or blank line appears within the sequence of text words that match operand-1 (see Replacement and comparison rules).

Lines containing *CONTROL (*CBL), EJECT, SKIP1, SKIP2, SKIP3, or TITLE statements can occur in library text.
Such lines are treated as comment lines during COPY statement processing.

The syntactic correctness of the entire COBOL source text cannot be determined until all COPY and REPLACE statements have been completely processed, because the syntactic correctness of the library text cannot be independently determined.

Library text copied from the library is placed into the same area of the resultant program as it is in the library.
Library text must conform to the rules forStandard COBOL 85 format.

Note: Characters outside those defined for COBOL words and separators must not appear in library text or pseudo-text except in comment lines, comment-entries, alphanumeric literals, DBCS literals, or national literals.

SUPPRESS phrase

The SUPPRESS phrase specifies that the library text is not to be printed on the source listing.

REPLACING phrase

In the discussion that follows, each operand can consist of one of the following:

  • Pseudo-text
  • An identifier
  • A literal
  • A COBOL word (except the word COPY)
  • Function identifier

When the REPLACING phrase is specified, the library text is copied, and each properly matched occurrence of operand-1 within the library text is replaced by the associated operand-2.

pseudo-text
A sequence of character-strings or separators, or both, bounded by, but not including, pseudo-text delimiters (==).
Both characters of each pseudo-text delimiter must appear on one line; however, character-strings within pseudo-text can be continued.

Individual character-strings within pseudo-text can be up to 322 characters long; they can be continued subject to the normal continuation rules for source code format.

Keep in mind that a character-string must be delimited by separators.
For more information, see Characters.

pseudo-text-1 refers to pseudo-text when used for operand-1, and pseudo-text-2 refers to pseudo-text when used for operand-2.

pseudo-text-1 can consist solely of the separator comma or separator semicolon. pseudo-text-2 can be null; it can consist solely of space characters or comment lines.

Pseudo-text must not contain the word COPY.

Each text word in pseudo-text-2 that is to be copied into the program is placed in the same area of the resultant program as the area in which it appears in pseudo-text-2.

Pseudo-text can consist of or include any words (except COPY), identifiers, or literals that can be written in the source text.
This includesDBCS user-defined words, DBCS literals, and national literals.

DBCS user-defined words must be wholly formed; that is, there is no partial-word replacement forDBCS words.

Words or literals containingDBCS characters cannot be continued across lines.

identifier
Can be defined in any section of the data division.

literal
Can be numeric, alphanumeric, DBCS, or national.

word
Can be any single COBOL word (except COPY), includingDBCS user-defined words.
DBCS user-defined words must be wholly formed. You cannot replace part of a DBCS word.

You can include the nonseparator COBOL characters (for example, +, *, /, $, <, >, and =) as part of a COBOL word when used as REPLACING operands.
In addition, a hyphenor underscore can be at the beginning of the word or a hyphen can be at the end of the word.

For purposes of matching, each identifier-1, literal-1, or word-1 is treated as pseudo-text containing only identifier-1, literal-1, or word-1, respectively.

Replacement and comparison rules

  1. Arithmetic and logical operators are considered text words and can be replaced only through the pseudo-text option.

  2. Beginning and ending blanks are not included in the text comparison process.
    Embedded blanks are used in the text comparison process to separate multiple text words.

  3. When operand-1 is a figurative constant, operand-1 matches only the same exact figurative constant.
    For example, if ALL "AB" is specified in the library text, then "ABAB" is not considered a match; only ALL "AB" is considered a match.

  4. When replacing a PICTURE character-string, the pseudo-text option should be used; to avoid ambiguities, pseudo-text-1 should specify the entire PICTURE clause, including the keyword PICTURE or PIC.

  5. Any separator comma, semicolon, or space preceding the leftmost word in the library text is copied into the source text.
    Beginning with the leftmost library text word and the first operand-1 specified in the REPLACING option, the entire REPLACING operand that precedes the keyword BY is compared to an equivalent number of contiguous library text words.

  6. operand-1 matches the library text if, and only if, the ordered sequence of text words in operand-1 is equal, character for character, to the ordered sequence of library words.
    For national characters, the sequence of national characters must be equal, national character for national character, to the ordered sequence of library words.
    For matching purposes, each occurrence of a comma or semicolon separator and each sequence of one or more space separators is considered to be a single space.
    However, when operand-1 consists solely of a separator comma or semicolon, it participates in the match as a text word (in this case, the space following the comma or semicolon separator can be omitted).

    When the library text contains a closing quotation mark that is not immediately followed by a separator space, comma, semicolon, or period, the closing quotation mark is considered a separator quotation mark.


  7. If no match occurs, the comparison is repeated with each successive operand-1, if specified, until either a match is found or there are no further REPLACING operands.

  8. Whenever a match occurs between operand-1 and the library text, the associated operand-2 is copied into the source text.

  9. The COPY statement with REPLACING phrase can be used to replace parts of words.
    By inserting a dummy operand delimited by colons into the program text, the compiler will replace the dummy operand with the desired text.
    Example 3 shows how this is used with the dummy operand :TAG:.

    The colons serve as separators and make TAG a stand-alone operand.


  10. When all operands have been compared and no match is found, the leftmost library text word is copied into the source text.

  11. The next successive uncopied library text word is then considered to be the leftmost text word, and the comparison process is repeated, beginning with the first operand-1.
    The process continues until the rightmost library text word has been compared.

  12. Comment lines or blank lines occurring in the library text and in pseudo-text-1 are ignored for purposes of matching; and the sequence of text words in the library text and in pseudo-text-1 is determined by the rules for reference format.
    Comment lines or blank lines appearing in pseudo-text-2 are copied into the resultant program unchanged whenever pseudo-text-2 is placed into the source text as a result of text replacement.
    Comment lines or blank lines appearing in library text are copied into the resultant source text unchanged with the following exception:
    a comment line or blank line in library text is not copied if that comment line or blank line appears within the sequence of text words that match pseudo-text-1.

  13. Text words, after replacement, are placed in the source text according toStandard COBOL 85 format rules.

  14. When text words are placed in the source text, additional spaces are introduced only between text words where there already exists a space (including the assumed space between source lines).

  15. COPY REPLACING does not affect the EJECT, SKIP1, SKIP2, SKIP3, or TITLE compiler-directing statements.

Sequences of code (such as file and data descriptions, error and exception routines) that are common to a number of programs can be saved in a library, and then used in conjunction with the COPY statement.
If naming conventions are established for such common code, then the REPLACING phrase need not be specified.
If the names will change from one program to another, then the REPLACING phrase can be used to supply meaningful names for this program.

Example 1

In this example, the library text PAYLIB consists of the following data division entries:

    01  A.
        05  B    PIC S99.
        05  C    PIC S9(5)V99.
        05  D    PIC S9999 OCCURS 1 TO 52 TIMES
                 DEPENDING ON B OF A.

The programmer can use the COPY statement in the data division of a program as follows:

    COPY PAYLIB.

In this program, the library text is copied; the resulting text is treated as if it had been written as follows:

    01  A.
        05  B    PIC S99.
        05  C    PIC S9(5)V99.
        05  D    PIC S9999 OCCURS 1 TO 52 TIMES
                 DEPENDING ON B OF A.

Example 2

To change some (or all) of the names within the library text, the programmer can use the REPLACING phrase:

    COPY PAYLIB REPLACING A BY PAYROLL
                          B BY PAY-CODE
                          C BY GROSS-PAY
                          D BY HOURS.

In this program, the library text is copied; the resulting text is treated as if it had been written as follows:

    01  PAYROLL.
        05  PAY-CODE    PIC S99.
        05  GROSS-PAY   PIC S9(5)V99.
        05  HOURS       PIC S9999 OCCURS 1 TO 52 TIMES
                        DEPENDING ON PAY-CODE OF PAYROLL.

The changes shown are made only for this program. The text, as it appears in the library, remains unchanged.

Example 3

If the following conventions are followed in library text, then parts of names (for example the prefix portion of data names) can be changed with the REPLACING phrase.

In this example, the library text PAYLIB consists of the following data division entries:

    01  :TAG:.
        05  :TAG:-WEEK          PIC S99.
        05  :TAG:-GROSS-PAY     PIC S9(5)V99.
        05  :TAG:-HOURS         PIC S999  OCCURS 1 TO 52 TIMES
                                DEPENDING ON :TAG:-WEEK OF :TAG:.

The programmer can use the COPY statement in the data division of a program as follows:

    COPY PAYLIB REPLACING ==:TAG:== BY ==Payroll==.

Usage Note: It is important to notice in this example the required use of colons or parentheses as delimiters in the library text.
Colons are recommended for clarity because parentheses can be used for a subscript, for instance in referencing a table element.

In this program, the library text is copied; the resulting text is treated as if it had been written as follows:

    01  PAYROLL.
        05  PAYROLL-WEEK        PIC S99.
        05  PAYROLL-GROSS-PAY   PIC S9(5)V99.
        05  PAYROLL-HOURS       PIC S999  OCCURS 1 TO 52 TIMES
                                DEPENDING ON PAYROLL-WEEK OF PAYROLL.

The changes shown are made only for this program. The text, as it appears in the library, remains unchanged.

Example 4

This example shows how to selectively replace level numbers without replacing the numbers in the PICTURE clause:

    COPY xxx REPLACING ==(01)== BY ==(01)==
                       == 01 == BY == 05 ==.

Veja também


© Copyright IBM Corp.