CGI Services Architecture
Recent Pages

Environment Variables
Template Processing
RDF Responses
RDF Messaging
URL Rewriting
File Uploads
Sample Authenticated Se ...
HTTP Cookies
Client Authentication
GET and POST Variables

Links

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

Advertising

Session

User ID
Password



Campaigns

stopsoftwarepatents.eu petition banner

The classical Hello World

Let's have a closer look at the "example.hello-world" CSA program (note the loosely Object-Oriented naming scheme here, see further down); if you followed the default directions provided in the Basic application setup step, the actual script will be located in /var/www/.csa/example/rpclib/, together with the other few Web "methods" that make up our example application. Here "rpclib" means "Remote Procedure Call Library", as calling a program over the Web is a form of RPC operation, at least this is the way I see it. Before things are really ready to run, you still need to set up a few local definitions in the "example" application main configuration file, /var/www/.csa/example/csa.rc. Here you will probably only need to set CSA_ALLOW_USER to the UID your Web server is running as ("goofy" in our example) and define the correct values for CSA_URL1, CSA_RPC_URL1 and CSA_DOCROOT1 in /var/www/.csa/example/csa.rc .

For the rest of this document I will occasionally call an application a "class", and its individual scripts "methods". Although CSA isn't Object Oriented Programming in any true sense, I like naming things in this way. So let's call our first example script the "hello-world" method in the "example" class.

First, take a look at the actual rpclib/hello-world script. Well, there isn't really much to it; this is all it contains:

# Sample "hello-world" CSA application.

csaExit.ok 1000 $CSA_PGM($#CSA_PGM)

# End of program.
Just one line of code, plus comments. Of course real-world scripts will usually be more than that, but even such a simple script can already show us how the CSA basics work. Open your Web browser and type the script URL (replace the relevant parts with your local values):
http://www.example.com/cgi-bin/CSA?0=example.hello-world  
Tell your browser to load that URL, and if everything was set up as explained you should see a response page with an "Hello World!" message on it. If that didn't work, please double-check all the setup steps that I have outlined above.

Some explanations are needed on the URL syntax first. The first part is pretty obvious:

http://www.example.com  
The next part tells your Web server to call the CSA CGI front-end:
/cgi-bin/CSA   
CSA is the CGI program that you copied to your /usr/lib/cgi-bin/. What comes after the "?" are CGI parameters, as usual, and they are passed to CSA:
?0=example.hello-world  
Since the CGI specs do not mandate that argument names use letters, I decided to use numbers for CSA own purposes, to make the syntax recall the familiar C-style argv[] argument list, where argv[0] is the program name, and argv[1] through to argv[n] are arguments. The adopted style is similar to the one suggested by spec n. 6 of the MIME-RPC proposed protocol.

Our "example.hello-world" script does not take arguments, but if it did they would therefore extend the above URL to become something like:

?0=example.hello-world&1=value1&2=value2&a=abc&b=123& ...   
I like to see this remote program invocation style as a kind of Web Command Line Interface, which I dubbed CSA-RPC.

Back to "example.hello-world", let's examine it a bit more in depth. All our program does is to call the CSA library function csaExit.ok . If called with no arguments, this function would usually display the default positive completion message 0028 through the default response template csaOk.html (sought for in CSA_ROOT/forms/$CSA_LANG/ first, and then in /usr/local/csa/lib/ if not found in the former place). Instead, for our example we want to display message 1000, and such message requires an argument, namely our hello-world program name, therefore we need to pass csaExit.ok the relevant non-default arguments. The CSA_PGM variable is maintained internally by CSA, and in this example it is a list containing (CSA hello-world); since we want to pass its rightmost element to our result message, we need to use the proper rc(1) construct, as shown.

The opposite of csaExit.ok is the csaExit.fault function, which can be used to display the generic csaError.html template to the client and then quit the program. For detailed usage info on CSA library functions, please refer to the relevant library source files in the CSA installation directory, usually /usr/local/csa/lib/. I will eventually provide detailed documentation for them, but it will probably take time. In the meantime, the best source of documentation remains the code itself, and the relevant comment lines.


Trackbacks (2) | New trackback | Print

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