HTTP Services

HTTP services are provided via http.i (implicitly included by html.i and xml.i) and are common services used to create programs that traffic data through websage. They deal primarily with the details of the HTTP protocol (coding, decoding, intepretting, etc)

Table of Contents

• Introduction
• Control Functions
• File Handling
• Encoding Tools
• Token Processing

Introduction

WebSage provides the transport and basic services for invoking Progress programs in response to a HTTP request

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 '...'), 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

(returns CHARACTER) GET CONTENT_TYPE theType
Returns a content type string for the passed content type. The two most common types are "HTML" and "XML". If you want another type, you'll need to specify a complete MIME compatible type your self (i.e. "application/x-document").

SET HTTP_FIELD theField theValue
Sets the value of the named HTTP field to the passed value. If the field already existed, it's existing value is discarded and replaced with the new value. If the field did not exist, it is created and the value attached. In general, you should really avoid using this function as it has the most ephemeral context possible.

(returns CHARACTER) GET HTTP_FIELD fldName
Returns the value of a specified field from the posted client connection. Fields can come as the result of a MIME element part submission or may be passed along on the requests URL line. If the passed field name doesn't exist, an empty string is returned.

(returns CHARACTER) GET HTTP_FIELD_LIST

Returns a list of all currently defined HTTP fields. The list is comma seperated and if there are no HTTP fields currently defined, an emptry string is returned.

(returns CHARACTER) GET MIME_ELEMENT_LIST

Returns a list of all currently defined known MIME elements. The list is comma seperated and if there are no MIME elements currently defined, an empty string is returned. MIME elements are only created as the result of submission of a MIME_FORM_START based form and the use of one or more FILE_FIELD tags.

(returns CHARACTER) GET MIME_ELEMENT_INFO elementName
Returns informationed on the specified MIME element name. If the passed name doesn't exist, an empty string is returned. If the element does exist, a list is returned. The list uses the pipe | character as a delimiter and is compatible with the Progress list handing functions. The elements in the list are as follows:

1. Name of element (should be same as passed)
2. Content type of element (as specified by the browser). This can be blank, depending on the browser.
3. File name of the contents of the element on the server (accessible to your program). This is a temporary file which will automatically and always be deleted when this web request completes (i.e. you return).
4. File name of the file on the users workstation. This is generally not too useful, but you might want to know what the file was called for later use. This can be blank, depending on the browser.
5. Size of file, in bytes

(returns CHARACTER) GET PAYLOAD_TYPE
Returns the type of payload from the most recent HTTP POST operation that did not receive standard web page posted material and also didn't receive MIME encoded (i.e. "other data"). This is the HTTP specified content type (like "text/xml" or "text/html"). If this is blank, there either wasn't any POSTed data or it was in an understood format (available via GET HTTP_FIELD or GET MIME_ELEMENT_INFO).

(returns CHARACTER) GET PAYLOAD_FILENAME
Returns the name of the local file that contains the payload from the most recent HTTP POST operation that did not receive standard web page posted material and also didn't receive MIME encoded (i.e. "other data"). This file is transitory and will automatically be deleted at the completion of this request. If this is blank, there either wasn't any POSTed data or it was in an understood format (available via GET HTTP_FIELD or GET MIME_ELEMENT_INFO).

(returns INTEGER) GET PAYLOAD_FILESIZE
Returns the size of the local file that contains the payload from the most recent HTTP POST operation that did not receive standard web page posted material and also didn't receive MIME encoded (i.e. "other data"). This file is transitory and will automatically be deleted at the completion of this request. If this is -1, there either wasn't any POSTed data or it was in an understood format (available via GET HTTP_FIELD or GET MIME_ELEMENT_INFO).

File Processing