Function
The IDENTIFIED clause defines which element or attribute names from the XML document a COBOL data item can assign itself. The NAMESPACE phrase defines the namespaces which must be taken into account.
Format
IDENTIFIED {BY {data-name-1 | literal-1} | USING data-name-2} IS {ATTRIBUTE | ELEMENT}
[ NAMESPACE {IS {data-name-3 | literal-2 | NULL} | USING data-name-4}]
Syntax rules
The IDENTIFIED clause may only be specified in record description entries of files with organization XML.
All the group items which are superordinate to the data description entry must also include an IDENTIFIED clause.
literal-1 and literal-2 must be alphanumeric or national literals, but not figurative constants.
literal-1 must be a valid XML name for an element or an attribute.
literal-2 must be a valid XML name for a namespace.
data-name-1, data-name-2, data-name-3 and data-name-4 may be qualified.
data-name-1, data-name-2, data-name-3 and data-name-4 must be alphanumeric or national data items. Their data description entry may not specify an IDENTIFIED clause.
If data-name-1, data-name-2, data-name-3 and data-name-4 are specified in a record description entry of a file with organization XML, they must be directly subordinate to the entry with the IDENTIFIED clause which references them.
No data description entries with an IDENTIFIED clause may be subordinate to a data description entry with an ATTRIBUTE phrase.
At most one data item which is neither referenced in the IDENTIFIED clause nor is itself an IDENTIFIED clause may be directly subordinate to a data description entry with an IDENTIFIED clause.
The table below specifies which combinations of phrases for the element or attribute name and specifications for the namespace are permitted within an IDENTIFIED clause.
IDENTIFIEDNAMESPACE
IS
NULLIS
data-name-3 /
literal-2USING
data-name-4BY data-name-1 /
literal-1permitted
permitted
forbidden
USING data-name-2
permitted
forbidden
permitted
Table 43: Permitted combination of IDENTIFIED and NAMESPACE phrases in an IDENTIFIED clause
If multiple data description entries which have the ELEMENT phrase are directly subordinate to a group item, the possible phrase for IDENTIFIED and NAMESPACE are subject to further restrictions. The same applies for data description entries which specify the ATTRIBUTE phrase. The table below shows which combinations are permitted in the case of two data description entries. The rows and columns highlighted in gray present combinations which are not permitted for a single data description entry.
Table 44: Permitted combination of two data description entries with IDENTIFIED and NAMESPACE phrases
If multiple data description entries which all specify the same explicit or implicit NAMESPACE phrase are directly subordinate to a group item, the following applies:
The values of literal-1 must be unique for all entries which specify or imply the ELEMENT phrase.
The values of literal-1 must be unique for all entries which specify the ATTRIBUTE phrase.
Neither the representation as an alphanumeric or national literal nor trailing blanks play a role for the uniqueness here.
If ATTRIBUTE is not specified, ELEMENT implied.
The IDENTIFIED clause may not be used in a type declaration entry.
General rules
The IDENTIFIED clause describes which nodes from the XML document are to be assigned to the data item:
If ELEMENT is specified, only element nodes are assigned.
If ATTRIBUTE is specified, only attribute nodes are assigned.
If BY is specified, literal-1 or the content of data-name-1 defines the name which the assigned node is to have. Neither the representation as an alphanumeric or national literal or data item nor trailing blanks are relevant here.
If IS is specified, literal-2 or the content of data-name-3 defines the namespace which the assigned node is to have. Neither the representation as an alphanumeric or national literal or data item nor trailing blanks are relevant here.
If USING is specified, the assigned nodes may have any names and may be located in any namespaces. When reading is successful, the names of such nodes are transferred to data-name-2, or the associated namespace is transferred to data-name-4.
A node can be assigned to a data item only if a node is also assigned to all the data items which rank higher than it does in the structure.
The NAMESPACE specification defines the name pace for an entry and for all data items which are subordinate to it and have an IDENTIFIED clause with an explicit or implicit ELEMENT phrase.
If a subordinate data item also has a NAMESPACE phrase, this specification has priority over a NAMESPACE phrase in the superordinate group item.
NAMESPACE NULL means an empty string as namespace. If the NAMESPACE phrase is missing, and if no superordinate group item has a NAMESPACE phrase, NAMESPACE NULL is implied.
If an OPEN DOCUMENT, READ or START statement references a group item, the following conditions must be fulfilled for this group item and all group items which are subordinate to it:
If a node from the XML tree can be assigned (see "Assigning nodes" in section "Statements for XML processing") to a data description entry which is directly subordinate to the group item, this assignment must be unique. In other words no other data description entry which is directly subordinate to the group item may exist to which the node from the tree could also be assigned.
Neither the description of the nodes’ names as alphanumeric or national literals or as data items is relevant with regard to uniqueness, nor are trailing blanks. If the uniqueness is not provided, the statement is not successful, and the I-O status of the file is set to 4C.
The complete name of the namespace, the Uniform Resource Identifier (URI), must always be made available, or it is returned. The prefixes used in XML are not visible in COBOL.
In an XML document namespace declarations have the form of an attribute, but they not supplied as attributes, even if they are described accordingly in an IDENTIFIED clause.