HP 3000 Manuals HP 3000 Manuals
COPY Statement The COPY statement is the method by which source records in a COBOL library are copied into your source program. This statement may appear anywhere in your source program, from the IDENTIFICATION DIVISION to the end of the PROCEDURE DIVISION. Aside from allowing you to copy modules into your source file, it also allows you to replace occurrences of a string of words, a substring, an identifier, a literal, or a word appearing in the module being copied. Syntax The COPY statement has the following format:Parameters text-name-1 the name of the module to be copied into your source program. library-name-1 a name containing one to eight alphanumeric characters, the first of which must be alphabetic. This name is used to specify the library in which the module to be copied resides. Library-name-1 must be used when you have more than one COBOL library in your log-on group. If library-name-1 is not used, the COBOL compiler assumes that the library name is COPYLIB. NOLIST if used, indicates that the text of the module named by text-name-1 is not included in the list file created by the compilation process. The NOLIST parameter is an HP extension to the ANSI COBOL standard. ==pseudo-text-1== a sequence of words, comment lines, and spaces delimited on either end by double equal signs. It may consist of any text you wish, except that it must not consist of null text (that is,= = = =), all spaces, commas, semicolons, or all comment lines. literal-1 and each can be any COBOL literal. literal-2 identifier-1 and can each be any COBOL identifier and can be identifier-2 qualified. word-1 and word-2 can each be any single COBOL word.
NOTE Where the sequence consists only of a single element, using the identifier-1, literal-1, or word-1 format is more efficient.
==pseudo-text-2== a sequence of words, comment lines, or spaces delimited on either end by double equal signs. It may be any text you wish, including null text (that is, it may be of the form, ====). Character strings within pseudo-text-1 and pseudo-text-2 may be continued. However, both equal signs forming the delimiters must be on the same line. Description A COPY statement may appear in a source program anywhere a character string or a separator is allowed. However, a COPY statement may not appear within another COPY statement. When a COPY statement is used, it must be preceded by a space and terminated by a period. COPY statements are executed before source lines associated with them are sent to the compiler. Thus, only the lines of the copied module, including any replaced words, identifiers, and so forth, are sent to the compiler. The COPY statement itself is not. Although the COPY statement is not sent to the compiler, it appears in the listing sent to the list file, along with the records of the copied module (unless NOLIST was specified). If the REPLACING phrase is not used, the module is copied exactly as it appears in the library, including its sequence field and text-name, which appears in columns 73 through 80 of each record in the module. REPLACING Phrase To facilitate the following discussion, the REPLACING phrase is rewritten as shown below. REPLACING text-to-replace BY replace-text Before the comparison to determine which text, if any, is to be replaced in the copied module, spaces, commas, and semicolons to the left of the first word in the records of the module are moved into the source program. The first word of the record in a module is the first part of the module to be compared. Starting with the left most word in the module being copied, and the first text-to-replace specified in the REPLACING phrase, text-to-replace is compared to an equivalent number of contiguous words in the module. Text-to-replace matches the text in the module if and only if each character in text-to-replace equals the character in the corresponding position of the text in the module. For purposes of matching, each occurrence of a separator comma, or semicolon in text-to-replace or in the text of the module is considered to be a single space. Each sequence of one or more spaces is considered to be a single space. If no match occurs, the comparison is repeated with each next successive text-to-replace, if any, in the REPLACING phrase until either match is found or there is no next successive text-to-replace. When all occurrences of text-to-replace have been compared to the text in the module and no match has occurred, the left most word in the text in the module is copied into your source program. The next word of the text in the module is then considered as the left most word of the text in the module, and the comparison cycle is repeated, starting with the first text-to-replace in the REPLACING phrase. Whenever a match occurs between text-to-replace and text in the module, replace-text is placed into the source program. The word immediately to the right of the text in the module which participated in the match is then considered as the left most word of the text in the module, and comparison begins again, starting with the first text-to-replace in the REPLACING phrase. The comparison operation continues until the rightmost word in the last line of the module has either participated in a match or has been considered as the left most word of text in the module and has participated in a complete comparison cycle. A comment line in text-to-replace or in the module is interpreted, for purposes of matching, as a single space. Comment lines appearing in replace-text and in the module are copied into the source program unchanged. The syntactic correctness of the lines in a module cannot be independently determined. Nor can the syntactic correctness of the entire COBOL source program until all COPY statements have been completely processed. The following are two examples of the COPY statement. Example 1 This example uses a module named RITESTUF in a library called UTIL to illustrate the COPY statement. 001000 WRITE-ROUTINE. RITESTUF 001100 OPEN OUTPUT CHECKS. RITESTUF 002000 WRITE AMOUNT BEF-AFT ADVANCING X LINES RITESTUF 003000 AT EOP IMP-STAT. RITESTUF The COPY statement appears as follows: 100000 PROCEDURE DIVISION. : 102100 COPY RITESTUF OF UTIL 102200 REPLACING CHECKS BY FILEOUT 102300 ==AMOUNT== BY ==RECOUT== 102310 ==X== BY ==1== 102400 ==BEF-AFT== BY ==BEFORE== 102500 ==IMP-STAT== BY ==PERFORM PAGER==. 102600 CLOSE FILEOUT. : Results of the COPY statement: 102500 001000 WRITE-ROUTINE. RITESTUF 001100 OPEN OUTPUT FILEOUT. RITESTUF 002000 WRITE RECOUT BEFORE ADVANCING 1 LINES RITESTUF 003000 AT EOP PERFORM PAGER. RITESTUF 102600 CLOSE FILEOUT. Example 2 This example illustrates how the COPY statement can copy substrings in library text. This is done by putting parentheses around the substring to be replaced and around pseudo-text-1. The name of the module is PRODUCT1 in library MFG1. 001000 01 (FIRST)-RECORD PIC X(80). PRODUCT1 The COPY statement appears as follows: COPY PRODUCT1 OF MFG1 REPLACING ==(FIRST)== BY ==MAIN-INPUT==. Below are the results of the COPY statement: 001000 01 MAIN-INPUT-RECORD PIC X(80). PRODUCT1 You cannot use COPY REPLACING to replace substrings within nonnumeric literals. For example, if the following DISPLAY statement were in a program, it would not be changed by the COPY REPLACING statement above: DISPLAY "(FIRST)-RECORD".
![[]](../../pic3k/M011820/FFN1343c50.gif)