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 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.
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 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.
- 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.
- 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.
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.