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.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):
csaExit.ok 1000 $CSA_PGM($#CSA_PGM)
# End of program.
http://www.example.com/cgi-bin/CSA?0=example.hello-worldTell 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.comThe next part tells your Web server to call the CSA CGI front-end:
/cgi-bin/CSACSA 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-worldSince 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.