Wcl v1.0.0 documentation

Documentation generated by XL CLAIRE v3.3.37 at Sat, 25 Nov 2006

Category index

  1. mod_wcl Apache 2.x module configuration
  2. HTTP headers
  3. Misceleanous
  4. Subscripts
  5. Session

Command line option index

  1. Wcl srcipt : -wcl [<file>]
  2. Wcl script : {-xwcl | -xwcl<S>-<W>} <file>

Method index

Wcl categories
categories
mod_wcl Apache 2.x module configuration

mod_wcl Apache 2.x module configuration

Communications between the Apache 2.x web server and a Web CLAIRE agent goes through the mod_wcl Apache 2.x module that requires to be configured in the Apache configuration syntax. The mod_wcl module understands a set of directives used to configure one or multiple Web CLAIRE services. mod_wcl supports per-directory configurations, also it's a good habbit to define a Web CLAIRE service inside a location block, for instance if we have a single service we may define our mod_wcl directives in a location block bound to the root path of the server :
 <location />
     mod_wcl directives ...
 </location>
The minimal configuration consists in two directives, first we need the WclCommand directive that specifies the path of the binary executable of our service including command line options, this binary have to be compiled with the module Wcl which, in order to behave as expected, should be launched with the -wcl option, on the other hand we have to specify a (wildcard) filter for the set of files that are handled by our service (usualy *.wcl that specifies that we handle all files with extension wcl) :
 <location />
     WclCommand /path/of/the/binary -wcl
     WclFileFilter *.wcl
 </location>
The file filter is necessary since mod_wcl is declared as a 'really first' apache module. Such modules have an opportunity to perform task as soon as a request is handled by apache. This is a requirement for our architecture because we have to properly handle session ID that we appear on the URL when session_url is used, the session ID have to be removed from the request URI in an early step such, for instance, images can be handled normaly by apache.

Then we may define some user environment variables with the following directive :
 WclUserEnv ENV_VAR_NAME env_var_value
These environment variables will be added to the CGI (like) environment in which the service is launched (they will be available from the service via getenv("ENV_VAR_NAME")).

We may also specify the name of a file that is taken a the default one when none are specified, this is done with the WclDefaultIndex directive. It allows the generation of an index page in a dynamic flavor without the need of an existing file :
 WclDefaultIndex name_of_default_index
mod_wcl will set the request URI to this file if none is actualy requested. For instance, the default Web CLAIRE configuration installed by the webclaire package specifies 'inspect.wcl' as the default index. Notice that such handling can only be made by a compiled handler.

When we use sessions from our service (that is our service calls session_url or session_cookie) we have to specify a directory where session files are saved, optionaly we can specify a session name that will be used to generate the session file name :
 WclSessionName NAME_OF_THE_SESSION
 WclSessionPath /path/to/session_folder
We may also specify a path where trace lines resulting of a script execution are saved (each request appends its trace to the file) :
 WclTraceFile /path/to/trace_file
Last some configuration paths can be specifies using environment variables that when used will be substituted by the environment variable value. The substitution environment includes variables defined with WlcUserEnv directive. The paths that are subject to subtitution are :

For instance the following configuration is valid :
 WclUserEnv HOME_DIR /path/to/custom/root_folder
 WclUserEnv SERVICE_BINARY the_name_of_my_binary
 WclCommand $(HOME_DIR)/path/to/$(SERVICE_BINARY)
For instance, it would be verry kind if we could have a per-client trace file. Such a configuration is possible using environment subtitution as in :
 WclTraceFile /path/to/trace_folder/$(REMOTE_ADDR).trace
categories
HTTP headers

HTTP headers
categories
Misceleanous

Misceleanous
categories
Subscripts

Subscripts
categories
Session

Session

Due to the architecture of client/server application we need a way to store server-side temporary datas between two client requests. These temporary datas are called session datas and are saved in a server side file between requests. A client is identified by a session ID that is transmited between the server and the client in each request. Wcl comes with two strategies for the ID transmition :

session_cookie() or session_url() would either load an existing session or, if none exists at the time of the call, create a new session with a new session ID. Using cookie require that the client browser supports and allows cookies. URL sessions are smarter since they don't need configuration of the client broswer at all. Notice that a session should be started before actualy sending data an error would be raised othewise.

Once a session is started we may add new entries in the session. Entries are identified by a variable name (string) and may hold any object, the register register method would insert a new entry in the session, for instance :
 register("counter", 0)
Once a variable has been registered it comes accessible through the $ table :
 (assert($["counter"] = 0))
When the executed script ends the session (all registered objects) is automaticaly saved in the session file. This operation relies on the serialize facility. Sometimes we need to register an object and also the relations of that object that are themself objects (i.e. not primitive or bag), we call that recursive registering and we would use rregister. For instance let's consider the following script that manage a simple fruit's basket :
 item <: ephemeral_object(name:string, quantity:integer)
 basket <: ephemeral_object(items:list[item])

 (if ($["add_item"] & $["basket"])
     $["basket"].items add
         item(name = $["name"],
             quantity = integer!($["quantity"])))

 (session_url()) // starts a session

 (if not($["basket"]) // register a new basket
     rregister("basket", basket()))

 ?>Your basket :
 <table><?
     for i in $["basket"].items
         ( ?><tr><td><?== i.quantity ?> <?== i.name)
 ?></table><?

 ?>Add item to your basket :
 <form>
     <select name='name'>
         <option value='banana'>banana
         <option value='orange'>orange
     </select>
     <input type=text name='quantity'>
     <input type=submit name='add_item'>
 </form><?
If we had use a simple register, the items added to the basket would not have been inserted in the session whereas the use of rregister tells to recurse the item objects.

At the time a session is saved the session file is locked to avoid multiple write access so that, for instance, a page that defines multiple frames for a single session does not alter the session file.

Wcl command line options
option index Wcl srcipt Wcl command line option

-wcl [<file>]

Where

Load the requested wcl file. One may test a single wcl file by specifying a <file> argument unless PATH_TRANSLATED is defined in the environment. In the later case a CGI environment is assumed as built by the mod_wcl Apache 2.x module.
option index Wcl script Wcl command line option

{-xwcl | -xwcl<S>-<W>} <file>

Where

Load the wcl script <file>. A (unix) file may have execution rights and one can make a wcl script by adding as the first line of the script something like :

#!/usr/local/bin/claire -xwcl

When <S> and <W> are specified they are used to inititalize CLAIRE memory (see option -s).

Wcl methods
categories Misceleanousnormal dispatch Wcl method

die() -> void

die() properly aborts the execution of the script and exits. If a session has been started and no error where issued by the script then the session is saved.
categories HTTP headersnormal dispatch Http method

force_content_length() -> void

force_content_length() forces the response to contain a Content-Length HTTP header. The default for HTTP/1.1 client is to transfer the response by chunks (chunked coding transfer). This would be necessary for instance when sending an application/pdf content type response to a Win32 client that uses Internet Explorer, this browser has difficulties to transmit a chunked encoded response to the Adobe Acrobat plugin...
categories HTTP headersnormal dispatch Http method

header(h:string) -> void

header(h) adds a custom HTTP header to the response. The specified header h should be a single line header without terminating CRLF. For instances :
 header("Some-Header: header-value")
categories Subscriptsnormal dispatch Wcl method

include(self:string) -> void

include(self) is the generic way (instead of calling load_wcl) to load sub-scripts. self is the path of the loaded subscript it is relative to the path of the main script.
categories Sessionnormal dispatch Reader method

register(varname:string, val:any) -> any

register(varname, val) adds a new entry in the current session. After this call we have $[varname] = val.
categories Sessionnormal dispatch Wcl method

rregister(varname:string, val:any) -> any

rregister(varname, val) adds a new entry in the current session. After this call we have $[varname] = val. rregister stands for 'recursive register' which means that the related objects are also registered (see serialize).
categories Sessionnormal dispatch Wcl method

session_clean_but(l:bag) -> any

session_clean_but(l) removes all datas from a session execpt those specified in l.
categories Sessionnormal dispatch Wcl method

session_clean_but(i:string) -> any

session_clean_but(i) removes all datas from a session execpt i.
categories Sessioninline Wcl method

session_cookie() => void

session_cookie() starts a session. The ID of the session is transmitted in a cookie. The client should support and allow cookies. If a session with a matching ID already exists then its data are loaded in memory.
categories Sessionnormal dispatch Wcl method

session_destroy() -> void

session_destroy() detroys an existing session. If the associated file that contain session datas then it is unlinked.
categories Sessionnormal dispatch Wcl method

session_url() -> void

session_url() starts a client session. Unlike session-cookie(), session_url() transmit the session ID (which identifies the client) on the URL. It is a more portable way than session_cookie since it does not require that the client allows cookies. If a session with a matching ID already exists then its data are loaded in memory.
categories Sessionnormal dispatch Wcl method

unregister(self:string) -> void

unregister(self) remove the entry self from the current session.