CGI Services Architecture
Recent Pages

Environment Variables
Handling Concurrency
Template Processing
RDF Responses
RDF Messaging
URL Rewriting
File Uploads
Sample Authenticated Se ...
HTTP Cookies
Client Authentication

Links

www.strozzi.it on Twitter
CSA Home
Table of Contents

Advertising

Session

User ID
Password



Campaigns

stopsoftwarepatents.eu petition banner

GET and POST Variables

Note: 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 variables

CSA 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=345 
will 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_RID 
if 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

This Web Site is Copyright © 2007,2008,2009,2010 Carlo Strozzi, Some Rights Reserved
site map | recent changes | disclaimer