The XML interface of openUTM

XML (Extensible Markup Language) is a logical description language that enables documents to be structured into elements. XML allows users to define their own language syntax, e.g. by means of a DTD (Document Type Definition) or an XML schema (XSD).

The XML interface of openUTM (short: UTM-XML) is a program interface with which XML documents can be created, processed and read. In addition, XML documents can be validated against XML schemas.

This interface is called inside of UTM program units and is available for the program languages C, C++ and COBOL.

Each of the interfaces described in this section (KDCS, CPI-C or XATMI) can be used as a communication interface. UTM-XML can also be used in openUTM clients.

A simple usage scenario such as processing an XML document in the KDCS program unit might look like this.

1. Read data with MGET

   The XML document is read into the message area of an XML schema (XSD).

2. Process the data via the UTM-XML interface

   The XML document is converted into an object tree and the individual elements are processed. Once processing is complete, the XML object is converted back into an XML document.

   A separate structure (t_value structure) is used for data type conversion.

3. Send the XML document with MPUT

   The processed XML document is made available in the message area and is sent back to the submitter.

If an XML document is processed interactively in several dialog steps (= program units), the programmer must ensure that the context is preserved. There are two ways of doing this.

• The XML object is converted into an XML document and buffered in a suitable UTM storage area, e.g. KB, LSSB or GSSB, see "UTM storage areas".

• The program uses the KDCS call PGWT. PGWT prevents a process change and preserves the entire program context.

Overview: C/C++ calls of the UTM-XML interface

C/C++ call	Description
KXLInitEnv	Initialize the UTM-XML environment
KXLFromdatatype	Convert from datatype to the t_value structure (datatype= Short, Int, Long, Float, Double, Char, String, Struct, Array)
KXLTodatatype	Convert from the t_value structure to datatype (datatype= Short, Int, Long, Float, Double, Char)
KXLCreateNewObj KXLWrite	Create an XML object
KXLSetSubObject KXLSetRootNode KXLSetParentNode	Navigate in the XML object
KXLRead KXLReadNode KXLReadNextSib KXLReadChild KXLReadNextSingleNode KXLReadAttr	Read an XML object
KXLConvDocToObj KXLConvObjToDoc KXLFreeObj	Convert between XML object and XML document, release (free) an object
KXLGetHomeEnc KXLGetDocEnc KXLSetDocEnc KXLStringFromUTF8 KXLStringToUTF8	Determine/set character set and convert from/to UTF8
KXLWriteNS KXLDelNS KXLReadNSList KXLSearchNS	Manage namespaces
KXLGetSizeOfNodeList	Query size of a node list
KXLTSENV KXLGetLastParserError	Diagnostic functions
KXLConvDocToObjAndValid KXLParseSchema KXLParseSchemaFile KXLValidDoc KXLValidDocBuf KXLFreeSchema	Support for schema functionality (converting, parsing, validating, freeing)

COBOL interface

The COBOL interface is called via an adapter module. When it is called, the desired function is passed in the form of parameters and a COPY element is used to describe the parameter area. This area must be supplied prior to the call. The parameters correspond to the parameters of the associated C function.

The COBOL interface, in contrast to the C/C++ interface, contains the additional function KXLSchemaGetRoot with which the root node of the schema object can be requested. In C/C++ this can be implemented directly using language resources.

You will find more information on the UTM-XML interface in the manual „XML for openUTM“.