home *** CD-ROM | disk | FTP | other *** search
/ Collection of Hack-Phreak Scene Programs / cleanhpvac.zip / cleanhpvac / DEVELOP.ZIP / MSGS.DOC < prev    next >
Text File  |  1993-03-24  |  16KB  |  349 lines
  1.   WARNING:  This document is subject to change at any time.  Any changes made
  2.   will be indicated by a vertical bar (|) in column 1 of the file.
  3.  
  4. | Last update: 03/24/93
  5.  
  6. =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
  7.  
  8.   The following information documents the format for PCBoard's message base
  9.   and message index formats.
  10.  
  11.   The message base consists of 128-byte blocks of data.  A single 128 byte
  12.   header is placed at the start of each message base giving information such
  13.   as the number of messages in the message base and the low to high range of
  14.   message numbers within the message base.
  15.  
  16.   Each individual message subsequently consists of a 128-byte header
  17.   describing who the message is to and from and an indicator of how many
  18.   128-byte blocks comprise the entire message.
  19.  
  20.   The following layout is specified in a "byte offset" format such that the
  21.   first field begins at offset 0.
  22.  
  23.   The following is a definition of the variable types that will be used below:
  24.  
  25.     char   = a 1 byte character
  26.     str    = an array of 2 or more "char" bytes
  27.     bsreal = a 4 byte Basic Single Precision real number
  28. |   int    = a 2 byte integer
  29. |   long   = a 4 byte integer
  30. |   bitmap = a single byte with individual bits set on or off
  31.  
  32.   Note that strings are not NULL terminated and that the length specified for
  33.   the string is full number of useable and storeable bytes.  All strings are
  34.   padded with spaces to fill the entire field.
  35.  
  36.  
  37.   Message Base Header
  38.   -------------------
  39.  
  40.     Offset  Type   Length Description
  41.     ------ ------  ------ -----------
  42.        0   bsreal     4   High Message Number       (0 to 16,700,000)
  43.        4   bsreal     4   Low Message Number        (0 to 16,700,000)
  44.        8   bsreal     4   Number of Active Messages (0 to 32,767)
  45.       12   bsreal     4   Number of System Callers (Main Message Base Only)
  46.       16   str        6   The "LOCKED" field for pre-14.2 systems (see note 1)
  47.       22   str      106   Reserved for future use
  48.  
  49.  
  50.   Individual Message Headers
  51.   --------------------------
  52.  
  53.     Offset   Type   Length  Description
  54.     ------  ------  ------  -----------
  55.        0    char       1    Message Status Flag (see note 2)
  56.        1    bsreal     4    Message Number   (0 to 16,700,000)
  57.        5    bsreal     4    Reference Number (0 to 16,700,000)
  58.        9    char       1    Number of 128 Byte Blocks in Message (see note 3)
  59.       10    str        8    Date of Message Entry (in "mm-dd-yy" format)
  60.       18    str        5    Time of Message Entry (in "hh:mm" format)
  61.       23    str       25    Name of the User to whom the Message is Addressed
  62.       48    bsreal     4    Date of the Reply Message (in yymmdd format)
  63.       52    str        5    Time of the Reply Message (in "hh:mm" format)
  64.       57    char       1    The Letter "R" if the Message has a Reply
  65.       58    str       25    Name of the User who wrote the Message
  66.       83    str       25    Subject of the Message
  67.      108    str       12    Password Need to Read the Message (if any)
  68.      120    char       1    Active Status (225 = active, 226 = inactive)
  69.      121    char       1    The Letter "E" if the Message is to be Echoed
  70. |    122    str        4    Reserved for future use
  71. |    127    bitmap     1    Extended Header Flags
  72. |    128    char       1    Reserved for future use
  73.  
  74.  
  75. | Extended Header Format
  76. | ----------------------
  77. | A mesage may contain one or more EXTENDED HEADERS within the body of the
  78. | message.  Please refer to HEADERS.DOC for a discussion of each of these
  79. | headers and their uses.
  80. |
  81. | The following is the physical layout of the Extended Header within the
  82. | message body.  You may assume that as soon as the Extended Header ID is not
  83. | found that there are no more extended headers in the message body.
  84. |
  85. |   Offset   Type   Length  Description
  86. |   ------  ------  ------  -----------
  87. |      0    int        2    Extended Header ID = must be equal to 40FFh
  88. |      2    str        7    Extended Header Function
  89. |      9    char       1    A colon (:) character
  90. |     10    str       60    Extended Header Description (subj, to, from, etc)
  91. |     70    char       1    Status (N or R)
  92. |     71    char       1    Line Separator (E3h, or 0Dh for foreign systems)
  93. |
  94. | While any value may be used for the Extended Header Function field, the only
  95. | values recognized and processed directly by PCBoard v15.0 are:
  96. |
  97. |   "TO     "      TO Name (or address for internet)
  98. |   "FROM   "      FROM Name (or address for internet)
  99. |   "SUBJECT"      Subject of the message
  100. |   "ATTACH "      File Attachment
  101. |   "LIST   "      Carbon List TO Name
  102. |   "ROUTE  "      Routing information for netmail
  103. |   "ORIGIN "      Origin information for netmail
  104. |   "REQRR  "      Request Return Receipt
  105. |   "ACKRR  "      Acknowledgement Return Receipt
  106. |   "ACKNAME"      Acknowledgement (FROM) Name
  107. |   "PACKOUT"      Pack Out Date (date to remove message)
  108. |
  109. | The Carbon List header Description Field is further subdivided as follows:
  110. |
  111. |   Offset   Type   Length  Description
  112. |   ------  ------  ------  -----------
  113. |     10    str       50    Extended Header Description (subj, to, from, etc)
  114. |     60    str        6    Date Message Was Read
  115. |     66    str        4    Time Message Was Read
  116. |
  117. | The File Attach header Description Field is formatted as follows:
  118. |
  119. |     "FILENAME (SIZE) STOREDNAME"
  120. |
  121. | The entire field is padded out to 60 spaces just like the rest of the
  122. | extended headers.  The FILENAME is the name of the file that the caller
  123. | uploaded.  The SIZE is the size of the file.  The STOREDNAME is the name
  124. | under which the file is actually stored on disk.
  125.  
  126.  
  127.   Index File Format
  128.   -----------------
  129. | There are now two separate Index File Formats used by PCBoard.  There is an
  130. | older format which was used from the beginning, and a new v15.0 specific
  131. | format.
  132. |
  133. | We encourage all authors to upgrade to the v15.0 format.  However, in the
  134. | meantime, PCBoard is capable of working with BOTH formats.  PCBoard will
  135. | no longer USE the old style format, but it will keep it up to date for
  136. | those programs that need to access it.  This functionality can be disabled
  137. | if the system does not make use of any software that uses the old style
  138. | format and this can save both time and disk space.
  139. |
  140. | The two index filenames are the same root name as used for the message base
  141. | plus the addition of an extension as follows:
  142. |
  143. |        .NDX      for old-style index files
  144. |        .IDX      for v15.0 style index files
  145. |
  146. | Example:  MSGS.NDX and MSGS.IDX would be the two index files for MSGS.
  147. |
  148. | Version 15.0 Style Index
  149. | ------------------------
  150. | This new format has several changes and at the same time some operational
  151. | simularities that make it easy to implement.  These changes are:
  152. |
  153. | - The index record now has the offset stored as a long integer instead of as
  154. |   a single precision real number.
  155. |
  156. | - The offset is no longer the number of the message block but instead is the
  157. |   actual offset within the file.  (the old style offset had to be multiplied
  158. |   by 128 to arrive at a physical offset)
  159. |
  160. | - The index record now has the most commonly accessed information that is
  161. |   used by PCBoard to determine the accessability of a message - that is,
  162. |   to decide whether or not the message can be read by the caller.  By putting
  163. |   all of this information into the index PCBoard no longer has to read BOTH
  164. |   the index AND the message header to find out of the message is readable.
  165. |   This also greatly speeds up the Y-scan because for most scans it no longer
  166. |   has to read the message base but just the information in the index file can
  167. |   be used.
  168. |
  169. | - A date is now included in the index making it possible to quickly locate
  170. |   messages that are newer than a given date.
  171. |
  172. | - The index file is not PRE-formatted.  This means that sysops no longer
  173. |   have to worry about filling up the message base index or setting an
  174. |   appropriate "block size" for the index.  PCBoard and PCBPack simply
  175. |   maintain an index that covers only the range of messages from low to high
  176. |   in the message base and nothinger more.
  177. |
  178. | The format for the index is as follows:
  179. |
  180. |   Offset   Type   Length  Description
  181. |   ------  ------  ------  -----------
  182. |      0    long       4    Offset (0 if none, >0 if active, <0 if killed)
  183. |      4    long       4    Message Number
  184. |      8    str       25    TO Name
  185. |     33    str       25    FROM Name
  186. |     58    char       1    Status Character (from Message Header)
  187. |     59    int        2    Date of Message (in julian date format)
  188. |     61    str        3    Reserved for future use
  189. |
  190. | Accessing the file is quite similar to the old style index.  Here is the
  191. | same example used for the Old Style Index access:
  192. |
  193. |    Message Number to Find:   1500
  194. |
  195. |    Low Message Number    :   1024
  196. |    Offset into INDEX File:   1500-1024 = 476, 476*64 = 30464
  197. |                              read 64 bytes at offset 30464 in INDEX file
  198. |    Offset into MSGS File :   Index.Offset
  199. |
  200. | The differences in the above as compared to Old Style Indexes are that the
  201. | size of the index record is now 64 bytes instead of 4 bytes.  And the Offset
  202. | in the record is used "as is" without having to perform any calculations
  203. | on it.
  204. |
  205. | Example C code implementing the above:
  206. |
  207. |        typedef struct {
  208. |          long     Offset;
  209. |          long     Num;
  210. |          char     To[25];
  211. |          char     From[25];
  212. |          char     Status;
  213. |          unsigned Date;
  214. |          char     Reserved[3];
  215. |        } indextype;
  216. |
  217. |        indextype Index;
  218. |
  219. |        LowNum = 1024;
  220. |        MsgNum = 1500;
  221. |        lseek(IndexFile,(MsgNum-LowNum)*sizeof(indextype),SEEK_SET);
  222. |        read(IndexFile,&Index,sizeof(indextype));
  223. |
  224. |        if (Index.Offset > 0) {
  225. |          lseek(MsgsFile,Offset,SEEK_SET);
  226. |          read(MsgsFile,Header,sizeof(Header));
  227. |          /* read the rest of the message here if you want */
  228. |        }
  229. |
  230. | The offsets contained in the index file will be 0 (indicating that no
  231. | message exists for that entry), a negative of the offset (example -476 in
  232. | the above) if the message has been killed or a positive offset value if the
  233. | message is active.
  234.  
  235.  
  236.   Old Style Index
  237.   ---------------
  238.   The file is preformatted to a size of 4096 times the number of message index
  239.   blocks.  Each message index block consists of 1024 entries each being of
  240.   type "bsreal" resulting in 4096 bytes per block.
  241.  
  242.   Each entry in the index is the block offset into the message base for a
  243.   given message number minus the low message number in the message base.  Take
  244.   the following example for instance:
  245.  
  246.      Message Number to Find:   1500
  247.  
  248.      Low Message Number    :   1024
  249.      Offset into INDEX File:   1500-1024 = 476, 476*4 = 1904
  250.                                read 4 bytes at offset 1904 in INDEX file
  251.                                (realizing that those 4 bytes are "bsreal")
  252.      Offset into MSGS File :   (Value from Index - 1) * 128
  253.  
  254.   The Offset into the MSGS file is then calculated according to the above
  255.   example by first determining where to read in the index file, grabbing the
  256.   block offset value from the index and then subtracting one from it and
  257.   multiplying by 128 (which is the size of all blocks in the message base).
  258.  
  259.   Example C code implementing the above:
  260.  
  261.          LowNum = 1024;
  262.          MsgNum = 1500;
  263.          lseek(IndexFile,(MsgNum-LowNum)*4,SEEK_SET);
  264.          read(IndexFile,Offset,sizeof(bsreal));
  265.  
  266.          MsgOffset = Offset;    /* <-- using your own routines you need */
  267.                                 /*     to convert the bsreal type to a  */
  268.                                 /*     long integer for use below       */
  269.  
  270.          if (MsgOffset > 0) {
  271.            lseek(MsgsFile,(MsgOffset-1)*128,SEEK_SET);
  272.            read(MsgsFile,Header,sizeof(Header));
  273.            /* read the rest of the message here if you want */
  274.          }
  275.  
  276.   The offsets contained in the index file will be 0 (indicating that no
  277.   message exists for that entry), a negative of the offset (example -476 in
  278.   the above) if the message has been killed or a positive offset value if the
  279.   message is active.
  280.  
  281.  
  282.   Note 1:
  283.   -------
  284.   In the past, to lock the message base while inserting messages, PCBoard put
  285.   the word "LOCKED" at position 16 and locked the first 128 bytes of the file
  286.   which made up the entire HEADER region of the file.  This 'lock' was placed
  287.   on the file so that other nodes on the network could not update the file at
  288.   the same time.
  289.  
  290.   The word "LOCKED" was used because some systems would not properly lock a
  291.   range of bytes within a file.  This method, however, causes a problem if a
  292.   system is rebooted (or locked up) prior to unlocking the file leaving it in
  293.   a "locked" state and unavailable for further system use.
  294.  
  295.   Version 14.5 will now lock ONLY the 6 bytes starting at offset 16 (16 bytes
  296.   from the start of the file which is byte #17 if you start counting at 1).
  297.   These 6 bytes have always been defined as the "LOCKED" bytes since v14.0 and
  298.   in effect were always locked anyway since a lock on the first 128 bytes
  299.   included those 6 bytes.  Therefore programs that were originally designed to
  300.   work with v14.0 should continue to work properly unmodified!
  301.  
  302.   The advantage to locking only the 6 bytes at offset 16 is that the first 16
  303.   bytes are still READABLE and that any node or process wishing to read the
  304.   first 16 bytes is now allowed to do so.
  305.  
  306.   For instance, a (R)ead command or a (Y)our Mail command will now be allowed
  307.   to proceed WHILE the message base is being updated.  Previously those
  308.   functions would be required to wait until the lock was removed before they
  309.   could proceed with reading the header bytes (which defined the 'High Message
  310.   Number', the 'Low Message Number', the 'Number of Active Messages' and the
  311.   'Number of System Callers').
  312.  
  313.   It is recommended that Third Party Authors use the same technique now for
  314.   updating the message base EVEN THOUGH the old method of locking all 128
  315.   bytes will continue to work fine.  The reason for the change was to enhance
  316.   the performance of systems where a large number of people could be reading
  317.   mail while a large number of messages are being written into the message
  318.   base.
  319.  
  320.  
  321.   Note 2:
  322.   -------
  323.   The status flags used by PCBoard for message read control are:
  324.   
  325.      ( ) - A message which can be read by anyone.
  326.      (*) - A private message to a specific person which has NOT
  327.            been read by the "addressed to" person.
  328.      (+) - A private message which HAS been read by the person
  329.            it was addressed to.
  330.      (-) - A message to a specific person, which was readble by anyone,
  331.            which has been read by the person it was addressed to.
  332.      (~) - A COMMENT to the sysop which has NOT been read by the
  333.            person defined as sysop record #1.
  334.      (`) - A COMMENT to the sysop which HAS been read by the person
  335.            defined as sysop record #1.
  336.      (%) - A message protected by SENDER PASSWORD which has not been read
  337.      (^) - A message protected by SENDER PASSWORD which has been read
  338.      (!) - A message protected by GROUP PASSWORD which has not been read
  339.      (#) - A message protected by GROUP PASSWORD which has been read
  340.      ($) - A message protected by GROUP PASSWORD which is addressed to ALL
  341.  
  342.  
  343.   Note 3:
  344.   -------
  345.   It should be noted that the number of message blocks indicated within the
  346.   message header includes the header block itself in the count.  In other
  347.   words, if a message has a body length of 1 block the number stored in the
  348.   header would be 2 counting both the message header and the body block.
  349.