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. 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
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 ¹	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.
JSON-CODE²	S9(9) BINARY VALUE 0	The JSON-CODE special register is used to indicate either that a JSON GENERATE statement executed successfully or that an exception occurred during JSON generation. When used in nested programs, this special register is implicitly defined with the global attribute in the outermost program. Following termination of an JSON GENERATE statement, JSON-CODE contains either a zero to indicate a successful JSON generation, or a non-zero error code to indicate an exception.
LENGTH OF data-name-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 ⁴	S9(4) COMP S9(9) COMP S9(18) 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 ⁵	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 and to indicate either that an XML GENERATE statement executed successfully or that an exception occurred during XML generation. 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. Following termination of an XML GENERATE statement, XML-CODE contains either a zero to indicate a successful XML generation, or a non-zero error code to indicate an exception.
XML-EVENT ⁶	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-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. The parser sets XML-NTEXT to the document fragment associated with an event before transferring control to the processing procedure in these cases: When the operand of the XML PARSE statement is a data item of category national or the RETURNING NATIONAL phrase is specified in the XML PARSE statement For the ATTRIBUTE-NATIONAL-CHARACTER event For the CONTENT-NATIONAL-CHARACTER event 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-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. The parser sets XML-TEXT to the document fragment associated with an event before transferring control to the processing procedure when the operand of the XML PARSE statement is an alphanumeric data item and the RETURNING NATIONAL phrase is not specified in the XML PARSE statement, except for the ATTRIBUTE-NATIONAL-CHARACTER event and the CONTENT-NATIONAL-CHARACTER event. 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.
XML-INFORMATION	S9(9) USAGE BINARY VALUE 0	The XML-INFORMATION special register is used to provide additional information to an XML PARSE processing procedure about the status of the parse. This register provides a mechanism to easily determine whether an XML EVENT is complete. Sometimes XML content might be split across multiple events and the application must concatenate the pieces of content together. The XML-INFORMATION register is used to indicate whether or not content of the XML event is complete. The value of the XML-INFORMATION register is set as follows for the various XML events: ATTRIBUTE-CHARACTERS 1 indicates that the attribute value in XML-TEXT or XML-NTEXT special register is complete 2 indicates that the attribute value in XML-TEXT or XML-NTEXT special register is not complete 4, 8, 16, ... are reserved for future use CONTENT-CHARACTERS 1 indicates that the content value in XML-TEXT or XML-NTEXT special register is complete 2 indicates that the content value in XML-TEXT or XML-NTEXT special register is not complete 4, 8, 16, ... are reserved for future use All other events 0 indicates that no additional information is currently available 2, 4, 8, 16, ... are reserved for future use
XML-NAMESPACE		The XML-NAMESPACE special register is defined during XML parsing to contain the identifier of the namespace, if any, associated with the name in XML-TEXT for XML events START-OF-ELEMENT, END-OF-ELEMENT, and ATTRIBUTE-NAME, and to contain the declared namespace identifier for XML event NAMESPACE-DECLARATION. The parser sets XML-NAMESPACE to the identifier of the namespace associated with a name before transferring control to the processing procedure when the operand of the XML PARSE statement is an alphanumeric data item and the RETURNING NATIONAL phrase is not specified in the XML PARSE statement. To use XML-NAMESPACE, you must compile with the XMLPARSE(XMLSS) compiler option. XML-NAMESPACE is an elementary data item of category alphanumeric. The length at run time is the length of the contained namespace identifier. XML-NAMESPACE has a length of zero for: The START-OF-ELEMENT, END-OF-ELEMENT and ATTRIBUTE-NAME XML events if there is no namespace associated with a name The NAMESPACE-DECLARATION XML event if the namespace is undeclared by specifying the empty string All other XML events When XML-NAMESPACE is set, the XML-NNAMESPACE special register has a length of zero. At any given time, only one of the two special registers XML-NAMESPACE and XML-NNAMESPACE has a nonzero length. Use the LENGTH function or the LENGTH OF special register to determine the number of bytes that XML-NAMESPACE contains. XML-NAMESPACE cannot be used as a receiving item.
XML-NAMESPACE-PREFIX		The XML-NAMESPACE-PREFIX special register is defined during XML parsing to contain the prefix, if any, of the name in XML-TEXT for XML events START-OF-ELEMENT, END-OF-ELEMENT, and ATTRIBUTE-NAME, and to contain the local attribute name for XML event NAMESPACE-DECLARATION. The namespace prefix is used as an alias for the complete namespace identifier. The parser sets XML-NAMESPACE-PREFIX before transferring control to the processing procedure when the operand of the XML PARSE statement is an alphanumeric data item and the RETURNING NATIONAL phrase is not specified. To use XML-NAMESPACE-PREFIX, you must compile with the XMLPARSE(XMLSS) compiler option. XML-NAMESPACE-PREFIX is an elementary data item of category alphanumeric. The length at run time is the length of the contained namespace prefix. XML-NAMESPACE-PREFIX has a length of zero for: The START-OF-ELEMENT, END-OF-ELEMENT, and ATTRIBUTE-NAME XML events if the name does not have a prefix The NAMESPACE-DECLARATION XML event if the declaration is for the default namespace, in which case the namespace declaration attribute name is not prefixed. All other XML events When XML-NAMESPACE-PREFIX is set, the XML-NNAMESPACE-PREFIX special register has a length of zero. At any given time, only one of the two special registers XML-NAMESPACE-PREFIX and XML-NNAMESPACE-PREFIX has a nonzero length. Use the LENGTH function or the LENGTH OF special register to determine the number of bytes that XML-NAMESPACE-PREFIX contains. XML-NAMESPACE-PREFIX cannot be used as a receiving item.
XML-NNAMESPACE		The XML-NNAMESPACE special register is defined during XML parsing to contain the identifier of the namespace, if any, associated with the name in XML-NTEXT for XML events START-OF-ELEMENT, END-OF-ELEMENT, and ATTRIBUTE-NAME, and to contain the declared namespace identifier for XML event NAMESPACE-DECLARATION. The parser sets XML-NNAMESPACE to the identifier of the namespace associated with a name before transferring control to the processing procedure when the RETURNING NATIONAL phrase is specified in the XML PARSE statement or the operand of the XML PARSE statement is a national data item. To use XML-NNAMESPACE, you must compile with the XMLPARSE(XMLSS) compiler option. XML-NNAMESPACE is an elementary data item of category national. The length at run time is the length of the contained namespace identifier. XML-NNAMESPACE has a length of zero for: The START-OF-ELEMENT, END-OF-ELEMENT and ATTRIBUTE-NAME XML events, if there is no namespace associated with a name The NAMESPACE-DECLARATION XML event if the namespace is undeclared by specifying the empty string All other XML events When XML-NNAMESPACE is set, the XML-NAMESPACE special register has a length of zero. At any given time, only one of the two special registers XML-NNAMESPACE and XML-NAMESPACE has a nonzero length. Use the LENGTH function to determine the number of national character positions that XML-NNAMESPACE contains; use the LENGTH OF special register to determine the number of bytes. XML-NNAMESPACE cannot be used as a receiving item.
XML-NNAMESPACE-PREFIX		The XML-NNAMESPACE-PREFIX special register is defined during XML parsing to contain the prefix, if any, of the name in XML-NTEXT for XML events START-OF-ELEMENT, END-OF-ELEMENT, and ATTRIBUTE-NAME, and to contain the local attribute name for XML event NAMESPACE-DECLARATION. The namespace prefix is used as an alias for the complete namespace identifier. The parser sets XML-NNAMESPACE-PREFIX before transferring control to the processing procedure when the operand of the XML PARSE statement is a national data item or the RETURNING NATIONAL phrase is specified in the XML PARSE statement. To use XML-NNAMESPACE-PREFIX, you must compile with the XMLPARSE(XMLSS) compiler option. XML-NNAMESPACE-PREFIX is an elementary data item of category national. The length at run time is the length of the contained namespace prefix. XML-NNAMESPACE-PREFIX has a length of zero for: The START-OF-ELEMENT, END-OF-ELEMENT, and ATTRIBUTE-NAME XML events if the name does not have a prefix NAMESPACE-DECLARATION XML event if the declaration is for the default namespace, in which case the namespace declaration attribute name is not prefixed. All other XML events When XML-NNAMESPACE-PREFIX is set, the XML-NAMESPACE-PREFIX special register has a length of zero. At any given time, only one of the two special registers XML-NNAMESPACE-PREFIX and XML-NAMESPACE-PREFIX has a nonzero length. Use the LENGTH function to determine the number of national character positions that XML-NNAMESPACE contains; use the LENGTH OF special register to determine the number of bytes. XML-NNAMESPACE-PREFIX cannot be used as a receiving item.

Table 2. Contents of XML events and associated special register contents
XML-EVENT⁷	XMLPARSE(XMLSS)	XMLPARSE(COMPAT)
ATTRIBUTE-CHARACTER	N/A	XML-TEXT or XML-NTEXT contains the single character that corresponds with the predefined entity reference in the attribute value.
ATTRIBUTE-CHARACTERS	XML-TEXT or XML-NTEXT contains the value within quotation marks or apostrophes. This can be a substring of the attribute value.	XML-TEXT or XML-NTEXT contains the value within quotation marks or apostrophes. This can be a substring of the attribute value if the value includes a character reference or an entity reference.
ATTRIBUTE-NAME	For attribute names that are not in a namespace, XML-TEXT or XML-NTEXT contains the attribute name. For attributes with names in a non-default namespace, attribute names are always prefixed and have the form: `prefix: local-part` = " `AttValue` ". XML-TEXT or XML-NTEXT contains the `local-part` , XML-NAMESPACE or XML-NNAMESPACE contains the namespace identifier, and XML-NAMESPACE-PREFIX or XML-NNAMESPACE-PREFIX contains the `prefix` .	XML-TEXT or XML-NTEXT contains the attribute name (the string to the left of the equal sign).
ATTRIBUTE-NATIONAL-CHARACTER	Regardless of the type of the XML document, XML-TEXT is empty with length zero and XML-NTEXT contains the single national character that corresponds with the numeric character reference.	XML-TEXT or XML-NTEXT content is the same as for XMLPARSE(XMLSS).
COMMENT	XML-TEXT or XML-NTEXT contains the text of the comment between the opening character sequence "<!--" and the closing character sequence "-->". This can be a substring of the text.	XML-TEXT or XML-NTEXT always contains the complete text of the comment.
CONTENT-CHARACTER	N/A	XML-TEXT or XML-NTEXT contains the single character that corresponds with the predefined entity reference in the element content.
CONTENT-CHARACTERS	XML-TEXT or XML-NTEXT contains the character content of the element between start and end tags. This can be a substring of the content.	XML-TEXT or XML-NTEXT contains the character content of the element between start and end tags. This can be a substring of the character content if the content includes a character reference or an entity reference.
CONTENT-NATIONAL-CHARACTER	Regardless of the type of the XML document, XML-TEXT is empty with length zero and XML-NTEXT contains the single national character that corresponds with the numeric character reference.	XML-TEXT or XML-NTEXT content is the same as for XMLPARSE(XMLSS).
DOCUMENT-TYPE-DECLARATION	XML-TEXT or XML-NTEXT contains the name of the root element, as specified in the document type declaration.	XML-TEXT or XML-NTEXT contains the entire document type declaration, including the opening and closing character sequences "<!DOCTYPE" and ">".
ENCODING-DECLARATION	XML-TEXT or XML-NTEXT contains the value, between quotation marks or apostrophes, of the encoding declaration in the XML declaration.	XML-TEXT or XML-NTEXT content is the same as for XMLPARSE(XMLSS).
END-OF-CDATA-SECTION	All XML special registers except XML-CODE and XML-EVENT are empty with length zero.	XML-TEXT or XML-NTEXT contains the string "]]>".
END-OF-DOCUMENT	All XML special registers except XML-CODE and XML-EVENT are empty with length zero.	XML-TEXT or XML-NTEXT content is the same as for XMLPARSE(XMLSS).
END-OF-ELEMENT	XML-TEXT or XML-NTEXT contains the local part of the end element tag or empty element tag name. If the element name is in a non-default namespace, XML-NAMESPACE or XML-NNAMESPACE contains the namespace identifier. If the element name is in a namespace and is prefixed (of the form `prefix: local-part` ), XML-NAMESPACE-PREFIX or XML-NNAMESPACE-PREFIX contains the prefix.	XML-TEXT or XML-NTEXT contains the name of the end element tag or empty element tag.
END-OF-INPUT	All XML special registers except XML-CODE and XML-EVENT are empty with length zero. To parse an additional segment of an XML document, move the next segment to identifier-1 and set XML-CODE to 1.	N/A
EXCEPTION	XML-CODE contains the unique return code and reason code that identifies the exception. XML-TEXT or XML-NTEXT contains the document fragment up to the point of the error or anomaly that caused the exception. All other XML special registers are empty with length zero.	XML-CODE contains the unique error code that identifies the exception. XML-TEXT or XML-NTEXT contains the part of the document that was successfully scanned, up to and including the point at which the exception was detected.
NAMESPACE-DECLARATION	XML-TEXT and XML-NTEXT are both empty with length zero. XML-NAMESPACE or XML-NNAMESPACE contains the declared namespace identifier. If the namespace is "undeclared" by specifying the empty string, XML-NAMESPACE and XML-NNAMESPACE are empty with length zero. XML-NAMESPACE-PREFIX or XML-NNAMESPACE-PREFIX contains the prefix if the namespace declaration is of the form `xmlns: prefix` = " `namespace-identifier` "; otherwise, if the declaration is for the default namespace and thus the attribute name is `xmlns` , XML-NAMESPACE-PREFIX and XML-NNAMESPACE-PREFIX are both empty with length zero.	N/A (ATTRIBUTE-NAME and ATTRIBUTE-CHARACTERS events are signaled instead.)
PROCESSING-INSTRUCTION-DATA	XML-TEXT or XML-NTEXT contains the rest of the processing instruction (after the target name), not including the closing sequence "?>", but including trailing, and not leading, white space characters. This can be a substring of the processing instruction data.	XML-TEXT or XML-NTEXT always contains the complete processing instruction data.
PROCESSING-INSTRUCTION-TARGET	XML-TEXT or XML-NTEXT contains the processing instruction target name, which occurs immediately after the processing instruction opening sequence, "<?". This event can occur multiple times for a given processing instruction: one occurrence preceding each substring of the data.	XML-TEXT or XML-NTEXT content is the same as for XMLPARSE(XMLSS). This event occurs only once for a given processing instruction.
STANDALONE-DECLARATION	XML-TEXT or XML-NTEXT contains the value, between quotation marks or apostrophes ("yes" or "no"), of the stand-alone declaration in the XML declaration.	XML-TEXT or XML-NTEXT content is the same as for XMLPARSE(XMLSS).
START-OF-CDATA-SECTION	All XML special registers except XML-CODE and XML-EVENT are empty with length zero.	XML-TEXT or XML-NTEXT contains the string "<![CDATA[".
START-OF-DOCUMENT	All XML special registers except XML-CODE and XML-EVENT are empty with length zero.	XML-TEXT or XML-NTEXT contains the entire document.
START-OF-ELEMENT	XML-TEXT or XML-NTEXT contains the local part of the start element tag name or the local part of the empty element tag name. If the element name is in a namespace, XML-NAMESPACE or XML-NNAMESPACE contains the namespace identifier. If the element name is in a namespace and is prefixed (of the form `prefix: local-part` , XML-NAMESPACE-PREFIX or XML-NNAMESPACE-PREFIX contains the prefix.	XML-TEXT or XML-NTEXT contains the name of the start element tag or empty element tag, also known as the element type.
UNKNOWN-REFERENCE-IN-ATTRIBUTE	For XMLPARSE(XMLSS), the parser always signals EXCEPTION.	XML-TEXT or XML-NTEXT contains the entity reference name, not including the "&" and ";" delimiters.
UNKNOWN-REFERENCE-IN-CONTENT	For XMLPARSE(XMLSS), the parser signals UNRESOLVED-REFERENCE or EXCEPTION instead.	XML-TEXT or XML-NTEXT contains the entity reference name, not including the "&" and ";" delimiters.
UNRESOLVED-REFERENCE	XML-TEXT or XML-NTEXT contains the entity name from XML content, not including the "&" and ";" delimiters.	N/A (The parser signals UNKNOWN-REFERENCE-IN-CONTENT instead.)
VERSION-INFORMATION	XML-TEXT or XML-NTEXT contains the value, between quotation marks or apostrophes, of the version information in the XML declaration.	XML-TEXT or XML-NTEXT content is the same as for XMLPARSE(XMLSS).