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.

Start of change 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'. End of change

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

Start of change 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' End of change 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. End of change

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

Start of change 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. End of change

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 Start of change , and represents a UTF-8 character when used in a context that requires a UTF-8 character End of change . 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 Start of change , a DBCS literal, a national literal, or a UTF-8 literal End of change .

ALL literal

literal can be an alphanumeric literal, a DBCS literal, a national literal, Start of change

a UTF-8 literal, End of change

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 Start of change or UTF-8 End of change 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 Start of change or UTF-8 End of change .)

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.