Output Hook

An important part of the application response process, strictly related to Template Processing, is the possibility for the application programmer to define a local AWK function, or hook, to perform additional complex processing of environment variables before they are used by the csaTemplate function to make substitutions on the response template.

Prior to doing the substitutions, csaTemplate first looks for a special AWK library file associated with the application program. In the case of our Hello World example script, such file is sought for in lib/rpcio/hello-world.awk. Here rpcio stands for "RPC I/O" library. If that file exists, it is expected to be a valid AWK function library, and to contain at least the AWK function _userproc(). Before sending the response template to the client, csaTemplate calls _userproc(_O_RESPONSE), so that the latter can perform further processing on the variables that will be used as replacements in the relevant locations of the template file. To perform its processing, _userproc() can make use of any other CSA library function, and in particular of _response().

For example, let's say that you have a response template like this:

 The value of program variable <pre>myvar</pre> is $[myvar] 
To replace $[myvar] with some value, say goofy, a possible _userproc() function may be like this:

 function _userproc(mode) { 
   if (mode == _O_RESPONSE) _response("myvar", "goofy") 
Of course that was a trivial example. In practise, the value to be replaced to $[myvar] will often not be a literal one, but will have to be fetched from the pool of program variables of the underlying rc script. In this case the _rcget() CSA library function can be used, and the previous example can be modified as follows:

 function _userproc(mode) { 
   if (mode == _O_RESPONSE) _response("myvar", _rcget("my_other_var")) 
These examples are highly artificial but they should give you an idea of how the output-hook mechanism can be used.

If option --tables file[,file, ...] is specified to csaTemplate, then each comma-separated file argument is expected to be a NoSQL table, which is loaded into memory by csaTemplate and made available to the output-hook in the global AWK array _TBLS[m,n], where "m" is the table position in the above file list and "n" is the table record number. That is, the first table record TAB-delimited fields will be loaded in _TBLS[1,1], the second table record TAB-delimited fields will be loaded in _TBLS[1,2], and so on. Likewise for records of the subsequent tables listed in the file argument, i.e. _TBLS[2,1] _TBLS[2,2] ... , _TBLS[3,1] _TBLS[3,2] ... etc. The special array position _TBLS[0,0] will contain the no. of comma-separated tables listed in the file argument.

Trackbacks (1) | New trackback | Print