Your Browser is not longer supported

Please use Google Chrome, Mozilla Firefox or Microsoft Edge to view the page correctly
Loading...

{{viewport.spaceProperty.prod}}

Namespace

Qualified names in XML documents consist of a local name and a namespace within which the local name must be unique. The namespace is specified like an attribute in the case of an element:

  • It can define a standard namespace: xmlns="..."
    This standard namespace applies for this element and all subordinate elements provided no other namespace is specified there in an element name, but not for attributes.

  • It can be completely disabled: xmlns=""
    This empty namespace also applies for this element and all those subordinate to it, provided nothing else is specified there.

  • It can define an abbreviation (prefix) for a (non-standard) namespace: xmlns:prefix="..."
    This is also be permitted more than once using different prefixes to make more than one namespace available.
    Such a prefix may precede the local name in this element, all the subordinate elements and also in the attributes of these elements in order to form a unique, qualified name with the format prefix:local-name.

The element and attribute names listed in the IDENTIFIED clause always describe the local name. The optional NAMESPACE phrase in the IDENTIFIED clause is used for processing namespaces from the XML document. For the element or attribute described, it permits:

  • a required namespace to be predefined:
    NAMESPACE IS {data-name-3 | literal-2}

  • arbitrary namespaces to be accepted:  NAMESPACE USING data-name-4
    The effect is the same as for the USING phrase in IDENTIFIED: the namespace which is read is returned in data-name-4.

  • the empty namespace to be defined:  NAMESPACE IS NULL


The implicit effect of namespaces for subordinate elements of an XML document is reflected in COBOL:

  • The NAMESPACE phrase of an IDENTIFIED clause applies for the specified data item and is inherited by all subordinate data items with an IDENTIFIED clause and ELEMENT phrase, but not by data items with the ATTRIBUTE phrase.

  • When a subordinate data item specifies a NAMESPACE phrase itself, this has priority over any that may have been inherited.

  • If the NAMESPACE phrase is missing at level 01 in an IDENTIFIED clause, this is equivalent to the NAMESPACE NULL phrase.


The prefixes which can be used as abbreviations in XML notation have nothing to do with the NAMESPACE in COBOL. They are not visible in COBOL.

The COBOL statements always use the 'complete' value from the xmlns specification in the XML document as the value for a namespace, never the prefix.

The distinction on the XML side between standard namespaces and namespaces specified with prefixes is irrelevant on the COBOL side because no prefixes exist there.


The possible combinations of the BY and USING phrases in the case of local names and namespaces are subject to particular restrictions. Here it is irrelevant whether the NAME-SPACE phrase is specified or implied. On the one hand the restrictions affect the phrases within a single IDENTIFIED clause. On the other hand they affect the combination of two or more data description entries with IDENTIFIED clauses of the same type (ELEMENT or AT-TRIBUTE), provided they are directly subordinate to the same data item in the COBOL structure.

The table below provides an overview of the permitted combinations of BY and USING phrases in an IDENTIFIED clause with any specification of the type (ELEMENT or ATTRIBUTE):

The table below provides an overview of the permitted combinations of BY and USING phrases in two data description entries with IDENTIFIED clauses of the same type. In other words the prohibitions only apply within the set of IDENTIFIED clauses which all specify the ELEMENT phrase or all specify the ATTRIBUTE phrase. There are no restrictions for mixtures. It is therefore permissible to subordinate two data items with IDENTIFIED BY ...ATTRIBUTE and IDENTIFIED USING...ELEMENTE directly to one data item.

(1)

IDENTIFIED clause is already invalid

(2)

Invalid because of combination of BY and USING

(3)

More than one IDENTIFIED clause with USING invalid

The procedure for assignment described above is not affected by namespaces. However, the namespaces must be taken into consideration as prerequisites for assigning a single node.

The following prerequisites therefore apply for assigning a node from the tree to a data item:

  • The same type of node in the tree and in the IDENTIFIED clause of the data item (i.e. both are element nodes or attribute nodes)

  • The local name specified in the IDENTIFIED clause must be the same as the local name of the node in the tree:

    • In the case of a BY phrase the names must be identical, except for trailing blanks.

    • In the case of a USING phrase any name from the tree is regarded as matching.

  • The namespace specified in the IDENTIFIED clause must match the namespace of the node in the tree (here it does not matter whether the NAMESPACE phrase was specified for the data item or was inherited; the same applies for the namespaces in the XML tree):

    • In the case of an IS phrase the namespaces must be identical, except for trailing blanks.

    • In the case of a USING phrase any namespace from the tree is regarded as matching, also the empty namespace.

    • If NULL is specified, the node in the tree must have an empty namespace.

Example 12-55 Predefined NAMESPACE

XML document

Pos

COBOL data structure

OPEN
DOCUMENT
xml-fil

READ
xml-fil
ELEMENT x

<doc xmlns="http://www.abc"
     xmlns:r="http://www.efg">
  <a>2</a>
  <b>3</b>
  <r:c>4</r:c>
</doc>

1

2
3
4

FD xml-fil
01 x IDENTIFIED BY "doc"
     NAMESPACE "http://www.abc".
02 y IDENTIFIED BY "a"
     NAMESPACE "http://www.abc".
  03 y-value PIC 9.
02 z IDENTIFIED BY "c".
  03 z-value PIC 9.
02 u IDENTIFIED BY "b"
     NAMESPACE NULL.
  03 u-value PIC 9.


1(o)

 2(o)


 inv

 inv


1(r)

 2(r)

2
inv

 inv



FILE STATUS

00

08

Comments:

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

  • Node 1 and data item x specify the same namespace. As the element names are also identical, node 1 can be assigned.

  • The NAMESPACE phrase for data item y is actually superfluous because it is identical to that of the superordinate data item x. If it did not have its own phrase, y would inherit the namespace of x.

  • Node 2 inherits the standard namespace of node 1 and consequently has the same namespace as data item y. As the element names are also identical, node 2 can be assigned.

  • Node 3 and data item u do have the same local name (b), but node 3 inherits the namespace http://www.abc, while data item u requests the empty namespace. Node 3 can therefore not be assigned.

  • Node 4 and data item z also have the same local name (c). However, node 4 specifies the namespace http://www.efg, while data item z, as an element without its own NAMESPACE phrase, inherits the namespace http://abc of the superordinate data item x. As the namespaces are different, node 4 cannot be assigned.

  • When reading via x, nodes 3 and 4 can never be assigned and cause I-O status 08.

Example 12-56 Arbitrary NAMESPACE

XML document

Pos

COBOL data structure

OPEN DOCUMENT
xml-fil

READ xml-fil
 ELEMENT x

READ xml-fil
 ELEMENT y

<doc
  xmlns:r=
  "http://www.efg">
  <a>2</a>
  <r:c>4</r:c>
</doc>

1


2
3

FD xml-fil
01 x IDENTIFIED
      USING x-name
     NAMESPACE
      USING x-nsp.
  02 x-name PIC XXX.
  02 x-nsp PIC X(14).
  02 y IDENTIFIED
        USING y-name
       NAMESPACE
        USING y-nsp.
    03 y-name PIC XXX.
    03 y-nsp PIC X(14).
    03 y-value PIC 9.


1(o)





 2(o)


1(r)



 doc
'BLANK' (x14) 1
2(r)


a'BLANK''BLANK'
'BLANK' (x14) 1
2


1(r)


doc
'BLANK' (x14) 1
3(r)
c'BLANK''BLANK'
http://www.efg
4



FILE STATUS

00

00

00

1 The symbol is repeated 14 times.

Comments:

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

  • Neither the element name nor the namespace stipulate requirements. Consequently all nodes can in principle be assigned. For this reason the first READ statement (unlike in Example  12-55) supplies I-O status 00.

  • Node 1 has no (i.e. an empty) namespace: for the transfer to data item x-nsp it acts like a sending item with the size zero. Hence the blanks in x-nsp. The same applies for node 2 and y-nsp.

  • The second READ statement reads node 3: only the local name 'c' is supplied in y-name as the element name. The complete namespace is supplied from the associated xmlns phrase (in the case of node 1) as namespace. Prefix 'r' which is used as the abbreviation is not visible in COBOL.

Powered by Atlassian Confluence and Scroll Viewport.