Concepts of the COBOL Language

This chapter explains the concepts of the COBOL language.

Character Set

The most basic and indivisible unit of the language is the character. The set of characters used to form COBOL character-strings and separators includes the letters of the alphabet, digits and special characters, and is defined below:

Character	Meaning
0 to 9	Digits
A to Z	Upper-case letters
a to z	Lower-case letters
	Space
+	Plus sign
-	Minus sign or hyphen
*	Asterisk
/	Oblique stroke/slash
=	Equal sign
$	Dollar sign
.	Period or decimal point
,	Comma or decimal point
;	Semicolon
"	Quotation mark
'	Apostrophe
(	Left parenthesis
)	Right parenthesis
>	Greater than symbol
<	Less than symbol
:	Colon
&	Ampersand
_	Underscore

Lower-case letters can be used in character strings and text words; except when used in nonnumeric literals and except for some picture symbols, each lower-case letter is equivalent to the corresponding upper-case letter.

This COBOL implementation is restricted to the above character set, but the content of nonnumeric literals, comment lines, comment entries and data can include any of the characters available under the character encoding scheme used for the COBOL compilation group. (See the topic Character Sets and Collating Sequences.)

Language Structure

The individual characters of the language are concatenated to form character-strings and separators. A separator can be concatenated with another separator or with a character-string. A character-string can be concatenated only with a separator. The concatenation of character-strings and separators forms your source text.

Separators

A separator is a string of one or more punctuation characters. The rules for formation of separators are:

1. The punctuation character space is a separator. Wherever a space is used as a separator or as part of a separator, more than one space can be used. All spaces immediately following the separators comma, semicolon, or period are considered part of that separator and are not considered to be the separator space.
2. Except when the comma is used in a PICTURE character-string, the punctuation characters comma and semicolon, immediately followed by a space, are separators that can be used anywhere the separator space is used.
3. The punctuation character period, when followed by a space, is a separator. It must be used only to indicate the end of a sentence, or as shown in formats.
4. The punctuation characters right and left parenthesis are separators. Except in pseudo-text, parentheses can appear only in balanced pairs of left and right parentheses delimiting subscripts,

   a list of function arguments, reference modifiers,
   

   arithmetic expressions, or conditions.

5. The opening delimiters and closing delimiters of literals are separators.

   Either an apostrophe or a quotation mark may be used as the quotation symbol character in opening and closing delimiters.

   The opening delimiters of literals are:

   • A quotation mark symbol
   • Any of the following pairs of contiguous characters: G", G' H", H', N" N', X" X'

   The closing delimiters of literals are:

   • A quotation mark when the opening delimiter uses a quotation mark
   • An apostrophe when the opening delimiter uses an apostrophe

   The opening delimiter must be immediately preceded by a space, left parenthesis or opening pseudo-text delimiter. The closing delimiter must be immediately followed by one of the separators space, comma, semicolon, period, right parenthesis or closing pseudo-text delimiter. Separators immediately preceding the opening delimiter are not part of the opening delimiter. Separators immediately following the closing delimiter are not part of the closing delimiter.

6. Pseudo-text delimiters are separators. An opening pseudo-text delimiter must be immediately preceded by a space; a closing pseudo-text delimiter must be immediately followed by one of the separators space, comma, semicolon, or period.

   The space immediately preceding the opening pseudo-text delimiter can be omitted.

   Pseudo-text delimiters can appear only in balanced pairs delimiting pseudo-text

   and verb-signatures
   

   . (See the topic Source Text Manipulation and the topic Method Interface Definition.)

7. The COBOL character colon, except as part of the invocation operator, is a separator and is required when shown in the general formats.
8. The separator space can immediately precede all separators except the following:
   1. As specified by reference format (see the section Reference Format in the chapter Language Fundamentals).
   2. The separator closing quotation mark. In this case, a preceding space is considered as part of the nonnumeric literal and not as a separator.
   3. The opening pseudo-text delimiter, where the preceding space is required.
9. The separator space can optionally immediately follow any separator except the opening quotation mark. In this case, a following space is considered as part of the nonnumeric literal and not as a separator.

Any punctuation character which appears as part of the specification of a PICTURE character-string (see the topic The PICTURE Clause) or numeric literal is not considered to be a punctuation character, but rather a symbol. PICTURE character-strings are delimited only by the separators space, comma, semicolon, or period.

The rules established for the formation of separators do not apply to the characters which comprise the contents of nonnumeric literals, comment-entries, or comment lines.

Character-strings

A character-string is a character or a sequence of contiguous characters forming a COBOL word, a literal, a PICTURE character-string, or a comment-entry. A character-string is delimited by separators.

COBOL Words

A COBOL word is a character-string of not more than 30 characters which forms a compiler-directive word, a context-sensitive word, user-defined word, a system-name, a reserved word, or an intrinsic-function-name. Each character of a COBOL word that is not a special character word is selected from the set of letters, digits, the hyphen

and the underscore
.

The hyphen

or the underscore

may not appear as the first or last character in such words. Each lower-case letter is considered to be equivalent to its corresponding upper-case letter.

The character-string may contain 31 characters.

User-Defined Words: A user-defined word is a COBOL word that must be supplied by the user to satisfy the format of a clause or statement.

The types of user-defined words are:

• alphabet-name
• class-name for object orientation
• class-name for truth value proposition
• condition-name
• constant-name
• data-name
• delegate-name
• enum-name
• file-name
• function-prototype-name
• index-name
• interface-name
• level-number
• library-name
• method-name
• mnemonic-name
• paragraph-name
• parameter-name
• program-name
• program-prototype-name
• property-name
• record-name
• report-name
• routine-name
• screen-name
• section-name
• segment-number
• split-key-name
• symbolic-character
• text-name
• typedef-name
• user-function-name
• valuetype-name

Within a given source element the following user-defined words are grouped into the following disjoint sets:

• alphabet-names
• class-names for object orientation
• class-names for truth value proposition
• condition-names,

  constant-names,

  data-names,

  property-names,

  record-names,

  split-key-names

  typedef-names

• delegate-name
• enum-name
• file-names
• function-prototype-names
• index-names
• interface-names
• library-names
• method-names
• mnemonic-names
• paragraph-names
• parameter-names
• program-names
• program-prototype-names
• report-names
• routine-names
• screen-names
• section-names
• symbolic-characters
• text-names.
• user-function-names
• valuetype-name

All user-defined words, except segment-numbers and level-numbers, can belong to one and only one of these disjoint sets. Furthermore, all user-defined words within a given disjoint set must be unique, except as specified in the section Uniqueness Of Reference.

With the exception of paragraph-name, section-name, level-number and segment-number, all user-defined words must contain at least one alphabetic character

or one occurrence of the hyphen character
.

Segment-numbers and level-numbers need not be unique; a given specification of a segment-number or level-number can be identical to any other segment-number or level-number and can even be identical to a paragraph-name or section-name.

The following user-defined words are externalized to the operating environment:

1. Program-names of programs that are not contained in other programs,

   class-names,

   function-prototype-names, interface-names,
   

   method-names,
   

   program-prototype-names, user-function-names
   .

2. Data-names, file-names, and record-names of items described with the EXTERNAL attribute.

If a literal is specified in place of or in addition to one of these names, the content of the literal is the name that is externalized to the operating environment in a case-sensitive manner. If no literal is specified, the externalized name is created by folding the name to upper case. The Compiler directive FOLD-CALL-NAME can be used to control the case of externalized class-names, interface-names and program-names. The F and U options of the Compiler directive OOCTRL can be used to control the case of externalized method-names. +F and -U cause method-names to be folded to lower case, which is the default.

Condition-name:	A condition-name is a name which is assigned to a specific value, set of values, or range of values, within a complete set of values that a data item can assume. The data item itself is called a conditional variable. Condition-names can be defined in the Data Division or in the Special-Names paragraph within the Environment Division where a condition-name must be assigned to one or both of the ON STATUS or OFF STATUS of the run-time switches. A condition-name is used only as follows: In the RERUN clause. In conditions as an abbreviation for a relation condition. This relation condition posits that the associated conditional variable is equal to one of the set of values to which that condition-name is assigned. In a SET statement indicating that the associated value is to be moved to the conditional variable.
Constant-name:	A constant-name is a name which is assigned as the name of a fixed value.
Mnemonic-name:	A mnemonic-name assigns a user-defined word to an implementor-name. These associations are established in the Special-Names paragraph of the Environment Division. (See the topic The Special-Names Paragraph .)
Paragraph-name:	A paragraph-name is a word that names a paragraph in the Procedure Division. Paragraph-names are equivalent if, and only if, they are composed of the same sequence of the same number of characters.
Section-name:	A section-name is a word that names a section in the Procedure Division. Section-names are equivalent if, and only if, they are composed of the same sequence of the same number of characters.
Other user-defined words:	See the Glossary for definitions of all other types of user-defined words.

System-names: A system-name is a COBOL word that is used to communicate with the operating environment.

System-names must contain at least one alphabetic character

or one occurrence of the hyphen character
.

There are three types of system-names:

• Computer-name
• Implementor-name
• Language-name.

Within a given implementation these three types of system-names form disjoint sets; a given system-name can belong to one and only one of them.

The system-names listed above are individually defined in the Glossary.

Intrinsic-function-names: An intrinsic-function-name is a word that is one of a specified list of words which can be used in COBOL source elements. The same word, with the exception of LENGTH, RANDOM and SUM, in a different context, can appear in a source element as a user-defined word or a system-name. (See the topic Definitions of Functions.)

Reserved words: A reserved word is a COBOL word that is one of a specified list of words which can be used in COBOL compilation groups, but which must not appear in the compilation groups as user-defined words or system-names. Reserved words can be used only as specified in the general formats. (See the topic Reserved Words.)

The types of reserved words are:

• Key words
• Optional words
• Special registers
• Figurative constants
• Special-character words
• Predefined object identifiers.

Key words:	A key word is a word whose presence is required when the format in which it appears is used in a compilation group. Within each format, such words are upper-case and underlined. Key words are of three types: Verbs such as ADD, READ, and ENTER Required words, which appear in statement and entry formats Words which have a specific functional meaning, such as NEGATIVE, SECTION, and so on.
Optional words:	Within each format, upper-case words that are not underlined are called optional words and can appear at the user's discretion. The presence or absence of an optional word does not alter the semantics of the COBOL source element in which it appears.
Special registers:	Certain words are used to name and reference special registers: special registers are certain storage areas created by your COBOL system, whose primary use is to store information produced in conjunction with the use of specific COBOL features. They are specified in the section Special Registers.
Figurative constants:	Certain reserved words are used to name and reference specific constant values. These reserved words are specified in the section Figurative Constant Values.
Special character words:	The arithmetic operators and relation characters are reserved words.
Predefined object identifiers:	Certain reserved words are used as predefined object identifiers. The predefined object identifiers are: SELF SUPER SELFCLASS

Context-sensitive Words: A context-sensitive word is a COBOL word that is reserved only in the general formats in which it is specified. The same word may also be used as an intrinsic-function-name, a user-defined word or a system-name. Context-sensitive words and the contexts in which they are reserved are specified in the section Context-sensitive Words Table in the appendix Reserved Words.

Literals

A literal is any of:

• A character-string whose value is implied by the ordered set of characters of which it is composed
• A reserved word which references a figurative constant
• A user-defined word which references a constant value

Every literal belongs to one of three types; nonnumeric, numeric and national.

Nonnumeric Literals

A nonnumeric literal is a character-string delimited at both ends by quotation marks

or apostrophes

and consisting of any allowable character in the computer's character set. Nonnumeric literals may be of 1 to 160 characters in length. Whether quotation marks

or apostrophes

are used as delimiters, the presence of that delimiter within a nonnumeric literal can be represented by two contiguous occurrences. The presence of the character that is not serving as the delimiter is represented by a single occurrence. The value of a nonnumeric literal in the run-time element is the string of characters itself, except:

• The delimiting quotation marks are excluded, and
• Each embedded pair of contiguous delimiter characters represents a single character.

All other punctuation characters are part of the value of the nonnumeric literal rather than separators; all nonnumeric literals are category alphanumeric. (See the topic The PICTURE Clause.)

In addition, hexadecimal binary values can be attributed to nonnumeric literals by expressing literals as: X"nn", where each n is a hexadecimal digit in the set 0 through 9, A through F; nn can be repeated up to 160 times, but the number of hexadecimal digits must be even.

The number of hexadecimal digits may be odd.

Numeric Literals

Numeric literals can be either fixed-point or floating-point numbers.

Fixed-Point Numeric Literals

A numeric literal is a character-string whose characters are selected from the digits 0 through 9, the plus sign, the minus sign, and the decimal point. This implementation allows for numeric literals of 1 to 18 digits in length. The rules for the formation of numeric literals are as follows:

• A literal must contain at least one digit.
• A literal must not contain more than one sign character. If a sign is used, it must appear as the leftmost character of the literal. If the literal is unsigned, the literal is positive.
• A literal must not contain more than one decimal point. The decimal point is treated as an assumed decimal point, and can appear anywhere within the literal except as the rightmost character. If the literal contains no decimal point, the literal is an integer.
• The value of a numeric literal is the algebraic quantity represented by the characters in the numeric literal. Every numeric literal is category numeric. (See the topic The PICTURE Clause.)

If a literal conforms to the rules for the formation of numeric literals, but is enclosed in quotation marks, it is a nonnumeric literal and is treated as such by your COBOL system.

The size of a numeric literal in standard data format characters is equal to the number of digits specified by the user.

In addition, hexadecimal binary values can be attributed to numeric literals by expressing literals as: H"nn", where each n is a hexadecimal digit in the set 0-9 A-F; nn can be repeated up to 8 times, but the number of hexadecimal digits must be even.

Floating-Point Numeric Literals

A floating-point literal is written in the form:

If you omit a sign, the system assumes a positive number.

The significand can contain between 1 and 16 digits. A decimal point must be included in the significand.

The exponent is represented by an E followed by an optional sign and one or two digits.

The magnitude of a floating-point literal value must fall between 0.54E-78 and 0.72E+76. For values outside this range, an error message is produced and the value is replaced by 0 or 0.72E+76 respectively. You must not use a floating-point literal when an integer literal is required.

Figurative Constant Values

Figurative constant values are generated by your COBOL system and referenced through the use of the reserved words given below. These words must not be bounded by quotation marks when used as figurative constants. The singular and plural forms of figurative constants are equivalent and can be used interchangeably.

The figurative constant values and the reserved words used to reference them are shown in Table 1.

Table 1: Figurative Constants and Their Reserved Words

Constant	Representation
ZERO ZEROS ZEROES	Represents the value "0", or one or more of the character "0" depending on the context.
SPACE SPACES	Represents one or more of the character space from the computer's character set.
HIGH-VALUE HIGH-VALUES	Represents one or more of the character that has the highest ordinal position in the program collating sequence. (x"FF" for the extended ASCII character set.)
LOW-VALUE LOW-VALUES	Represents one or more of the character that has the lowest ordinal position in the program collating sequence. (x"00" for the ASCII character set.)
QUOTE QUOTES	Represents one or more of the character """. The word QUOTE or QUOTES cannot be used in place of a quotation mark in a source program to bound a nonnumeric literal. Thus QUOTE ABD QUOTE is incorrect as a way of stating "ABD".
ALL literal	Represents one or more characters of the string of characters comprising the literal. The literal must be either a nonnumeric literal or a national literal or a figurative constant other than ALL literal. This nonnumeric literal and this national literal may be concatenation expressions. When a figurative constant is used, the word ALL is redundant and is used for readability only.
NULL NULLS	Represents one or more unset pointer or procedure-pointer values. A data item with USAGE POINTER or PROCEDURE-POINTER and with a value of NULL is guaranteed not to represent the address of any data item or procedure . The NULL value varies between environments and is generally consistent with the equivalent value used in non-COBOL languages for each environment.

When a figurative constant represents a string of one or more characters, the length of the string is determined by your COBOL system from context by applying the following rules in order:

1. When a figurative constant is specified in a concatenation expression, the length of the string is one character.
2. When a figurative constant is either specified in a VALUE clause, or associated with another data item, (for example, when the figurative constant is moved to or compared with another data item), the string of characters specified is repeated character by character on the right until the size of the resultant string is greater than or equal to the number of character positions in the associated data item. This resultant string is then truncated from the right until the number of character positions remaining is equal either to 1 or to the number of character positions in the associated data item, whichever is greater. This is done prior to and independent of the application of any JUSTIFIED clause that can be associated with the data item.
3. When a figurative constant is other than ALL literal, the length of the string is one character.
4. The length of the string is the length of the literal.

   Use of figurative constants in Format 3 DISPLAY statements has specific effects, described in the General Rules for that statement.

A figurative constant can be used wherever a literal appears in a format, except that whenever the literal is restricted to having only numeric characters in it, the only figurative constant permitted is ZERO (ZEROS, ZEROES).

When the figurative constants HIGH-VALUE(S) or LOW-VALUE(S) are used , the actual character associated with each figurative constant depends upon the program collating sequence specified. (See the topics The Object-Computer Paragraph and the The Special-Names Paragraph.)

Each reserved word that is used to reference a figurative constant value is a distinct character-string, with the exception of the construction "ALL literal" which is composed of two distinct character-strings.

The value associated with the QUOTE/QUOTES figurative constant is sensitive to the APOST and QUOTE directives.

The figurative constant ALL literal, when associated with a numeric or numeric edited item, and when its length is greater than one, is classed as an obsolete element in the ANSI'85 standard and is scheduled to be deleted from the next full revision of the ANSI Standard.

All dialects within this COBOL implementation fully support this obsolete ALL literal syntax. The FLAGSTD directive can be used to detect all occurrences of this syntax.

Although this obsolete ALL literal syntax is a part of the standard COBOL definition, this syntax is explicitly excluded from the X/Open COBOL language definitions and should not be used in a conforming X/Open COBOL source program.

Special Registers

Special registers are data items or transient values generated by your COBOL system and referenced through the use of their associated names or expressions (see Table 2). These special registers are subject to special rules of reference and have implicit data descriptions (PICTUREs), as individually described.

Table 2: Special Registers

Special Register Name or Expression	Implicit Data Description Picture	Usage
ADDRESS OF data-name-1	USAGE IS POINTER	The expression generates a pointer value representing the address of data-name-1. The expression is explicitly shown in the general format for statements in which it can be used. Data-name-1 must be a data item declared in the Linkage Section with a level number or 01 or 77 or must be declared anywhere in the Data Division and with any level number .
CURRENT-DATE 1	X(8)	The CURRENT-DATE special register contains the value of the current date (as supplied by the COBOL execution environment), in the form: MM/DD/YY where MM is the month number, DD is the day of the month, and YY is the year number (from 1900). CURRENT-DATE is valid only as the sending area of a MOVE statement.
DEBUG-ITEM	A group item of variable size	The DEBUG-ITEM special register provides information about the conditions that caused the execution of a Debugging Section. For further information see the section Debug Module.
LENGTH OF data-name-2 2	9(9)	The expression generates a value representing the current number of bytes of storage used by data-name-2. The expression can be used wherever a numeric data item can be used except as a subscript or a reference modifier. It can also be used to set the value of a level 78 item.
LINAGE-COUNTER		The LINAGE-COUNTER special register is generated by the presence of a LINAGE clause in a file description entry for a record sequential file. The implicit description is that of an unsigned integer whose size is equal to the size of integer-1 or the data item referenced by data-name-1 in the LINAGE clause.
RETURN-CODE 3	S9(4) COMP S9(9) COMP	The RETURN-CODE special register can: be set by a program, prior to the execution of a STOP RUN, EXIT PROGRAM or GOBACK statement, to pass a value to the calling run-time element (or the execution environment) be read, subsequent to a CALL to another COBOL program, to obtain the value of the RETURN-CODE special register set by that CALLed program. A program's RETURN-CODE special register is set to zero when that program is first entered. RETURN-CODE is valid as a data-name in a Procedure Division statement wherever an elementary data item can be referenced.
SHIFT-IN	X(1)	Used to switch the character representation from double-byte characters (DBCS) back to single-byte characters (SBCS) in environments where this is applicable.
SHIFT-OUT	X(1)	Used to switch the character representation from single-byte characters (SBCS) to double-byte characters (DBCS) in environments where this is applicable.
SORT-CONTROL	X(8)	Used only during sort and merge operations. You can reference it in the Procedure Division but it will contain spaces.
SORT-CORE-SIZE	S9(8) COMP	Used only during sort and merge operations. You can reference it in the Procedure Division but it will contain zeros.
SORT-FILE-SIZE	S9(8) COMP	Used only during sort and merge operations. You can reference it in the Procedure Division but it will contain zeros.
SORT-MESSAGE	X(8)	Used only during sort and merge operations. You can reference it in the Procedure Division but it will contain spaces.
SORT-MODE-SIZE	S9(5) COMP	Used only during sort and merge operations. You can reference it in the Procedure Division but it will contain zeros.
SORT-RETURN	S9(4) COMP	SORT-RETURN can be used to cause an abnormal termination of a SORT procedure. If a value of 16 is moved into this field, the SORT operation is terminated after the next RELEASE or RETURN.
TALLY	9(5) COMP	The TALLY special register contains information produced by the EXAMINE...TALLYING statement. It is valid as a data-name in a Procedure Division statement wherever an elementary data item can be referenced.
TIME-OF-DAY	9(6) DISPLAY	The TIME-OF-DAY special register contains the value of the current time of day (24-hour clock) (as supplied by the COBOL execution environment), in the form: hhmmss where hh =hour, mm=minutes, and ss=seconds. TIME-OF-DAY is valid only as the sending area of a MOVE statement.
WHEN-COMPILED	X(20)	The WHEN-COMPILED special register contains the time and date that the COBOL compilation group was submitted to your COBOL system, in the form: hh.mm.ssMMM DD, YYYY where hh=hours (24-hour clock), mm=minutes, ss=seconds, MMM=month name (first 3 characters), DD=day of month, and YYYY=year. WHEN-COMPILED is valid only as the sending area of a MOVE statement.
WHEN-COMPILED	X(20)	The WHEN-COMPILED special register contains the time and date that the COBOL compilation group was submitted to your COBOL system, in the form: MM/DD/YYhh.mm.ss where DD, hh, mm and ss are as above. YY=year in century and MM=month in year. WHEN-COMPILED is valid only as the sending area of a MOVE statement.
XML-CODE 4	S9(9) COMP	The XML-CODE special register is used to communicate status between the XML parser and the processing procedure identified in the XML PARSE statement. The XML parser sets XML-CODE for each event and at parser termination. You can reset XML-CODE in the processing procedure to -1 after a normal event, to indicate that the parser is to terminate with a user-initiated exception, which is not an EXCEPTION XML event, indicated by the returned XML-CODE value of -1.
XML-EVENT 5	X(30)	The XML-EVENT special register is used to communicate event information from the XML parser to the processing procedure that was identified in the XML PARSE statement. Before passing control to the processing procedure, the XML parser sets the XML-EVENT special register to the name of the XML event. XML-EVENT cannot be used as a receiving data item.
XML-NTEXT5		The XML-NTEXT special register is defined during XML parsing to contain document fragments that are USAGE NATIONAL. XML-NTEXT is an elementary national data item of the length of the contained XML document fragment. The length of XML-NTEXT varies dynamically at run time. When the operand of the XML PARSE statement is a national data item, and for the ATTRIBUTE-NATIONAL-CHARACTER and CONTENT-NATIONAL-CHARACTER events, the XML parser sets XML-NTEXT to the document fragment associated with an event before transferring control to the processing procedure. When XML-NTEXT is set, the XML-TEXT special register has a length of zero. At any given time, only one of the two special registers XML-NTEXT and XML-TEXT has a non-zero length. Use the LENGTH function to determine the number of national characters that XML-NTEXT contains. XML-NTEXT cannot be used as a receiving item.
XML-TEXT5		The XML-TEXT special register is defined during XML parsing to contain document fragments that are of class alphanumeric. XML-TEXT is an elementary alphanumeric data item of the length of the contained XML document fragment. The length of XML-TEXT varies dynamically at run time. When the operand of the XML PARSE statement is an alphanumeric data item, except for the ATTRIBUTE-NATIONAL-CHARACTER event and the CONTENT-NATIONAL-CHARACTER event, the parser sets XML-TEXT to the document fragment associated with an event before transferring control to the processing procedure. When XML-TEXT is set, the XML-NTEXT special register has a length of zero. At any given time, only one of the two special registers XML-NTEXT and XML-TEXT has a non-zero length. Use the LENGTH function or the LENGTH OF special register for XML-TEXT to determine the number of bytes that XML-TEXT contains. XML-TEXT cannot be used as a receiving item.

Footnotes:

1.

The format of the contents of the CURRENT-DATE special register is sensitive to the CURRENT-DATE directive.

2.

The LENGTH OF special register may be followed by an alphanumeric literal when using the Micro Focus dialect.

3.

The size of the RETURN-CODE special register is sensitive to the XOPEN and RTNCODE-SIZE directives.

4.

For a list of supported exception codes, see the topic XML-CODE Exception Codes.

5.

The contents of XML-TEXT and XML-NTEXT vary depending on the contents of XML-EVENT. See Table 3 for additional information.

Table 3: Contents of XML-EVENT and XML-NTEXT or XML-TEXT Special Registers

Contents of XML-EVENT	Contents of XML-TEXT or XML-NTEXT
ATTRIBUTE-CHARACTER	The single character corresponding with the predefined entity reference in the attribute value.
ATTRIBUTE-CHARACTERS	The value within quotes or apostrophes. This can be a sub-string of the attribute value if the value includes an entity reference.
ATTRIBUTE-NAME	The attribute name, the string to the left of =.
ATTRIBUTE-NATIONAL-CHARACTER	Regardless of the type of the XML document specified by identifier-1 in the XML PARSE statement, XML-TEXT is empty and XML-NTEXT contains the single national character corresponding with the (numeric) character reference.
COMMENT	The text of the comment between the opening character sequence "<!--" and the closing character sequence "-->".
CONTENT-CHARACTER	The single character corresponding to the predefined entity reference in the element content.
CONTENT-CHARACTERS	The element content between start and end tags. This can be a substring of the element content if the content contains an entity reference to another element.
CONTENT-NATIONAL-CHARACTER	Regardless of the type of the XML dcument specified by identifier-1 in the XML PARSE statement, XML-TEXT is empty and XML-NTEXT contains the single national character corresponding with the (numeric) character reference.6
DOCUMENT-TYPE-DECLARATION	The entire document type declaration including the opening and closing character sequences, "<!DOCTYPE" and ">".
ENCODING-DECLARATION	The value, between quotes or apostrophes, of the encoding declaration in the XML declaration.
END-OF-CDATA-SECTION	Always contains the string "]]>".
END-OF-DOCUMENT	Null, zero-length.
END-OF-ELEMENT	The name of the end element tag or empty element tag.
EXCEPTION	The part of the document successfully scanned, up to and including the point at which the exception was detected. 7 Special register XML-CODE contains the unique error code identifying the exception.8
PROCESSING-INSTRUCTION-DATA	The rest of the processing instruction, not including the chlosing sequence, "?>", but including trailing, and not leading, white space characters.
PROCESSING-INSTRUCTION-TARGET	The processing instruction target name, which occurs immediately after the processing instruction opening sequence, "<?".
STANDALONE-DECLARATION	The value, between quotes or apostrophes, of the standalone declaration in the XML declaration.
START-OF-CDATA-SECTION	Always contains the string "<![CDATA[".
START-OF-DOCUMENT	The entire document.
START-OF-ELEMENT	The name of the start element tag or empty element tag, also know as the element type.
UNKNOWN-REFERENCE-IN-CONTENT	The entity reference name, not including the "&" and ";" delimiters.
UNKNOWN-REFERENCE-IN-ATTRIBUTE	The entity reference name, not including the "&" and ";" delimeters.
VERSION-INFORMATION	The value, between quotes or apostrophes, of the version declaration in the XML declaration. This is always "1.0".

Footnotes:

6.

National characters with scalar values larger than 65,535 (NX"FFFF") are represented using two encoding units (a surrogate pair). You should ensure that operations on the content of XML-NTEXT do not split the pair of encoding units that together form a graphic character, thereby forming invalid data.

7.

Exceptions for encoding conflicts are signaled before parsing begins. For these exceptions, XML-TEXT is either zero in length or contains just the encoding delcaration value from the document.

8.

See the IBM Enterprise COBOL Programming Guide for information on XML exception codes. Any exception not documented in the IBM Enterprise COBOL Programming Guide is returned with a value of 201.

Predefined Object Identifiers

The predefined object identifiers are:

Predefined Object Identifier	Usage
SELF	References the object on which the current method is executing. May be used in the Procedure Division of a method. References the object that was used to invoke the method in which SELF appears. If SELF is specified for a method invocation, the search for the method includes all methods declared for the object.
SELFCLASS	References the object that is the class object of the current object (SELF). If SELF is itself a class object, SELFCLASS is the system class BEHAVIOR. The class object BEHAVIOR terminates this self-reference. (i.e., If SELF is the BEHAVIOR of class, so is SELFCLASS.)
SUPER	References the object on which the current method is executing. May be used in the Procedure Division of a method. May be the object used to invoke a method with the INVOKE statement or inline invocation. References the object that was used to invoke the method in which SELF appears. If SUPER is specified for a method invocation, the search for the method ignores all the methods defined in the same class as the executing method.
NULL	References the null object reference value, which is a unique value that is guaranteed to never reference an object. NULL is implicitly described as class object and category object reference, and is not a universal object reference. NULL must not be specified as a receiving operand.

PICTURE Character-Strings

A PICTURE character-string consists of certain combinations of characters in the COBOL character set, used as symbols. See the topic The PICTURE Clause for the PICTURE character-string and for the rules that govern its use.

Any punctuation character that appears as part of the specification of a PICTURE character-string is not considered to be a punctuation character, but a symbol used in the specification of that PICTURE character-string.

Comment-entries

A comment-entry is an entry in the Identification Division that can be any combination of characters from the computer's character set. A comment-entry is for documentary purposes only, may extend over more than one line and is terminated upon encountering a division, section or paragraph name that is a reserved word

or encountering any character

in area A of a line. The continuation of a comment-entry by the use of the hyphen in the indicator area is not permitted.

Formats and Rules

General Format

A general format is the specific arrangement of the elements of a clause or a statement. Throughout this document a format is shown adjacent to information defining the clause or statement. When more than one specific arrangement is permitted, the general format is separated into numbered formats. Clauses must be written in the sequence given in the general formats. (Clauses that are optional must appear in the sequence shown if they are used.) In certain cases, stated explicitly in the rules associated with a given format, the clauses can appear in sequences other than that shown. Applications, requirements or restrictions are shown as rules.

Syntax Rules

Syntax rules are those rules that define or clarify the order in which words or elements are arranged to form larger elements, such as phrases, clauses, or statements. Syntax rules also impose restrictions on individual words or elements.

These rules are used to define or clarify how the statement must be written; that is, the order of the elements of the statement and restrictions on what each element may represent.

General Rules

General rules are those rules that define or clarify the meaning or relationship of meanings of an element or set of elements. They are used to define or clarify the semantics of the statement and the effect that it has on either execution or on the way intermediate code is produced.

Elements

Elements which make up a clause or a statement consist of upper-case words, lower-case words, level-numbers, brackets, braces, connectives and special characters.

Concept of Computer-independent Data Description

To make data as computer-independent as possible, the characteristics or properties of the data are described in relation to a standard data format rather than to an equipment-oriented format. This standard data format is oriented to general data processing applications and uses the decimal system to represent numbers (regardless of the radix used by the computer) and the remaining characters in the COBOL character set to describe nonnumeric data items.

Concept of Levels

A level concept or hierarchy is inherent in the structure of a logical data record. This concept arises from the need to specify subdivisions of a record for the purpose of data reference. Once a subdivision has been specified, it can be further subdivided to permit more detailed data referral.

The most basic subdivisions of a record, that is, those not further subdivided, are called elementary items; consequently, a record is said to consist of a sequence of elementary items, or the record itself can be an elementary item.

In order to refer to a set of elementary items, the elementary items are combined into groups. Each group consists of a named sequence of one or more elementary items. Groups, in turn, can be combined into groups of two or more groups, and so on. Thus, an elementary item can belong to more than one group.

Level-Numbers

A system of level-numbers shows the organization of elementary items and group items. Since records are the most inclusive data items, level-numbers for records start at 01. Less inclusive data items are assigned higher (not necessarily successive) level-numbers not greater in value than 49. A maximum of 49 levels in a record is allowed. There are special level-numbers, 66, 77

, 78

and 88 which are exceptions to this rule (see below). Separate entries are written for each level-number used.

A group includes all group and elementary items following it until a level-number less than or equal to the level-number of that group is encountered. All items which are immediately subordinate to a given group item should be described using identical level-numbers greater than the level-number used to describe that group item

; this rule is not insisted upon
.

Example

Correct	Incorrect but Permitted
01 A. 05 C-1. 10 D PICTURE X. 10 E PICTURE X. 05 C-2.	01 A. 05 C-1. 10 D PICTURE X. 10 E PICTURE X. 04 C-2.

Four types of entries exist for which there is no true concept of level. These are:

1. Entries that specify elementary items or groups introduced by a RENAMES clause.
2. Entries that specify noncontiguous working storage and linkage data items.
3. Entries that specify condition-names.
4. Entries that specify constant-names.

Entries describing items by means of RENAMES clauses for the purpose of regrouping data items have been assigned the special level-number 66.

Entries that specify noncontiguous data items, which are not subdivisions of other items, and are not themselves subdivided, have been assigned the special level-number 77.

Entries that specify condition-names, to be associated with particular values of a conditional variable, have been assigned the special level-number 88.

Entries that specify constant-names, to be associated with the value of a particular literal, have been assigned the special level-number 78.

Figure 2: Example of Level-numbers Representing a Data Hierarchy

Note that indentation of COBOL source code is a readability convention only and is not part of the language.

Elementary items are by definition those items without any subordinate entries (entries without numerically greater level-numbers) following, and must have a storage definition associated with them (see the topics The PICTURE Clause and the The USAGE Clause).

Note that only elementary items (marked with an asterisk, "*", above) and FILLER items (marked with a "#" sign above) have storage explicitly reserved for them (in accordance with the associated PICTURE clause); non-elementary items have implicit storage associated with them of size determined by their subordinate items plus any FILLER bytes needed for synchronization (see the topic The SYNCHRONIZED Clause).

Level-numbers need not be consecutively ascending or descending as shown above for clarity; thus, the next subordinate level after 01 could be 05, and the next level 10, and so on.

The above data descriptions would produce storage allocation in the following manner:

Figure 3: Data Record Storage Allocation

where:

Class and Category of Data

Every elementary data item, every literal, and every function has a class and a category. The class and category of a data item are defined by its picture character string, by the BLANK WHEN ZERO clause, or by its usage; the class and category of a literal are defined in the section Literals.

and the class and category of an intrinsic function are specified by the definition of that intrinsic function (see the topic Intrinsic Functions)
.

The category of a group item is alphanumeric.

The following table depicts the relationship of categories to classes of data for elementary items.

Algebraic Signs

Algebraic signs fall into two categories:

1. Operational signs, which are associated with signed numeric data items and signed numeric literals to indicate their algebraic properties.
2. Editing signs, which appear on edited reports to identify the sign of the item.

The SIGN clause permits you to state explicitly the location of the operational sign. The clause is optional; if it is not used, operational signs are represented as described in the section Selection Of Character Representation And Radix.

Editing signs are inserted into a data item through the use of the sign control symbols of the PICTURE clause.

Standard Alignment Rules

The standard rules for positioning data within an elementary item depend on the category of the receiving item. These rules are:

1. If the receiving data item is described as numeric:
   1. The data is aligned by decimal point and is moved to the receiving character positions with zero fill or truncation on either end as required
   2. When an assumed decimal point is not explicitly specified, the data item is treated as if it had an assumed decimal point immediately following its rightmost character and is aligned as in paragraph a. above.
2. If the receiving data item is a numeric edited data item, the data moved to the edited item is aligned by decimal point with zero fill or truncation at either end as required within the receiving character positions of the data item, except where editing requirements cause replacement of the leading zeros.
3. If the receiving data item is alphanumeric (other than a numeric edited data item), alphanumeric edited or alphabetic, the sending data is moved to the receiving character position and aligned at the leftmost character position in the data item with space fill or truncation to the right, as required.
4. If the receiving data item is external floating-point, the leftmost non-zero digit, if one exists, is aligned on the leftmost digit position: the exponent is adjusted accordingly.

If the JUSTIFIED clause is specified for the receiving item, these standard rules are modified as described in the section The JUSTIFIED Clause in the chapter Data Division - File and Data Description.

Item Alignment for Increased Object-code Efficiency

Some computer memories are organized so that natural addressing boundaries exist in the computer memory (for example, word boundaries, half-word boundaries, byte boundaries). The way in which data is stored need not respect these natural boundaries.

However, certain uses of data (for example, in arithmetic operations or in subscripting) can be facilitated if the data is stored so as to be aligned on these boundaries. Specifically, additional machine operations in the run-time element can be repeated for the accessing and storage of data if portions of two or more data items appear between adjacent natural boundaries, or if certain natural boundaries divide a single data item.

Data items which are aligned on these natural boundaries in such a way as to avoid additional machine operations are defined to be synchronized. A synchronized item is assumed to be introduced and carried in that form; conversion to synchronized form occurs only during the execution of a statement (other than READ or WRITE) which stores data in the item.

Synchronization can be accomplished in two ways:

1. By use of the SYNCHRONIZED clause
2. By organizing the data suitably on the appropriate natural boundaries without the use of the SYNCHRONIZED clause.

By use of the SYNCHRONIZED clause, the use of special types of alignment within a group can affect the results of statements in which the group is used as an operand. The effect of the implicit FILLER and the semantics of any statement referencing these groups is described later in this chapter.

Selection of Character Representation and Radix

The value of a numeric item (defined as numeric by its PICTURE, see the topic The PICTURE Clause) can be represented in the computer's storage in either binary or decimal form depending on the USAGE clause of the declaration (see the topic The USAGE Clause). These numeric formats are:

• DISPLAY
• COMPUTATIONAL, COMP,

  BINARY,
  

  COMPUTATIONAL-4 or COMP-4
  

• COMPUTATIONAL-3, COMP-3 or
  

  PACKED-DECIMAL
  

• COMPUTATIONAL-5, COMP-5,
• COMPUTATIONAL-X or COMP-X
• COMPUTATIONAL-1, COMPUTATIONAL-2
  ,

  FLOAT-SHORT or FLOAT-LONG
  

• POINTER
• PROCEDURE-POINTER

An alphanumeric function is always represented in the standard data format. Its size is determined by the definition of the function.

The representation of integer and numeric functions is as follows:

• COMP-2 if the function is trigonometric or if one or more function arguments are COMP-2 and the function is not defined as returning an integer.
• Otherwise, as PIC SV9(39)ES9(4). The exponent is S9(4) COMP and so has a range of approximately +/-32k.

Integer and numeric functions can be used only in arithmetic expressions, and represent the value resulting from the evaluation of the function without the restriction on composite of operands and/or receiving data items.

When a computer provides more than one means of representing data, the standard data format must be used for data items

other than integer and numeric functions,

if not otherwise specified by the data description.

DISPLAY Format

The COBOL digit characters from 0 through 9 that represent the number value are held in radix 10, one digit character per byte of computer storage. This is the standard data format of the COBOL language. If the data item is signed and the sign is not specified as SEPARATE (see the topic The SIGN Clause and the rules for the NUMERIC SIGN clause in the topic The Special-Names Paragraph) the numeric sign is incorporated into either the leading or trailing digit, according to the LEADING or TRAILING phrase in the SIGN clause. Signed data is incorporated into the requisite digit as shown in Table 4 below. (Effectively, bit 6 (hexadecimal value "40" ) of the character is set from 0 to 1 if the number has a negative value.) If the data item is signed and the sign is specified as SEPARATE, then the sign is held as a separate single COBOL character, additional to the digits, either plus (+) or minus (-) as necessary. If the data item is signed and no SIGN clause applies, the numeric sign is incorporated into the trailing digit, unless the NUMERIC SIGN clause is specified in the Special-Names paragraph. If the SIGN clause is specified in a data description entry, the NUMERIC SIGN clause, if specified, is ignored for that entry.

In the following table, the numbers in brackets represent the hexadecimal encoding for the COBOL character. On some systems, the encoding can be varied by the CHARSET and SIGN Compiler directives.