Script Inputs


Overview

A user-written CGI script can get input from a variety of sources. All of these sources are reached by the script either through the Web Server/400 Get Environment Variable API or Read API. Possible sources of input are any of the pseudo-environment variables, the standard input, or the command line parameters.

Input Sources

Environment Variables
The environment variables make various server-specific and request-specific values available to the script. The main two sources of input provided by the environment variables are the QUERY_STRING and PATH_INFO.

Standard Input
The standard input is a Unix term adopted by CGI to indicate a stream file that any process can read to get input. Generally, in the Unix environment this input is piped to a program by the command processor or another program. Through Web Server/400's CGI support, standard input is made available to scripts through two Web Server/400 APIs: Read or Get Form Variable. Get Form Variable is a high-level function that hides where the actual input is coming from.

What is received by the script through standard input? Most browsers currently in use only use standard input to send to the script the user-entered HTML form data. This is done when the form is submitted using the POST method. The less common PUT method also provides data to a script over standard input. The HTML form data is sent by the browser to the server in the request body. The request body usually has a content type of application/x-www-form-urlencoded. If this is the content type of the request body, the server automatically converts the form data into EBCDIC before providing it to the script.

If another content type is provided by the browser, then no conversion takes place and it is up to the script program to perform its own conversions. This would make it possible for a script to accept a multi-part document as form input. Since each part could require a different type of conversion (or no conversion at all), having the server blindly convert everything wouldn't work in these cases.

Command Line Parameters
Scripts usually do not receive any command line parameters. The only case that they do have command line parameters is when a Query String is entered as part of the URL for the script and the Query String does not have an equal sign ("=") in it. When a Query String without equal signs is supplied, the Query String is split-up and passed in as command line parameters. The Query String is separated into plus ("+") divided words, each word being passed in as a separate parameter. The Query String is not escaped prior to turning it into parameters. The reason a plus ("+") separates the parameters is because all spaces in a Query String should be escaped to pluses prior to making a request.

For example, if the URL /cgi-bin/cgitest?This+Isn't+%41+Big+Deal is requested, the Query String would be passed into the script as command line parameters:

CALL WWWCGI/CGITEST PARM('This' 'Isn''t' '%41' 'Big' 'Deal')

Notice that the capital "A" is passed in escaped to hex 41 ("%41") which is the ASCII code point for that letter. The Web Server/400 API UnEscape Read Data can be used to unescape this data to an EBCDIC string.

Note: Command line parameters to scripts written in REXX/400 are slightly different. These parameters are not separated into multiple parameters but are sent in as one single parameter. Any pluses ("+") are converted to spaces first.

Request Methods

The HTTP method used to make the request indicates to the server where to receive its input. Possible methods are GET, HEAD, POST, PUT, DELETE. The method can be obtained by calling the Get Environment Variable Web Server/400 API with a variable name of REQUEST_METHOD.

GET
The GET method is the most common and default method used by browsers. This tells the Web server that the browser is requesting a document to be returned. Scripts can also be performed with a GET. A script that is requested with a GET receives its input through a query string. Standard input is not sent by the browser.

HEAD
The HEAD method performs the same way as a GET except that only the response headers are sent back. The object body is not sent. If a script is called with the HEAD method, it should not send back an object body.

POST
The POST method is normally used for an HTML form. This is similar to a GET except that the form input data is send through standard input to the script instead of using the query string.

PUT
The PUT method is the same as the POST except that the PUT can be used to indicate a different mode of operation. The PUT usually implies that the operation should take effect immediately whereas the POST's action might be delayed.

DELETE
The DELETE method can be used to instruct a script to remove some entity instead of creating something like POST and PUT imply.