(*-------------------------------------------------------------------*)
(*  Santronics Software, Co.                                         *)
(*  30034 SW 153 Ct.                                                 *)
(*  Leisure City, FL  33033                                          *)
(*  hector@santronics.com                                            *)
(*                                                                   *)
(*           Silver Xpress OPX/REP Mail Packet Specifications        *)
(*                                                                   *)
(*        (C) Copyright 1988-2000, Santronics Software, Inc          *)
(*                     All Rights Reserved                           *)
(*                                                                   *)
(* These data structures are owned by SSI and no change can be made  *)
(* with the consent and permission from SSI.  The specification is   *)
(* release to the public domain for commercial and non-commercial    *)
(* usage.  No legal request is required to use these formats for     *)
(* OPX implementation. However, all implementations must retain a    *)
(* SSI copyright in their source code indicating the copyrighted     *)
(* usage of the OPX specification.                                   *)
(*-------------------------------------------------------------------*)

The information provided in this document describes the OPX mail
packet.

Since its inception, the OPX was a closed and proprietary offline
mail format.  For over 14 years, the format has endured a vast
engineering and fine tuning over time, with every revision retaining
a high regard for compatibility with all version of SX mail readers.

The OPX format is both simple and complex, yet rich in its ability off
line readers authors powerful offline reader operations with a close
relationship with the BBS.

To best understand OPX, you should read the "opxhist.txt" file which
will explain how the format was developed and engineered over the years.
But you don't need to read it now, as we have tried to clean up and
summary the OPX format in this document for you.  With this document
and the structure header files, you should be able to read OPX doors
and readers.   The only thing you should remember is that the OPX
mail format is basically a Fidonet (FTSC) format, and its history
of design for all the various BBS SX mail doors is molded around the
fidonet layout.

Lets begin with a summary table of versions and the OPX files:

The following table provides a list of all the files that are created by
the Silver Xpress Mail Doors.  The files indicated with ! is the minimum
requirement for OPX support.  No other files is required.

                      Silver Xpress
                      Door Version
  OPX BASE FILES      1  2  3  4  5    Comment
  ---------------     -  -  -  -  -    --------------------------------
! MAIL.DAT            X  X  X  X  X    Message database
! MAIL.IDX            X  X  X  X  X    Index to 1st msg in each area
! BRDINFO.DAT         X  X  X  X  X    BBS Info, Mail Areas, Mail Index
  MAIL.FDX                  X  X  X    Current Mail Index File
  EXTAREAS.DAT              X  X  X    Mail Areas for systems over 256
  XPAREAS.XUA               X  X  X    Area History Snap Shot
  XCONTROL.DAT                    X    Optional: New BBS Configuration

  OPX MISC FILES      1  2  3  4  5
  ---------------     -  -  -  -  -
  DUSRCFG.DAT               X  X  X    Offline Configuration User Options
  DUSRCFG.KW                X  X  X    Offline Configuration User Keywords
  DOPTIONS.DAT                 X  X    Offline Configuration User Options
  XPFILE.LST                X  X  X    List of Files attached.
  NEWFILES.TXT/DAT       X  X  X  X    New file listing
  BULLETIN.LST           X  X  X  X    List of the bulletins available
  SERVICES.XP               X  X  X    Xpress Service File.
  XPNLV?.*                  X  X  X    Xpress Nodelist Files
  TTAPE.DAT                 X  X  X    Ticker tape data file.
  boardid.LIB               X  X  X    BBS Menu for this system
  XFORMS.DAT                X  X  X    List of Form Files

Most of the above files are designed specifically for Silver Xpress
Reader operations.  For example, the services files, the BBS menu
information and the Form Input System.   Most readers will not need
these files.

                      OPX STYLE REPLY FILES
                           (REP PACKET)
                      ======================

The following table shows a list of file expected by the Silver
Xpress Mail Door.

                      Silver Xpress
                      Door Version
  REP BASE FILES      1  2  3  4  5    Comment
  ---------------     -  -  -  -  -    --------------------------------
  !nnn.xxx            X  X  X  X  X    New msg for area XXX (base 36)
  XPFILE.REQ          X  X  X  X  X    List of requested files
  XPAREAS.XUA               X  X  X    Area History Snap Shot
  XPFILE.FAT                X  X  X    Files attached for uploading
  RUSRCFG.KW                X  X  X    List of changed keywords
  OFFLINE.CFG               X  X  X    User Offline Configuration

All Silver Xpress Doors support the above for sending a REP file.

Each !nnn.xxx file is a pure fido style message with the TFidoMsgType
style header.  The nnn number is not important when uploading to the
mail door.  The XXX extension is the area to import. It is a base 36
number.

MAIL.DAT Database File
----------------------

MAIL.DAT is the OPX mail storage file.  The layout of this file is:

    +----------------------------------+
    | 16 byte HEADER for msg 1         |   TMailHdrType
    |----------------------------------|
    | Basic Fido (*.MSG style) Message |   TFidoMsgType+Body
    |----------------------------------|
    | 16 byte HEADER for msg 2         |   TMailHdrType
    |----------------------------------|
    | Basic Fido (*.MSG style) Message |   TFidoMsgType+Body
    +----------------------------------+
                  ..
                  ..
    +----------------------------------+
    | 16 byte HEADER for msg X         |   TMailHdrType
    |----------------------------------|
    | Basic Fido (*.MSG style) Message |   TFidoMsgType+Body
    +----------------------------------+

The first header TMailHdrType is a fixed structure that basically
provides basic information for each message; msg number, area number,
size of message and some basic flags.  Please note the field called
fsize in TMailHdrType is sizeof(TFidoMsgType) plus the length of the
message.

After the TMailHdrType, follows the Basic Fido *.MSG style message. A
basic *.MSG has the pure layout:

    FTSC1 Header Structure, followed by the
    Message Body (Null Terminated)

OPX, which stands for OPus Xpress, was first designed under a OPUS BBS
system. It used the style OPUS used for *.MSG FTSC messages. The mail
door packer simply did a directory search for *.MSG files and copied
each one into the MAIL.DAT file putting the small header in between each
message.

There are a few changes in the FTSC1 structure as used for OPX when the
mail.dat file is created. The following few fields is not important (or
used) and is used for OPX for the following:

    TFidoMsgType.Dest_Zone       << FTSC1 timesread
    TFidoMsgType.Orig_Zone       << FTSC1 cost
    TFidoMsgType.Date_Written    << OPUS Style. optional in FTSC1
    TFidoMsgType.Date_Arrival    << OPUS Style. optional in FTSC1

See the TFidoMsgType structure for further information.

MAIL.IDX/MAIL.FDX Index Files
-----------------------------

Technically, you don't need any index files.  A good reader can stream
in the MAIL.DAT at load time and create its own index logic. But there
are two index files; MAIL.IDX and MAIL.FDX, and there is also an old
(but still required) mail indicing data layout in the BRDINFO.DAT file.
This one will be described later.

MAIL.IDX is basically an simple index file to the 1st message in each
mail conference.  The goal was to be able to jump to each message area
very quickly and begin reading the conference mail.  See the structure
TMailIdxType.  Of course, this assumes that the door is creating a
MAIL.DAT in conference sorted order. This is the case with all Silver
Xpress Doors. MAIL.DAT is a streamed database of sorted conference mail.

MAIL.FDX is the current index file created by the mail door and used
by the Silver Xpress Reader.  The only problem with this file is that
is a complex Virtual Memory File system based in a 16 bit Pascal
API from Turbo Power Software.  If you have Turbo Power's Pascal
Toolkit, then you can immediately use the TPRARRAY and TPVARRAY
libaries.  For other languages, like C, you will need a C library that
can handle the format.   However, MAILFDX.C was provided which will
explain the format with an example showing how to read a MAIL.FDX file.
See the structure for TMailFDXType.

BRDINFO.DAT and EXTAREAS.DAT
----------------------------

BRDINFO.DAT is the BBS, Mail Conference and the old mail index
information file. You can expect this file to always be in an
OPX mail packet.  The layout is:

    -------------------------------------
      BBS and USER information             TBrdInfoType
    -------------------------------------
      Bulletin FileNames, if ANY           records of TBullFileName
      1 to TBrdInfoType.Total_Bulletins
    ------------------------------------
      Total Number of TConfRecType         1 Byte
    ------------------------------------
      Conference Areas Information         records TConfRecType
      1 to TBrdInfoType.Total_Areas
        or
      1 to 256 if EXTAREAS.DAT exist.
               Read tota_areas-256 from
               EXTAREAS.DAT
    ------------------------------------
      Old Mail Index Information           records of TBrdMailIdxType
      1 to end of file
    ------------------------------------

You basically in TBrdInfoType, read in total_bulletins, read the 1 byte
area count (This is explained below), then read in the conference areas
and the old mail index information.

Note: If you are going to create a OPX Mail Door, you MUST create the
TBrdMailIdxType records for Silver Xpress Mail Reader compatibility. The
SX Reader expects the old mail index data to be there for establishing
internal memory requirments.  All opx door authors MUST add this
information.

BBS and User Information:

The TBrdInfoType Structure provides all the basic information about
the BBS. Note: The new optional XCONTROL.DAT file makes this file
obsolete, however BRDINFO.DAT should still be created for current
Silver Xpress Mail Readers who uses the mail info.

Conference Information:

The Conference Areas part of BRDINFO.DAT contains the BBS configurtion
informat for each mail area.

For backward compatibility with older SX mail readers, the limit was 256
areas.  So if the EXTAREAS.DAT exist, you should read 256 areas in
BRDINFO.DAT then switch to read the remaining areas in EXTAREAS.DAT.

When you read the BRDINFO.DAT, the TBrdInfoType.Total_Area will tell you
the true total count of conferences.  After you read the bulletin file
names (if any), you should read 1 byte. This will tell you how mail
areas you have from 0 to 255.  The EXTAREAS.DAT should only exist if
you download a packet with over 256 conferences.

If you wish to create OPX mail packets, you should stick with storing
256 areas or in BRDINFO.DAT and then create the EXTAREAS.DAT for areas
totally over 256 (Put 0-255 in BRDINFO.DAT, and the rest in
EXTAREAS.DAT).

Here is a pseudo logic to read the conferences:

        Open BrdInfo.Dat
        if Exist, open EXTAREAS.DAT

        Read TBrdInfoType

        For X = 1 to TbrdInfoType.Total_Areas do

           if  X < 256
               read TConfRecType from BrdInfo.Dat
           else
               read TConfRecType from Extareas.Dat

        Next X

        Close BrdInfo.Dat
        if Open, Close ExtAreas.Dat

