home *** CD-ROM | disk | FTP | other *** search
/ synchro.net / synchro.net.tar / synchro.net / main / BBS / OPXSPEC1.ZIP / opxinfo.txt < prev    next >
Encoding:
Text File  |  2000-01-27  |  11.9 KB  |  264 lines
  1. (*-------------------------------------------------------------------*)
  2. (*  Santronics Software, Co.                                         *)
  3. (*  30034 SW 153 Ct.                                                 *)
  4. (*  Leisure City, FL  33033                                          *)
  5. (*  hector@santronics.com                                            *)
  6. (*                                                                   *)
  7. (*           Silver Xpress OPX/REP Mail Packet Specifications        *)
  8. (*                                                                   *)
  9. (*        (C) Copyright 1988-2000, Santronics Software, Inc          *)
  10. (*                     All Rights Reserved                           *)
  11. (*                                                                   *)
  12. (* These data structures are owned by SSI and no change can be made  *)
  13. (* with the consent and permission from SSI.  The specification is   *)
  14. (* release to the public domain for commercial and non-commercial    *)
  15. (* usage.  No legal request is required to use these formats for     *)
  16. (* OPX implementation. However, all implementations must retain a    *)
  17. (* SSI copyright in their source code indicating the copyrighted     *)
  18. (* usage of the OPX specification.                                   *)
  19. (*-------------------------------------------------------------------*)
  20.  
  21. The information provided in this document describes the OPX mail
  22. packet.
  23.  
  24. Since its inception, the OPX was a closed and proprietary offline
  25. mail format.  For over 14 years, the format has endured a vast
  26. engineering and fine tuning over time, with every revision retaining
  27. a high regard for compatibility with all version of SX mail readers.
  28.  
  29. The OPX format is both simple and complex, yet rich in its ability off
  30. line readers authors powerful offline reader operations with a close
  31. relationship with the BBS.
  32.  
  33. To best understand OPX, you should read the "opxhist.txt" file which
  34. will explain how the format was developed and engineered over the years.
  35. But you don't need to read it now, as we have tried to clean up and
  36. summary the OPX format in this document for you.  With this document
  37. and the structure header files, you should be able to read OPX doors
  38. and readers.   The only thing you should remember is that the OPX
  39. mail format is basically a Fidonet (FTSC) format, and its history
  40. of design for all the various BBS SX mail doors is molded around the
  41. fidonet layout.
  42.  
  43. Lets begin with a summary table of versions and the OPX files:
  44.  
  45. The following table provides a list of all the files that are created by
  46. the Silver Xpress Mail Doors.  The files indicated with ! is the minimum
  47. requirement for OPX support.  No other files is required.
  48.  
  49.                       Silver Xpress
  50.                       Door Version
  51.   OPX BASE FILES      1  2  3  4  5    Comment
  52.   ---------------     -  -  -  -  -    --------------------------------
  53. ! MAIL.DAT            X  X  X  X  X    Message database
  54. ! MAIL.IDX            X  X  X  X  X    Index to 1st msg in each area
  55. ! BRDINFO.DAT         X  X  X  X  X    BBS Info, Mail Areas, Mail Index
  56.   MAIL.FDX                  X  X  X    Current Mail Index File
  57.   EXTAREAS.DAT              X  X  X    Mail Areas for systems over 256
  58.   XPAREAS.XUA               X  X  X    Area History Snap Shot
  59.   XCONTROL.DAT                    X    Optional: New BBS Configuration
  60.  
  61.   OPX MISC FILES      1  2  3  4  5
  62.   ---------------     -  -  -  -  -
  63.   DUSRCFG.DAT               X  X  X    Offline Configuration User Options
  64.   DUSRCFG.KW                X  X  X    Offline Configuration User Keywords
  65.   DOPTIONS.DAT                 X  X    Offline Configuration User Options
  66.   XPFILE.LST                X  X  X    List of Files attached.
  67.   NEWFILES.TXT/DAT       X  X  X  X    New file listing
  68.   BULLETIN.LST           X  X  X  X    List of the bulletins available
  69.   SERVICES.XP               X  X  X    Xpress Service File.
  70.   XPNLV?.*                  X  X  X    Xpress Nodelist Files
  71.   TTAPE.DAT                 X  X  X    Ticker tape data file.
  72.   boardid.LIB               X  X  X    BBS Menu for this system
  73.   XFORMS.DAT                X  X  X    List of Form Files
  74.  
  75. Most of the above files are designed specifically for Silver Xpress
  76. Reader operations.  For example, the services files, the BBS menu
  77. information and the Form Input System.   Most readers will not need
  78. these files.
  79.  
  80.                       OPX STYLE REPLY FILES
  81.                            (REP PACKET)
  82.                       ======================
  83.  
  84. The following table shows a list of file expected by the Silver
  85. Xpress Mail Door.
  86.  
  87.                       Silver Xpress
  88.                       Door Version
  89.   REP BASE FILES      1  2  3  4  5    Comment
  90.   ---------------     -  -  -  -  -    --------------------------------
  91.   !nnn.xxx            X  X  X  X  X    New msg for area XXX (base 36)
  92.   XPFILE.REQ          X  X  X  X  X    List of requested files
  93.   XPAREAS.XUA               X  X  X    Area History Snap Shot
  94.   XPFILE.FAT                X  X  X    Files attached for uploading
  95.   RUSRCFG.KW                X  X  X    List of changed keywords
  96.   OFFLINE.CFG               X  X  X    User Offline Configuration
  97.  
  98. All Silver Xpress Doors support the above for sending a REP file.
  99.  
  100. Each !nnn.xxx file is a pure fido style message with the TFidoMsgType
  101. style header.  The nnn number is not important when uploading to the
  102. mail door.  The XXX extension is the area to import. It is a base 36
  103. number.
  104.  
  105. MAIL.DAT Database File
  106. ----------------------
  107.  
  108. MAIL.DAT is the OPX mail storage file.  The layout of this file is:
  109.  
  110.     +----------------------------------+
  111.     | 16 byte HEADER for msg 1         |   TMailHdrType
  112.     |----------------------------------|
  113.     | Basic Fido (*.MSG style) Message |   TFidoMsgType+Body
  114.     |----------------------------------|
  115.     | 16 byte HEADER for msg 2         |   TMailHdrType
  116.     |----------------------------------|
  117.     | Basic Fido (*.MSG style) Message |   TFidoMsgType+Body
  118.     +----------------------------------+
  119.                   ..
  120.                   ..
  121.     +----------------------------------+
  122.     | 16 byte HEADER for msg X         |   TMailHdrType
  123.     |----------------------------------|
  124.     | Basic Fido (*.MSG style) Message |   TFidoMsgType+Body
  125.     +----------------------------------+
  126.  
  127. The first header TMailHdrType is a fixed structure that basically
  128. provides basic information for each message; msg number, area number,
  129. size of message and some basic flags.  Please note the field called
  130. fsize in TMailHdrType is sizeof(TFidoMsgType) plus the length of the
  131. message.
  132.  
  133. After the TMailHdrType, follows the Basic Fido *.MSG style message. A
  134. basic *.MSG has the pure layout:
  135.  
  136.     FTSC1 Header Structure, followed by the
  137.     Message Body (Null Terminated)
  138.  
  139. OPX, which stands for OPus Xpress, was first designed under a OPUS BBS
  140. system. It used the style OPUS used for *.MSG FTSC messages. The mail
  141. door packer simply did a directory search for *.MSG files and copied
  142. each one into the MAIL.DAT file putting the small header in between each
  143. message.
  144.  
  145. There are a few changes in the FTSC1 structure as used for OPX when the
  146. mail.dat file is created. The following few fields is not important (or
  147. used) and is used for OPX for the following:
  148.  
  149.     TFidoMsgType.Dest_Zone       << FTSC1 timesread
  150.     TFidoMsgType.Orig_Zone       << FTSC1 cost
  151.     TFidoMsgType.Date_Written    << OPUS Style. optional in FTSC1
  152.     TFidoMsgType.Date_Arrival    << OPUS Style. optional in FTSC1
  153.  
  154. See the TFidoMsgType structure for further information.
  155.  
  156. MAIL.IDX/MAIL.FDX Index Files
  157. -----------------------------
  158.  
  159. Technically, you don't need any index files.  A good reader can stream
  160. in the MAIL.DAT at load time and create its own index logic. But there
  161. are two index files; MAIL.IDX and MAIL.FDX, and there is also an old
  162. (but still required) mail indicing data layout in the BRDINFO.DAT file.
  163. This one will be described later.
  164.  
  165. MAIL.IDX is basically an simple index file to the 1st message in each
  166. mail conference.  The goal was to be able to jump to each message area
  167. very quickly and begin reading the conference mail.  See the structure
  168. TMailIdxType.  Of course, this assumes that the door is creating a
  169. MAIL.DAT in conference sorted order. This is the case with all Silver
  170. Xpress Doors. MAIL.DAT is a streamed database of sorted conference mail.
  171.  
  172. MAIL.FDX is the current index file created by the mail door and used
  173. by the Silver Xpress Reader.  The only problem with this file is that
  174. is a complex Virtual Memory File system based in a 16 bit Pascal
  175. API from Turbo Power Software.  If you have Turbo Power's Pascal
  176. Toolkit, then you can immediately use the TPRARRAY and TPVARRAY
  177. libaries.  For other languages, like C, you will need a C library that
  178. can handle the format.   However, MAILFDX.C was provided which will
  179. explain the format with an example showing how to read a MAIL.FDX file.
  180. See the structure for TMailFDXType.
  181.  
  182. BRDINFO.DAT and EXTAREAS.DAT
  183. ----------------------------
  184.  
  185. BRDINFO.DAT is the BBS, Mail Conference and the old mail index
  186. information file. You can expect this file to always be in an
  187. OPX mail packet.  The layout is:
  188.  
  189.     -------------------------------------
  190.       BBS and USER information             TBrdInfoType
  191.     -------------------------------------
  192.       Bulletin FileNames, if ANY           records of TBullFileName
  193.       1 to TBrdInfoType.Total_Bulletins
  194.     ------------------------------------
  195.       Total Number of TConfRecType         1 Byte
  196.     ------------------------------------
  197.       Conference Areas Information         records TConfRecType
  198.       1 to TBrdInfoType.Total_Areas
  199.         or
  200.       1 to 256 if EXTAREAS.DAT exist.
  201.                Read tota_areas-256 from
  202.                EXTAREAS.DAT
  203.     ------------------------------------
  204.       Old Mail Index Information           records of TBrdMailIdxType
  205.       1 to end of file
  206.     ------------------------------------
  207.  
  208. You basically in TBrdInfoType, read in total_bulletins, read the 1 byte
  209. area count (This is explained below), then read in the conference areas
  210. and the old mail index information.
  211.  
  212. Note: If you are going to create a OPX Mail Door, you MUST create the
  213. TBrdMailIdxType records for Silver Xpress Mail Reader compatibility. The
  214. SX Reader expects the old mail index data to be there for establishing
  215. internal memory requirments.  All opx door authors MUST add this
  216. information.
  217.  
  218. BBS and User Information:
  219.  
  220. The TBrdInfoType Structure provides all the basic information about
  221. the BBS. Note: The new optional XCONTROL.DAT file makes this file
  222. obsolete, however BRDINFO.DAT should still be created for current
  223. Silver Xpress Mail Readers who uses the mail info.
  224.  
  225. Conference Information:
  226.  
  227. The Conference Areas part of BRDINFO.DAT contains the BBS configurtion
  228. informat for each mail area.
  229.  
  230. For backward compatibility with older SX mail readers, the limit was 256
  231. areas.  So if the EXTAREAS.DAT exist, you should read 256 areas in
  232. BRDINFO.DAT then switch to read the remaining areas in EXTAREAS.DAT.
  233.  
  234. When you read the BRDINFO.DAT, the TBrdInfoType.Total_Area will tell you
  235. the true total count of conferences.  After you read the bulletin file
  236. names (if any), you should read 1 byte. This will tell you how mail
  237. areas you have from 0 to 255.  The EXTAREAS.DAT should only exist if
  238. you download a packet with over 256 conferences.
  239.  
  240. If you wish to create OPX mail packets, you should stick with storing
  241. 256 areas or in BRDINFO.DAT and then create the EXTAREAS.DAT for areas
  242. totally over 256 (Put 0-255 in BRDINFO.DAT, and the rest in
  243. EXTAREAS.DAT).
  244.  
  245. Here is a pseudo logic to read the conferences:
  246.  
  247.         Open BrdInfo.Dat
  248.         if Exist, open EXTAREAS.DAT
  249.  
  250.         Read TBrdInfoType
  251.  
  252.         For X = 1 to TbrdInfoType.Total_Areas do
  253.  
  254.            if  X < 256
  255.                read TConfRecType from BrdInfo.Dat
  256.            else
  257.                read TConfRecType from Extareas.Dat
  258.  
  259.         Next X
  260.  
  261.         Close BrdInfo.Dat
  262.         if Open, Close ExtAreas.Dat
  263.  
  264.