Event-oriented processing of an XML document makes data about the detected syntax units available in special registers at the start of the processing procedure.
Data description entries for the special registers may not be written by the programmer. Rather, the compiler generates these automatically when the option for detecting XML-specific keywords is enabled when the program is compiled (see the "COBOL2000 User Guide" [1], section 10.2 “Using XML language elements in programs”). The special registers exist only once per run unit and are also available in nested programs.
There are three groups of special registers:
XML-EVENT, XML-CODE:
The data supplied in these special registers always has a fixed length and describes an event.
For XML documents which are made available in an alphanumeric data item:
XML-TEXT, XML-NAMESPACE, XML-NAMESPACE-PREFIX.
The data supplied in these special registers is of variable length and describes the data associated with an event.
For the exception in the special case of the CONTENT-NATIONAL-CHARACTER event, see also sections "XML-TEXT" and "XML-NTEXT" .
For XML documents which are made available in a national data item:
XML-NTEXT, XML-NNAMESPACE, XML-NNAMESPACE-PREFIX.
The data supplied in these special registers is of variable length and describes the data associated with an event.
The special registers – with the exception of XML-CODE – are modified only by the XML PARSE statement. If they occur in the program as a receiving item, this results in undefined behavior. The special registers – with the exception of XML-CODE – consequently only have meaningful contents while an XML statement is being executed. When required, the standard function FUNCTION LENGTH (special-register) supplies the current length of the variable-length data.
XML-EVENT
At the start of the processing procedure this special register contains the name of the event which has just been detected. The possible events are described in detail in section "Processing procedure".
This special register corresponds to an elementary item with the description
USAGE DISPLAY PIC X(30).
XML-CODE
At the start of the processing procedure this special register contains an error code if the event is 'EXCEPTION'. With all other events it contains the value 0. The possible values for the error code are provided in the "COBOL2000 User Guide" [1], section 10.6 "Extended I-O status for XML statements (CBX code).”
This is the only special register which may also be modified by the program in order to signal the required type of continuation when control is returned from a processing procedure to the XML PARSE statement (see section "XML statement").
This special register corresponds to a data item with the description
USAGE COMP-5 PICTURE S9(9).
XML-TEXT
If the XML document is contained in an alphanumeric data item, at the start of the processing procedure this special register contains part of the XML document which is described exactly by the event.
This special register corresponds to an elementary item with the description
USAGE DISPLAY PICTURE X ANY LENGTH,
the current length being the same as the length of the document part supplied (in characters). If the XML document is contained in a national data item or if the event is END-OF-DOCUMENT, CONTENT-NATIONAL-CHARACTER or NAMESPACE-DECLARATION, the current length is 0.
XML-NTEXT
If the XML document is contained in a national data item, at the start of the processing procedure this special register contains part of the XML document which is described exactly by the event.
This special register corresponds to an elementary item with the description
USAGE NATIONAL PICTURE N ANY LENGTH,
the current length being the same as the length of the document part supplied (in characters). If the XML document is contained in an alphanumeric data item – with the exception of the CONTENT-NATIONAL-CHARACTER event – or if the event is END-OF-DOCUMENT or NAMESPACE-DECLARATION, the current length is 0.
XML-NAMESPACE
If the XML document is contained in an alphanumeric data item, at the start of the processing procedure this special register contains the name of the namespace in the case of the ATTRIBUTE-NAME, DEFAULTED-ATTRIBUTE-NAME, END-OF-ELEMENT, NAMESPACE-DECLARATION and START-OF-ELEMENT events.
This special register corresponds to an elementary item with the description
USAGE DISPLAY PICTURE X ANY LENGTH,
the current length being the same as the length of the namespace name (in characters). If the XML document is contained in a national data item or the namespace is empty or another event is involved, the current length is 0.
XML-NNAMESPACE
If the XML document is contained in a national data item, at the start of the processing procedure this special register contains the name of the namespace in the case of the ATTRIBUTE-NAME, DEFAULTED-ATTRIBUTE-NAME, END-OF-ELEMENT, NAMESPACE-DECLARATION and START-OF-ELEMENT events.
This special register corresponds to an elementary item with the description
USAGE NATIONAL PICTURE N ANY LENGTH,
the current length being the same as the length of the namespace name (in characters). If the XML document is contained in an alphanumeric data item or the namespace is empty or another event is involved, the current length is 0.
XML-NAMESPACE-PREFIX
If the XML document is contained in an alphanumeric data item, at the start of the processing procedure this special register contains the prefix of the namespace in the case of the ATTRIBUTE-NAME, DEFAULTED-ATTRIBUTE-NAME, END-OF-ELEMENT, NAMESPACE-DECLARATION and START-OF-ELEMENT events.
This special register corresponds to an elementary item with the description
USAGE DISPLAY PICTURE X ANY LENGTH,
the current length being the same as the length of the prefix (in characters). If the XML document is contained in a national data item or the namespace has no prefix or another event is involved, the current length is 0.
XML-NNAMESPACE-PREFIX
If the XML document is contained in a national data item, at the start of the processing procedure this special register contains the prefix of the namespace in the case of the ATTRIBUTE-NAME, DEFAULTED-ATTRIBUTE-NAME, END-OF-ELEMENT, NAMESPACE-DECLARATION and START-OF-ELEMENT events.
This special register corresponds to an elementary item with the description
USAGE DISPLAY PICTURE N ANY LENGTH,
the current length being the same as the length of the prefix (in characters). If the XML document is contained in an alphanumeric data item or the namespace has no prefix or another event is involved, the current length is 0.