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), one or more occurrences of the alphanumeric character zero, or the Boolean value B"0", 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'3000'). 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.

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 indicated by the locale. For more information about locales, see Locale considerations.

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 can be used in a context that requires a national literal only when the NCOLLSEQ(BIN) compiler option is in effect.

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 or ASCII 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 indicated by the locale. For more information about locales, see Locale considerations.

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 can be used in a context that requires a national literal only when the NCOLLSEQ(BIN) compiler option is in effect.

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. The national character value of quotation mark is NX'2200'. The national character value of apostrophe is NX'2700'.

QUOTE and QUOTES cannot be used in place of a quotation mark or an apostrophe to enclose an alphanumeric literal.

ALL literal
literal can be an alphanumeric literal, a DBCS literal, a national 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, 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 character only when implicit conversion of alphanumeric to national characters is defined. (It can be used, for example, in a MOVE statement where the receiving item is of class national because implicit conversion is defined when the sending item is alphanumeric and the receiving item is national .)

You cannot specify the SYMBOLIC CHARACTERS clause if a multibyte codepage is indicated by the compile-time locale setting. For more information about locales, see Locale considerations.

NULL, NULLS
Represents a value used to indicate that data items defined with USAGE POINTER, USAGE PROCEDURE-POINTER, USAGE FUNCTION-POINTER, 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 where the expression is an argument to a function. The figurative constant ZERO can be used as a Boolean literal.

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, STOP, STRING, or UNSTRING statement), the length of the character-string is one character.