The data interface and HTTP

This topic describes the data interface and its use of HTTP, covering the following subjects:

HTTP request URL format

The data interface commands are an extension of the existing Web User Interface commands, and use the HTTP URL to specify the command. All data interface commands are of the form:

/CICSPlexSM/ENU1/userid/DATA/command
ENU1
Specifies the client code page identifier as ENU1 for US English. Although the CICSPlex® SM Web User Interface supports the languages and code pages, the data interface always uses ISO-8859-1 code page.
userid
Specifies the user ID of the user signed on to the Web User Interface server.
DATA
This indicates that the request is a data interface command.
command
Specifies the name of the data interface command. This can be one of the commands listed in Table 11

The elements in this portion of the command structure are not case sensitive.

You specify the additional options you need on the command as a standard URL-encoded query string. For all except the CONNECT command, you use the HTTP GET method, and therefore the options appear after the URL, as shown in the following DATA/FETCH example:

/CICSPlexSM/ENU1/user1/DATA/FETCH?option1&...&...

For the DATA/CONNECT command, you use the POST method. In this case, the Web User Interface server expects the Multipurpose Internet Mail Extensions (MIME) type of the body to be application/x-www-form-urlencoded, and the URL-encoded HTTP query string to be delivered as the body of the POST request (that is, the command looks like an HTML form submission from a browser).

For more information about accessing a Web User Interface server using HTTP requests, see Access to the Web User Interface.

HTTP responses and codes

When a client application has established successfully a TCP/IP socket connection with a Web User Interface server, the server responds to a data interface command with an HTTP response, which could contain an error response code.

If the HTTP response code is 200 (OK), the body of the HTTP response contains the response to the command issued by the client application. The responses consist of one or more self-describing records encoded using standard URL-encoding, which the client application should inspect and take appropriate action.

The Web User Interface server sets the MIME type for the contents of an HTTP 200 response from the data interface to application/x-ibm-eyu-data-urlencoded. If the client application receives an HTTP response code of 200, but the MIME type for the contents is not application/x-ibm-eyu-data-urlencoded, it is for one of the following reasons:

If the HTTP response code is not 200, the body of the HTTP response can be ignored by the client application. In this case, the body is likely to be an HTML page generated by an HTTP proxy or a Web User Interface server for display by a Web browser. The client application is responsible for interpreting the HTTP response code and taking the appropriate action. For example, the following are two HTTP responses that can be generated by a Web User Interface server:

404 - Not found
The resource specified by the HTTP URL cannot be located.
503 - Service temporarily unavailable
The Web User Interface server address space is active (that is, CICS® is running and the port is open) but the Web User Interface server application is not currently running.

Other HTTP error responses (for example, response code 500--Internal server error) generated by the Web User Interface server are exception conditions that might require additional diagnostic information. Useful sources of such information are the Web User Interface server messages, logged in the EYULOG data set, and the exception trace entries written by the server to the CICS auxiliary trace data sets. If the client application is connecting through a proxy, the HTTP error response could be from the proxy, not from the Web User Interface server.

Response records

Each data interface response contains a single header record followed by zero or more data records. If the response contains multiple records, each record is separated from the next by a new-line sequence. For an illustration of the structure an HTTP response from a data interface request, see Figure 41.

Your client application encodes data interface command options using standard URL-encoding, and the Web User Interface server uses the same techniques for response records. For example, two record fields and their values are expressed as follows:

field1=value1&field2=value2

You encode special characters in field names and values (including space, &, and =) using escape characters that follow the escaping scheme described in the URL specification. The URL escaping scheme specifies that escaped characters are represented by a % (percent sign) followed by 2 hexadecimal digits (in ASCII code). (For information about encoded strings, where some characters can be escaped using "% HEX HEX" see the Uniform Resource Locators (URL) memorandum, RFC1738, at www.ietf.org/rfc/.)

The data interface encodes all data flows in the ISO-8859-1 code page, using the Web User Interface ENU1 conversion table and follows a standard character representation, regardless of the Web User Interface server's current language or locale settings. You do not need to ensure that the client is using same language and code page as the server. However, your client application might have to convert some character representations used by the data interface to those required by the client application; for example, if you want to use different separator characters for time and date fields.

Response header fields

A successful HTTP response does not mean that the command was successful: it indicates only that the Web User Interface server was able to interpret the command and the result status is indicated in the header record. Each header record contains at least the fields shown in Table 12. There can also be other header fields, as described for individual commands under Data interface command reference. The order in which header fields appear in the header record is undefined.

Table 12. HTTP header record base fields
Header field Description
CMASSYSID SYSID of the CMAS to which the Web User Interface server is connected, if known.
CPSMREL The version and release number character string of CICSPlex SM.
SERVERAPPLID The CICS APPLID of the Web User Interface server.
STATUS Main response status indicator. See Table 13 for details.
TASKID The task identifier of the CICS task that generated the response.
Table 13. HTTP header record STATUS values
Status Meaning
BADCOMMAND The specified command is unknown.
BADTICKET The ticket (cookie) was invalid or missing. This could be, for example, because the user session has expired.
FAILURE The command failed with an undefined errror.
OK The command executed successfully, and additional header fields can contain the results, depending on the command.
TIMEOUT The command timed out. See Dealing with time out failures

Dealing with time out failures

It is possible that a data interface command, especially a GET command, can take a significant amount of time. One effect of this is that, by the time the response is available, the HTTP socket connection between the client application and Web User Interface server could have expired. To avoid this situation, the Web User Interface server can respond early with a status of TIMEOUT, while continuing to process the original request.

To retrieve the results of the original request, the client application should reply to a TIMEOUT response by sending another request to the server. On this new request, the client application specifies the TIMEOUTTOKEN query string and value taken from the TIMEOUT response. If the server receives a request with a TIMEOUTTOKEN, it either sends the response built for the original request or, if it is still not ready after a further period of time, sends another TIMEOUT response.

If a client application fails to reply to a TIMEOUT response, the results of the original request become inaccessible, but continue to use the resources of the user session. It is important, therefore, for the client application to reply to all TIMEOUT responses.

Note:
The TIMEOUTTOKEN value is a "black box" to the client application, which should return the TIMEOUTTOKEN to the server unaltered. The client application should also assume that the TIMEOUTTOKEN value is variable length to protect against possible change in a future release of the data interface.

Data interface stubs

To correlate a sequence of requests relating to a result set, the data interface uses a STUB header for DATA/GET, DATA/FETCH, and DATA/DISCARD commands. The stub header is similar to a CICSPlex SM API result set token, except it is valid for one request only. Each DATA/GET and DATA/FETCH command generates a new STUB header and the client application must use the new value on its next request against the result set. Failure to use the correct STUB value results in a BADSTUB response.

The Web User Interface server manages each active data interface result set as a single user session window. Each user session can have a maximum of 64 windows active at anyone time, and these are shared between the client application data interface and the HTML browser interface.

The Web User Interface server creates a new result set in response to a DATA/GET command that omits the STUB option. The client application can request the server to replace the contents of a result set with the result of a new query by issuing a DATA/GET command that specifies the STUB value of an existing result set.

Data representation

The representation used for CICSPlex SM resource table attributes depends on the attribute types. In general, the representation is as documented in the CICSPlex SM Resource Tables Reference. However, note following conventions used by the data interface:

Decimal points
These are always represented by a . (period).
Time and date fields
The separator for time fields is always a : (colon), and the separator for dates is always a / (slash). The representation used for dates is always of the form YYYY/DD/MM.
Non-printable characters
Character strings that contain non-printable characters are expressed in a quoted hexadecimal format. For example, 'DDFF0400DDFF0400'X .
Special characters
Character strings that contain special characters (such as an apostrophe, for example) are expressed as quoted strings. In the following example, the phrase It's raining again, which contains a single apostrophe, is encoded as follows :
'It''s raining again.'

The data records

The body of an HTTP response from a data interface request always contains a header, and can also return one or more data records following the HTTP header. The description of each individual command states which commands return data records (see Data interface command reference ). The structure of the complete HTTP response to a data interface request is shown in Figure 41, which illustrates the response to a DATA/FETCH request.

Figure 41. Structure of an HTTP response to a data interface request
 This diagram illustrates the various elements that make up the structure of an HTTP response. The whole respresents the complete HTTP package, which consists of an HTTP header and an HTTP body. The HTTP body is further split into the data header and data records.
[[ Contents Previous Page | Next Page Index ]]