zFileIndex, zFileUpload
=============================================================================

    These two classes provide a convenient interface to the ProBoard's
    filebase index and file upload listings. The filebase index can be
    used for extremely efficient searches (by file name), and the upload
    listing contains the information about all files recently uploaded to
    the system.

    The file index is in the FILESIDX.PB binary data file. UPLOAD.LOG is
    the text file which logs all system uploads. The information that can
    be extracted from this file includes the name of the file uploaded,
    the time and date of the upload, and the name of the user who did it.


    ZFILEINDEX::ZFILEINDEX
    -------------------------------------------------------------------------

        Synopsis  Constructs the zFileIndex object

        Syntax    zFileIndex();

        Remarks   The constructor will locate and open the filebase index so
                  that immediate searching is possible. It uses the PROBOARD
                  environment variable to locate the system directory where
                  the filebase index resides.

        Return    n/a


    ZFILEINDEX::~ZFILEINDEX
    -------------------------------------------------------------------------

        Synopsis  Destroy the object and close the index

        Syntax    ~zFileIndex();

        Remarks   The destructor will close the filebase index file and will
                  release all resources used by the object during its life.


    ZFILEINDEX::FIND
    -------------------------------------------------------------------------

        Synopsis  Search the filebase for files

        Syntax    short Find(char *name, const char *pattern);

        Remarks   This function will search the filebase index for all files
                  that match the specification in 'pattern'. Note that only
                  upper-case patterns should be used, wildcards such as '*',
                  '?', and even '[]' are fine. The 'name' parameter should
                  point to a buffer which will be used to store the name of
                  the file which matched. This function will return the area
                  number on a successful match (areas are numbered from 1)
                  or 0 to indicate that there are no more matches. You can
                  call this function repeatedly by passing NULL as the
                  'pattern' parameter in order to scan the entire filebase
                  index for matches.

        Return    On success, returns the area number; 0 otherwise


    ZFILEINDEX::RESTART
    -------------------------------------------------------------------------

        Synopsis  Rewinds the index file

        Syntax    void Restart();

        Remarks   This function allows you to reposition the filebase index
                  file pointer to the start of the index so that the next
                  call to find begins searching from there.

        Return    Nothing


    ZFILEUPLOAD::ZFILEUPLOAD
    -------------------------------------------------------------------------

        Synopsis  Constructs the zFileUpload object

        Syntax    zFileUpload();

        Remarks   This constructor will locate the upload log file using the
                  PROBOARD environment variable. It will then open it and
                  prepare it for reading. The caller can then call any of
                  the methods to extract the information needed. Note that
                  this constructor will not read the initial record. You
                  must call the Load() function to extract it.


    ZFILEUPLOAD::~ZFILEUPLOAD
    -------------------------------------------------------------------------

        Synopsis  Destroys the object

        Syntax    ~zFileUpload();

        Remarks   The destructor will close the upload log and will free all
                  resources allocated by the object during its lifetime.


    ZFILEUPLOAD::LOAD
    -------------------------------------------------------------------------

        Synopsis  Extract a record from the upload log

        Syntax    Boolean Load(char *filename = 0, struct tm *dateptr = 0,
                               char *uploader = 0);

        Remarks   This function will extract the record at the current
                  position in the file. You can call this method repeatedly
                  to read all records from the upload log. If any of the
                  parameters is not NULL (default), then the relevant info
                  will be stored there. The default operation will simply
                  load the record into the internal data structures of the
                  object, for later retrieval via the Get*() methods. This
                  routine will return True if a record was extracted, and
                  False if we are at the end of file.

        Return    On success, returns True; False otherwise


    ZFILEUPLOAD::RESTART
    -------------------------------------------------------------------------

        Synopsis  Rewind the upload log file

        Syntax    void Restart();

        Remarks   This function can be used to rewind the upload log and
                  cause the Load() function to start extracting records from
                  the beginning of the file. It is rarely used.

        Return    Nothing


    ZFILEUPLOAD::GETFILE, ZFILEUPLOAD::GETNAME, ZFILEUPLOAD::GETDATE
    -------------------------------------------------------------------------

        Synopsis  Retrieve data for upload log fields

        Syntax    const char*      GetFile() const;
                  const char*      GetName() const;
                  const struct tm* GetDate() const;

        Remarks   These functions can be used after a successful call to the
                  Load() method which will extract an upload record from the
                  log file. Note that the object uses its own buffers so
                  these functions will somply return pointers to them.

                  GetFile() returns the name of the file uploaded. GetName()
                  returns the name of the uploader, and GetDate() returns a
                  tm structure with the date and time of the upload.

        Return    Pointer to internal buffer

