XML Services

The XML services provide a set of tools for sending and receiving XML documents via HTTP. Actual construction and parsing of XML documents is not covered here, just the moving of XML data via HTTP.

Table of Contents

Introduction

XML files can be moved between applications in many ways (flat files, network connections, etc). One common way XML documents are moved is via the HTTP protocol. The HTTP protocol is easy to use, reasonably simple in form, well understood and easily passed by most firewalls. It can also integrate in a machines web server and benefit from that servers ability to log connections, activate programs and enforce security.

Sending an XML file to a destination is very, very easy using the EXPORT_FILE and EXPORT_XML services. Receving an XML file is a bit different as the underlying HTTP protocol wasn't orignally designed to handle arbitrarily large amounts and varied types of data. As a result, a method for encapsulating received data was devised that used MIME - a standard for encoding multi-part data.

When you receive a XML request, the "onPresentPage" IP in your web object is invoked. You can then interrogate supplied name/value pairs with the GET HTTP_FIELD service as well as see if there are any data supplied via MIME encoding using GET MIME_ELEMENT_LIST. Each MIME encoded item is stored in a transitory file and is available in that file only for the duration of the call to onPresentPage. Using GET MIME_ELEMENT_INFO, you can get access to the actual file for processing. If you expect to receive XML, you can also use the IMPORT_XML command to import a named MIME element into a XML DOM handle.

Other miscellaneous services handle encoding data (URL_ENCODE, XML_ENCODE) and support for token processing. Token processing allows you to use a static file that has token references in it and export it to the client with that token names replaced with runtime supplied values.

For writing your own data out to the client (including the required CONTENT_TYPE 'XML'), use the {&WRITE} function much like you'd use PUT STREAM ... UNFORMATTED. It will correctly direct the contents to the client with no formatting of the data - what you write is exactly what is sent.

Control Services

DEFINE
Define the context needed for the XML services. You must include this call at the start of each source module that uses the XML services

File Processing

(returns LOGICAL) EXPORT_XML xmlHandle
Causes the supplied XML DOM (Document Object Model) represented in the passed handle to be converted to XML text format and sent to the current client. If the XML DOM is successfully sent, TRUE is returned. If there is an error (a bad DOM, band handle, etc), then FALSE is returned.

(returns HANDLE) IMPORT_XML PAYLOAD [strictFlag]
(returns HANDLE) IMPORT_XML MIME mimeElementName [strictFlag]
Imports the value of a payload or MIME element into a new XML DOM. If fromFlag is PAYLOAD, then the XML is imported from the payload data, if any. If the fromFlag is MIME, the next field is the MIME element name to import from. If the strictFlag is set, strict XML interpretation of the XML document is done. You can check the ERROR-STATUS:ERROR attribute on return to see if there were errors and what sort of errors there were. strictFlag is optional and if omitted, default to No. If the XML document is successfully read, a handle to the main XML X-DOCUMENT is returned. If the element specified doesn't exist or there are serious errors in parsing the file, NULL (?) is returned.

Last updated on July 18, 2000