Syntax
CALL "utcgi.wbb",env$,cgi$,errmsg$
Description
With the exception of utaddr.wbb, this is the first Business BASIC CGI application program called. Once executed, the env$ and cgi$ string templates can be used to determine environment and CGI values.
|
Parameter |
Description |
|---|---|
|
env$ |
System environment variables, many of which are used in CGI applications. For example, env.script_name$ contains the logical name of the executable script that started the BBx session, and env.remote_addr$ contains the IP address of the client browser that sent the request to the host server. In addition to creating env$ values for each environment variable, a global string (STBL on PRO/5) is created for each environment variable as well. |
|
cgi$ |
Values of any input values set by the CGI input stream. |
|
errmsg$ |
Error message to return if an error occurs. |
The cgi$ template holds the values of any input values set by the CGI input stream. These are sent to the CGI application in two ways:
-
Through the URL, where name=value pairs are present following a "?" character in the URL. For example, the URL would set four values in the cgi$ string template:
"http://abc.com/cgi-bin/runapp?state=CA&type=A+B&zip=&name=A%26P+Market"
The following identifies the cgi$ string template:
cgi.state$="CA"
cgi.type$="A B"
cgi.zip$=""
cgi.name$="A&P Market"
-
Through an HTML form "post", where input form values are passed to the CGI input stream on the stdin file handle (though the Win-CGI specification passes values through a file).
In both methods, the data sent into the CGI application is URL-encoded, All nonprintable and some special characters are converted to hex notation, and spaces are replaced with "+" characters. utcgi.wbb decodes these values before placing them in the cgi$ template.
In the Win-CGI environment, large values are stored in temporary disk files. If any cgi$ variable value begins with a $FF$, the balance of the value contains a disk file name to store the value sent by the browser. This also makes it important to CALL "utexit.wbb" before exiting the Business BASIC environment to remove any temporary files that may have been created.
Names used in both the env$ and cgi$ string templates are fixed to be valid variable names, if necessary, by replacing any nonletter, nondigit character with an underscore, and by trimming long names to 32 characters. Sequences of more than one underscore are changed to a single underscore. In addition, any names that do not start with a letter are prefixed with an "X_".
If any CGI input value is in the format name-n, then an array element is created in cgi$. All high-level routines understand arrays and the format name-n, when moving data to and from the CGI environment. For example, if a CGI input stream name is "keywords-1", the cgi$ string template variable would be referenced as cgi.keywords$[1].
The global string "$arraysep" may be specified before calling utcgi.wbb to override the use of a single dash "-" as the element delimiter. For example, setting STBL("$arraysep","__") causes the name "keywords__1" to be treated as described above. This is important to scripting languages, such as Javascript, that cannot work with elements named with dashes.
This program stores two global strings for use by another program or application, if necessary: $cgi stores the cgi$ string, and $cgitpl stores the template definition. To recreate cgi$:
dim cgi$:stbl("$cgitpl")
cgi$=stbl("$cgi")
File Uploading
Forms that have been specified as "method=post enctype=multipart/form-data" are handled by utcgi.wbb. Any field types of "file" are stored in a temporary file, and the file name is stored in the cgi$ field. For example, if a form contains a file field named "datafile", a text field named "name", and the user filled in "c:\files\customers.dat" for the datafile field, then cgi$ might look like this:
cgi.name$="xyz"
cgi.datafile$="/tmp/bw123999.dat"
The extension of the uploaded filename is retained, but the name is changed to guarantee its uniqueness. The original file name is stored in a global string (STBL) $filename-fieldname, so the above example would set stbl("$filename-datafile") to "c:\files\customers.dat". See uttempfl.wbb for a description of where temporary files are stored.