Figurative constants
Figurative constants are reserved words that name and refer to specific constant values. The reserved words for figurative constants and their meanings are listed in this section.
- ZERO, ZEROS, ZEROES
- Represents the
numeric value zero (0) or one or more occurrences of the character zero, depending on context.
When the figurative constant ZERO, ZEROS, or ZEROES is used in a context that requires an alphanumeric character, an alphanumeric character zero is used. When the context requires a national character zero, a national character zero is used (value NX'0030'). When the context cannot be determined, an alphanumeric character zero is used.
- SPACE, SPACES
- Represents one
or more blanks or spaces. SPACE is treated as an alphanumeric literal
when used in a context that requires an alphanumeric character, as
a DBCS literal when used in a context that requires a DBCS character,
as a national literal when used in a context that requires a national
character.
The EBCDIC DBCS space character has the value X'4040', the national space character has the value NX'0020', and the UTF-8 space character has the value UX'20'.
- HIGH-VALUE, HIGH-VALUES
-
Represents one or more occurrences of the
character that has the highest ordinal position in the collating sequence used.
HIGH-VALUE is treated as an alphanumeric literal in a context that requires an alphanumeric character. For alphanumeric data with the EBCDIC collating sequence, the value is X'FF'. For other alphanumeric data, the value depends on the collating sequence in effect.
HIGH-VALUE is treated as a national literal when used in a context that requires a national literal. The value is national character NX'FFFF'.
HIGH-VALUE is treated as a UTF-8 literal when used in a context that requires a UTF-8 literal. The value is UTF-8 character UX'F48FBFBF' corresponding to Unicode code point U+10FFFF, except when HIGH-VALUE is used in a move or compare operation with a fixed byte-length UTF-8 data item that has a length that is not a multiple of 4 bytes. In that case, when HIGH-VALUE is moved into or compared against the final 3, 2 or 1 byte(s) of the UTF-8 data item, the value of HIGH-VALUE is UX'EFBFBF' (U+FFFF), UX'DFBF' (U+07FF), and UX'7F' (U+007F), respectively.
When the context cannot be determined, an alphanumeric context is assumed and the value X'FF' is used.
Usage note: You should not use HIGH-VALUE (or a value assigned from HIGH-VALUE) in a way that results in conversion between one data representation and another. X'FF' does not represent a valid EBCDIC character, and NX'FFFF' does not represent a valid national character. Conversion of either the alphanumeric or the national HIGH-VALUE representation to another representation results in a substitution character. For example, conversion of X'FF' to UTF-16 would give a substitution character, not NX'FFFF'.
- LOW-VALUE, LOW-VALUES
- Represents
one or more occurrences of the character that has the lowest ordinal
position in the collating sequence used.
LOW-VALUE is treated as an alphanumeric literal in a context that requires an alphanumeric character. For alphanumeric data with the EBCDIC collating sequence, the value is X'00'. For other alphanumeric data, the value depends on the collating sequence in effect.
LOW-VALUE is treated as a national literal when used in a context that requires a national literal. The value is national character NX'0000'.
LOW-VALUE is treated as a UTF-8 literal when used in a context that requires a UTF-8 literal. The value is UTF-8 character UX'00' corresponding to Unicode code point U+0000.
When the context cannot be determined, an alphanumeric context is assumed and the value X'00' is used.
- QUOTE, QUOTES
- Represents one
or more occurrences of:
- The quotation mark character (
"
), if the QUOTE compiler option is in effect - The apostrophe character (
'
), if the APOST compiler option is in effect
QUOTE or QUOTES represents an alphanumeric character when used in a context that requires an alphanumeric character, represents a national character when used in a context that requires a national character, and represents a UTF-8 character when used in a context that requires a UTF-8 character. The national character value of quotation mark is NX'0022'. The national character value of apostrophe is NX'0027'. The UTF-8 character value of quotation mark is UX'22'. The UTF-8 character value of apostrophe is UX'27'.
QUOTE and QUOTES cannot be used in place of a quotation mark or an apostrophe to enclose an alphanumeric literal, a DBCS literal, a national literal, or a UTF-8 literal.
- The quotation mark character (
- ALL literal
- literal can
be an alphanumeric literal, a DBCS literal, a national literal, a UTF-8 literal, or a figurative constant other than
the ALL literal.
When literal is not a figurative constant, ALL literal represents one or more occurrences of the string of characters that compose the literal.
When literal is a figurative constant, the word ALL has no meaning and is used only for readability.
The figurative constant ALL literal must not be used with the CALL, INSPECT, INVOKE, STOP, or STRING statements.
- symbolic-character
- Represents
one or more of the characters specified as a value of the symbolic-character in
the SYMBOLIC CHARACTERS clause of the SPECIAL-NAMES paragraph.
symbolic-character always represents an alphanumeric character; it can be used in a context that requires a national or UTF-8 character only when implicit conversion of alphanumeric to national or UTF-8 characters is defined. (It can be used, for example, in a MOVE statement where the receiving item is of class national or UTF-8 because implicit conversion is defined when the sending item is alphanumeric and the receiving item is national or UTF-8.)
- NULL, NULLS
- Represents a value used to indicate that data items defined with USAGE POINTER, USAGE PROCEDURE-POINTER, USAGE FUNCTION-POINTER, USAGE OBJECT REFERENCE, or the ADDRESS OF special register do not contain a valid address. NULL can be used only where explicitly allowed in the syntax formats. NULL has the value zero.
The singular and plural forms of NULL, ZERO, SPACE,
HIGH-VALUE, LOW-VALUE, and QUOTE can be used interchangeably. For
example, if DATA-NAME-1
is a five-character data
item, each of the following statements moves five spaces to DATA-NAME-1
:
MOVE SPACE TO DATA-NAME-1
MOVE SPACES TO DATA-NAME-1
MOVE ALL SPACES TO DATA-NAME-1
When the rules of COBOL permit any one spelling of a figurative constant name, any alternative spelling of that figurative constant name can be specified.
You can use a figurative constant wherever literal appears in a syntax diagram, except where explicitly prohibited. When a numeric literal appears in a syntax diagram, only the figurative constant ZERO (or ZEROS or ZEROES) can be used. Figurative constants are not allowed as function arguments except in an arithmetic expression, where the expression is an argument to a function.
The length of a figurative constant depends on the context of its use. The following rules apply:
- When a figurative constant is specified in a VALUE clause or associated with a data item (for example, when it is moved to or compared with another item), the length of the figurative constant character-string is equal to 1 or the number of character positions in the associated data item, whichever is greater.
- When a figurative constant, other than the ALL literal, is not associated with another data item (for example, in a CALL, INVOKE, STOP, STRING, or UNSTRING statement), the length of the character-string is one character.