Script Outputs


Overview

Returning viewable data to a browser at the end of processing a script is not required. However, all practical scripts return some sort of output. This output might be something the browser displays, such as a dynamically created HTML document, or it might be a response header that redirects a browser to another URL.

Even if a script only adds a record to a database or creates a new stream file, outputting a confirmation back to the user is usually expected. Also, if something goes wrong, a helpful error message can be returned to the browser for display.

HTTP provides two ways to return output to a browser. One way is to send back pre-defined response headers that will modify the browser's behavior. Another is to send back an object body that the browser displays to the user. Both of these outputs are sent back through standard output. Standard output is a Unix term adopted by CGI to indicate a stream file that any process can write its output to. In Unix environments, standard output is generally redirected to a file or to another program. Through Web Server/400's CGI support, standard output is made available to scripts through the Write Web Server/400 API.

Structure of a Response

The Hypertext Transfer Protocol defines the structure a script needs to follow in order to communicate properly with a browser. The Web server assists the script in following this structure unless the script wants to handle everything.

The basic structure is fairly simple. A script's response should begin with any response headers that it chooses to return. This is followed by a blank line (i.e., a line containing only a carriage return and linefeed). After the blank line, the object body is returned. The object body is usually what is displayed by the browser. In an older HTTP/0.9 version transaction, only the object body is returned and the response header is completely skipped. However, no matter which version of HTTP is being used, a script must always return a response header (even if it is an empty header). This header is not passed on to the client by the Web server if HTTP/0.9 is being used.

Response Headers

Response headers are the first thing a server sends back to a browser to satisfy a request. This information is generally not displayed to the user. The response headers are used to describe the Web server to the browser, to describe what the server is sending back, and to inform the browser of anything it needs to do.

A complete specification of the response headers in HTTP/1.0 is available from IETF. An overview of their use is provided below.

Response Header Format

The Response Header is a line oriented data stream that begins with the first line of output by the script. It continues until the first blank line. All response header data is in US-ASCII (which is essentially character set 850).

The format of all response headers is:

Header-Name: Header-Value<CR><LF>

where,

Header-Name
A string that identifies the header. This generally has a descriptive name where each word is separated by a dash ("-"). Many Header-Names are pre-defined.

Header-Value
After a colon (":") and a space, the value of the response header is included. This is a text string that represents the current value for the specified header. The Header-Value is terminated with a carriage return and linefeed. Some headers require a list of data to be returned. Lists are composed of comma and space separated text strings. Most pre-defined response headers have a well-defined Header-Value.

<CR><LF>
All header lines end with a US-ASCII carriage return and linefeed. These are code points 13 and 10 decimal in character set 850, respectively. A line with just these two characters on it ends the response header section.

Common Response Headers

Any valid response header can be sent back by a script. Some are handled specially by the Web server to fill header values that the server normally returns. Other headers are almost always returned by the Web server whether they are specified by the script or not. The following response headers are the more popular and useful headers used by scripts. Any header not known by the Web server is directly passed on to the browser.

Status
The Status header is a special header that is intercepted by the Web server to determine what type of status line should be sent back to the browser. The format of this is Status: XXX Reason-Phrase, where XXX is a valid numeric Status Code that indicates the success, failure, or special action of the request and Reason-Phrase is a text description of how the request turned out. The number is for computers to use and the text is for humans to use.

Content-Type
The Content-Type header indicates what type of data is being returned to the browser in the object body. The format of this header is Content-type: Type/Subtype, where Type and Subtype follow the rules for MIME types. If an object body is being returned, this header should be set. Typically, this is set to either text/html or text/plain.

Content-Length
The Content-Length header indicates to the browser how much data, in bytes, is being returned in the object body. This count does not include the response headers or the blank line that ends the response headers. If this is not included, the browser will read data until the Web server closes the connection. Note that the script does not have the ability to close the connection (nor should it need to). The format of this header is Content-length: X, where X is the number of bytes in decimal being returned.

Location
The Location header indicates to the Web server that instead of relying on the script to create an object body, the Web server should redirect the browser to the URL specified as a parameter to this header. The format of this header is Location: URL, where URL is either a fully qualified URL or a fully qualified path that specifies a URL on the current Web server. The browser will retrieve and display this other URL to satisfy this request.

NOTE: Web Server/400 deviates slightly from the CGI standard when handling the Location header. The standard says that if the URL specified as the value to the Location header is only a fully qualified path instead of a fully qualified URL (e.g., it doesn't begin with http://), the server should directly return the file rather than redirect the browser. Web Server/400 always redirects the browser. If a fully qualified path is the Location value, Web Server/400 redirects the browser to that file on the current Web server.

NPH Scripts

NPH stands for "No Parse Header." If a script is requested whose name begins with "NPH_", then the Web server will not parse any of the response headers that the script sends back. Typically, the Web server reads in the response headers and transforms any headers that it recognizes into its own response headers. This is a way to turn off this processing. This puts the responsibility on the script to get the response headers correct. It is not recommended to do these types of scripts unless you have a strong understanding of the HTTP protocol.

NOTE: Web Server/400 deviates in two ways from the CGI standard with regard to NPH scripts.

  1. With Web Server/400, an NPH script must always begin with a response header even though the CGI standard does not specify this. See the discussion on conversions to understand why.

  2. In the CGI standard, scripts that begin with "NPH" followed by a dash ("-") are considered No Parse Header scripts, but since the AS/400 does not allow program names to have dashes in them, the underscore ("_") is used instead.

Data Conversions

The AS/400's native coded character set is EBCDIC. The HTTP specifications dictate that the protocol communications that occur between a server and a client need to be in US-ASCII (ANSI X3.4-1986). Additionally, the practical standard for the textual information that is viewed on browsers is Latin I ASCII. Both of these character sets are supported by the AS/400, but most data generated on an AS/400 is in EBCDIC.

However, Web Server/400 takes care of automatically converting a script's response headers and, if appropriate, object body. In the case that a normal (non-NPH) script is running, Web Server/400 accepts all the response headers in the EBCDIC CCSID of the server's job. These are then parsed and converted to US-ASCII before sending them to the browser.

The object body is also converted if the Content-type is explicitly set in the script's response header and the Content-type begins with TEXT/. If Web Server/400 does convert the object body, it is converted to the configured Content CCSID. In all other cases, the script is responsible for sending the object body in the correct format.

In the case of NPH (No Parse Header) scripts, the headers are still read in the EBCDIC CCSID of the server's job and converted to US-ASCII before sending them to the browser, but they are not parsed. Other than converting them to US-ASCII, nothing is done to them. This however, requires that even an NPH script needs to have a response header that matches the response header format. The Content-type response header is still examined to determine if Web Server/400 should convert the object body. A Content-type that begins TEXT/ causes Web Server/400 to convert the response headers to US-ASCII and the object body to the configured Content CCSID.