START

The new second format of the START statement solely for XML files is used for positioning on one or more nodes (elements and/or attributes) from the XML document tree. A comparison with the old START statement for files reveals only the following minor differences for the simplest form:

• A START statement can position on multiple keys simultaneously: on the data item specified in the statement and all data items which are subordinate to it.

• The KEY phrase is omitted. As an XML document tree is generally a two-dimensional structure, it does not make sense to transfer the positioning 'before' and 'after' a key which is possible with one-dimensional files to XML documents (with more than one key simultaneously).

• The type of data item which is used for positioning must be specified analogously to the XML format of the READ statement.

A new READ statement looks like this:

START xml-file ELEMENT data-name-1

or

START xml-file ATTRIBUTE data-name-1

The difference between the START statement and the READ statement which also positions on nodes in the tree is that the range starting from the data item specified in the statement is defined.

The data item specified in the START statement plays no role itself here. In contrast to the READ statement, no node need be assigned to this data item. It is decisive that a node from the tree must be assigned to the data item which is directly superordinate in the COBOL structure. The range of the START statement then includes the subtree which has this node as its root.

The assignment procedure begins in the first step on the COBOL side with the data item which was specified in the READ statement. On the XML side all the children of the root node which are in the range (as defined above) are checked for a possible assignment in the order from the older ones to the younger ones (in other words, in contrast to the READ statement, if data-name-1 has a valid position, its older siblings are also checked). Further assignments are then implemented, as described under "Assignment procedure" in section "Statements for XML processing".

START modifies the EPV only, but leaves data unchanged.

 

Example 12-51 Positioning using START

XML document	Pos	COBOL data structure		OPEN DOCUMENT xml-fil	READ xml-fil ELEMENT x		START xml-fil ELEMENT y	READ xml-fil ELEMENT y
<doc>1   <a>2     <b>3</b>     <c>4</c>   </a>   <a>5     <b>6</b>     <c>7</c>   </a> </doc>	1 2 3 4 5 6 7	FD xml-fil 01 x IDENTIFIED        BY "doc".   02 x-value PIC 9.   02 y IDENTIFIED        BY y-name.     03 y-name PIC X.     03 y-value PIC 9.     03 z IDENTIFIED        BY z-name.       04 z-name PIC X.       04 z-value PIC 9.	MOVE "f" TO y-name MOVE "g" TO z-name	1(o) inv f inv g	1(r) 1 inv f inv g	MOVE "a" TO y-name MOVE "b" TO z-name	1(r) 1 2(o) a 3(o) b	1(r) 1 2(r) a 2 3(r) b 3

Comments:

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

• The data item (y) specified in the START statement need not have a valid position. The directly superordinate data item (x with node 1) must have a valid position.

• The range of the START statement is the subtree with the root node 1. The children of this node are checked (first node 2, then node 5) for assignment to data item y. Node 2 matches first, and assignment is continued with this subtree.

• As the START statement only provides a position but transfers no data, the following START statement supplies the data to the positioned node 2 and the subtree determined by node 2.

   

Example 12-52 Repeated positioning on the same node (continuation of Example 12-51 )

XML document	Pos	COBOL data structure	...	READ xml-fil ELEMENT y	START xml-fil ELEMENT y
<doc>1   <a>2     <b>3</b>     <c>4</c>   </a>   <a>5     <b>6</b>     <c>7</c>   </a> </doc>	1 2 3 4 5 6 7	FD xml-fil 01 x IDENTIFIED        BY "doc".   02 x-value PIC 9.   02 y IDENTIFIED        BY y-name.     03 y-name PIC X.     03 y-value PIC 9.     03 z IDENTIFIED        BY z-name.       04 z-name PIC X.       04 z-value PIC 9.	1(r) 1 2(r) a 2 3(r) b 3	1(r) 1 5(r) a 5 6(r) b 6	1(r) 1 2(o) a 5 3(o) b 6

Comments:

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

• Reading via data item y supplies the next copy of the node with the name 'a'.

• The positions of data items y and z are irrelevant for the following START statement via y; only the position of data item x, which is superordinate to y, is relevant.

• As the position of data item x has not changed since the first START statement (see Example 12-51), the range is still the same. Since the values of keys y-name and zname are also unchanged, the assignment is the same as with the first START statement.

• The START statement permits positioning once more on one of the older siblings which have already been read (node 2). This is never possible with the READ statement; there only younger siblings would be contained in the range.

• The START statement transfers no data. Consequently the contents of the values be longing to y and z (y-value and z-value) are unchanged, but do not correspond to those of the nodes assigned by the new positioning (nodes 2 and 3).

INDEX phrase with START

START also permits the following to be specified after data-name-1:

INDEX {identifier-1 | integer-1}

The integer positive value specified determines which node from a number with the same element name is to be positioned on.

The INDEX phrase is also permitted for attribute nodes, although attribute names must be unique. If the nth attribute is to be read regardless of the name (i.e. IDENTIFIED USING), the INDEX phrase still makes sense for attribute names.

Example 12-53 INDEX phrase with START

XML document	Pos	COBOL data structure		OPEN DOCU- MENT xml-fil	START xml-fil ELE- MENT z INDEX 2	START xml-fil ELE- MENT u INDEX 3	START xml-fil ELE- MENT y
<doc>1   <a>2     <b>3</b>     <c>4       <d>5</d>       <d>6</d>     </c>     <c>7       <e>8</e>       <e>9</e>     </c>   </a>   <f>10</f> </doc>	1 2 3 4 5 6 7 8 9 10	FD xml-fil   01 x IDENTIFIED BY "doc".     02 x-value PIC 99.     02 y IDENTIFIED BY y-name.       03 y-name PIC X.       03 y-value PIC 99.       03 z IDENTIFIED BY z-name.         04 z-name PIC X.         04 z-value PIC 99.         04 u IDENTIFIED BY u-name.           05 u-name PIC X.           05 u-value PIC 99.	MOVE "a" TO y-name MOVE "c" TO z-name MOVE "e" TO u-name	1(o) 2(o) a 4(o) c inv e	1(o) 2(o) a 7(o) c 8(o) e	1(o) 2(o) a 7(o) c inv e	1(o) 2(o) a 4(o) c inv e
		FILE STATUS		00	00	23	00

Comments:

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

• The range of the first START statement via z is the subtree with the root node 2 (as the node which is assigned to the superordinate data item y).

• In the first step the children of node 2, i.e. nodes 3, 4 and 7, are checked for a possible assignment. Since 2 is specified as the index, not the first matching node (node 4) is assigned, but the second matching node (node 7).

• The index refers only to the data item specified in the START statement, not to the as signment of subordinate data items (u). Of the 2 copies with the name 'e', the first is assigned. If an INDEX phrase is also to be effective for subordinate data items, a corresponding START statement is required for each of these.

• The assignment procedure for the second start STATEMENT takes nodes 8 und 9 into consideration (as children of node 7, which is assigned to z), and therefore does not find as many nodes as requested (index 3, but only 2 matching nodes with the name 'e'). Consequently no node can be assigned. The position of the data item (u) is set to invalid and an invalid key condition exists.

• The third START statement’s range is the entire document. Positioning which has alrea dy taken place for subordinate data items (y, z, u) is irrelevant.

• In the case of the third START statement, no node can be assigned to the data item (u).
  As u is subordinate to data item y which is specified in the statement, this situation does not lead to an invalid key condition.