home *** CD-ROM | disk | FTP | other *** search
/ ftp.wwiv.com / ftp.wwiv.com.zip / ftp.wwiv.com / pub / MISC / PBAPI10.ZIP / APIDOCS.ZIP / USERSSPM.DOC < prev    next >
Text File  |  1998-02-21  |  8KB  |  207 lines
  1. Author....... : Gary Price
  2. Copyrighted by: Freejack's Software 1997-98
  3.  
  4. USERS_SPM API for TriBBS v10.x/11.x written in PowerBasic v3.5
  5. ---------------------------------------------------------------------------
  6.  
  7. The USERS_SPM unit is used to manipulate data in the USERS.SPM data file
  8. found in node 1's MWORK directory. The USERS.SPM unit is declared in
  9. PBAPI10.INC as follows:
  10.  
  11. ===========================================================================
  12. Users.spm BitField Breakdown
  13.  
  14.   BIT Assignment
  15.     0 = AccessPrivateConferenceFlag      0 = No, 1 = Yes
  16.     1 = CoSysopStatusFlag                0 = No, 1 = Yes
  17.     2 to 7 = 0 (Reserved)
  18.  
  19. Sub Type Structure for 1 byte BitFields
  20.   TYPE UserSpmBit
  21.     bit1 AS BYTE
  22.   END TYPE
  23.  
  24. -----------------------------------------------------------------------------
  25.  
  26. File Name: "USERS.SPM"
  27.    TYPE USERSSPM
  28.      LastMessageRead        AS LONG
  29.      LastWaitingMessageRead AS LONG
  30.      WaitingMessageCounter  AS INTEGER
  31.      QueuedConference       AS INTEGER
  32.      UserSpmBitFields       AS UserSpmBit
  33.    END TYPE
  34.  
  35.    DIM UserSpmBit AS UserSpmBit
  36.    DIM USERSSPM   AS SHARED USERSSPM
  37.    DIM uspm       AS SHARED USERSSPM PTR
  38.  
  39.    uspm = VARPTR32(USERSSPM)
  40.    LSET USERSSPM = USERSSPM
  41. -----------------------------------------------------------------------------
  42.  
  43. FUNCTION's below are from the USERSSPM.PBU Unit and DECLAREd in PBAPI10.INC.
  44.  
  45. FUNCTION USERS_SPM_OPEN()
  46. FUNCTION USERS_SPM_CLOSE()
  47. FUNCTION USERS_SPM_READ(u AS WORD, n AS INTEGER)
  48. FUNCTION USERS_SPM_WRITE(u AS WORD, n AS INTEGER)
  49. FUNCTION USERS_SPM_OpenRead(u AS WORD, n AS INTEGER)
  50. FUNCTION USERS_SPM_WriteClose(u AS WORD, n AS INTEGER)
  51. FUNCTION USERS_SPM_OpenReadClose(u AS WORD, n AS INTEGER)
  52. FUNCTION USERS_SPM_OpenWriteClose(u AS WORD, n AS INTEGER)
  53. FUNCTION USERS_SPM_Clearit(n AS WORD)
  54. FUNCTION USERS_SPM_TotalRecords() AS WORD
  55.  
  56. FUNCTION USERS_SPM_GetLMR() AS LONG
  57. FUNCTION USERS_SPM_PutLMR(n AS LONG)
  58. FUNCTION USERS_SPM_GetLWMR() AS LONG
  59. FUNCTION USERS_SPM_PutLWMR(n AS LONG)
  60. FUNCTION USERS_SPM_GetWMC() AS INTEGER
  61. FUNCTION USERS_SPM_PutWMC(n AS INTEGER)
  62. FUNCTION USERS_SPM_GetQC() AS INTEGER
  63. FUNCTION USERS_SPM_PutQC(n AS INTEGER)
  64. FUNCTION USERS_SPM_GetAPCF() AS INTEGER
  65. FUNCTION USERS_SPM_PutAPCF(n AS INTEGER)
  66. FUNCTION USERS_SPM_GetCSSF() AS INTEGER
  67. FUNCTION USERS_SPM_PutCSSF(n AS INTEGER)
  68. -----------------------------------------------------------------------------
  69.  
  70. The total file size for the Users.spm file is determined by the following
  71. formula:
  72.  
  73. Users.spm record length = 13 Bytes
  74.  
  75. SizeOf(Users.spm) = (13 * TotalRecordsOf(Mconf.dat) * TotalRecordsOf(Users.dat))
  76.  
  77. -----------------------------------------------------------------------------
  78. IMPORTANT NOTES:
  79.  
  80.   Before these functions will allow you to write to the users.spm file, the
  81.   Mconf.dat must not be at '0' bytes. Otherwise, these functions will abort
  82.   if a call is made and the Mconf.dat is at '0' bytes.
  83.  
  84.   Also, before you can use USERS_SPM_Clearit(n AS WORD) to add a new set of
  85.   records to the Users.spm, record 'n' must first be added to the Users.dat
  86.   file as these function will check to see if 'n' exist first prior to doing
  87.   any operations.
  88.  
  89. -----------------------------------------------------------------------------
  90.  MPORTANT: TBNode1sMainDirectory must be set to node 1's main directory
  91.  before calling any function with the "Open" word.
  92. -----------------------------------------------------------------------------
  93.  
  94. USERS_SPM_Open()
  95.  The USERS_SPM_Open function opens the USERS.SPM data file in node 1's MWORK
  96.  directory. 
  97.  
  98. USERS_SPM_Close()
  99.  The USERS_SPM_Close function closes the USERS.SPM data file in node 1's MWORK
  100.  directory.
  101.  
  102. USERS_SPM_Read(u AS WORD, n AS INTEGER)
  103.  The USERS_SPM_Read function reads the data record for user "u" and message
  104.  conference "n" into memory.
  105.  
  106. USERS_SPM_Write(u AS WORD, n AS INTEGER)
  107.  The USERS_SPM_Write function updates the data record for user "u" and message
  108.  conference "n" from memory.
  109.  
  110. USERS_SPM_OpenRead(u AS WORD, n AS INTEGER)
  111.  The USERS_SPM_OpenRead function provides the functionality of the
  112.  USERS_SPM_Open and USERS_SPM_Read functions in a single function call.
  113.  
  114. USERS_SPM_WriteClose(u AS WORD, n AS INTEGER)
  115.  The USERS_SPM_WriteClose function provides the functionality of the
  116.  USERS_SPM_Write and USERS_SPM_Close functions in a single function call.
  117.  
  118. USERS_SPM_OpenReadClose(u AS WORD, n AS INTEGER)
  119.  The USERS_SPM_OpenReadClose function provides the functionality of the
  120.  USERS_SPM_Open, USERS_SPM_Read, and USERS_SPM_Close functions in a single
  121.  function call.
  122.  
  123. USERS_SPM_OpenWriteClose(u AS WORD, n AS INTEGER)
  124.  The USERS_SPM_OpenWriteClose function provides the functionality of the
  125.  USERS_SPM_Open, USERS_SPM_Write, and USERS_SPM_Close functions in a single
  126.  function call.
  127.  
  128. USERS_SPM_ClearIt(n AS WORD)
  129.  The USERS_SPM_ClearIt function sets the entire USERS_SPM data record for 'n'
  130.  to all zeros. Also can be used to add new records for 'n' to the Users.spm
  131.  file, however, this function will check to see if this record has been added
  132.  to the Users.dat file first, if not, then this function will abort.
  133.  
  134. USERS_SPM_TotalRecords() AS WORD
  135.  The USERS_SPM_TotalRecords function will return Total Records for a single
  136.  user. If Mconf.dat is 0 byte, then this function will abort.
  137.  
  138. -----------------------------------------------------------------------------
  139. POINTERS Uses a hidden variable I use called "@uspm". Any reference to this
  140. is only for your information for discussion in this doc file. You will not
  141. need to concern yourself trying to use this.. All calls are handled in the
  142. main USERSSPM.PBU Unit by my routines automatically. In other words, I am
  143. trying to keep Pointers as easy as possible for your use. :)
  144. -----------------------------------------------------------------------------
  145.  
  146. USERS_SPM_GetLMR() AS LONG
  147.  This form of the USERS_SPM_GetLMR function returns the user's last message
  148.  read.
  149.  
  150. USERS_SPM_PutLMR(n AS LONG)
  151.  This form of the USERS_SPM_PutLMR function sets the user's last message read
  152.  to "n".
  153.  
  154. USERS_SPM_GetLWMR() AS LONG
  155.  This form of the USERS_SPM_GetLWMR function returns the user's last waiting
  156.  message read.
  157.  
  158. USERS_SPM_PutLWMR(n AS LONG)
  159.  This form of the USERS_SPM_PutLWMR function sets the user's last waiting
  160.  message read to "n".
  161.  
  162. USERS_SPM_GetWMC() AS INTEGER
  163.  This form of the USERS_SPM_GetWMC function returns the user's waiting message
  164.  counter.
  165.  
  166. USERS_SPM_PutWMC(n AS INTEGER)
  167.  This form of the USERS_SPM_PutWMC function sets the user's waiting message
  168.  counter to "n".
  169.  
  170. USERS_SPM_GetQC() AS INTEGER
  171.  This form of the USERS_SPM_GetQC function returns the user's queued
  172.  conference flag.
  173.  
  174. USERS_SPM_PutQC(n AS INTEGER)
  175.  This form of the USERS_SPM_QueuedConference function sets the user's queued
  176.  conference flag to "n". "n" must be in the range of 0 to 1 as follows:
  177.  
  178.     0 = The conference isn't queued.
  179.     1 = The conference is queued.
  180.  
  181. -----------------------------------------------------------------------------
  182. All BIT Field Flags below have been converted to Integers to allow easier
  183. access and handling.
  184. -----------------------------------------------------------------------------
  185. USERS_SPM_GetAPCF() AS INTEGER
  186.  This form of the USERS_SPM_GetAPC function returns the user's access private
  187.  conference flag.
  188.  
  189. USERS_SPM_PutAPCF(n AS INTEGER)
  190.  This form of the USERS_SPM_AccessPrivateConference function sets the user's
  191.  access private conference flag to "n". "n" must be in the range of 0 to 1
  192.  as follows:
  193.  
  194.     0 = The user doesn't have access to a private conference.
  195.     1 = The user has access to a private conference.
  196.  
  197. USERS_SPM_GetCSSF() AS INTEGER
  198.  This form of the USERS_SPM_GetCSS function returns the user's Cosysop status
  199.  flag.
  200.  
  201. USERS_SPM_PutCSSF(n AS INTEGER)
  202.  This form of the USERS_SPM_CoSysopStatus function sets the user's Cosysop
  203.  status flag to "n". "n" must be in the range of 0 to 1 as follows:
  204.  
  205.     0 = The user doesn't have cosysop status in the conference.
  206.     1 = The user has cosysop status in the conference.
  207.