CGI Services Architecture
|
CGI Services Architecture
|
|
GET and POST VariablesNote: this page assumes that the reader be already familiar with the underlying topics of HTTP, GET/POST processing and form variables. As it is often the case with other Web programming environments, CSA makes usually no real distinction between a GET and a POST operation. It is therefore perfectly ok to have an HTML form snippet like this:<form method=post action="http://www.example.com/cgi-bin/CSA?0=example.hello-world&var1=123"> <input type=text name=var2 value=456>With the exception of a few special variable names, GET and POST variables are made accessible to the application program through the program environment, with their names prefixed by WWW_. That is, the
Hello World example program would receive through its environment the assignments
WWW_var1=123 and
WWW_var2=456.
Since values are loaded into the environment, the total size of the data that a client can send to our program through GET and POST actions is limited to the value contained in the
$CSA_RPC_MAXSIZE variable. The default limit is 10 KBytes, and it can be changed by setting a different value in the CSA shell wrapper.
If the same variable is assigned multiple values, as it may happen for instance with a
<select multiple> HTML element, it will be made available to the application program as an
rc list. For example:
WWW_var=('value1' 'value2' ...). As with single-valued variables, if individual values contain single-quotes they will be automatically escaped. See
rc(1) for more.
As explained in
HTTP Cookies, cookies are just a third way to set variables, beside GET and POST. CSA considers cookie assignments first, then POST variables and finally GET ones. So, if a GET variable contains the assignment
goofy=123, a cookie contains
goofy=345 and a POST says
goofy=789, the application program environment will contain
WWW_goofy=('345' '789' '123'). Furthermore, multiple cookies may assign different values to the same variable, the resulting list will contain all of them. When a cookie is set more than once in the client browser, the latter returns the latest setting first. It will be up to the application program to account for this and explicitly reference the relevant list element if appropriate.
Another way of conveying application-level data is through custom HTTP headers, like
X-Something: somevalue. This is supported by CSA in a way very similar to HTTP cookies, so for instance the above will result in a
WWW_X_SOMETHING=('somevalue') assignment to be passed to the application program. Since HTTP header names are case-insensitive, the corresponding variable name is turned into upper-case before it is passed to the application program.
Form variables that refer to
<textarea> HTML elements SHOULD always have names that begin with a dot (as in
.name). The way such variables are handled is modelled after
Un-CGI, a rather well-known HTML form processor, except that the latter uses a leading underscore (as in
_name). Please refer to the Un-CGI Web page (section
Special Processing) for more on this.
Up to now I have been stating that HTTP variables are passed to the application program through the environment. Well, this is not really true, or not until the application explicitly asks for them by calling the CSA function
csaGetArgs. Only then the assignments will be loaded in the environment. Before
csaGetArgs is called, all assignments only exist in the temporary file pointed to by the CSA variable
$CSA_RPC_WWW.
Special CGI variablesCSA supports numeric variable names, as already mentioned in Hello World. That is, the following URL:http://www.example.com/cgi-bin/cgiwrap/~goofy/CSA?0=example.hello-world&1=123&2=345will cause the program environment to contain the assignments WWW_1=('123') and
WWW_2=('345'). Such variables are meant to bring a positional connotation associated with their names. Of course, the just
look like numbers from the Web client point of view, but they are actually strings, like any other CGI variable. and that becomes evident once CSA has prefixed them with the usual
WWW_ prefix. As usual, the same variable may be assigned multiple values by a GET/POST/cookie assignment, in which case we will have
WWW_1=('123' '456' ...), as usual.
CGI variables that begin with
X- are treated especially by CSA. They are considered custom HTTP headers, regardless of whether they are entered via GET/POST variables, actual HTTP custom headers or HTTP cookie assignments. Treating such variables as headers means that their names will always be turned into upper-case, with invalid characters replaced by underscores (
_). For instance,
X-SomeHeader: 123 will be passed to the application program as
WWW_X_SOMEHEADER=123. Refer also to
Client Authentication.
The following special CSA variables:
CSA_CONFIRMED CSA_FMT CSA_GUID CSA_LANG CSA_RIDif present, MUST have been entered in the form of an HTTP custom header, as explained above. Those variables are first checked for valid values by CSA, and then are passed to the application program without being prefixed by WWW_ and with the
X- prefix stripped-off. That is, for example,
X-CSA-Lang: en_US (when entered through an HTTP header), or
X-CSA-Lang=en_US (if entered via a GET/POST variable or a cookie), will be passed to the application as
CSA_LANG=en_US. In case those variables are entered as GET/POST variables, they can also be specified durectly in their
normalized form, i.e. as
X_CSA_LANG as opposed to
X-CSA-Lang, but in that case they must be specified in upper-case, as they will not undergo the case-folding process. Failing any of the above, a variable will not be considered special and will be passed to the application program prefixed by
WWW_, as usual.
Trackbacks (0) | New trackback | Print |