SREhttp/2 Manual

The SREhttp/2 File Cache Daemon

The SREhttp/2 file cache daemon is primarily used to cache "partially compiled HTML files containing server side includes" (SHTML files for short).

It can also be used for caching other files; a useful capability to have when a cached file can be used as a response to some other "partially dynamic" request. For example, it can be used to save directory listings (say, as created by the _DIR addon).

To clarify, the file-cache-daemon associates a temporary file to an identifier. This temporary file typically contains generated output. For example, if the identifier is a selector pointing to a SHTML file, then the temporary file could contain the compiled results (the file after the SSIs have been replaced). By using this temporary file, SREhttp/2 can save time (by avoiding the processing needed to insert the SSIs in the original SHTML file).

Thus, the file-cache daemon stores, and returns, file names. It does not store actual content. To store actual content, you can use the SRE2003 SRE_CACHE procedure.

The rest of this document describe the SREH2_FILE_CACHE procedure; a procedure that is designed to work with the file-cache daemon.

SREH2_FILE_CACHE

Syntax:
   astat=sreh2_file_cache(id_name,params,msec_wait,ownid,action)
where:
id_name A string that identifies a cache entry. This is often a selector, or a host_nickname:/selector, or a directory name.
Note that spaces are stripped from this string before it is used.
params Parameters that control how to cache id_name
msec_wait Wait time, in milli seconds. Optional -- the default value is 30 seconds (30000). After this many seconds, the procedure gives up (it stops waiting on the cache daemon), and returns an error code.
ownid optional. The calling procedure's Own_ID. If you have it, supplying the OWN_ID can speed up processing a bit.
action An action to take.
Valid actions are:GET PUT INFO RESET REMOVE
Note that if action is not specified, then:
  • if params not specified, then a GET is done
  • if params is specified: a PUT is done
Hence, for GET and PUT (which are usually the only ACTIONS you bother with), you do NOT need to specify ACTION.
astat depends on action

More details on ACTIONs

GET Lookup the entry matching ID_NAME. 
If no match, return 0.
If match ... 
    If HASH trigger type was used (see PUT for the details),
    then PARAMS should contain the current hash value for
    the object that ID_NAME refers to. If this is different
    then the one that the ID_NAME was saved with, then
    return 0 (and remove this ID_NAME entry).

    Otherwise, check the trigger files to see if none of
    them have changed. If any of them have, return 0
    (and remove this ID_NAME entry).

    Astat will be one of:
         0           == no match (or fatal error)
         1 filename  == use the cache in "filename" as is
         2 filename  == read filename, and perform more operations on it
         3           == The object (say, an SHTML file) referred to by
                        ID_NAME is known to not require caching
PUT Store an entry under ID_NAME
PARAMS contains information denoting what file to store,
and how to store it.

Note that astat is always 1

PARAMS has the following syntax:
      var = value ; var = value ; ...

Currently supported VARs are:
              FILE = filename
                       The filename (fully qualified) to store
                       This is REQUIRED.
               TRIGGERS= file1 file2 ... 
                          A space delimited list of (fully qualified) filenames
                          to use as "trigger files". Typically, you SHOULD 
                          include the "filename" (used in FILE) in this list.
                          Alternatively, you can use HASH instead of TRIGGERS.
               HASH = a_word
                      A_WORD is a string that contains NO spaces.  Often,
                      this is a CRC hash of some larger object.
                      This is ignored if TRIGGER_TYPE <> 'HASH'
               TRIGGER_TYPE = types
                      Types can be one of the following:
                        ALL DATE TIME DATETIME SIZE or HASH     
               STATUS=  Indicates what sort of cache this is.
                         ASIS : cached file should be used "as is"
                         PARTIAL : cached file should be further processed
                         NOSSI : there is no cached file associated with
                                 this entry; but one is not needed
                                 (the object pointed to by ID_NAME can
                                 be used without any modification)
                      These values are used with future GET actions -- they
                      influence the value of astat (the returned value).

              DURATION= lifespan of file (in days).  Entries older then this
                        are removed.
INFO Return the current set of cached information, in a mime-like list. If ID_NAME not specified, return for all entries. Otherwise, return for the record matching ID_NAME.
RESET Remove all entries from the cache.
astat will be a message of the form 15 file-cache records removed
REMOVE Remove the entry that matches ID_NAME Astat will be either 0 or 1, where:
    0 = no such entry
    1 = entry succesfully removed