Error handling

The language elements used for handling errors in current file input/output are also available for processing XML documents using the new statement formats:

• OPEN DOCUMENT and READ: AT END and NOT AT END phrases

• START: INVALID KEY and NOT INVALID KEY phrases 

• For all new formats of the statements: USE procedures and additional new XML-specific values for the I-O status (FILE STATUS).

• OPEN DOCUMENT: new exceptional condition EC-XML-CODESET-CONVERSION

The [NOT] END and [NOT] KEY phrases correspond to the phrases in the old input/output statements, both in their syntax and also in their function.

OPEN DOCUMENT

Basically multiple XML documents are permitted in a file one after the other. However, at present only files with a single document are supported. Each OPEN DOCUMENT statement without an AT phrase closes any document which may still be open and opens the next document in the file. If there is no next document or the file is empty, the at end condition occurs and the I-O status is set to 10.

If the XML document contains characters which cannot be represented as national characters (UTF-16), the exceptional condition EC-XML-CODESET-CONVERSION occurs. This exceptional condition does not lead to termination. The characters concerned are replaced in the XML document tree by the replacement character '.'.
EC-XML-CODESET-CONVERSION occurs only when the external representation of the XML document is converted to a tree – at most once.

READ

The AT END phrase refers only to an at end condition for the one data item which was specified in the READ statement, not for subordinate data items. The at end condition occurs during both sequential and random reading if there is no node in the XML document tree which can be assigned to the data item (from the statement). The corresponding value for the I-O status is 10.

For transfers from the XML document tree, national (UTF-16) must be assumed as the en-coding for representing the data. As a result, the exceptional condition EC-DATA-CONVER-SION can occur during each transfer in the context of a READ statement.

In contrast to EC-XML-CODESET-CONVERSION from the OPEN DOCUMENT statement, EC-DATA-CONVERSION can occur when data is transferred from the tree to the program – possibly even several times during a single READ statement.

START

The INVALID KEY phrase refers only to an invalid key condition for the one data item which was specified in the START statement, not to subordinate data items The invalid key condition occurs when there is no node in the XML document tree which can be assigned to this data item. The corresponding value for the I-O status is 23.

All statements

When the order of the statements is not observed (see also "Statement sequences" in section "Statements for XML processing"), the prerequisites for executing a single statement are not satisfied. This results in unsuccessful execution on account of logical errors and a corresponding I-O status.

I-O status for XML files

I-O status	Meaning
	Successful execution
00	The statement was executed successfully. No further information is available.
05	OPEN statement for a non-existent optional file.
08	A READ statement was unable to assign some elements and/or attributes from the XML document to any COBOL description entry.
	Unsuccessful execution: at end condition
10	A READ statement was used to attempt to read an attribute or element which does not exist. An attempt was made to execute an OPEN DOCUMENT statement for an empty or a non-existent optional file. An attempt was made to open a second document in an XML file by means of an OPEN DOCUMENT statement.
	Unsuccessful execution: invalid key condition
23	A START statement was used to attempt to position on an attribute or element which does not exist. The index phrase in the START statement was not positive.
25	An attempt was made to execute a START phrase without a valid position.
	Unsuccessful execution: permanent error
30	No further information is available.
35	OPEN for non-existent file.
39	An attempt was made to open a file with unsuitable file attributes.
3A	An attempt was made to execute an OPEN DOCUMENT statement for an XML document which is not well-formed. This also includes file contents which are not XML documents.
3D	An attempt was made to execute an OPEN DOCUMENT statement, but the encoding in which the XML document is represented could not be determined.
	Unsuccessful execution: logical error
41	An attempt was made to execute an OPEN statement for a file which is already open.
42	An attempt was made to execute a CLOSE statement for a file which has not been opened.
46	An attempt was made to execute an OPEN DOCUMENT statement (with AT phrase) or a READ statement without a valid position. An attempt was made to execute an OPEN DOCUMENT statement (without AT phrase) after the preceding OPEN DOCUMENT statement had caused an at end condition.
47	An attempt was made to execute a READ or START statement for a file which has not been opened.
4B	An attempt was made to execute an OPEN DOCUMENT or CLOSE DOCU-MENT statement for a file which has not been opened.
4C	An attempt was made to execute an OPEN DOCUMENT, START or READ statement in which names in IDENTIFIED clauses for sibling nodes were not unique.
4D	An attempt was made to execute a CLOSE DOCUMENT, OPEN DOCUMENT (with AT phrase), READ or START statement for a document which has not been opened.
4E	An attempt was made to execute an OPEN DOCUMENT, READ or START statement in which element and/or attribute names specified in the COBOL program cannot be represented in UTF-16.
	Other cases of unsuccessful execution
90	System error - no further information is available about the cause.
91	OPEN error. Actual cause may be apparent from the SIS code
97	The memory required for an OPEN DOCUMENT statement is not available.

Table 47: I-O statuses for XML files

These I-O statuses refer only to the primary XML file which is to be processed. If errors occur during access (which may also be required) to external entities, these generally lead to I-O status 3A.

Example 12-54 Ambiguous names

XML document	Pos	COBOL data structure		OPEN DOCUMENT xml-fil		READ xml-fil ELEMENT x
<doc>1    <a>2</a>    <b>3</b>    <a>4</a> </doc>	1 2 3 4	FD xml-fil 01 x IDENTIFIED BY "doc". 02 y IDENTIFIED BY y-name.   03 y-name PIC X. 02 z IDENTIFIED BY z-name.   03 z-name PIC X.	MOVE "a" TO y-name MOVE "b" TO z-name	1(o) 2(o) a 3(o) b	MOVE "a" TO z-name	inv inv a inv a
		FILE STATUS		00		4C

Comments:

• Information on the presentation of this example is provided in section  "Statements for XML processing".

• The current keywords of data items y and z are the same in the READ statement: This is forbidden because no unique assignment is defined for this case (is node 2 to be assigned to z and node4 to y or vice versa?). The READ statement consequently returns the I-O status 4C.

• In this case the data item via which reading took place – although the problem did not occur in this data item at all but in subordinate ones – and all the data items subordinate to it contain an invalid position.