






   fSys.Txt - or 'How to get access to the Adept File System thru fSys.Dll'

                                 Release 1.00

          Copyright (c) 1995-1996 by AdeptSoft   All Rights Reserved



   fSys.Dll provides a convenient method of accessing the AdeptXBBS file
system. Nearly all data, and the format of said data is hidden from the
programmer. This means fSys controls most of the action which is just the
way it should be. All access to data is thru specific function calls.

   fSys uses a handle based concept which means it can be used by more
than one thread in a process.  It also contains one 'per process' function
'FSysInit' which initializes a couple variables which would be used by
all threads in the process.


   How to use fSys:
   ----------------

   First place fSys.Dll in directory pointed to by the LIBPATH statement
in CONFIG.SYS.


   Programming with fSys:
   ----------------------

   For every process you should start out by calling 'FSysInit' to initialize
fSys. Then for every thread which will use the file system, you need to 
call 'FSysOpen' to gain access.

   At the end of the threads use of the file system, it should call 'FSysClose'
Before the process terminates, it should call 'FSysDeInit'.  This ensures 
that any allocated resources are freed.  This is very important!

   Link your program with fSys.Lib to get access to the functions in the DLL
and away you go.

   FSys.Dll always deals with one file record which is stored in memory. The
format of this data is hidden from you for the most part. You use the FSys
functions to manipulate this data. You can tell FSys to read data from the
disk into the record stored in memory. Likewise, you can tell FSys to write
the data currently stored in memory out to the file system on disk.

   You strictly use FSys functions to get or set the data in the file record
stored in memory.

Instead of the conventional:

   FSysRecord.FileAreaNumber = 12; // set the file area number

You would use:

   FSysSetFileArea(hFSys, 12); // set the file area number

These two lines act in the same manner, except the format of the data is
hidden from you with the latter function call.

   And now, on with the functions in fSys.Dll:

  #include <fSys.h>

  LONG APIENTRY FSysGetVersion(VOID)

  FSysGetVersion returns the version of fSys.

  PARAMETERS
    None.

  RETURNS
    fSys version number.

  REMARKS
    The version number returned by FSysGetVersion is mutliplied by 1000.

    This will give you an accurate version of fSys.

    For instance, if FSysGetVersion returns  932 then the fSys version is
    .932

    fSys does not need to be initialized for this call to work.

  EXAMPLE CODE
    This example prints the fSys version number.

        LONG VersionNumber;

        VersionNumber = FSysGetVersion();

        printf("Using fSys version %d\n", VersionNumber);


  #include <fSys.h>

  APIRET APIENTRY FSysInit(VOID)

  FSysInit initializes fSys.Dll on a per process basis.

  PARAMETERS
    None.

  RETURNS
    Return Code.

    0           No errors.
    8           ERROR_NOT_ENOUGH_MEMORY
    87          ERROR_INVALID_PARAMETER
    290         ERROR_TOO_MANY_HANDLES
    
  REMARKS
    FSysInit should be called by the process before any threads in the process
    make any calls to FSysOpen, and any other FSys calls, excluding 
    FSysGetVersion.

    Not calling FSysInit could cause corruption of the file system if more than
    one process or thread is accessing the file system at the same time.

  EXAMPLE CODE
    This example calls FSysInit

        APIRET RetCode;

        RetCode = FSysInit();

        if (RetCode)
        {
            printf("Error %d at FSysInit\n", RetCode);

            return;
        }

  #include <fSys.h>

  VOID APIENTRY FSysDeInit(VOID)

  FSysDeInit frees fSys resources on a per process basis.

  PARAMETERS
    None.

  RETURNS
    None.

  REMARKS
    FSysDeInit frees resources allocated by FSysInit, and should be
    called after the file system is no longer in use, and before the
    process ends.

  EXAMPLE CODE
    This example calls FSysInit

        APIRET RetCode;

        RetCode = FSysInit();

        .
        .
        // use file system
        .
        .

        FSysDeInit();

  #include <fSys.h>

  APIRET APIENTRY FSysOpen(PSZ Directory, PHFSYS phFSys, BOOL Create)

  FSysOpen should be called by each thread in the process which wants
  to use the file system.

  PARAMETERS
    Directory (PSZ) - input
        This is the directory that the files system is located in. Normally
        a program whis uses the Adept file system is started in the '\Adept'
        directory, and the files system would then be in '.\Files', or more
        simply, 'Files'.   The directory name should NOT end with a 
        backslash or forward slash.

    phFSys (PHFSYS) - output
        This contains the address of the handle to the file system.

    Create (BOOL) - input
        Tells the file system whether to open the current file system files,
        or to create new ones.

        FALSE - Open current files.
        TRUE  - Create/Open new files.

  RETURNS
    Return Code.

    FSysOpen may return the following values:

    0           No errors.
    90          FSYS_ERROR_ALLOC_MEM        
    91          FSYS_ERROR_INIT_BIDX
    100         FSYS_ERROR_OPEN_DATA
    101         FSYS_ERROR_OPEN_DESC
    102         FSYS_ERROR_OPEN_PATH
    103         FSYS_ERROR_OPEN_NIDX
    104         FSYS_ERROR_OPEN_DIDX
    105         FSYS_ERROR_OPEN_AIDX
    180         FSYS_ERROR_CREATING_KEY

  REMARKS
    A successful FSysOpen request returns a handle to the file system. All
    other calls to the file system functions require this handle.

    NOTE: When you choose to CREATE a new file system, the indexes are
    DESTROYED if they exist. All other files are opened, and NOT destroyed.
    If you wish to create all files from scratch, make sure there are no
    files in the directory.

    You could call FSysOpen twice with a different directory to open
    two different files system to copy entries from one file system
    to another.

  EXAMPLE CODE
    This example calls FSysOpen, and uses the current file system files.

        APIRET RetCode;
        HFSYS  hFSys;

        RetCode = FSysOpen("Files", &hFSys, FALSE);

  #include <fSys.h>

  INT APIENTRY FSysClose(HFSYS hFSys)

  FSysClose close the file system.

  PARAMETERS
    hFSys (HFSYS) - input
        Handle to the currently open file system.

  RETURNS
    Return Code.

    FSysClose may return the following values:

    0           No errors.

  EXAMPLE CODE
    This example calls FSysOpen, and creates new file system files, then
    closes the file system.

        APIRET RetCode;
        HFSYS  hFSys;

        RetCode = FSysOpen("Files", &hFSys, FALSE);

        .
        .
        // use the file system.
        .
        .

        RetCode = FSysClose(hFSys);

  #include <fSys.h>

  INT APIENTRY FSysDeleteIndexEntries(HFSYS hFSys)

  FSysDeleteIndexEntries deletes a file from all of the indexes.

  PARAMETERS
    hFSys (HFSYS) - input
        Handle to the currently open file system.

  RETURNS
    Return Code.

    FSysOpen may return the following values:

    0           No errors.
    92          FSYS_ERROR_SEM_TIMEOUT
    190         FSYS_ERROR_DELETING_DATED
    191         FSYS_ERROR_DELETING_ANAME
    192         FSYS_ERROR_DELETING_NAME
  
  REMARKS
    FSysDeleteIndexEntries deletes all refrences to a certain file in the
    indexes. It does NOT remove that files record from the data file.

    To set which file you wish to delete, you must either search for, and
    find the file using the searching functions, or you must use the
    FSysSetIndexXXXXX series of functions to set the correct filename, date,
    area name, and file record offset.  Obviously it is best to search for
    the file, find it, and confirm it is the file you wish to delete before
    you delete it.

  EXAMPLE CODE
    Assuming you have already set the file index information this example 
    calls FSysDeleteIndexEntries to delete the file from the indexes.

        APIRET RetCode;
        HFSYS  hFSys;

        RetCode = FSysDeleteIndexEntries(hFSys);

  #include <fSys.h>

  INT APIENTRY FSysAddIndexEntries(HFSYS hFSys)

  FSysAddIndexEntries adds entries in the indexes for a file.

  PARAMETERS
    hFSys (HFSYS) - input
        Handle to the currently open file system.

  RETURNS
    Return Code.

    FSysOpen may return the following values:

    0           No errors.
    92          FSYS_ERROR_SEM_TIMEOUT
    200         FSYS_ERROR_ADDING_DATED
    201         FSYS_ERROR_ADDING_ANAME
    202         FSYS_ERROR_ADDING_NAME
  
  REMARKS
    Index data should be set using the FSysSetIndexXXXX series of functions
    before adding a file to the indexes.

  EXAMPLE CODE
    This example deletes the old index entries for a file, set the new index
    data, then adds in the new index entries.

        CHAR  Buffer[CCHMAXPATH];
        HFSYS hFSys;
        FDATE Date;

        // delete old entries (old index data already set..)
        FSysDeleteIndexEntries(hFSys);

        // set new index data
        FSysSetIndexFilename(hFSys, FSysGetFileName(hFSys, Buffer));

        FSysSetIndexEntryDate(hFSys, FSysGetFileDate(hFSys, &Date));

        FSysSetIndexAreaNumber(hFSys, FSysGetFileArea(hFSys));

        // add in new index entries
        FSysAddIndexEntries(hFSys);

  #include <fSys.h>

  VOID APIENTRY FSysSetIndexFilename(HFSYS hFSys, PSZ FileName)

  FSysSetIndexFilename sets the filename to be used in the indexes.

  PARAMETERS
    hFSys (HFSYS) - input
        Handle to the currently open file system.

    FileName (PSZ) - input
        Pointer to a buffer which contains the filename.

  RETURNS
    None.

  REMARKS
    The buffer which contains the filename should be CCHMAXPATH characters
    in length. This is defined in BSEDOS.H as 260.

    The filename is _only_ the filename, no path should be included.

    In all cases the index filename should be the same as the filename of
    the file.

    NOTE: The Adept file system considers only the first 20 characters of
    a filename to be significant in the indexes.

  EXAMPLE CODE
    This example sets the filename to be used in the indexes as 'My.Text.File'

        CHAR  MyFileName[CCHMAXPATH] = "My.Text.File";
        HFSYS hFSys;

        FSysSetIndexFilename(hFSys, MyFileName);

  #include <fSys.h>

  VOID APIENTRY FSysGetIndexFilename(HFSYS hFSys, PSZ FileName)

  FSysGetIndexFilename returns the index filename in FileName.

  PARAMETERS
    hFSys (HFSYS) - input
        Handle to the currently open file system.

    FileName (PSZ) - output
        Pointer to a buffer which, upon return, will contain the index
        filename.

  RETURNS
    None.

  REMARKS
    The buffer 'FileName' should be at least CCHMAXPATH characters in length.
    This is defined in BSEDOS.H as 260.

  EXAMPLE CODE
    This example gets the filename used in the indexes.

        CHAR  FileName[CCHMAXPATH];
        HFSYS hFSys;

        FSysGetIndexFilename(hFSys, FileName);

  #include <fSys.h>

  VOID APIENTRY FSysSetIndexRecordOffset(HFSYS hFSys, LONG Offset)

  FSysSetRecordOffset sets the file offset of the file data record
  for use in the indexes.

  PARAMETERS
    hFSys (HFSYS) - input
        Handle to the currently open file system.

    Offset (LONG) - input
        Offset in the data file of the files data record.

  RETURNS
    None.

  REMARKS
    This is normally set by fSys.Dll.

    You can also set the offset to -1 to indicate to fSys that this file 
    should be appended to the data file. This would be used when adding
    a file to the file system.  When a file is added, the index record
    offset is updated by fSys.Dll to show you what the new offset is.

  EXAMPLE CODE
    This example adds a new file to the indexes, and data file.

        HFSYS hFSys;

        // indicate this is new file
        FSysSetIndexRecordOffset(hFSys, -1);

        // add record to data file
        FSysSetFileRecord(hFSys);

        // add in new index entries
        FSysAddIndexEntries(hFSys);

  #include <fSys.h>

  LONG APIENTRY FSysGetIndexRecordOffset(HFSYS hFSys)

  FSysGetIndexRecordOffset returns the file offset of the file data record.

  PARAMETERS
    hFSys (HFSYS) - input
        Handle to the currently open file system.

  RETURNS
    Offset of data file record.

  REMARKS
    Returns the file offset of the file data record stored in memory. This
    offset is used to distinguish one file (possibly with the same filename)
    from another.
    
  EXAMPLE CODE
    This example retrieves the offset of the file record stored in the file
    system indexes.

        HFSYS hFSys;
        LONG  RecordOffset;

        RecordOffset = FSysGetIndexRecordOffset(hFSys);

  #include <fSys.h>

  VOID APIENTRY FSysSetIndexAreaNumber(HFSYS hFSys, LONG Area)

  FSysSetIndexAreaNumber sets the file area number the current file will be
  listed in.

  PARAMETERS
    hFSys (HFSYS) - input
        Handle to the currently open file system.

    Area (LONG) - input
        AdeptXBBS file area number.

  RETURNS
    None.

  REMARKS
    Sets the index file area to the number of the AdeptXBBS file area in which
    the current file in memory resides. The file would then be listed in that
    area when the chose to list files. The number should be the same as the
    area number actually stored in the file record. If you change the index
    area number, you should also change the area number in the record, though
    this is not required.

  EXAMPLE CODE
    This example sets the area number used in the index files.

        #define DOS_UTILITIES   2  // My BBS File Area #2 is Dos util's

        HFSYS hFSys;

        FSysSetIndexAreaNumber(hFSys, DOS_UTILITIES);

  #include <fSys.h>

  LONG APIENTRY FSysGetIndexAreaNumber(HFSYS hFSys)

  FSysGetIndexAreaNumber returns the file area that the current file would
  be listed in.

  PARAMETERS
    hFSys (HFSYS) - input
        Handle to the currently open file system.

  RETURNS
    The AdeptXBBS file area number contained in the index for the current
    file.

  REMARKS
    Used to determine which file area the current file would be listed in.
    The index area number is stored in the indexes, not in the file record.

  EXAMPLE CODE
    This example retrieves the area number of the file record in the 
    file system indexes.

        HFSYS hFSys;
        LONG  RecordOffset;

        RecordOffset = FSysGetIndexRecordOffset(hFSys);

  #include <fSys.h>

  VOID APIENTRY FSysSetIndexEntryDate(HFSYS hFSys, PFDATE pEntryDate)

  FSysSetIndexEntryDate sets the date that the file was imported into the
  file system.

  PARAMETERS
    hFSys (HFSYS) - input
        Handle to the currently open file system.

    pEntryDate (PFDATE) - input
        Date file was added to the file system.

  RETURNS
    None.

  REMARKS
    This function sets the date that the current file was imported into the
    file system. This date is stored in the indexes. It is separate from the
    file date stored in the file record, but it is typically the same date.

  EXAMPLE CODE
    This example sets the file date, and index file date.

        time_t t;
        struct tm TimeBuf;
        FDATE TempFileDate;

        t = time(NULL);

        _localtime(&t, &TimeBuf);

        Date.year  = TimeBuf.tm_year;
        Date.month = TimeBuf.tm_mon + 1;
        Date.day   = TimeBuf.tm_mday;

        FSysSetFileDate(hFSys, &Date);

        //////////////////////////
        // Set index entry date //
        //////////////////////////
        FSysSetIndexEntryDate(hFSys, FSysGetFileDate(hFSys, &TempFileDate));

  #include <fSys.h>

  PFDATE APIENTRY FSysGetIndexEntryDate(HFSYS hFSys, PFDATE pEntryDate)

  FSysGetIndexEntryDate gets the date that the file was imported into the
  file system.

  PARAMETERS
    hFSys (HFSYS) - input
        Handle to the currently open file system.

    pEntryDate (PFDATE) - input/output
        Address of FDATE buffer to store date file was added to the file
        system.

  RETURNS
    'pEntryDate' buffer address is returned.

  REMARKS
    The date returned is the one stored in the file system indexes, not the
    file record itself.

  EXAMPLE CODE
    This example gets the file import date stored in the file indexes for the
    current file.

        HFSYS hFSys;
        FDATE FDate;

        FSysGetIndexEntryDate(hFSys, &FDate); 

  #include <fSys.h>

  APIRET APIENTRY FSysSetFileRecord(HFSYS hFSys)

  FSysSetFileRecord saves the file record to the File.Data file.

  PARAMETERS
    hFSys (HFSYS) - input
        Handle to the currently open file system.

  RETURNS
    Return Code.

     0        No error.
     150      Seek error
     151      Write error

  REMARKS
    This function tells FSys to save the current file record to disk.

    The offset at which to save the record is contained in the index record
    offset (ie. 'FSysSetIndexRecordOffset') and is usually set by FSys.

    If the IndexRecordOffset is -1, then file the data is appended to the
    file system.

  EXAMPLE CODE
    This example saves the current file in memory to the file system at
    the offset stored in the IndexRecordOffset.

        HFSYS hFSys;
        APIRET RetCode;

        RetCode = FSysSetFileRecord(hFSys);

  #include <fSys.h>

  APIRET APIENTRY FSysGetFileRecord(HFSYS hFSys)

  FSysGetFileRecord gets the file record at the current index record offset
  into memory.

  PARAMETERS
    hFSys (HFSYS) - input
        Handle to the currently open file system.

  RETURNS
    Return Code.

     0        No error.
     150      Seek error
     152      Read error

  REMARKS
    This function tells FSys to read the current file record from the disk.

    This function also sets the index filename, index entry date, and index 
    area number. It will also read in the description for the file, if any,
    if the 'read description' flag is TRUE. (See 'FSysSetReadDescFlag')
    You may not want to read in the description if all you are dealing with
    is the file data.

  EXAMPLE CODE
    This example gets the file at the offset stored in the IndexRecordOffset
    into memory.

        HFSYS hFSys;
        APIRET RetCode;

        RetCode = FSysGetFileRecord(hFSys);

  #include <fSys.h>

  APIRET APIENTRY FSysRawReadFileRecord(HFSYS hFSys)

  FSysRawReadFileRecord reads in a file record from the current file offset.

  PARAMETERS
    hFSys (HFSYS) - input
        Handle to the currently open file system.

  RETURNS
    0           No errors.
    152         FSYS_ERROR_READ

  REMARKS
    This function tells FSys to read the current file record from the disk.

    It reads from the current file pointer to the end of the record. It does
    not set or check the file pointer before doing so.

    This function is used when reading the records from disk one by one to
    the end of the file. It returns FSYS_ERROR_READ if any errors occur,
    which normally means the end of the file.

    This function also sets the index filename, index entry date, index 
    area number, and index record offset.

  EXAMPLE CODE

  #include <fSys.h>

  APIRET APIENTRY FSysZeroFileRecord(HFSYS hFSys)

  PARAMETERS
    hFSys (HFSYS) - input
        Handle to the currently open file system.

  RETURNS
    0           No errors.

  REMARKS
    This function wipes the current file record data, and description
    to all 'zeros', effectively eliminating the data in memory.

  EXAMPLE CODE
    This example gets the file record from the current file offset.

        HFSYS hFSys;
        APIRET RetCode;

        RetCode = FSysGetFileRecord(hFSys);

  #include <fSys.h>

  APIRET APIENTRY FSysResetFilePtr(HFSYS hFSys)

  FSysResetFilePtr sets the file data record pointer to the beginning of the
  file.

  PARAMETERS
    hFSys (HFSYS) - input
        Handle to the currently open file system.

  RETURNS
    Return Code.

    0           No errors.

    - any return code 'DosSetFilePtr' may return. See OS2 documentation -

  REMARKS
    This function returns the file pointer to the beginning of the file
    data file. It is most often used in conjunction with 
    'FSysRawReadFileRecord'.

  EXAMPLE CODE
    This example resets the file pointer to the beginning of the file data
    file and gets the file record.

        HFSYS hFSys;
        APIRET RetCode;

        RetCode = FSysResetFilePtr(hFSys);

        if (RetCode == 0)
            RetCode = FSysGetFileRecord(hFSys);

  #include <fSys.h>

  APIRET APIENTRY FSysResetDescFilePtr(HFSYS hFSys)

  FSysResetDescFilePtr sets the file description file pointer to the beginning
  of the file.

  PARAMETERS
    hFSys (HFSYS) - input
        Handle to the currently open file system.

  RETURNS
    Return Code.

    0           No errors.

    - any return code 'DosSetFilePtr' may return. See OS2 documentation -

  REMARKS
    This function returns the file pointer to the beginning of the file
    description file. It is most often used in conjunction with
    'FSysReadDescriptionLine'

  EXAMPLE CODE
        HFSYS hFSys;
        APIRET RetCode;
        CHAR LineBuffer[512];

        RetCode = FSysResetDescFilePtr(hFSys);

        if (RetCode == 0)
            RetCode = FSysReadDescriptionLine(hFSys, LineBuffer);

  #include <fSys.h>

  VOID APIENTRY FSysSetFileName(HFSYS hFSys, PSZ NewFileName)

  FSysSetFileName sets the filename of the file currently in memory.

  PARAMETERS
    hFSys (HFSYS) - input
        Handle to the currently open file system.

    NewFileName (PSZ) - input
        Pointer to buffer which contains the file name.

  RETURNS
    None.

  REMARKS
    In order to change the file name of a current file, you must first
    delete the current index entries, then change the file name, and
    then re-add the index entries to the file system.

    If you call FSysSetFileName, you should also call FSysSetIndexFilename.

    You will also want to rename the file on the disk :)

  EXAMPLE CODE
    This example sets the name of the file to 'MyFileName'.

        HFSYS hFSys;
        APIRET RetCode;

        FSysSetFileName(hFSys, "MyFileName");

  #include <fSys.h>

  PSZ APIENTRY FSysGetFileName(HFSYS hFSys, PSZ FileNameBuffer)

  PARAMETERS
    hFSys (HFSYS) - input
        Handle to the currently open file system.

    FileNameBuffer (PSZ) - input/output
        Buffer which will receive a copy of the current file name.

  RETURNS
    Pointer to 'FileNameBuffer'.

  REMARKS

  EXAMPLE CODE

  #include <fSys.h>

  VOID APIENTRY FSysSetUploader(HFSYS hFSys, PSZ NewUploader)

  PARAMETERS
    hFSys (HFSYS) - input
        Handle to the currently open file system.

    NewUploader (PSZ) - input
       Pointer to a buffer which contains the name of the person who
       added the file to the file system. 
       
  RETURNS
    None.

  REMARKS
    Sets the name of the person who added the file to the file system.
    The maximum size of the name is 19 characters.

  EXAMPLE CODE

  #include <fSys.h>

  PSZ APIENTRY FSysGetUploader(HFSYS hFSys, PSZ UploaderBuffer)

  PARAMETERS
    hFSys (HFSYS) - input
        Handle to the currently open file system.

    UploaderBuffer (PSZ) - input/output
        Buffer which will receive a copy of the person who added the file to
        the file system.

  RETURNS
    Pointer to 'UploaderBuffer'.

  REMARKS
    UploaderBuffer should be at least 20 characters in length.

  EXAMPLE CODE

  #include <fSys.h>

  VOID APIENTRY FSysSetPassword(HFSYS hFSys, PSZ NewPassword)

  PARAMETERS
    hFSys (HFSYS) - input
        Handle to the currently open file system.

    NewPassword (PSZ) - input
        Buffer which contains password needed to download file.

  RETURNS
    None.

  REMARKS
    The password should be no longer than 12 characters.

    NOTE: In the future the password may be saved as a 32-bit numerical
    representation of the password for security reasons. In this way
    the actual password is not saved to the disk. At this point, you
    will not be able to get the actual password from the file system,
    only the numerical representation of it.

  EXAMPLE CODE

  #include <fSys.h>

  PSZ APIENTRY FSysGetPassword(HFSYS hFSys, PSZ PasswordBuffer)

  PARAMETERS
    hFSys (HFSYS) - input
        Handle to the currently open file system.

    PasswordBuffer (PSZ) - input/output
        Buffer to copy the password to.

  RETURNS
    Pointer to 'PasswordBuffer'

  REMARKS
    The password buffer should be at least 13 characters in length.

    NOTE: In the future the password may be saved as a 32-bit numerical
    representation of the password for security reasons. In this way
    the actual password is not saved to the disk. At this point, you
    will not be able to get the actual password from the file system,
    only the numerical representation of it. Therefore the 'FSysGetPassword'
    function may change to return a 32-bit integer.


  EXAMPLE CODE

  #include <fSys.h>

  VOID APIENTRY FSysSetFileSize(HFSYS hFSys, ULONG NewSize)

  PARAMETERS
    hFSys (HFSYS) - input
        Handle to the currently open file system.

  RETURNS
    None.

  REMARKS

  EXAMPLE CODE

  #include <fSys.h>

  ULONG APIENTRY FSysGetFileSize(HFSYS hFSys)

  PARAMETERS
    hFSys (HFSYS) - input
        Handle to the currently open file system.

  RETURNS
    Returns the size of the file as stored in the file system record.

  REMARKS

  EXAMPLE CODE

  #include <fSys.h>

  VOID APIENTRY FSysSetPathIndex(HFSYS hFSys, ULONG NewPathIndex)

  PARAMETERS
    hFSys (HFSYS) - input
        Handle to the currently open file system.

  RETURNS
    None.

  REMARKS

  EXAMPLE CODE

  #include <fSys.h>

  ULONG APIENTRY FSysGetPathIndex(HFSYS hFSys)

  PARAMETERS
    hFSys (HFSYS) - input
        Handle to the currently open file system.

  RETURNS
    Returns the record number of the file path as stored in the 'File.Paths'
    file.

  REMARKS

  EXAMPLE CODE

  #include <fSys.h>

  VOID APIENTRY FSysSetFileArea(HFSYS hFSys, ULONG NewArea)

  PARAMETERS
    hFSys (HFSYS) - input
        Handle to the currently open file system.

    NewArea (LONG) - input
        AdeptXBBS file area number.

  RETURNS
    None.

  REMARKS
    In order to change the area number of a current file, you must first
    delete the current index entries, then change the area number, and
    then re-add the index entries to the file system.

    If you call FSysSetFileArea, you should also call FSysSetIndexAreaNumber.

  EXAMPLE CODE

  #include <fSys.h>

  ULONG APIENTRY FSysGetFileArea(HFSYS hFSys)

  PARAMETERS
    hFSys (HFSYS) - input
        Handle to the currently open file system.

  RETURNS
    The AdeptXBBS file area number this file is listed in.

  REMARKS

  EXAMPLE CODE

  #include <fSys.h>

  VOID APIENTRY FSysSetDescOffset(HFSYS hFSys, ULONG Offset)

  PARAMETERS
    hFSys (HFSYS) - input
        Handle to the currently open file system.

  RETURNS
    None.

  REMARKS

  EXAMPLE CODE

  #include <fSys.h>

  ULONG APIENTRY FSysGetDescOffset(HFSYS hFSys)

  PARAMETERS
    hFSys (HFSYS) - input
        Handle to the currently open file system.

  RETURNS
    Returns the file offset where the desciption of this file starts in the
    'File.Descriptions' file.
    
  REMARKS

  EXAMPLE CODE

  #include <fSys.h>

  VOID APIENTRY FSysSetTimesDL(HFSYS hFSys, ULONG TimesDL)

  PARAMETERS
    hFSys (HFSYS) - input
        Handle to the currently open file system.

  RETURNS
    None.

  REMARKS

  EXAMPLE CODE

  #include <fSys.h>

  LONG APIENTRY FSysGetTimesDL(HFSYS hFSys)

  PARAMETERS
    hFSys (HFSYS) - input
        Handle to the currently open file system.

  RETURNS
    Returns the number of times the file has been downloaded.

  REMARKS

  EXAMPLE CODE

  #include <fSys.h>

  VOID APIENTRY FSysSetGroup(HFSYS hFSys, SHORT Group)

  PARAMETERS
    hFSys (HFSYS) - input
        Handle to the currently open file system.

  RETURNS
    None.

  REMARKS

  EXAMPLE CODE

  #include <fSys.h>

  SHORT APIENTRY FSysGetGroup(HFSYS hFSys)

  PARAMETERS
    hFSys (HFSYS) - input
        Handle to the currently open file system.

  RETURNS

  REMARKS

  EXAMPLE CODE

  #include <fSys.h>

  VOID APIENTRY FSysSetAge(HFSYS hFSys, SHORT Age)

  PARAMETERS
    hFSys (HFSYS) - input
        Handle to the currently open file system.

  RETURNS
    None.

  REMARKS

  EXAMPLE CODE

  #include <fSys.h>

  SHORT APIENTRY FSysGetAge(HFSYS hFSys)

  PARAMETERS
    hFSys (HFSYS) - input
        Handle to the currently open file system.

  RETURNS
    Returns the minimum age require to list or download this file.

  REMARKS

  EXAMPLE CODE

  #include <fSys.h>

  VOID APIENTRY FSysSetCost(HFSYS hFSys, SHORT Cost)

  PARAMETERS
    hFSys (HFSYS) - input
        Handle to the currently open file system.

    Cost (SHORT) - input
        Cost in single monetary units need to download the file.

  RETURNS
    None.

  REMARKS
    The cost system is up to the SysOp. For instance the unit may
    be a penny, or it may be a dollar. But the SysOp should consistently
    use the same monetary unit.

  EXAMPLE CODE

  #include <fSys.h>

  SHORT APIENTRY FSysGetCost(HFSYS hFSys)

  PARAMETERS
    hFSys (HFSYS) - input
        Handle to the currently open file system.

  RETURNS
    Cost to download the current file.

  REMARKS
    The cost system is up to the SysOp. For instance the unit may
    be a penny, or it may be a dollar. But the SysOp should consistently
    use the same monetary unit.

  EXAMPLE CODE

  #include <fSys.h>

  VOID APIENTRY FSysSetFileDate(HFSYS hFSys, PFDATE pDate)

  PARAMETERS
    hFSys (HFSYS) - input
        Handle to the currently open file system.

  RETURNS
    None.

  REMARKS
    In order to change the upload date of a current file, you must first
    delete the current index entries, then change the upload date, and
    then re-add the index entries to the file system.

    If you call FSysSetFileDate, you should also call FSysSetIndexEntryDate.


  EXAMPLE CODE

  #include <fSys.h>

  PFDATE APIENTRY FSysGetFileDate(HFSYS hFSys, PFDATE pDateBuffer)

  PARAMETERS
    hFSys (HFSYS) - input
        Handle to the currently open file system.

  RETURNS
    Returns address of buffer passed in 'pDateBuffer'.

  REMARKS

  EXAMPLE CODE

  #include <fSys.h>

  VOID APIENTRY FSysSetSecLevel(HFSYS hFSys, ULONG NewSecLevel)

  PARAMETERS
    hFSys (HFSYS) - input
        Handle to the currently open file system.

    NewSecLevel (ULONG) - input
        AdeptXBBS security level needed to download file.

  RETURNS
    None.

  REMARKS
    This may not be used in the future. The security level may be taken
    from the file area information itself, instead of from the individual
    file.

  EXAMPLE CODE

  #include <fSys.h>

  ULONG APIENTRY FSysGetSecLevel(HFSYS hFSys)

  PARAMETERS
    hFSys (HFSYS) - input
        Handle to the currently open file system.

  RETURNS
    Security level needed to download the file.

    This may not be used in the future. The security level may be taken
    from the file area information itself, instead of from the individual
    file.

  REMARKS

  EXAMPLE CODE

  #include <fSys.h>

  VOID APIENTRY FSysSetFreeFile(HFSYS hFSys, BOOL IsFree)

  PARAMETERS
    hFSys (HFSYS) - input
        Handle to the currently open file system.

    IsFree (BOOL) - input
        Tells file system whether or not the file bypasses byte/time ratios.

  RETURNS
    None.

  REMARKS

  EXAMPLE CODE

  #include <fSys.h>

  BOOL APIENTRY FSysGetFreeFile(HFSYS hFSys)

  PARAMETERS
    hFSys (HFSYS) - input
        Handle to the currently open file system.

  RETURNS
    1           TRUE - File bypasses byte/time limits or ratios.
    0          FALSE - File does not bypass byte/time limits or ratios.

  REMARKS
    The FREEFILE flag says whether or not the file bypasses normal
    byte/time limits or ratios.

  EXAMPLE CODE

  #include <fSys.h>

  VOID APIENTRY FSysSetFreeTime(HFSYS hFSys, BOOL IsFree)

  PARAMETERS
    hFSys (HFSYS) - input
        Handle to the currently open file system.

    IsFree (BOOL) - input
        Tells file system whether or not the file bypasses time limits.

  RETURNS
    None.

  REMARKS

  EXAMPLE CODE

  #include <fSys.h>

  BOOL APIENTRY FSysGetFreeTime(HFSYS hFSys)

  PARAMETERS
    hFSys (HFSYS) - input
        Handle to the currently open file system.

  RETURNS
    1           TRUE - File bypasses time limits.
    0          FALSE - File does not bypass time limits.

  REMARKS

  EXAMPLE CODE

  #include <fSys.h>

  VOID APIENTRY FSysSetFreeBytes(HFSYS hFSys, BOOL IsFree)

  PARAMETERS
    hFSys (HFSYS) - input
        Handle to the currently open file system.

    IsFree (BOOL) - input
        Tells file system whether or not the file bypasses byte limits or
        ratios.

  RETURNS
    None.

  REMARKS

  EXAMPLE CODE

  #include <fSys.h>

  BOOL APIENTRY FSysGetFreeBytes(HFSYS hFSys)

  PARAMETERS
    hFSys (HFSYS) - input
        Handle to the currently open file system.

  RETURNS
    1           TRUE - File bypasses byte limits or ratios.
    0          FALSE - File does not bypass byte limits or ratios.

  REMARKS

  EXAMPLE CODE

  #include <fSys.h>

  VOID APIENTRY FSysSetCopyFile(HFSYS hFSys, BOOL CopyIt)

  PARAMETERS
    hFSys (HFSYS) - input
        Handle to the currently open file system.

    CopyIt (BOOL) - input
        Tells file system whether or not to copy the file from the drive
        on which it current resides to a temporary directory where the
        BBS resides.

  RETURNS
    None.

  REMARKS
    This flag is used to indicate whether or not the file should be copied
    from its present location to a temporary directory where the BBS resides.
    Most often it is used to copy a file from a CD-ROM to a hard disk.

  EXAMPLE CODE

  #include <fSys.h>

  BOOL APIENTRY FSysGetCopyFile(HFSYS hFSys)

  PARAMETERS
    hFSys (HFSYS) - input
        Handle to the currently open file system.

  RETURNS
    1           TRUE - Copy file to temporary directory.
    0          FALSE - Do not copy file.

  REMARKS

  EXAMPLE CODE

  #include <fSys.h>

  VOID APIENTRY FSysSetListable(HFSYS hFSys, BOOL ListOK)

  PARAMETERS
    hFSys (HFSYS) - input
        Handle to the currently open file system.

    ListOK (BOOL) - input
        Tells file system whether or not the file can be listed.

  RETURNS
    None.

  REMARKS

  EXAMPLE CODE

  #include <fSys.h>

  BOOL APIENTRY FSysGetListable(HFSYS hFSys)

  PARAMETERS
    hFSys (HFSYS) - input
        Handle to the currently open file system.

  RETURNS
    1           TRUE - File can be listed.
    0          FALSE - File cannot be listed.

  REMARKS

  EXAMPLE CODE

  #include <fSys.h>

  VOID APIENTRY FSysSetDLable(HFSYS hFSys, BOOL DLOK)

  PARAMETERS
    hFSys (HFSYS) - input
        Handle to the currently open file system.

    DLOK (BOOL) - input
        Tells file system whether or not the file can be downloaded.

  RETURNS
    None.

  REMARKS

  EXAMPLE CODE

  #include <fSys.h>

  BOOL APIENTRY FSysGetDLable(HFSYS hFSys)

  PARAMETERS
    hFSys (HFSYS) - input
        Handle to the currently open file system.

  RETURNS
    1           TRUE - File can be downloaded.
    0          FALSE - File cannot be downloaded.

  REMARKS

  EXAMPLE CODE

  #include <fSys.h>

  VOID APIENTRY FSysSetListed(HFSYS hFSys, BOOL Listed)

  PARAMETERS
    hFSys (HFSYS) - input
        Handle to the currently open file system.

    Listed (BOOL) - input
        Tells file system whether or not the file has been listed.

  RETURNS
    None.

  REMARKS
    Reserved flag. Indicates whether or not the file has been listed
    in the file system. (used when building new list)

  EXAMPLE CODE

  #include <fSys.h>

  BOOL APIENTRY FSysGetListed(HFSYS hFSys)

  PARAMETERS
    hFSys (HFSYS) - input
        Handle to the currently open file system.

  RETURNS
    1           TRUE - File has been listed.
    0          FALSE - File has not been listed.

  REMARKS
    Reserved flag. Indicates whether or not the file has been listed
    in the file system. (used when building new list)

  EXAMPLE CODE

  -----------------------------
  File listing functions
  -----------------------------

  #include <fSys.h>

  INT APIENTRY FSysFirstName(HFSYS hFSys)

  PARAMETERS
    hFSys (HFSYS) - input
        Handle to the currently open file system.

  RETURNS
    0           No error.
    >0          Error finding file.

  REMARKS
    Loads in the first name in the file system, alphabetically.

  EXAMPLE CODE

  #include <fSys.h>

  INT APIENTRY FSysFindExact(HFSYS hFSys, PSZ FileName, INT AreaNum)

  PARAMETERS
    hFSys (HFSYS) - input
        Handle to the currently open file system.

  RETURNS
    0           No error.
    >0          Error finding file.

  REMARKS
    Loads in the file name which matches the input parameters 'FileName',
    and 'AreaNum'.

  EXAMPLE CODE

  #include <fSys.h>

  INT APIENTRY FSysFindFirstName(HFSYS hFSys, PSZ SearchString)

  PARAMETERS
    hFSys (HFSYS) - input
        Handle to the currently open file system.

  RETURNS
    0           No error.
    >0          Error finding file.

  REMARKS
    Loads in the first file matching the search string.

    The search string 'RAF' may find the file 'RAFEL.ZIP', 

  EXAMPLE CODE

  #include <fSys.h>

  INT APIENTRY FSysFindNextName(HFSYS hFSys)

  PARAMETERS
    hFSys (HFSYS) - input
        Handle to the currently open file system.

  RETURNS
    0           No error.
    >0          Error finding file.

  REMARKS
    Loads in the next file matching the last search string.

  EXAMPLE CODE

  #include <fSys.h>

  INT APIENTRY FSysFindPreviousName(HFSYS hFSys)

  PARAMETERS
    hFSys (HFSYS) - input
        Handle to the currently open file system.

  RETURNS
    0           No error.
    >0          Error finding file.

  REMARKS
    Loads in the previous file matching the last search string.

  EXAMPLE CODE

  #include <fSys.h>

  INT APIENTRY FSysListFirst(HFSYS hFSys, INT AreaNum, ULONG Flags, ULONG Date,
                             PCHAR SearchString)

  PARAMETERS
    hFSys (HFSYS) - input
        Handle to the currently open file system.

    AreaNum (INT) - input
        AdeptXBBS area number to list.

    Flags (ULONG) - input
        FS_DATE - list files in dated order. Default is by name.
        FS_REV  - Reverse the order of the search.

    Date (ULONG) - input
        Unix style date (seconds since 1/1/70) at which to start a dated 
        search.

    SearchString (PCHAR) - input
        Filename search string.

  RETURNS
    0           No error.
    >0          Error finding file.

  REMARKS
    Loads in the first name in the file area indicated. By default the names
    are listed alphabetically, but if you use the FS_DATE flag, you may list
    the in dated order. If you use the FS_REV flag, you reverse the order of
    the search from dated:newest->oldest or alpha:z->a

  EXAMPLE CODE

  #include <fSys.h>

  INT APIENTRY FSysListNext(HFSYS hFSys)

  PARAMETERS
    hFSys (HFSYS) - input
        Handle to the currently open file system.

  RETURNS
    0           No error.
    >0          Error finding file.

  REMARKS
    Loads in the next file following the parameters set in 'FSysListFirst'.

    Note: FSysListNext does not stop when it reaches the next file area!
          You must check for that yourself.

  EXAMPLE CODE

  #include <fSys.h>

  INT APIENTRY FSysReadDescriptionLine(HFSYS hFSys, PSZ DescBuffer)

  PARAMETERS
    hFSys (HFSYS) - input
        Handle to the currently open file system.

  RETURNS
    INT - The file offset of the line immediately following the line read in.

  REMARKS
    Reads in the description file line by line.

    Lines beginning with ':' are remarked lines, and are ignored by the
    file system. 

    Lines beginning with ';' indicate that a filename and file area are
    on the same line:  ';filename areanum'

    All other lines are assumed to be description lines.

  EXAMPLE CODE

  #include <fSys.h>

  INT APIENTRY FSysGetFileDescription(HFSYS hFSys, PSZ DescBuffer)

  PARAMETERS
    hFSys (HFSYS) - input
        Handle to the currently open file system.

    DescBuffer (PSZ) - input/output
        Pointer to a buffer at least 4096 bytes in length.

  RETURNS
    0           No error.

  REMARKS
    Moves a  copy of the description from the DLLs data to a user supplied
    buffer. That buffer must be at least 4096 bytes in length. That is the
    maximum size of a description no matter how many lines it contains.

    Each line of the description is separated by a line feed '\n' character.

  EXAMPLE CODE

  #include <fSys.h>

  INT APIENTRY FSysSetFileDescription(HFSYS hFSys, PSZ DescBuffer)

  PARAMETERS
    hFSys (HFSYS) - input
        Handle to the currently open file system.

    DescBuffer (PSZ) - input
        Pointer to a buffer at least 4096 bytes in length.

  RETURNS

  REMARKS
    If there was already a file description, each line will be remarked out
    with colons ':' and then the new description added to the end of the file.

    DescBuffer should contain a description up to 4096 bytes in length each
    line separated by a '\n' line feed character.

  EXAMPLE CODE

  #include <fSys.h>

  VOID APIENTRY FSysSetReadDescFlag(HFSYS hFSys, BOOL ReadDesc)

  PARAMETERS
    hFSys (HFSYS) - input
        Handle to the currently open file system.

  RETURNS
    None.

  REMARKS
    Sets whether of not we want to read in the description whenever we read
    in the file data record. By default the description is always read in.
    You can change that with this function.

  EXAMPLE CODE
 
  ------------------------------
  Path where file resides
  ------------------------------

  #include <fSys.h>

  INT APIENTRY FSysReadFilePath(HFSYS hFSys, INT PathIndex, PSZ PathBuffer)

  PARAMETERS
    hFSys (HFSYS) - input
        Handle to the currently open file system.

  RETURNS

  REMARKS

  EXAMPLE CODE

  #include <fSys.h>

  INT APIENTRY FSysWriteFilePath(HFSYS hFSys, INT PathIndex, PSZ PathBuffer)

  PARAMETERS
    hFSys (HFSYS) - input
        Handle to the currently open file system.

  RETURNS

  REMARKS

  EXAMPLE CODE

  #include <fSys.h>

  INT APIENTRY FSysGetPathName(HFSYS hFSys, PSZ PathBuffer)

  PARAMETERS
    hFSys (HFSYS) - input
        Handle to the currently open file system.

    PathBuffer (PSZ) - input/output
        Pointer to a buffer which will receive the path name.

  RETURNS
    0           No error.

  REMARKS
    Returns the path name of the current file. 'PathBuffer' should be
    at least CCHMAXPATH bytes in size.

  EXAMPLE CODE
