Description

The UPPER-CASE function returns a character string that is the same length as the argument with each lowercase letter in the argument replaced by the corresponding uppercase letter.

string

is an alphabetic or alphanumeric argument at least one character in length.

Rules

1. The type of this function is alphanumeric.
2. The returned value is the same character string as the argument, except that each lowercase letter in the argument is replaced by the corresponding uppercase letter.

Examples

1. MOVE FUNCTION UPPER-CASE (STR) TO UC-STR.

   If STR (an alphanumeric data item six characters in length) contains the value "Autumn" the value returned and stored in UC-STR (also an alphanumeric data item six characters in length) is "AUTUMN"; if STR contains "FALL98" the value returned is unchanged ("FALL98").

2. ACCEPT NAME-FIELD. WRITE RECORD-OUT FROM FUNCTION UPPER-CASE(NAME-FIELD).

   The value in NAME-FIELD is made all-uppercase, unless it was already all-uppercase, in which case it is unchanged. Any nonalphabetic characters remain unchanged.

Description

The VARIANCE function returns a numeric value that approximates the variance of its arguments.

arg

is an integer or numeric argument.

Rules

1. The type of this function is numeric.
2. The returned value is the approximation of the variance of the argument series, and is defined as the square of the standard deviation of the argument series. (For a definition of standard deviation, see the description of the
   Section 7.41 function.)
3. If the argument series consists of only one value, the returned value is 0.

Examples

1. COMPUTE RSULT = FUNCTION VARIANCE (A).

   The value returned and stored in RSULT is 0, because there is only one argument.

2. COMPUTE RSULT = FUNCTION VARIANCE (A, B, C).

   If A has the value 1, B has 2, and C has 12, the value returned and stored in RSULT is approximately 24.667. This represents the variance, which is the square of the standard deviation of these arguments; the calculation is described in the description of the Section 7.41 function. In the above examples, A, B, C, and RSULT are numeric data items.

Description

The WHEN-COMPILED function returns the date and time the program was compiled.

Rules

1. The type of this function is alphanumeric.
2. The returned value is the date and time of compilation of the source program that contains this function. If the program is a contained program, the returned value is the compilation date and time associated with the separately compiled program in which it is contained.
3. The returned value denotes the same time as the compilation date and time provided in the listing of the source program and in the generated object code for the source program. The representation differs, and the precision can differ, as shown in the second example.
4. The contents of the character positions returned, numbered from left to right, are as follows:

   Character Positions	Contents
   1-4	Four numeric digits of the year in the Gregorian calendar.
   5-6	Two numeric digits of the month of the year, in the range 01 through 12.
   7-8	Two numeric digits of the day of the month, in the range 01 through 31.
   9-10	Two numeric digits of the hours past midnight, in the range 00 through 23.
   11-12	Two numeric digits of the minutes past the hour, in the range 00 through 59.
   13-14	Two numeric digits of the seconds past the minute, in the range 00 through 59.
   15-16	Two numeric digits of the hundredths of a second past the second, in the range 00 through 99 (Tru64 UNIX and OpenVMS systems. The digits are 00 on Windows NT systems, which do not show fractions of a second.)
   17-21	The value 00000. (Reserved for future use.)

Examples

MOVE FUNCTION WHEN-COMPILED TO VERSION-STAMP.

The value returned and stored in VERSION-STAMP (an alphanumeric data item) is the date and time of the program's compilation.

199701101652313200000 (Tru64 UNIX and OpenVMS systems) 199701101652310000000 (Windows NT systems)

This is a sample value returned by the WHEN-COMPILED function. Reading from left to right, it shows

• The year, 1997
• The month, January
• The day of the month, the 10th
• The time of day, 16:52 (4:52 P.M.)
• On Tru64 UNIX and OpenVMS, the seconds, 31, and the hundredths
  of seconds, 32, after 16:52 <>
• On Windows NT, the seconds, 31, followed by zeros (Windows NT systems do
  not show hundredths of seconds) <>

This compilation date and time as shown on the compiler listing (which does not show hundredths of seconds) is as follows:

10-Jan-1997 16:52:31

7.49 YEAR-TO-YYYY

Description

The YEAR-TO-YYYY function converts a two-digit year to a four-digit year. An optional second argument, when added to the current year (at the time the program executes), defines the ending year of a 100-year interval. This interval determines to what century the two-digit year belongs.

General Format

FUNCTION YEAR-TO-YYYY ( arg-1 [ arg-2 ] )

arg-1

is a nonnegative integer between 0 and 99.

arg-2

is an integer. Its value, when added to the current year, must be between 1700 and 9999. If it is omitted, the default value is 50.

Rules

1. The type of this function is integer.
2. The returned value is an integer representing a four-digit year calculated as follows:

   max-year = current-yyyy + arg-2 if mod(max-year, 100) >= arg-1 return (arg-1 + 100 * int(max-year / 100)) else return (arg-1 + 100 * int(max-year / 100) - 1)

Example

IF FUNCTION YEAR-TO-YYYY (80, 50 ) = 1980 DISPLAY "correct". IF FUNCTION YEAR-TO-YYYY (80, 100 ) = 2080 DISPLAY "correct". IF FUNCTION YEAR-TO-YYYY (80, -100 ) = 1880 DISPLAY "correct".

YEAR-TO-YYYY implements a sliding window algorithm. To use it for a fixed window, you can specify arg-2 as follows:

(fixed-ending-year - function numval (function current-date (1:4)))

If fixed-ending-year is 2100, then for 1999 arg-2 has the value 101. If arg-1 is 50, the returned-value is 2050. If arg-1 is 99, the returned-value is 2099.

Source programs can copy frequently used COBOL text from a Tru64 UNIX or Windows NT directory containing library files, an OpenVMS Librarian file, a COBOL library file, or (for OpenVMS Alpha) Oracle CDD/Repository. The COPY statement can include text without change, or it can change the text as it is copied into the source program.

The COPY statement REPLACING phrase changes text in the copying process. It matches arguments against the text to determine which text to replace. The matching procedure operates on text-words.

The REPLACE statement changes text in the source program. It matches source text to the pseudo-text specified in the REPLACE statement and changes the specified text when a match is detected.

8.1 Text-Word Definition Rules

A text-word is a character or sequence of characters in a COBOL library, source program, pseudo-text, or repository. It can be any of the following:

1. A literal, including the opening and closing quotation marks for nonnumeric literals
2. A hexadecimal literal, including the opening and closing delimiters
3. A separator other than:

   A space
   A pseudo-text delimiter
   The opening and closing quotation marks of a nonnumeric literal

4. Any other sequence of contiguous characters, bounded by separators, except:

   Comment lines
   Separators

Examples

These examples show how the compiler interprets COBOL text in terms of text-words. The rule letters refer to the text-word definition rules.

Text	Interpretation
MOVE	One text-word (Rule 4).
MOVE ITEMA TO ITEMB	Four text-words.
MOVE ITEMA TO ITEMB.	Five text-words. The separator period is a text-word (Rule 3).
PIC S9(4)V9(6)	Nine text-words. Each parenthesis is a separator, and therefore a text-word. The nine text-words are PIC, S9, (, 4, ), V9, (, 6, and ).
"PIC S9(4)V9(6)"	One text-word (Rule 1).
X"4865784C6974"	One text-word (Rule 2).
ITEMA.	Two text-words. ITEMA and the separator period are text words.
==ITEMA. :=,=	Two text-words. The pseudo-text delimiters are not text-words (Rule 3). However, the separator period is a text-word.
==ITEMA.:=,=	One text-word. The pseudo-text delimiters are not text-words. The punctuation character period is part of the character-string "ITEMA."; the period is not a separator because a space does not follow it.

8.1.1 COPY

The COPY statement includes text in a COBOL program.

General Formats

Format 1

text-name

is the name of a COBOL library file available during compilation; or, if library-name is specified, is the name of a text record within the library file. (See Technical Notes.)

library-name

is the directory that contains library files on the Tru64 UNIX or Windows NT system; or, on OpenVMS Alpha, is the name of the OpenVMS Librarian library file that contains text-name. (See Technical Notes.)

pseudo-text-1

identifier-1

literal-1

word-1

are text-matching arguments that the compiler compares against text-words in the library text.

pseudo-text-2

identifier-2

literal-2

word-2

are replacement items that the compiler inserts into the source program.

record-name (OpenVMS)

is a partial or complete Oracle CDD/Repository pathname. It specifies the Oracle CDD/Repository record description to be copied into the source program. (See Technical Notes.) <>

Syntax Rules

1. A Format 1 COPY statement can be used anywhere that a character-string or separator (other than a closing quotation mark) can be used in a program.
2. On OpenVMS, a Format 2 COPY statement can appear only in the File, Working-Storage, or Linkage Sections. <>
3. A space must precede the word COPY.
4. The COPY statement must be terminated by the separator period.
5. pseudo-text-1 must contain at least one text-word.
6. pseudo-text-2 can contain zero, one, or more text-words.
7. word-1 or word-2 can be any COBOL word.
8. pseudo-text-1 must not consist entirely of a separator comma or a separator semicolon.

General Rules

Format 1

1. On Tru64 UNIX and Windows NT, when both text-name and library-name are specified, library-name refers to the directory containing library files; text-name identifies a specific file within the directory. <>
2. On OpenVMS, when both text-name and library-name are specified, library-name refers to an OpenVMS Alpha Librarian library file; text-name identifies a text record within the library file. <>
3. When only text-name is used, it identifies a file that contains library text.
4. Library text must follow the source reference format rules. Library text and source program text formats must be the same; that is, both must be ANSI format, or both must be terminal format.
5. On Tru64 UNIX and Windows NT, the COPY statement references source text from a directory containing library files or from a COBOL library file. <>

Format 2 (OpenVMS)

6. record-name refers to a record description stored in Oracle CDD/Repository.
7. The compiler translates the record description associated with record-name to COBOL source text. If the source program containing the COPY statement is in terminal format, the translated record description is in terminal format; otherwise, the record description is translated to ANSI format. <>

Both Formats

8. On OpenVMS, the COPY statement references source text from an OpenVMS Librarian file, a COBOL library file, or the Oracle CDD/Repository.<>
9. The compiler evaluates the COBOL source program after processing all COPY statements.
10. The COPY statement does not change the original source program text file.
11. The COPY statement causes the compiler to copy the source text associated with text-name into the program. The source text logically replaces the COPY statement, beginning with the word COPY and ending with the punctuation character period (inclusive).
12. If there is no REPLACING phrase, the compiler copies the source text without modification.
13. If there is a REPLACING phrase, the compiler changes the source text as it copies it. The compiler replaces each successfully matched occurrence of a text-matching argument in the source text by the corresponding replacement item.
14. For the purposes of matching, the compiler treats each text-matching argument as pseudo-text that contains identifier-1, word-1, or literal-1.
15. The comparison operation starts with the leftmost source text text-word and the first text-matching argument. The compiler compares the entire text-matching argument to an equivalent number of consecutive source text text-words.
16. A text-matching argument matches the source text only if the ordered sequence of text-words that forms the text-matching argument is equal, character for character, to the ordered sequence of source text text-words.
    In the matching operation, the compiler treats each occurrence or combination of the following items in source text as a single space:
    • Separator comma
    • Separator semicolon
    • A sequence of one or more separator spaces
    • A blank line
    • A comment line
17. If no match occurs, the compiler repeats the comparison with each successive text-matching argument in the REPLACING phrase until either:
    • A match occurs.
    • There are no more text-matching arguments.
18. If no match occurs after the compiler compares all text-matching arguments, the compiler copies the leftmost source text text-word into the source program. The next source text text-word then becomes the leftmost text-word for the next cycle. The comparison cycle resumes with the first text-matching argument in the REPLACING phrase.
19. If a match occurs between a text-matching argument and the source text, the compiler inserts the replacement item into the source program. The source text-word immediately after the rightmost replaced text-word then becomes the leftmost text-word for the next cycle. The comparison cycle resumes with the first text-matching argument in the REPLACING phrase.
20. The comparison cycle continues until the rightmost text-word in the source text has been either:
    • Matched and replaced
    • Used as the leftmost library text-word in a comparison cycle
21. The rules for Reference Format determine the sequence of text-words in the source text and the text-matching arguments.
22. When the compiler inserts pseudo-text-2 into the source program, any comment lines or blank lines within pseudo-text-2 are inserted without modification. (See Example 5.)
23. The compiler copies any comment lines and blank lines in the source text into the source program unchanged (see Example 1). However, the compiler does not copy a comment line or blank line from the source text if it is in the sequence of text-words that matches the text-matching argument.
24. The resultant source program cannot contain a COPY statement after the compiler processes a COPY statement.
    • Text copied from a source text cannot contain a COPY statement unless the replacement operation changes the word COPY in the resultant source text.
    • The replacement item in the REPLACING phrase must not insert a COPY statement into the source text.
25. The compiler cannot determine the syntactic correctness of source text, or the source program, until all COPY statements are processed.
26. When the compiler copies a text-word from the source text, it places it in the source program beginning in the same area as in the source text. That is, a text-word that begins in Area A in the source text begins in Area A of the source program after the copy operation. Similarly, a text-word that begins in Area B in the source text begins somewhere in Area B of the source program.
27. When the compiler inserts a text-word from pseudo-text-2, it places it in the source program beginning in the same area as in pseudo-text-2.
28. When the compiler inserts text from identifier-2, literal-2, or word-2, it places the first text-word in the source program beginning in the same area as the leftmost library text-word that matches the argument. It places all other replacement text-words in the source program beginning in the same area as they appear in the COPY statement.
29. Pseudo-text insertion can change parts of a single character-string. An unmatched text-word and a replaced text-word can combine to form a character-string. For example, the COPY statement can replace part of a PICTURE character-string. (See Example 3.)
30. Conditional compilation lines are permitted within the library text and pseudo-text. Text-words within a conditional compilation line participate in the matching process as if the indicator area character of the line on which they began was not present. A conditional compilation line is specified within pseudo-text if it begins in the source program after the opening pseudo-text delimiter, but before the matching closing pseudo-text delimiter.
31. The resultant text can occur on conditional compilation lines according to the following precedence rules:
    • If a COPY statement begins on a conditional compilation line, each line of the resulting text appears on the same kind of line.
    • If a library text-word that is not involved in a match begins on a conditional compilation line, it appears in resulting text on the same kind of line.
    • If the first library text-word that is involved in a match begins on a conditional compilation line, the identifier-2, literal-2, word-2, or pseudo-text-2 that replaces the first library text-word appears on the same kind of line.
    • If text-words within pseudo-text-2 begin on a conditional compilation line, resulting text appears on the same kind of line.

Technical Notes

Format 1

1. If there is a library-name phrase, text-name is tr-name.
   On OpenVMS systems, tr-name is defined as a user-defined name or nonnumeric literal that matches the name of a text record in library-name.<>
2. library-name (or text-name, when there is no library-name phrase) represents a complete or partial file specification, defined to be f-name: f-name is a nonnumeric literal or a COBOL word formed according to the rules for user-defined names.
3. The COBOL command-line qualifier /INCLUDE (or -include ) can be used at compile time to set up a search list for the COPY command. Assume that the following conditions are all true:
   • library-name is not used.
   • text-name does not include a directory specification.
   • /INCLUDE is specified.
   Then the compiler searches for the text-name file in the following order:
   1. The current working directory when the compiler is invoked
   2. The directory specified after /INCLUDE (or -include )
      If more than one directory is specified, they are searched in left to right order.
   
   On OpenVMS, if library-name is used, and library-name does not include a directory specification, the /INCLUDE qualifier causes a search for a .TLB file, in the same search order. <>
   The first file encountered that matches the text-name terminates the search.
   On Tru64 UNIX and Windows NT, /INCLUDE (or -include ) can be used to set up a search list for a text-name without a directory specification only if library-name is not specified. <>
   If the default, /NOINCLUDE, is in effect, a file without a directory specification is searched for only in the current default directory at compile time.
   The pathname(s) specified with /INCLUDE can be relative or absolute directory specifications, logical names on OpenVMS, or environment variables on Windows NT or Tru64 UNIX.
4. If f-name or tr-name is not a literal, the compiler translates hyphens in the word to underscore characters and treats it as if it were enclosed in quotation marks.
5. When the COPY statement executes, the I/O system:
   • Removes leading and trailing spaces and tab characters from f-name and from tr-name
   • Translates lowercase letters to uppercase in f-name and in tr-name
6. The default file type for text-name, when text-name is f-name, is LIB. For example, COPY CUSTFILE becomes COPY CUSTFILE.LIB.
7. On OpenVMS, the default file type for library-name is TLB. For example, COPY "ACCOUNTS" OF CUSTLIB becomes COPY "ACCOUNTS" OF CUSTLIB.TLB.<>
8. On all platforms, file names must conform to the rules of the operating system where compilation occurs. For example:
   • On Windows NT systems:

     COPY "C:\usr\proj\empl\empl_file". COPY "empl_file" IN "C:\usr\proj\empl". <>

   • On Tru64 UNIX systems:

     COPY "/usr/proj/empl/empl_file". COPY "empl_file" IN "/usr/proj/empl". <>

   • On OpenVMS systems:

     COPY "COPYDIR:EMPL_FILE.LIB". COPY "EMPL_FILE" IN "EMPLLIB.TLB". <>

9. On Tru64 UNIX, when compiling in the Compaq FUSE environment (using the compiler options -xref or -xref_stdout ), certain COBOL programs may raise the following fatal diagnostic:

   cobol: Severe: Fatal error -7 returned from a cross-referencing library procedure

   
   To avoid this error, any COBOL source files that contain a PROGRAM-ID or END PROGRAM statement for a program must contain that entire program. In other words, the PROGRAM-ID and END PROGRAM clauses cannot appear in library text.<>

10. With certain COBOL programs in the Compaq FUSE environment a problem will manifest itself by displaying the wrong file in the Compaq FUSE Editor tool for certain COBOL items that are clicked on from the Cross-Referencer tool. This can happen only for COBOL programs with successive COPY statements where there are no intervening data item references or declarations. To work around this problem, insert an extra declaration between successive COPY statements in the DATA DIVISION as follows:

    COPY "LIBRARY-1". 01 EXTRA-ITEM PIC X. COPY "LIBRARY-2".

    
    You should also insert an extra reference to a data item between successive COPY statements in the PROCEDURE DIVISION as follows:

    ---

    Previous

    Next

    Contents

    Index