HTTP header reference for CICS Web support

In CICS® Web support, when messages are sent out from CICS, some HTTP headers are provided automatically by CICS, and some can be added by the user. When messages are sent to CICS, CICS takes action in response to some HTTP headers, and a user application program can take action in response to others. This reference describes how CICS Web support handles HTTP headers.

The standard HTTP headers are described in the HTTP/1.1 specification (RFC 2616) and the HTTP/1.0 specification (RFC 1945). There are many possible HTTP headers, including extension headers that are not part of the HTTP protocol specifications. For fuller listings, you should consult the HTTP specification to which you are working. The HTTP protocol has more information about the HTTP specifications.

This topic explains the general use of HTTP headers in CICS Web support, and the actions that CICS Web support takes for specific headers. Check the HTTP specification to which you are working for detailed guidance and requirements about how you should use HTTP headers, such as the correct format for header values, and the contexts in which each header should be used.

HTTP headers on messages received by CICS

• When an HTTP request or response is received by CICS, some of the HTTP headers are used to determine actions that CICS Web support takes. Table 1 shows the actions taken by CICS for headers on an HTTP request. Table 2 shows the actions taken by CICS for headers on an HTTP response. Other headers are not used by CICS, and it is up to the user application to take appropriate action in response to these.
• All headers received for a message, whether or not they have been used by CICS, are made available to a user application for inspection using the WEB READ HTTPHEADER command and the HTTP header browsing commands. CICS does not alert the user application to the presence of any particular header on a message. Ignore any headers that the application does not need or understand.
• CICS already deals with the MUST level requirements in the HTTP/1.1 specification relating to actions that the server or client must perform on receiving a message. Because of this, you may receive and use a request or response without examining the headers. However, you will probably need to examine the headers for information relating to actions that you take in future communications with the Web client or server.

HTTP headers on messages sent out from CICS

• On an HTTP request or response that is sent out from CICS with HTTP/1.1 as its version, CICS automatically supplies key headers that should normally be written for a basic message to be compliant with the HTTP/1.1 specification. On an HTTP response with HTTP/1.0 as its version, CICS automatically supplies a smaller number of headers. Some of these headers are generated by CICS for every message, and some are produced because of options that you specify on the WEB SEND command in a user application program. Table 3 and Table 4 list the headers that are written for each HTTP version, and the source of the header.
  If the user application program writes a header that CICS also generates, CICS handles this depending on the situation:
  

  • For CICS as an HTTP server, if the header is appropriate for a response, CICS does not overwrite it, but allows the application's version to be used.
  • For CICS as an HTTP client, if the header is appropriate for a request, CICS does not allow the application to write it, and returns an error response to the WEB WRITE HTTPHEADER command. The exceptions are the TE header and the Content-Type header. Application programs can add further instances of the TE header. They can also supply the Content-Type header, if the required header needs to contain spaces or more than 56 characters, and so cannot be specified on the MEDIATYPE option of the WEB SEND command.
  • If the header is not normally appropriate for the type of message (request or response), CICS allows it, as is the case for all user-defined headers. This situation should not occur if your message is compliant with the HTTP specification to which you are working.
• A user application program can add further HTTP headers to a request or response using the WEB WRITE HTTPHEADER command. CICS tolerates and passes on any additional HTTP headers. Note that for CICS as an HTTP server, if you are providing a static response with a CICS document template or HFS file, headers cannot be added to the response beyond those that are automatically supplied by CICS.
• CICS does not check the name or value of user-written headers. You should ensure that your application program is providing correct, and correctly formatted, information in a way that meets the HTTP specification to which you are working. Be particularly careful to check the HTTP specification for applicable requirements if your application is performing complex actions. There are likely to be important (MUST or SHOULD level) requirements to provide certain headers to describe these actions. For example, special HTTP headers are required if you are:
  • Responding to, or making, conditional requests using the modification date of the document or an entity tag.
  • Varying the content of a response according to the client capability or national language requirements of the Web client.
  • Providing a response, or making a request, that involves a range of a document rather than the full document.
  • Providing cache control information for a response.
  The use of certain status codes on your response might also require particular HTTP headers. For example, if you use the status code 405 (Method not allowed), you must use the Allow header to state the methods which are allowed. HTTP status code reference for CICS Web support has more information about the use of status codes.

Examining the request line for an HTTP request

CICS® stores the request line used for each HTTP request, for the application program to access if needed. An application program can use the WEB EXTRACT command to extract components of the request URL (including the path, host name, port number and query string), the method used for the request, or the HTTP version of the request. Non-HTTP requests can also be identified in this way.

HTTP requests explains the items in a request line. The request URL is a major element of the request line; The components of a URL explains the different parts of a URL. Your application program might need to examine any of the items in the request line in order to process the request and provide an appropriate response. Some common reasons for extracting information from a request line are:

• Because the same application program is called to handle a number of different requests, perhaps as part of a logical request sequence, or as different requests that relate to the same resource.
• To see what action is being requested from the application by the HTTP method. HTTP method reference for CICS Web support explains the different methods that a Web client might use for a request, and suggests action that is appropriate in each case.
• To use the path component of the URL. This identifies the resource to which the request applies. As well as being used to map the request to the handling application, the path component of the URL can be designed to provide processing information to the application. For example, the path component can be used to specify a particular function provided by the application. Or if the Web-aware application is providing a front end for more than one other application, the path component of the URL can identify the application to which the request applies.URLs for CICS Web support explains how this can be achieved.
• To obtain a query string for processing by the application.
• To identify the HTTP version for the Web client, so that the application can provide an appropriate response. The HTTP version used by the Web client can affect the HTTP headers, status code, and message content for the response. HTTP/1.0 clients might not understand the more advanced features described in the HTTP/1.1 specification.
• To identify a non-HTTP request. CICS Web support and non-HTTP requests has more information about handling non-HTTP requests.

The components of a URL

A URL (Uniform Resource Locator) is a specific type of URI (Universal Resource Identifier). A URL normally locates an existing resource on the Internet. A URL is used when a Web client makes a request to a server for a resource.

The concepts of the URI and the URL are defined by the Internet Society and IETF (Internet Engineering Task Force) Request for Comments document RFC 2396, Uniform Resource Identifiers (URI): Generic Syntax (http://www.ietf.org/rfc/rfc2396.txt). Briefly, a URI is defined as any character string that identifies a resource. A URL is defined as those URIs that identify a resource by its location or by the means used to access it, rather than by a name or other attribute of the resource.

A URL for HTTP (or HTTPS) is normally made up of three or four components:

1. A scheme. The scheme identifies the protocol to be used to access the resource on the Internet. It can be HTTP (without SSL) or HTTPS (with SSL).
2. A host. The host name identifies the host that holds the resource. For example, www.example.com. A server provides services in the name of the host, but there is not a one-to-one mapping between hosts and servers. Host names explains more about host names.
   Host names can also be followed by a port number. Port numbers explains more about these. Well-known port numbers for a service are normally omitted from the URL. Most servers use the well-known port numbers for HTTP and HTTPS , so most HTTP URLs omit the port number.
3. A path. The path identifies the specific resource within the host that the Web client wants to access. For example,/software/htp/cics/index.html.
4. A query string. If a query string is used, it follows the path component, and provides a string of information that the resource can use for some purpose (for example, as parameters for a search or as data to be processed). The query string is usually a string of name and value pairs, for example,q=bluebird.

The scheme and host components of a URL are not defined as case-sensitive, but the path and query string are case-sensitive. Usually, the whole URL is specified in lower case.

The components of the URL are combined and delimited as follows:

scheme://host:port/path?query

• The scheme is followed by a colon and two forward slashes.
• If a port number is specified, that number follows the host name, separated by a colon.
• The path name begins with a single forward slash.
• If a query string is specified, it is preceded by a question mark.

Figure 1. Syntax of an HTTP URL

                            .-:80-----.                      
>>-http://--+-host name--+--+---------+--/--path component------>
            '-IP address-'  '-:--port-'                      

>--+-----------------+-----------------------------------------><
   '-?--query string-'   

This is an example of an HTTP URL:

http://www.research.ibm.com/software/htp/cics/index.html

If a port number was specified, the URL would be:

http://www.research.ibm.com:1030/software/htp/cics/index.html

A URL can be followed by a fragment identifier. The separator used between the URL and the fragment identifier is the # character. A fragment identifier is used to point a Web browser to a reference or function within the item that it has just retrieved. For example, if the URL identifies an HTML page, a fragment identifier can be used to indicate a subsection within the page, using the ID of the subsection. In this case, the Web browser normally displays the page to the user so that the subsection is visible. The action taken by the Web browser for a fragment identifier differs depending on the media type of the item and the defined meaning of the fragment identifier for that media type.

Other protocols, such as File Transfer Protocol (FTP) or Gopher, also use URLs. The URLs used by these protocols may have a different syntax to the one used for HTTP.

CICS as an HTTP server

In CICS®, Web-aware application programs are programs that use EXEC CICS WEB commands to interact with a Web client or a server through CICS. For CICS as an HTTP server, these programs can receive and analyze HTTP requests and provide application-generated responses to the Web client.


    For each HTTP request that requires an application-generated response, CICS calls the Web-aware application program that is specified on the URIMAP definition for the request, or by the analyzer program, if an analyzer is used. If you use a URIMAP definition to specify the application program, you can select a single application program to service all requests using a particular URL. If you are using an analyzer program either instead of, or in addition to, the URIMAP definition, it can carry out analysis on the request and decide on an alternative application program.


     For CICS as an HTTP server, when an application program has sent a response to a request and returned control to CICS, it does not wait for further requests from the Web client. This is the case even when requests form a logical sequence, or are made using a persistent connection, or are pipelined. If you need to share information between different programs (or new instances of the same program) across a series of requests and responses, you can do this using CICS-managed resources, or using elements of the requests sent by the Web client.


You can code each of your Web-aware application programs to perform some or all of the following actions for processing an HTTP request:

1. Retrieve any information that your application program needs from the request line (including the request URL), using the WEB EXTRACT command.Examining the request line for an HTTP request tells you how to do this. The request line includes the HTTP method, which indicates the action that the application program should take. You can also design the path component of a request URL to provide processing information to the application program. If there is a query string in the request URL, the application program can extract it as a whole for processing.
2. Read or browse the HTTP headers for the request, using the HTTP header commands. Examining the HTTP headers for a message tells you how to do this. The information in the HTTP headers might be useful to the application program for processing and responding to the request.
3. Retrieve any technical information about the request that your application program needs to use. You can use EXEC CICS commands to access information about the TCP/IP environment and security options. Retrieving technical and security information about an HTTP request tells you how to do this.
4. If the request contains form data that you want to extract, read or browse the data using the form field commands. Examining form data in an HTTP request tells you how to do this. The data can be in the body of the request or as a query string in the URL, and CICS can extract the data from either of these locations.
5. If the request has a message body that you need to use, receive it into a buffer using the WEB RECEIVE command. Receiving the entity body of an HTTP request tells you how to do this. CICS does not require you to receive a message body if one is present, and some requests do not have a message body.
6. Execute the business logic for the request processing, using the information you have gathered. You might want to involve other application programs to perform processing. A Web-aware application program can produce a response to the HTTP request based on information that it receives from non-Web-aware programs. It is advisable to separate the business logic from the presentation logic. In a Web-aware application, presentation logic controls the interaction with the Web client. For advice on how to separate business and presentation logic, see the CICS Application Programming Guide.
7. Write HTTP headers for the response, using the WEB WRITE HTTPHEADER command. Writing HTTP headers for a response tells you how to do this.CICS automatically provides some required headers, such as the Date header. You can provide additional headers for other purposes.
8. Produce an entity body, or message body, which is the content of the HTTP response. Producing an entity body for an HTTP message tells you how to do this. The entity body can be formed from a CICS document (which is created using the EXEC CICS DOCUMENT application programming interface) or from a buffer of data supplied by the application program.
9. Send the response to the Web client using the WEB SEND command. Sending an HTTP response from CICS as an HTTP server tells you how to do this. You need to select a suitable status code and reason phrase, and specify the entity body. CICS assembles the response using these items and the HTTP headers. If you want to use chunked transfer-coding, you also need to follow the special instructions in Using chunked transfer-coding to send an HTTP request or response.
10. If you expect to exchange further requests and responses with this Web client, and you need to share data across the request sequence, use the suggestions in Managing application state across an HTTP request sequence to achieve this.