TRANSFORM XMLTODATA

Description

The TRANSFORM XMLTODATA command can either transform XML to application data or query XML to return information about the XML elements to the application program. The XMLTRANSFORM resource defines the location of the XML binding and schema for transforming the XML to application data. If you do not specify an XMLTRANSFORM resource on the command, CICS queries the XML instead.

Options

CHANNEL(data-value)

Specify the 16-byte name of the channel used to pass the containers holding the XMLCONTAINER and DATCONTAINER data. The name of the channel must be 16 characters in length. If the channel name is less than 16 characters, you must pad the data value with trailing blanks.

DATCONTAINER(data-value)

Specify the 16-byte name of the output container that CICS populates with the converted data. The name of the container must be 16 characters in length. If the container name is less than 16 characters, you must pad the data value with trailing blanks.

CICS® populates this container in BIT mode.

ELEMNAME(data-area)

Specify an input value to return the name of an XML element. CICS populates the ELEMNAME option with the local name of the first XML element that it finds in the XMLCONTAINER container. The application must also specify an input value for the ELEMNAMELEN option that indicates the maximum length of the data area.

ELEMNAMELEN(data-area)

Specify an input value to return the fullword binary length of the XML element in the ELEMNAME option. CICS updates the value of the ELEMNAMELEN option to indicate the real length of the element name that it finds.

ELEMNS(data-area)

Specify an input value to return the namespace URI of the XML element to which the ELEMNAME option refers. CICS populates this parameter with the namespace URI of the first XML element that it finds in the XMLCONTAINER container. The application must also specify an input value for the ELEMNSLEN option that indicates the maximum length of the data area.

ELEMNSLEN(data-area)

Specify an input value to return the length of the ELEMNS option. CICS updates the value of the ELEMNSLEN option to indicate the real length of the namespace URI.

NSCONTAINER(data-value)

Specify the 16-byte name of the container that contains a list of XML namespace declarations that are in scope. These XML namespace declarations can be referenced in the body of the XMLCONTAINER container. The container must be populated in CHAR mode.

TYPENAME(data-area)

Specify an input value to return the xsi:type of the XML element referred to by the ELEMNAME option. This parameter is populated by CICS with the local name of the xsi:type attribute of the first XML tag that is found in the XMLCONTAINER container. If the first XML tag does not have an xsi:type attribute, this parameter remains empty. If the application supplies a value for the TYPENAME option, this value overrides any element and type information in the supplied XML and CICS attempts the transformation using the type name supplied by this application (together with the associated TYPENS option).

TYPENAMELEN(data-area)

Specify an input value to return the length of the TYPENAME option.

TYPENS(data-area)

Specify an input value to return the namespace of the xsi:type attribute of the XML element to which the ELEMNAME option refers. This parameter is populated by CICS with the namespace of the xsi:type attribute of the first XML element that is found in the XMLCONTAINER container.

TYPENSLEN(data-area)

Specify an input value to return the length of the TYPENS option.

XMLCONTAINER(data-value)

Specify the 16-byte name of the input container that contains the XML to be converted. This container must already exist and be populated in CHAR mode. If it is populated in BIT mode, CICS tries to determine the data encoding.

XMLTRANSFORM(name)

Specify the 32-byte name of the XMLTRANSFORM resource that CICS uses to transform the data to XML. The resource defines the XML binding and the XML schema. The name of the XMLTRANSFORM resource must be 32 characters. If the resource name is less than 32 characters, you must pad the value with blanks.

If you do not specify the XMLTRANSFORM option, no data transformation occurs. Instead, the application queries the XML. CICS returns the XML element and type information in the ELEMNAME, ELEMNS, TYPENAME, and TYPENS options.

Conditions

NOTFND

RESP2 values:

1

The XMLTRANSFORM was not found.

CHANNELERR

RESP2 values:

1

The channel specified by the CHANNEL parameter is incorrect.

2

The channel specified by the CHANNEL parameter was not found.

CONTAINERERR

RESP2 values:

1

The container specified by the XMLCONTAINER parameter was not found.

2

The container specified by the NSCONTAINER parameter was not found.

3

The container specified by the DATCONTAINER parameter was not found.

LENGERR

RESP2 values:

1

The data in the container specified by the DATCONTAINER parameter is too short for the specified transformation type.

2

The ELEMNAME buffer is too small.

3

The ELEMNS buffer is too small.

4

The TYPENAME buffer is too small.

5

The TYPENS buffer is too small.

INVREQ

RESP2 values:

1

The XMLTRANSFORM resource is not enabled.

2

The XMLCONTAINER container is empty.

3

The XML input data is incorrect. For more information, see the error message in the DFH-XML-ERRORMSG container.

4

The XML input data cannot be converted. For more information, see the error message in the DFH-XML-ERRORMSG container.

5

The application data is incorrect. For more information, see the error message in the DFH-XML-ERRORMSG container.

6

The application data cannot be converted. For more information, see the error message in the DFH-XML-ERRORMSG container.

7

Either the XML container or the NAMESPACE container is not CHAR mode.

9

The XMLTRANSFORM does not support the requested XML element.

10

The XMLTRANSFORM does not support the requested XML type.

11

There was a problem linking to a vendor-supplied transformer program.

13

The CHANNEL parameter was not supplied and is required.

14

The ELEMNAME parameter was not supplied and is required.

15

The ELEMNS parameter was not supplied and is required.

16

The DATCONTAINER parameter was not set and is required.

17

There is a runtime validation failure.

18

There is a container datatype error.

101

The user is not authorized to use the XMLTRANSFORM.