=========================================================
' Function design, structures, and working with the cache
=========================================================

Which functions take structures, and which take simple parameters?
If a function will modify the database - The function should take 
the minimum number of parameters, in the simplest form, and fetch
the structures for itself.

Always pass valid IDs (forumid, threadid, etc).  To validate an ID
from user input, run the ID through the appropriate GetXXXInfo() function
and use the ID returned.  A -1 ID returned indicates an invalid ID.  
You can either choose to ignore -1 IDs and procede by operating on a null
record, or supply the user with an appropriate error message.

Security context checking is usually the responsibility of the calling page.

If a funciton modifies the database, decide whether it's worthwhile to 
update the cache in-place or just to delete that item and let it be recreated.
If it is decided to update the cache in-place, call BBS.CacheLock and 
BBS.CacheUnlock at the beginning and end of critical locations.
To update a cache in-place, you will need to create a new structure
and overwrite the old one.  Updating an existing structure in cache
does not seem to be possible (confirm?)

What constitutes a critical location of a function?  The decision is not 
easily answered.  If an operation needs to be uninterrupted and atomic,
updating multiple tables, if the possibility of database corruption
may occur, if there is any possibility that the cache might be updated
between the time you get a structure and the time you update the cache, 
then it may be critical-- use the lock and unlock.

WHEN IN DOUBT, SIMPLY DELETE A CAHCE ITEM AND LET IT BE RECREATED NATURALLY

Example scenario: UpdateForumPostCount
===================================================================
=        |Client 1                 | Client 2                     =
=timeline|-------------------------|------------------------------=
=========|Posts message            | Edits forum with admin panels
         |Gets ForumInfo struct.   | Calls UpdateForumInfo()       
         |database operations      | Updates database
         |Calculations             | Clears cache
         |Updates cache with       |
         | -dirty copy of ForumInfo|
         
At which point, the administrator's edit to the forum will not take effect
until the cache is wiped during periodic cache maintenance (default five minutes)
This is not acceptable and would cause confusion.  THe likelyhood of this
happening on a lightly loaded system is low, but very much possible on a heavily
trafficked system.


Example scenario: UpdateForumPostCount using BBS.CacheLock
===================================================================
=        |Client 1                 | Client 2                     =
=timeline|-------------------------|------------------------------=
=========|Posts message            | Edits forum with admin panels
         |BBS.CacheLock         | 
         |Gets ForumInfo struct.   | Calls UpdateForumInfo()      
         |database operations      | Waiting for application unlock
         |Calculations             | Waiting for application unlock
         |Updates cache with       | Waiting for application unlock
         | - copy of ForumInfo     | Waiting for application unlock
         |BBS.CacheUnlock       | BBS.CacheLock
                                   | Updates database
                                   | Clears cache
                                   | BBS.CacheUnlock
         
The next person to request the foruminfo will retrieve client 2's updated
forum information.

The downside is that overuse of lock and unlock will impact performance.
ASP does not give us more granular control over the application locking,
too bad...... Use careful judgment! Sometimes having a slightly off-copy
of a cached item is OK, as long as the underlying database remains
uncorrputed.  Therefore, never rely 100% upon data coming from the cache
if you are updating the database!  Getting a headache yet?


==========================
' Application Cache
==========================

CI-CategoryID, Categoryinfo structures

TI-(ThreadID), 
ThreadInfo structures

FI-(ForumID), 
ForumInfo structures

LM-iModuleID-iUserlevel-iTargetID, 
ListMembers results

-- more (needs documented)