S/Web Objects

Cache

This object handles information relating to the S/WEB cache.

The Cache object is used to manipulate the S/Web disk-based caching system. It's methods allow you to add items to the cache and retrieve them, and they also deal with saving and retrieving select lists in a special manner that allows the list to be split up into several frames so it is easier to represent it across several HTML pages.

[top]

Properties:

[top]

Methods:

call www_Exec_Method( "CACHE", method, param1, param2, param3, param4, param5 )

[top]

ADDOBJECT method

This method allows you to save an item in the cache.

Example:

declare function www_Exec_Method, www_Get_Status, www_Set_Status
$insert www_Status_Equates
cacheID = "MYCACHEKEY"
cacheObject = "Some data" : @fm : date() : @fm : "Some more data"
errorText = ""
call www_Set_Status( WWWSTATUS_CLEAR$ )
call www_Exec_Method( "CACHE", "ADDOBJECT", cacheID, cacheObject )
if www_Get_Status( errorText ) then
    * Do error stuff - reason is in errorText
end else
    * Cached object is now saved and can be retrieved using the GETOBJECT
    * method
end

[top]

CLEAR Method

This method allows you to delete all cached items for a specific client. It does NOT clear out the entire cache ( see the PURGE method ).

Example:

declare function www_Exec_Method, www_Get_Status, www_Set_Status
$insert www_Status_Equates
* Clear out all the contents for the current client
errorText = ""
call www_Set_Status( WWWSTATUS_CLEAR$ )
call www_Exec_Method( "CACHE", "CLEAR", "" )
if www_Get_Status( errorText ) then
    * Do error stuff - reason is in errorText
end else
    * All objects belonging to the current client have now
    * been cleared from the cache
end

[top]

CREATE Method

This method initializes the cache for use with the SERVER object and is usually only called when a SERVER object is first created so does not need to be called by developers.

Example:

declare function www_Exec_Method, www_Get_Status, www_Set_Status
$insert www_Status_Equates
errorText = ""
call www_Set_Status( WWWSTATUS_CLEAR$ )
call www_Exec_Method( "CACHE", "CREATE" )
if www_Get_Status( errorText ) then
    * Do error stuff - reason is in errorText
end else
    * The CACHE is now ready for use
end

[top]

DELETELIST method

This method allows you to delete a saved list from the cache.

Example:

declare function www_Exec_Method, www_Get_Status, www_Set_Status
$insert www_Status_Equates
listID        = "MYLISTID"
errorText     = ""
call www_Set_Status( WWWSTATUS_CLEAR$ )
call www_Exec_Method( "CACHE", "DELETELIST", listID )
if www_Get_Status( errorText ) then
    * Do error stuff - reason is in errorText
end else
    * All gone ...
end

[top]

GET method

This method allows you to retrieve properties from the cache object.

Example:

declare function www_Exec_Method, www_Get_Status, www_Set_Status
$insert www_Status_Equates
$insert logical
Properties  =   "XVERSION"
if www_Exec_Method( "GET", Properties, RetVals, "", "", "", "", errorText ) then
   cliObjVersion  =  Field( RetVals, @RM, 1 )
end else
   abort = TRUE$
end

[top]

GETLIST method

This method allows you to retrieve a list of keys from a saved list in the cache by specifying a frame number.  

Example:

declare function www_Exec_Method, www_Get_Status, www_Set_Status
$insert www_Status_Equates
$insert www_Cache_Equates
* This example gets the 4th frame from a cached select list
listID        = "MYLISTID"
frameNo       = 4
listKeys      = ""
listHeaderRec = ""
otherData     = ""
errorText     = ""
call www_Set_Status( WWWSTATUS_CLEAR$ )
call www_Exec_Method( "CACHE", "GETLIST", listID, frameNo, listKeys, listHeaderRec, otherData )
if www_Get_Status( errorText ) then
    * Do error stuff - reason is in errorText
end else
    * We now have our list of keys for this frame in the listKeys array.  We can
    * process this list and use it to build an HTML page that displays these keys
    * as links to records for example.
    xCount = count( listKeys, @fm ) + ( listKeys # "" )
    for x = 1 to xCount
       * formatting ...
    next
end

[top]

GETOBJECT method

This method allows you to retrieve a previously saved item from the cache.  

Example:  
declare function www_Exec_Method, www_Get_Status, www_Set_Status
$insert www_Status_Equates
cacheID = "MYCACHEKEY"
cacheObject = ""
errorText = ""
call www_Set_Status( WWWSTATUS_CLEAR$ )
call www_Exec_Method( "CACHE", "GETOBJECT", cacheID, cacheObject )
if www_Get_Status( errorText ) then
    * Do error stuff - reason is in errorText
end else
    * Cached object is now in the cacheObject variable
end

[top]

GETRECCOUNT method

This method allows you to retrieve the number of records held in the cache for a particular client.  

Example:  
declare function www_Exec_Method, www_Get_Status, www_Set_Status
$insert www_Status_Equates
errorText = ""
call www_Set_Status( WWWSTATUS_CLEAR$ )
call www_Exec_Method( "CACHE", "GETRECCOUNT", "", rowCount )
if www_Get_Status( errorText ) then
    * Do error stuff - reason is in errorText
end else
    * Row count is now in rowCount variable
end

[top]

PURGE Method

This method deletes ALL items from the cache, and is usually called by the primary SERVER object when it is first created.

Example:

declare function www_Exec_Method, www_Get_Status, www_Set_Status
$insert www_Status_Equates
$insert logical
errorText = ""
call www_Set_Status( WWWSTATUS_CLEAR$ )
call www_Exec_Method( "CACHE", "PURGE", TRUE$ )
if www_Get_Status( errorText ) then
    * Do error stuff - reason is in errorText
end else
    * Gone...
end

[top]

REMOVEOBJECT method

This method allows you to delete a previously saved item from the cache.  

Example:  
declare function www_Exec_Method, www_Get_Status, www_Set_Status
$insert www_Status_Equates
cacheID = "MYCACHEKEY"
cacheObject = ""
errorText = ""
call www_Set_Status( WWWSTATUS_CLEAR$ )
call www_Exec_Method( "CACHE", "DELETEOBJECT", cacheID )
if www_Get_Status( errorText ) then
    * Do error stuff - reason is in errorText
end else
    * Cached object is now deleted
end

[top]

SAVELIST method

This method allows you to save a resolved select list into the cache.  

The list to be saved must be either the currently active select list, a list already saved in the LISTS ( for Arev ) or the SYSLISTS ( for OpenInsight ) tables, or an @fm delimited array of keys.

When a list is saved via this method, it is saved to the LISTS or SYSLISTS table as normal but it is also split into a number of frames. These frames each contain a list of keys that can be retrieved via the GETLIST method. This is designed to make it easier and faster to retrieve a series of keys for displaying on a page, such as the results of a search like those seen in popular web search engines. Basically each frame equates to one page of results.

Note that you will be passed back a header record ( in param4 ) describing attributes of the saved list if the method is successful. This is so you can see how may key frames were generated during the save process and which keys were saved to which frame. It is an @fm delimited array structured as follows:

<1> - listID:     Key of the list as saved to the LISTS or SYSLISTS table
<2> - recCount:   Total number of records in the list
<3> - frameSize:  Maximum number of keys in each frame (see param3)
<4> - frameIndex: Specifies how the frames are arranged across multiple frame records
                   in the cache table
<5> - dataFlag:   TRUE$ if this list has supplemental data (see param5)
See WWW_CACHE_EQUATES for more details

It is also used by the CACHE object to find frames on subsequent GETLIST method calls.  

Example:  

declare function www_Exec_Method, www_Get_Status, www_Set_Status
$insert www_Status_Equates
$insert www_Cache_Equates
* For this example we are going to select and order all the keys
* in the SYSREPOS table and then save them to the cache, splitting
* up the list into frames of 20 keys each.
*
* The otherData variable can be used to set an supplemental information
* that we want to save along with the list.
call RList( "SELECT SYSREPOS BY @ID", 5, "", "", "" )
listID = "MYLISTID"
listData = ""
keysPerFrame = 20
listHeaderRec = ""
otherData = "Some data that I want to attach to this list" : @fm : "SYSREPOS keys"
errorText = ""
call www_Set_Status( WWWSTATUS_CLEAR$ )
call www_Exec_Method( "CACHE", "SAVELIST", listID, listData, keysPerFrame, listHeaderRec, otherData )
if www_Get_Status( errorText ) then
    * Do error stuff - reason is in errorText
end else
    * The list has now been saved and split up into frames.  The listHeaderRec
    * Will now give us some info about what we saved ...
    *
    * eg...
    recCount = listHeaderRec<WWWCACHE_LIST_HDR_RECCOUNT$>
end

Notes

When an item is saved to the cache ( ie. by using ADDOBJECT or SAVELIST ) it is tagged as belonging to the current client ( see the ID property of the CLIENT object ). If for some reason an object is added without a client being present, the cache item will be tagged with the SYSTEM keyword instead. There is no need to specify these tags as this process is handled transparently for you.

The disk-based cache system uses the WWW_CACHE table. This table is cleared using the PURGE method when the primary S/Web SERVER object is created.

[top]