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.
is an alphabetic or alphanumeric argument at least one character in
- The type of this function is alphanumeric.
- 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.
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").
MOVE FUNCTION UPPER-CASE (STR) TO UC-STR.
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.
FROM FUNCTION UPPER-CASE(NAME-FIELD).
The VARIANCE function returns a numeric value that approximates the
variance of its arguments.
is an integer or numeric argument.
- The type of this function is numeric.
- 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.)
- If the argument series consists of only one value, the returned
value is 0.
The value returned and stored in RSULT is 0, because there is only one
COMPUTE RSULT = FUNCTION VARIANCE (A).
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
COMPUTE RSULT = FUNCTION VARIANCE (A, B, C).
The WHEN-COMPILED function returns the date and time the program was
- The type of this function is alphanumeric.
- 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
- 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.
- The contents of the character positions returned, numbered from
left to right, are as follows:
Four numeric digits of the year in the Gregorian calendar.
Two numeric digits of the month of the year, in the range 01 through 12.
Two numeric digits of the day of the month, in the range 01 through 31.
Two numeric digits of the hours past midnight, in the range 00 through
Two numeric digits of the minutes past the hour, in the range 00
Two numeric digits of the seconds past the minute, in the range 00
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
The value 00000. (Reserved for future use.)
The value returned and stored in VERSION-STAMP (an alphanumeric data
item) is the date and time of the program's compilation.
MOVE FUNCTION WHEN-COMPILED TO VERSION-STAMP.
This is a sample value returned by the WHEN-COMPILED function. Reading
from left to right, it shows
199701101652313200000 (Tru64 UNIX and
199701101652310000000 (Windows NT systems)
- 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
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:
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
YEAR-TO-YYYY ( arg-1 [ arg-2 ] )
is a nonnegative integer between 0 and 99.
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.
- The type of this function is integer.
- 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))
return (arg-1 + 100 * int(max-year / 100) - 1)
YEAR-TO-YYYY implements a sliding window algorithm. To use it for a
fixed window, you can specify arg-2 as follows:
IF FUNCTION YEAR-TO-YYYY (80, 50 ) = 1980
IF FUNCTION YEAR-TO-YYYY (80, 100 ) = 2080
IF FUNCTION YEAR-TO-YYYY (80, -100 ) = 1880
(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 Text Manipulation
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
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:
- A literal, including the opening and closing quotation marks for
- A hexadecimal literal, including the opening and closing delimiters
- A separator other than:
A pseudo-text delimiter
The opening and closing quotation marks of a nonnumeric literal
- Any other sequence of contiguous characters, bounded by separators,
These examples show how the compiler interprets COBOL text in terms of
text-words. The rule letters refer to the text-word definition rules.
One text-word (Rule 4).
MOVE ITEMA TO ITEMB
MOVE ITEMA TO ITEMB.
Five text-words. The separator period is a text-word (Rule 3).
Nine text-words. Each parenthesis is a separator, and therefore a
text-word. The nine text-words are PIC, S9, (, 4, ), V9, (, 6, and ).
One text-word (Rule 1).
One text-word (Rule 2).
Two text-words. ITEMA and the separator period are text words.
Two text-words. The pseudo-text delimiters are not text-words (Rule 3).
However, the separator period is a text-word.
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.
The COPY statement includes text in a COBOL program.
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.)
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.)
are text-matching arguments that the compiler compares against
text-words in the library text.
are replacement items that the compiler inserts into the source program.
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.) <>
- 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.
- On OpenVMS, a Format 2 COPY statement can appear only in the File,
Working-Storage, or Linkage Sections. <>
- A space must precede the word COPY.
- The COPY statement must be terminated by the separator period.
- pseudo-text-1 must contain at least one text-word.
- pseudo-text-2 can contain zero, one, or more text-words.
- word-1 or word-2 can be any COBOL word.
- pseudo-text-1 must not consist entirely of a separator
comma or a separator semicolon.
- 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. <>
- 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. <>
- When only text-name is used, it identifies a file that
contains library text.
- 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.
- On Tru64 UNIX and Windows NT, the COPY statement references source
text from a directory containing library files or from a COBOL library
Format 2 (OpenVMS)
- record-name refers to a record description stored in
- 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. <>
- On OpenVMS, the COPY statement references source text from an
OpenVMS Librarian file, a COBOL library file, or the
- The compiler evaluates the COBOL source program after processing
all COPY statements.
- The COPY statement does not change the original source program text
- 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).
- If there is no REPLACING phrase, the compiler copies the source
text without modification.
- 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.
- For the purposes of matching, the compiler treats each
text-matching argument as pseudo-text that contains
identifier-1, word-1, or literal-1.
- 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.
- 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
In the matching operation, the compiler treats each
occurrence or combination of the following items in source text as a
- Separator comma
- Separator semicolon
- A sequence of one or more separator spaces
- A blank line
- A comment line
- 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.
- 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.
- 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
- 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
- The rules for Reference Format determine the sequence of text-words
in the source text and the text-matching arguments.
- 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.)
- 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
- 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
- The replacement item in the REPLACING phrase must not insert a COPY
statement into the source text.
- The compiler cannot determine the syntactic correctness of source
text, or the source program, until all COPY statements are processed.
- 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.
- 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
- 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.
- 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.)
- 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.
- 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.
- If there is a library-name phrase, text-name is
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.<>
- 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
- The COBOL command-line qualifier /INCLUDE (or
) can be used at compile time to set up a search list for the COPY
command. Assume that the following conditions are all true:
Then the compiler searches for the text-name file in the
- library-name is not used.
- text-name does not include a directory specification.
- /INCLUDE is specified.
- The current working directory when the compiler is invoked
- The directory specified after /INCLUDE (or
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
The first file encountered that matches the
text-name terminates the search.
On Tru64 UNIX and Windows
NT, /INCLUDE (or
) can be used to set up a search list for a text-name without
a directory specification only if library-name is not
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.
specified with /INCLUDE can be relative or absolute directory
specifications, logical names on OpenVMS, or environment variables on
Windows NT or Tru64 UNIX.
- 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.
- 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
- The default file type for text-name, when
text-name is f-name, is LIB. For example, COPY
CUSTFILE becomes COPY CUSTFILE.LIB.
- On OpenVMS, the default file type for library-name is TLB.
For example, COPY "ACCOUNTS" OF CUSTLIB becomes COPY "ACCOUNTS" OF
- On all platforms, file names must conform to the rules of the
operating system where compilation occurs. For example:
- On Windows NT systems:
COPY "empl_file" IN "C:\usr\proj\empl". <>
- On Tru64 UNIX systems:
COPY "empl_file" IN "/usr/proj/empl". <>
- On OpenVMS systems:
COPY "EMPL_FILE" IN "EMPLLIB.TLB". <>
- On Tru64 UNIX, when compiling in the Compaq FUSE environment
(using the compiler options
), certain COBOL programs may raise the following fatal
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.<>
- 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:
01 EXTRA-ITEM PIC X.
You should also insert an extra reference to a data item between
successive COPY statements in the PROCEDURE DIVISION as follows: