This topic describes the data interface and its use of HTTP, covering the following subjects:
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
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.
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:
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.
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.
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.
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. |
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 |
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.
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.
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:
'It''s raining again.'
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.
[[ Contents Previous Page | Next Page Index ]]