Processing procedure

During execution a processing procedure behaves as if it were activated by the XML statement via PERFORM, in a similar manner to an INPUT/OUTPUT PROCEDURE with SORT, see also section "SORT statement". The same rules and restrictions therefore apply for specification in the XML statement as for a PERFORM statement.

Events

Within the processing procedure the application can perform further processing operations which are of interest. Almost all events make specific data available in special register XML-TEXT or XML-NTEXT for this purpose. The nsp column in the table below indicates events for which the namespace special registers are also supplied with values. These registers are XML-NAMESPACE and XML-NAMESPACE-PREFIX or XML-NNAMESPACE and XML-NNAMESPACE-PREFIX. If no namespace or the empty namespace is specified, the current length of the special registers is 0; in the case of a standard namespace the current length of the prefix special register is 0.

The single quotes enclosing various strings in the table below are included to highlight the strings. They are not part of the strings.

Name of the event (in XML-EVENT)	Content of XML-TEXT or XML-NTEXT	nsp
ATTRIBUTE-CHARACTERS	Value of the attribute without the opening and closing literal identifiers.	–
ATTRIBUTE-NAME	Local name of the attribute.	X
COMMENT	Content of the comment without the '<!--' string at the start and the '-->' string at the end.	–
CONTENT-CHARACTER	A single character which corresponds to a predefined entity reference.	–
CONTENT-CHARACTERS	Substring between an element’s start and end tags. This is only the entire value if it contains no other elements or entity references.	–
CONTENT-NATIONAL-CHARACTER	Only in XML-NTEXT for documents which are made available in an alphanumeric data item: a single national character which corresponds to a numeric entity that cannot be represented as an alphanumeric character. With this event XML-TEXT always has 0 as its current length.	–
DEFAULTED-ATTRIBUTE-NAME	Local name of an attribute which is not contained in the XML document but is declared with a default value in the DTD (Document Type Definition) used.	X
DOCUMENT-TYPE-DECLARATION	The entire document type definition, inclu ding the '<!DOCTYPE' string at the start and '>' at the end.	–
ENCODING-DECLARATION	Encoding name (as expected by XHCS) which is implied for interpreting the document. This is generally not the name specified in the encoding declaration of the XML document. Rather, it can be a different encoding if, for example, the XML document was transferred and, in the process, converted by means of File Transfer without at the same time adjusting the specification in the encoding declaration.	–
END-OF-CDATA-SECTION	The ']]>' string.	–
END-OF-DOCUMENT	Empty, i.e. current length = 0	–
END-OF-ELEMENT	Local name of the element	X
EXCEPTION	Start of the document, up to and including the error location.	–
NAMESPACE-DECLARATION	Empty, i.e. current length = 0.	X
PROCESSING-INSTRUCTION-DATA	Content of the processing instruction after the name without the '?>' string at the end. Leading white spaces are not part of this, but trailing ones are.	–
PROCESSING-INSTRUCTION-TARGET	Name of the processing instruction (without the '?>' string at the start).	–
STANDALONE-DECLARATION	The 'yes' or 'no' string from the text declaration.	–
START-OF-CDATA-SECTION	The '<![CDATA[' string.	–
START-OF-DOCUMENT	The complete document.	–
START-OF-ELEMENT	Local name of the element.	X
VERSION-INFORMATION	Value from the version information of the text declaration without the opening and closing literal identifiers.	–

Error handling

The parser uses the 'EXCEPTION' event to notify the processing procedure of errors it detects. The special register XML-CODE then has a value not equal to 0 which describes the error more exactly. For all other events this special register has the value 0.

The content of the special register XML-CODE when the processing procedure is exited controls how the XML statement is continued. The processing procedure signals how the statement is to continue by setting corresponding values:

-1	Terminates the XML statement with 'error'. This is possible with every event, even if the EXCEPTION event did not occur beforehand.
0	Continuation of the XML statement. If an error has already been reported, continuation is only possible in the event of 'minor' errors. However, it is restricted to searching for further errors. The XML statement is nevertheless always aborted in the case of 'serious' errors.
Other values	The further behavior is undefined.

Depending on how the XML statement was terminated, existing EXCEPTION and NOT EXCEPTION clauses are executed after it:

NOT EXCEPTION	In the case of normal termination.
EXCEPTION	I the case of abnormal termination because of errors. This includes active termination by setting the special register XML-CODE in the processing procedure.

Example 12-57 Events and content of the special registers

DATA DIVISION.
WORKING-STORAGE SECTION.
...
01 document.
  02     VALUE "<?xml version='1.1'?>".
  02     VALUE "<doc xmlns:r='http://www.efg'>".
  02     VALUE "111".
  02     VALUE "<a att='XX'/>".
  02     VALUE "<![CDATA[tse-da-da segdschn]]".
  02     VALUE "222".
  02     VALUE "<r:b>".
  02     VALUE "yyyyy ".
  02     VALUE "</r:b>".
  02     VALUE "</doc>".

Parsing of the document by the XML statement results in the following series of events and contents of the special registers

XML-EVENT	XML-TEXT	XML-NAME-SPACE	XML-NAME- SPACE-PREFIX
VERSION-INFORMATION	1.1
START-OF-DOCUMENT	<?xml version='1.1'?> <doc xmlns:r= 'http://www.efg'>111 <a att='XX'/><![CDATA [tse-da-da segdschn]]> 222 <r:b>yyyyy'BLANK''BLANK''BLANK'</r:b> </doc>
START-OF-ELEMENT	doc
NAMESPACE-DECLARATION		http://www.efg	r
CONTENT-CHARACTERS	111
START-OF-ELEMENT	a
ATTRIBUTE-NAME	att
ATTRIBUTE-CHARACTERS	XX
END-OF-ELEMENT	a
START-OF-CDATA-SECTION	<![CDATA[
CONTENT-CHARACTERS	tse-da-da segdschn
END-OF-CDATA-SECTION	]]>
CONTENT-CHARACTERS	222
START-OF-ELEMENT	b	http://www.efg	r
CONTENT-CHARACTERS	yyyyy'BLANK''BLANK''BLANK'
END-OF-ELEMENT	b	http://www.efg	r
END-OF-ELEMENT	doc
END-OF-DOCUMENT

Comments:

• The value (111222) of the element 'doc' is split into two parts by the inserted element 'a'. Because the XML document is processed sequentially, the parser supplies the segments separately – interrupted by the events for element 'a' – each with the CONTENT-CHARACTERS event.

• An empty entry indicates that the special register’s current length in the event is 0.

Example 12-58 XML statement and processing procedure

PROCEDURE DIVISION.
...
  XML PARSE document
    PROCESSING PROCEDURE IS event
    ON EXCEPTION ...
    NOT ON EXCEPTION ...
  END-XML.
...
event.
  EVALUATE XML-EVENT
   WHEN "VERSION-INFORMATION"
     IF XML-TEXT NOT = "1.0"
        DISPLAY "XML Version not 1.0"
        MOVE -1 TO XML-CODE
     END-IF
   WHEN "CONTENT-CHARACTERS"
     ...
   WHEN "START-OF-ELEMENT"
     IF FUNCTION LENGTH(XML-TEXT) > 31
        DISPLAY "Element name too long"
        MOVE -1 to XML-CODE
     ELSE
        MOVE XML-TEXT TO ...
     END-IF
   WHEN "END-OF-ELEMENT"
   ...
   WHEN OTHER
     CONTINUE
END-EVALUATE.

Comments:

• The program wants to process only XML documents of Version 1.0 and terminate processing for all other versions: if the special register XML-CODE is supplied with the value -1 in the processing procedure, this signals the wish for the XML statement to be aborted immediately.

• -1 in the special register XML-CODE when the XML statement is returned to means abnormal termination and continuation with the statements in the ON EXCEPTION phrase.

• The program only processes elements and their values. The processing procedure 'swallows' other events without doing anything to achieve this (WHEN OTHER).

• The program wants to accept only element names with a maximum of 31 characters. If longer element names occur in the document, the XML statement is terminated immediately. The length of an element name made available in the special register XML-TEXT corresponds to the current length of the special register: it is supplied by FUNCTION LENGTH.

• Even if individual special registers cannot be defined with conventional COBOL language elements, they may be used in COBOL statement. They behave like alphanumeric or national groups of variable length, e.g. as a sending item in the MOVE statement.