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 1). These special registers are subject to special rules of reference and have implicit data descriptions (PICTUREs), as individually described.

Table 1. Special Registers
Special Register Name or Expression Implicit Data Description Picture Usage
VSC2MF 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

MF or must be declared anywhere in the Data Division and with any level number

.
OSVS 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.
VSC2MF 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.

MF 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.
OSVSVSC2MF RETURN-CODE 3 S9(4) COMP

XOPEN 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.
VSC2 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.
VSC2 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.
VSC2 SORT-CONTROL X(8) Used only during sort and merge operations. You can reference it in the Procedure Division but it will contain spaces.
OSVSVSC2  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.
OSVSVSC2  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.
OSVSVSC2  SORT-MESSAGE X(8) Used only during sort and merge operations. You can reference it in the Procedure Division but it will contain spaces.
OSVSVSC2  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.
OSVSVSC2MF 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.
OSVSVSC2 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.
OSVS 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.
OSVS 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.
VSC2 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.
ENTMF 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.
ENTMF 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.
ENTMF XML-NTEXT   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.
ENTMF XML-TEXT   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.

ENTMF 
Table 2. 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".
Parent topic: Language Structure
Related information
Debug Module
XML-CODE Exception Codes
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 2 for additional information.
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.