ftp.wwiv.com/ftp.wwiv.com.zip/ftp.wwiv.com/pub/MISC/PBAPI10.ZIP/APIDOCS.ZIP/FAREA.DOC

Text File | 1998-02-21 | 14KB | 366 lines

Author....... : Gary Price
Copyrighted by: Freejack's Software 1997-98

FAREA_DAT API for TriBBS v10.x/11.x written in PowerBasic v3.5
---------------------------------------------------------------------------

The FAREA_DAT unit is used to manipulate data in the FAREA.DAT data file
found in node 1's MWORK directory. The FAREA_DAT unit is declared in
PBAPI10.INC as follows:

 Farea.dat BitFields Breakdown

 FareaBit.bit1 BIT Assignment
    0 = PrivateAreaFlag
    1 = CDROMFileAreaFlag
    2 = AliasAreaFlag
    3 = OfflineFileAreaFlag
    4 = MasterIndexFlag
    5 to 7 Reserved, set to all 0's

 FareaBit.bit2 to FareaBit.bit10, Reserved and all bit's set to 0

 Sub Type Structure for 10 byte BitFields
TYPE FareaBit
  bit1  AS BYTE
  bit2  AS BYTE
  bit3  AS BYTE
  bit4  AS BYTE
  bit5  AS BYTE
  bit6  AS BYTE
  bit7  AS BYTE
  bit8  AS BYTE
  bit9  AS BYTE
  bit10 AS BYTE
END TYPE

---------------------------------------------------------------------------

 Sub Type Structure for 10 Additional File Area Paths BitFields

TYPE AFAP
  FP1  AS STRING * 81
  FP2  AS STRING * 81
  FP3  AS STRING * 81
  FP4  AS STRING * 81
  FP5  AS STRING * 81
  FP6  AS STRING * 81
  FP7  AS STRING * 81
  FP8  AS STRING * 81
  FP9  AS STRING * 81
  FP10 AS STRING * 81
END TYPE

---------------------------------------------------------------------------

 File Name: Main Type Structure for "FAERA.DAT" file

TYPE FAREA
  FareaName               AS STRING * 41
  FileAreaPath            AS STRING * 81
  FileAreaUploadPath      AS STRING * 81
  FileAreaFileList        AS STRING * 81
  FileAreaUploadList      AS STRING * 81
  FileAreaIndexFile       AS STRING * 81
  AdditionalFileAreaPaths AS AFAP
  SecurityLevel           AS INTEGER
  ViewSecurityLevel       AS INTEGER
  FileSortType            AS INTEGER
  FileBitFields           AS FareaBit
  OfflineDiscNumber       AS INTEGER
  ReservedDataArea        AS STRING * 2822
END TYPE

DIM FareaBit AS FareaBit
DIM AFAP     AS AFAP
DIM FAREA    AS SHARED FAREA
DIM fa       AS SHARED FAREA PTR

fa = VARPTR32(FAREA)
LSET FAREA = FAREA
---------------------------------------------------------------------------

FUNCTION's below are from the FAREA.PBU Unit and DECLAREd in PBAPI10.INC.

FUNCTION FAREA_DAT_OPEN()
FUNCTION FAREA_DAT_CLOSE()
FUNCTION FAREA_DAT_READ(n AS INTEGER)
FUNCTION FAREA_DAT_WRITE(n AS INTEGER)
FUNCTION FAREA_DAT_Length() AS LONG
FUNCTION FAREA_DAT_OpenRead(n AS INTEGER)
FUNCTION FAREA_DAT_WriteClose(n AS INTEGER)
FUNCTION FAREA_DAT_OpenReadClose(n AS INTEGER)
FUNCTION FAREA_DAT_OpenWriteClose(n AS INTEGER)
FUNCTION FAREA_DAT_Clearit(n AS INTEGER)

FUNCTION FAREA_DAT_GetFAN() AS STRING
FUNCTION FAREA_DAT_PutFAN(s AS STRING)
FUNCTION FAREA_DAT_GetFAP() AS STRING
FUNCTION FAREA_DAT_PutFAP(s AS STRING)
FUNCTION FAREA_DAT_GetFAUP() AS STRING
FUNCTION FAREA_DAT_PutFAUP(s AS STRING)
FUNCTION FAREA_DAT_GetFAFL() AS STRING
FUNCTION FAREA_DAT_PutFAFL(s AS STRING)
FUNCTION FAREA_DAT_GetFAUL() AS STRING
FUNCTION FAREA_DAT_PutFAUL(s AS STRING)
FUNCTION FAREA_DAT_GetFAIF() AS STRING
FUNCTION FAREA_DAT_PutFAIF(s AS STRING)
FUNCTION FAREA_DAT_GetAFAP(n AS INTEGER) AS STRING
FUNCTION FAREA_DAT_PutAFAP(n AS INTEGER, s AS STRING)

FUNCTION FAREA_DAT_GetSL() AS INTEGER
FUNCTION FAREA_DAT_PutSL(n AS INTEGER)
FUNCTION FAREA_DAT_GetVSL() AS INTEGER
FUNCTION FAREA_DAT_PutVSL(n AS INTEGER)
FUNCTION FAREA_DAT_GetODN() AS INTEGER
FUNCTION FAREA_DAT_PutODN(n AS INTEGER)
FUNCTION FAREA_DAT_GetFST() AS INTEGER
FUNCTION FAREA_DAT_PutFST(n AS INTEGER)

FUNCTION FAREA_DAT_GetPFAF() AS INTEGER
FUNCTION FAREA_DAT_PutPFAF(n AS INTEGER)
FUNCTION FAREA_DAT_GetCDFAF() AS INTEGER
FUNCTION FAREA_DAT_PutCDFAF(n AS INTEGER)
FUNCTION FAREA_DAT_GetAFAF() AS INTEGER
FUNCTION FAREA_DAT_PutAFAF(n AS INTEGER)
FUNCTION FAREA_DAT_GetOFAF() AS INTEGER
FUNCTION FAREA_DAT_PutOFAF(n AS INTEGER)
FUNCTION FAREA_DAT_GetMIFAF() AS INTEGER
FUNCTION FAREA_DAT_PutMIFAF(n AS INTEGER)

-----------------------------------------------------------------------------
IMPORTANT: TBNode1sMainDirectory must be set to node 1's main directory
           before calling to any Function with the "OPEN" command in it.

FAREA_DAT_Open
 The FAREA_DAT_Open Function opens the FAREA.DAT data file in node 1's MWORK
  directory.

FAREA_DAT_Close
 The FAREA_DAT_Close Function closes the FAREA.DAT data file in node 1's MWORK
 directory.

FAREA_DAT_Read(n AS INTEGER)
 The FAREA_DAT_Read Function reads the record for file area "n" into memory.

FAREA_DAT_Write(n AS INTEGER)
 The FAREA_DAT_Write Function updates the record for file area "n" from
 memory.

FAREA_DAT_Length() AS LONG
 The FAREA_DAT_Length Function returns the number of records in the FAREA.DAT
 file.

FAREA_DAT_OpenRead(n AS INTEGER)
 The FAREA_DAT_OpenRead Function provides the Functionality of the
 FAREA_DAT_Open and FAREA_DAT_Read Functions in a single Function call.

FAREA_DAT_WriteClose(n AS INTEGER)
 The FAREA_DAT_WriteClose Function provides the Functionality of the
 FAREA_DAT_Write and FAREA_DAT_Close Functions in a single Function call.

FAREA_DAT_OpenReadClose(n AS INTEGER)
 The FAREA_DAT_OpenReadClose Function provides the Functionality of the
 FAREA_DAT_Open, FAREA_DAT_Read, and FAREA_DAT_Close Functions in a single
 Function call.

FAREA_DAT_OpenWriteClose(n AS INTEGER)
 The FAREA_DAT_OpenWriteClose Function provides the Functionality of the
 FAREA_DAT_Open, FAREA_DAT_Write, and FAREA_DAT_Close Functions in a single
 Function call.

FAREA_DAT_ClearIt(n AS INTEGER)
 The FAREA_DAT_ClearIt Function sets the entire FAREA_DAT data record for 'n'
 to all zeros, leaving the data record in place, but empty.

-----------------------------------------------------------------------------
POINTERS Uses a hidden variable I use called "@fa". Any reference to this is
only for your information for discussion in this doc file. You will not need
to concern yourself trying to use this.. All calls are handled in the main
FAREA.PBU Unit by my routines automatically. In other words, I am trying to
keep Pointers as easy as possible for your use. :)

Also, all calls to any Functions which gets data with the string routines
will auto-trim each string's extra spaces and the null terminator, CHR$(0),
off so printing will be easier for you to manipulate. When calling the string
routines to put data back into the string space, all string data will be
resized to fit the farea.dat type structure and will add the null terminator
back to the end of the string. Just remember, when working the data in memory
with the pointer calls, you still have to write the data back to the farea.dat
in order for the changes to become permanent.

-----------------------------------------------------------------------------
FAREA_DAT_GetFAN() AS STRING
 This form of the FAREA_DAT_GetFAN Function returns a pointer to the file
 area's name string. Also, trims the extra spaces off of the end of the
 string.

FAREA_DAT_PutFAN(s AS STRING)
 This form of the FAREA_DAT_PutFAN Function sets the file area's name string
 to the string pointed to by "@fa". Note that the string pointed to by "@fa"
 can be no more than 40 characters in length. Also, will add the NULL
 Terminator back to the end of the string.

FAREA_DAT_GetFAP() AS STRING
 This form of the FAREA_GetDAT_GetFAP Function returns a pointer to the file
 area's file area path string. Also, trims the extra spaces off of the end of
 the string.

FAREA_DAT_PutFAP(s AS STRING)
 This form of the FAREA_DAT_PutFAP Function sets the file area's file area
 path string to the string pointed to by "@fa". Note that the string pointed
 to by "@fa" can be no more than 80 characters in length. Also, will add the
 NULL Terminator back to the end of the string.

FAREA_DAT_GetFAUP() AS STRING
 This form of the FAREA_DAT_GetFAUP Function returns a pointer to the file
 area's file area upload path string. Also, trims the extra spaces off of
 the end of the string.

FAREA_DAT_PutFAUP(s AS STRING)
 This form of the FAREA_DAT_PutFAUP Function sets the file area's file area
 upload path string to the string pointed to by "@fa".  Note that the string
 pointed to by "@fa" can be no more than 80 characters in length. Also, will
 add the NULL Terminator back to the end of the string.

FAREA_DAT_GetFAFL() AS STRING
 This form of the FAREA_DAT_GetFAFL Function returns a pointer to the file
 area's file area file list string. Also, trims the extra spaces off of the
 end of the string.

FAREA_DAT_PutFAFL(s AS STRING)
 This form of the FAREA_DAT_PutFAFL Function sets the file area's file area
 file list string to the string pointed to by "@fa". Note that the string
 pointed to by "@fa" can be no more than 80 characters in length. Also, will
 add the NULL Terminator back to the end of the string.

FAREA_DAT_GetFAUL() AS STRING
 This form of the FAREA_GetDAT_FAUL Function returns a pointer to the file
 area's file area upload list string. Also, trims the extra spaces off of
 the end of the string.

FAREA_DAT_PutFAUL(s AS STRING)
 This form of the FAREA_DAT_PutFAUL Function sets the file area's file area
 upload list string to the string pointed to by "@fa".  Note that the string
 pointed to by "@fa" can be no more than 80 characters in length. Also, will
 add the NULL Terminator back to the end of the string.

FAREA_DAT_GetFAIF() AS STRING
 This form of the FAREA_DAT_GetFAIF Function returns a pointer to the file
 area's file area index file string. Also, trims the extra spaces off of the
 end of the string.

FAREA_DAT_PutFAIF(s AS STING)
 This form of the FAREA_DAT_PutFAIF Function sets the file area's file area
 index file string to the string pointed to by "@fa". Note that the string
 pointed to by "@fa" can be no more than 80 characters in length. Also, will
 add the NULL Terminator back to the end of the string.

FAREA_DAT_GetAFAP(n AS INTEGER) AS STRING
 This form of the FAREA_DAT_GetAFAP Function returns a pointer to the file
 area's additional file area path string number "(n)". "(n)" can be 1 to 10
 for the 10 additional file area paths. Also, trims the extra spaces off of
 the end of the string.

FAREA_DAT_PutAFAP(n AS INTEGER, s AS STRING)
 This form of the FAREA_DAT_PutAFAP Function sets a file area's additional
 file area paths string number "n" to the string pointed to by "@fa".  Note
 that the string pointed to by "@fa" can be no more than 80 characters in
 length. "n" can be 1 to 10 for the 10 additional file area paths. Also,
 will add the NULL Terminator back to the end of the string.

FAREA_DAT_GetSL() AS INTEGER
 This form of the FAREA_DAT_GetSL Function returns the file area's security
 level.

FAREA_DAT_PutSL(n AS INTEGER)
 This form of the FAREA_DAT_SecurityLevel Function sets the file area's
 security level to "n". "n" must be in the range of "0 to 9999."

FAREA_DAT_GetVSL() AS INTEGER
 This form of the FAREA_DAT_GetVSL Function returns the file area's view
 security level.

FAREA_DAT_PutVSL(n AS INTEGER)
 This form of the FAREA_DAT_PutVSL Function sets the file area's security
 level to "n". "n" must be in the range of "0 to 9999."

FAREA_DAT_GetODN() AS INTEGER
 This form of the FAREA_DAT_GetODN Function returns the file area's offline
 disc number.

FAREA_DAT_PutODN(n AS INTEGER)
 This form of the FAREA_DAT_PutODN Function sets the file area's offline disc
 number to "n". "n" must be in the range of "0 to 9999."

FAREA_DAT_GetFST() AS INTEGER
 This form of the FAREA_DAT_GetFST Function returns the file area's sort type.

FAREA_DAT_PutFST(n AS INTEGER)
 This form of the FAREA_DAT_PutFST Function sets the file area's sort type to
 "n". "n" must be in the range of 0 to 1 as follows:

    0 = Sorts the file list by date.
    1 = Sorts the file list alphabetically by file name.

-----------------------------------------------------------------------------
The BIT Fields, Private File Area Flag, CDROM File Area Flag, Alias Area Flag,
Offline File Area Flag, & Master Index Flag, have been converted to INTEGER's
to allow easier access and handling.
-----------------------------------------------------------------------------

FAREA_DAT_GetPFAF() AS INTEGER
 This form of the FAREA_DAT_GetPFAF Function returns the file area's private
 file area flag.

FAREA_DAT_PutPFAF(n AS INTEGER)
 This form of the FAREA_DAT_PutPFAF Function sets the file area's private
 file area flag to "n". "n" must be in the range of 0 to 1 as follows:

    0 = The file area is not a private file area.
    1 = The file area is a private file area.

FAREA_DAT_GetCDFAF() AS INTEGER
 This form of the FAREA_DAT_GetCDFAF Function returns the file area's CDROM
 file area flag.

FAREA_DAT_PutCDFAF(n AS INTEGER)
 This form of the FAREA_DAT_PutCDFAF functoin sets the file area's CDROM file
 area flag to "n". "n" must be in the range of 0 to 1 as follows:

    0 = The file area isn't a CD-ROM file area.
    1 = The file area is a CD-ROM file area.

FAREA_DAT_GetAFAF() AS INTEGER
 This form of the FAREA_DAT_GetAFAF Function returns the file area's alias
 file area flag.

FAREA_DAT_PutAFAF(n AS INTEGER)
 This form of the FAREA_DAT_PutAFAF Function sets the file area's alias file
 area flag to "n". "n" must be in the range of 0 to 1 as follows:

    0 = The file area isn't an alias file area.
    1 = The file area is an alias file area.

FAREA_DAT_GetOFAF() AS INTEGER
 This form of the FAREA_DAT_GetOFAF Function returns the file area's offline
 file area flag.

FAREA_DAT_PutOFAF(n AS INTEGER)
 This form of the FAREA_DAT_PutOFAF Function sets the file area's offline
 file area flag to "n".  "n" must be in the range of 0 to 1 as follows:

    0 = The file area isn't an offline file area.
    1 = The file area is an offline file area.

FAREA_DAT_GetMIFAF() AS INTEGER
 This form of the FAREA_DAT_GetMIFAF Function returns the file area's master
 index file area flag.

FAREA_DAT_PutMIFAF(n AS INTEGER)
 This form of the FAREA_DAT_PutMIFAF Function sets the file area's master
 index file area flag to "n".  "n" must be in the range of 0 to 1 as follows:

    0 = Do not include this file area in the master index.
    1 = Include this file area in the master index.