# Compaq COBOL
Reference Manual

Previous | Contents | Index

# 7.46 UPPER-CASE

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.

# 7.47 VARIANCE

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.

# 7.48 WHEN-COMPILED

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.
   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

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 <>

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.

# Chapter 8
Source Text Manipulation

Source programs can copy frequently used COBOL text from a Tru64 UNIX directory containing library files, an OpenVMS Librarian file, a COBOL library file, or (for OpenVMS) 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

Function

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 system; or, on OpenVMS, 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, 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 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, 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. On Alpha systems, 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 Alpha, 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, /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 Alpha, or environment variables on 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 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".   <>

Format 2 (OpenVMS)

11. record-name can be a nonnumeric literal or COBOL word formed according to the rules for user-defined names. It represents a complete or partial Oracle CDD/Repository pathname specifying the Oracle CDD/Repository record description to be copied into the source program. If record-name is not a literal, the compiler translates hyphens in the COBOL word to underline characters.
    The resultant pathname must conform to all rules for forming Oracle CDD/Repository pathnames.
12. Table 8-1 shows the representation of Oracle CDD/Repository data types in the Compaq COBOL compiler. It lists the data types that can be specified using CDO with the corresponding COBOL data item picture. Note that COBOL does not have an equivalent specification for some data types.

    Table 8-1 Oracle CDD/Repository Data Types and Compaq COBOL Equivalents (OpenVMS)
    Oracle CDD/Repository Data Type | Compaq COBOL Equivalent
    --- | ---
    BIT l | No equivalent 1
    SIGNED BYTE l s | No equivalent 1
    UNSIGNED BYTE l s | No equivalent 1
    D_FLOATING s | COMP-2 (with /FLOAT=D_FLOAT)
    D_FLOATING COMPLEX s | No equivalent 1
    DATE | No exact equivalent 2
    F_FLOATING s | COMP-1 (with /FLOAT=D_FLOAT or /FLOAT=G_FLOAT)
    F_FLOATING COMPLEX s | No equivalent 1
    G_FLOATING s | COMP-2 (with /FLOAT=G_FLOAT) on Alpha; no equivalent on VAX
    G_FLOATING COMPLEX s | No equivalent 1
    H_FLOATING s | No equivalent 1
    H_FLOATING COMPLEX s | No equivalent 1
    IEEE S_FLOATING | COMP-1 (with /FLOAT=IEEE_FLOAT) on Alpha; no equivalent on VAX
    IEEE T_FLOATING | COMP-2 (with /FLOAT=IEEE_FLOAT) on Alpha; no equivalent on VAX
    SIGNED LONGWORD l s | S9(9) COMP
    UNSIGNED LONGWORD l s | No exact equivalent 3
    UNSIGNED NUMERIC l s | 9(m)V9(n)
    SIGNED NUMERIC LEFT SEPARATE l s | S9(m)V9(n) LEADING SEPARATE
    SIGNED NUMERIC LEFT OVERPUNCHED l s | S9(m)V9(n) LEADING
    SIGNED NUMERIC RIGHT SEPARATE l s | S9(m)V9(n) TRAILING SEPARATE
    SIGNED NUMERIC RIGHT OVERPUNCHED l s | S9(m)V9(n) TRAILING
    SIGNED OCTAWORD l s | S9(31) COMP on Alpha; no equivalent on VAX
    UNSIGNED OCTAWORD l s | No exact equivalent 3
    PACKED NUMERIC l s | S9(m)V9(n) COMP-3
    SIGNED QUADWORD l s | S9(18) COMP
    UNSIGNED QUADWORD l s | No exact equivalent 3
    TEXT m CHARACTERS | X(m)
    UNSPECIFIED m BYTES | X(m)
    VARYING STRING m CHARACTERS | No equivalent 1
    VIRTUAL FIELD | Ignored 4
    SIGNED WORD l s | S9(4) COMP
    UNSIGNED WORD l s | No exact equivalent 3
    POINTER | POINTER
    SEGMENTED STRING | No equivalent 1
    ZONED | No equivalent 1

    1COBOL has no equivalent for this data type. A warning diagnostic will be issued for such an item that is part of a record description entry. The compiler will treat that item as if it had been specified as an alphanumeric data item that occupies that same number of bytes.
    2COBOL has no exact equivalent for this data type. A warning diagnostic will be issued for such an item that is part of a record description entry. The compiler will treat that item as if it had been specified as PIC S9(11)V9(7) COMP. (This gives the item units of seconds.)
    3COBOL has no exact equivalent for this data type. A warning diagnostic will be issued for such an item that is part of a record description entry. The compiler will treat that item as if it had been specified as the corresponding unsigned COMP data type.
    4The Compaq COBOL compiler ignores this data item and all its phrases.

    > l The total number of digits in the item.
    > s The decimal offset to l.

    The method for describing the assumed decimal point is different in the two products. In a COBOL picture, the decimal position is directly indicated by the symbol V or implied by the symbol P. In CDO, scaled numbers are specified by two integers: (1) the first integer represents the total number of decimal digits that the item represents, and (2) the second integer represents the decimal offset to the first integer. These are indicated in Table 8-1 by l and s, respectively.
    For example, the COBOL data item described by PIC 9(4)V99 is equivalent to the CDO entry UNSIGNED NUMERIC 6 DIGITS SCALE -2. Similarly, the CDO entry SIGNED NUMERIC LEFT SEPARATE NUMERIC 6 DIGITS SCALE 2 is equivalent to the COBOL description PIC S9(6)PP SIGN IS LEADING SEPARATE. You can also represent digits to the right of the decimal point in CDO with the FRACTIONS phrase. For example, instead of UNSIGNED NUMERIC 6 DIGITS SCALE -2, you can also use UNSIGNED NUMERIC 6 DIGITS 2 FRACTIONS.
13. One of the primary goals of Oracle CDD/Repository is to describe data in such a way that data definitions can be shared among many different processors. Many languages have different semantic interpretations for the same physical data. Record descriptions in Oracle CDD/Repository must be able to describe the physical characteristics of data unambiguously. In other words, the logical view of the data must be separated from the physical description if different processors are to access the same record description.
    Compaq COBOL expects numeric literals and PICTURE character-strings to be obtained from Oracle CDD/Repository in standard representation. Whether or not a particular COBOL source program uses the DECIMAL-POINT IS COMMA clause or the CURRENCY SIGN clause in the SPECIAL-NAMES paragraph, the record description that was stored in Oracle CDD/Repository must have used the period (.) to represent the decimal point in numeric literals and PICTURE character-strings, the comma (,) to represent the comma in PICTURE character-strings, and the currency symbol ($) to represent the currency symbol in PICTURE character-strings.
    When the COBOL source program contains the DECIMAL-POINT IS COMMA clause, the Compaq COBOL compiler substitutes commas for decimal points in numeric literals and PICTURE character-strings obtained from Oracle CDD/Repository. It substitutes decimal points for commas in PICTURE character-strings obtained from Oracle CDD/Repository.
    When the COBOL source program contains the CURRENCY SIGN clause, the Compaq COBOL compiler substitutes the currency symbol for the currency sign in PICTURE character-strings obtained from Oracle CDD/Repository. <>

Previous | Next | Contents | Index