







                            ******** NOT FOR DISTRIBUTION *********            1

                               UTI Driver Specification
                                     Revision 2.1
             UTIVER Only Writes integer part of version -- ie, 2, not 2.1


          What is a UTI Driver?

                  The Universal Text Interface (UTI) is a set of programs which allow mail
                  software to be compatible with virtually any BBS software.  It consists
                  of a set of six short programs which generate specifically formatted
                  text files which are read by the mail software.  A UTI Driver is a set
                  of six programs described below, usually written by second or third
                  parties.  This document describes these programs and the text files they
                  should produce.

                  It should be noted that although this standard was developed by Kip
                  Compton, the only person who can be responsible for the results of a UTI
                  driver's accessing your BBS files is the author of the UTI driver.  I
                  cannot, and will not, endorse any UTI driver, although I may keep a
                  directory of them for my customers.  It is SOLELY the responsibility of
                  the UTI developer to thoroughly test the driver, and by writing a driver
                  conforming to the specifications set forth in this document, the author
                  of the driver recognizes that Kip Compton is not responsible for the
                  results of their programming efforts or the products thereof.

                  Several terms need to be clarified before proceeding to the definitions
                  of the programs and files.  A conference is a message base area, which
                  is separate from other message base areas, and is usually intended to
                  house messages concerning a certain topic.  A conference identifier is a
                  string, up to 65 characters in length, which identifies the Conference. 
                  Conference identifiers cannot contain spaces.  As part of your UTI
                  driver, you should write an explanation of what your conference
                  identifiers are.  For example, you may decide that it would be easiest
                  to use a number for each conference.  Or you might use the name of the
                  conference, or even the path.  It is up to the UTI driver author to
                  determine what should be used as conference identifiers.  A message
                  number is a number corresponding to a specific message.  No two messages
                  in the same conference should have the same number, and numbers should
                  be allocated sequentially.  The range of message numbers supported is
                  from 1 to 999,999.

                  For ease of finding and calling, all UTI driver programs should be .EXE
                  files residing in the PATH.

            Changes In Revision 2.1 from Revison 2.0 : 

                        1)    Added the /NETWORK flag to the UTIIMPRT program.  If
                              present, it means that the software putting the mail into
                              the base is Networking Software, and therefore the messages
                              should be marked (if this is supported by the BBS) to NOT go

                       ************ NOT FOR DISTRIBUTION *************







                       ******** NOT FOR DISTRIBUTION *********            2

                         out on the network.  This works in concert with the /NETWORK
                              flag on UTIEXPRT.

                        2)    Added the UTIRFLAG Program.  This is an OPTIONAL program
                              that will enable a program using a UTI driver to update the
                              Read Flags on messages.  See the section on this program for
                              more information.

                        3)    Added "echo flags" to the message header on the UTI format. 
                              See the appendix describing the message header format for
                              more information.  

             


            The Highest Message Number in a Given Conference

                  This program is used to determine the highest numbered message in a
                  given Conference.  The name of this program should be UTIHIGH.  When
                  UTIHIGH is called, the first command line argument will be the
                  Conference ID of the Conference to act on, and the second will a full
                  path where a single-line ASCII text file should be generated, with the
                  number of the highest message in the conference, without spaces.  

                  Example Command line for UTIHIGH:


                                  Ŀ
                                  UTIHIGH 1 C:\PCRELAY\HIGHNUM.TXT 
                                  


                  When passed these arguments, UTIHIGH should determine the highest
                  numbered message in the Conference identified by "1", and write the
                  number out to the file C:\PCRELAY\HIGHNUM.TXT.  (Note that if
                  C:\PCRELAY\HIGHNUM.TXT already exists, UTIHIGH should overwrite it, not
                  append to it.)  There is a sample file, HIGHNUM.TXT, provided with this
                  document if you have further questions about the format of the file.


            Message Extraction From a Given Conference

                  This program is used to extract messages, starting with a specific
                  message number, for which a message may or may not exist, to the end of
                  the Conference.  This program should be called UTIEXPRT.  When this
                  program is run, the first command line argument will be the Conference
                  ID of the conference to act on, the second command line argument will be
                  the number of the message to start with, and the third will be the full
                  path where the output file should be generated.  The fourth, optional,
                  command line parameter is /NETWORK.  If /NETWORK is present and it is

                       ************ NOT FOR DISTRIBUTION *************







                       ******** NOT FOR DISTRIBUTION *********            3

               supported by the system, UTIEXPRT should only put out messages that
                  should be sent out in the network.  If such a flag is not supported by
                  the system, UTIEXPRT should ignore the /NETWORK flag.  If the /NETWORK
                  parameter is not present, the UTIEXPRT program should place all
                  messages, regardless of "echo flag" status, into the requested text
                  file.  Note that even if there are no messages to be extracted (i.e.,
                  the given message number is larger than the highest number in the
                  conference), UTIEXPRT should create a 0 byte file.  If the file already
                  exists, UTIEXPRT should overwrite it.  See Appendix A for information on
                  how the output file should be formatted.

                  Example Command Line for UTIEXPRT:


                                 Ŀ
                                 UTIEXPRT 1 123 C:\PCRELAY\MAIL.TXT 
                                 



            Message Merging Into a Given Conference

                  This program is used to merge messages into a given conference.  This
                  program should be called UTIIMPRT.  When run, the first command line
                  argument will be the Conference ID of the conference to act on, and the
                  second command line argument will be the full path of an input file in
                  the format described in Appendix A.  UTIIMPRT will not be run unless
                  there is mail to be imported.  The third, optional command line
                  parameter is the name of a text file to which any discrepancies in the
                  message numbering is written.  This feature is completely optional in
                  the UTI driver, but, if implemented, will insure that PCRelay networking
                  software will work properly in a multi-node BBS environment.  See
                  Appendix C for information on this optional feature.  The third (or
                  fourth), optional, command line parameter is /NETWORK.  If the /NETWORK
                  flag is present, and it is supported by the system, messages that are
                  imported should be flagged to NOT be sent out on the network.  If the
                  flag is not present, they should be flagged to be sent out on the
                  network (ie, so that UTIEXPRT will export them even when called with the
                  /NETWORK parameter).  If this type of flag is not supported by the
                  system, the /NETWORK parameter should be ignored.

                  Example Command Line for UTIIMPRT:


                                  Ŀ
                                  UTIIMPRT 1 C:\PCRELAY\MAIL.TXT   
                                  


            Conference Listing

                       ************ NOT FOR DISTRIBUTION *************







                       ******** NOT FOR DISTRIBUTION *********            4

               The UTILIST program generates a listing of conferences suitable for
                  configuration purposes.  The first command line parameter for UTILIST is
                  the name of the file to place the listing in.  For information on the
                  format of the listing, see Appendix B.

                  Example Command Line for UTILIST:

                                  Ŀ
                                        UTILIST LISTING.UTI        
                                  


            "Last Read" Management

                  The UTILSTRD program allows the UTI application to access a user's "last
                  read" pointers for the message bases.  The "last read" pointer for a
                  given user in a given conference is the highest message number that the
                  user has read.  The first command line parameter given to UTILSTRD
                  determines the mode that UTILSTRD is operating in : READ or WRITE.  The
                  second command line parameter is the name of the text file to be used,
                  and the third, fourth, etc., parameters are the name of the user who's
                  last read pointers are to be manipulated.

                  In READ mode, UTILSTRD is to get the user's last read pointers and write
                  them to the text file supplied, and in WRITE mode, UTILSTRD is to get
                  the user's last read pointers from the text file and write them to the
                  mail system's last read pointers.  

                  The text file manipulated by UTILSTRD should have one last read pointer
                  per line.  The last read pointers should be in the same order that
                  UTILIST lists the conferences in.  If the user is not "registered" in a
                  conference or doesn't have access to a conference, his/her last read
                  pointer should be written out as a -1.


                  Example Command Line for UTILSTRD:

                                Ŀ
                                 UTILSTRD READ LAST.UTI KIP COMPTON 
                                


            UTI Revision Number

                  The UTIVER program is simply used to obtain the revision level of the
                  UTI driver that is installed on the system.  The UTIVER has one command
                  line parameter, the name of the file to write the version number and
                  identification string.  This is revision number two, so an ASCII 2
                  should be written to the first line of the file for this version.  The
                  second line of the text file should be a string that identifies the UTI

                       ************ NOT FOR DISTRIBUTION *************







                       ******** NOT FOR DISTRIBUTION *********            5

               driver.  For example, if your UTI driver was for GAP BBS, and the
                  version of the UTI was 1.01, you might write "GAP UTI Driver By Gap
                  Development Company, Version 1.01" on the second line.  The UTI
                  Application may or may not display this string.

                  Example Command Line for UTIVER:

                                  Ŀ
                                         UTIVER VERSION.UTI        
                                  



            Door Information File

                  At first, we very much wanted to support the DOOR.SYS "standard" which
                  was already in place.  Unfortunately, after calling around, we found at
                  least three DIFFERENT versions of the DOOR.SYS standard, and we're sure
                  that there are more out there.  So, to avoid confusion, we have included
                  a minimal door standard in the UTI specification.  It is as follows:

                              Line 1 :    Full User Name (First and Last), all caps
                              Line 2 :    Actual BPS rate that the caller called at
                              Line 3 :    COM Port : 0, 1, 2, 3, or 4.
                              Line 4 :    DTE "Locked" Rate
                              Line 5 :    Number of Seconds the user has left before
                                          forced logoff

                  The traditional filename for this file will be UTIDOOR.TXT.  The program
                  to create this file should be called UTIDOOR.EXE.  UTIDOOR.EXE should be
                  called in the batch file before the door itself is run; in this respect
                  it is not actually a UTI driver, but it should be included in any UTI.


            Message Read Flag Updating

                  This program is OPTIONAL.  UTIRFLAG.EXE, if it is included in a UTI, is
                  used to update the Read: Flags on a given user's mail, starting with a
                  given message number in a given forum.

                  The UTIRFLAG.EXE program does not write out or read in any text files.

                  The command line format for the UTIRFLAG program is as follows:

                  UTIRFLAG.EXE CONFID START# STOP# FIRSTNAME ... LASTNAME

                  The first command line parameter is the Conference/Forum ID for the
                  conference to work with.  The second command line parameter is the
                  Message # to start updating the Read flags at, the third command line
                  parameter is the message number to STOP updating the Read: flags at, and

                       ************ NOT FOR DISTRIBUTION *************







                       ******** NOT FOR DISTRIBUTION *********            6

               the FIRSTNAME .. LASTNAME series of command line parameters is the full
                  logon name of the user who's Read flags should be updated.

                  For example,

                        UTIRFLAG C:\SYSOPS\SYSOP 100 110 DON MC COLLOUGH

                  Would tag all messages in the conference/forum with the UTI Conference
                  ID of C:\SYSOPS\SYSOP with message numbers greater than or equal to 100
                  and less than or equal to 110 that are addressed to DON MC COLLOUGH as
                  having been "read."



            Important Tips for Writing UTI Drivers


                  UTI Drivers should be written to use as little memory as possible, since
                  in most situations they will be shelled to.  They should also be written
                  with speed in mind, especially the UTIIMPRT and UTIEXPRT programs, since
                  they will probably be handling a large amount of mail.

                  UTI Driver should return an errorlevel if there is a problem.  The
                  Software which uses UTI drivers will print an error message on the
                  screen and list the errorlevel if the error_level returned is not 0.

                  Example Error Message:


                               Ŀ
                               UTI Error : UTIEXPRT : Error_Level = 5
                               


                  In this manner, it is possible for you to support your driver without
                  taking the extra memory, etc to put in your own error messages.  

                  Important: Your UTI Drivers should never do anything to endanger the
                  parent task, since even if your UTI driver experiences a Fatal error,
                  there is often clean-up which needs to be performed by the parent task. 
                  For example, if your UTIEXPRT driver dies, and it was called by PCRelay
                  Networking Software, the networking software must find out about this to
                  prevent making a long-distance call to attempt to upload a corrupted
                  file.  It is therefore highly recommended that you return an Error_Level
                  to the parent task if anything goes wrong.

                  Your UTI driver should come with a short document explaining what BBS
                  the UTI driver is for.  You should also include information on how to
                  install your UTI driver, what to put in a batch file running a door to
                  generate a DOOR.SYS file, what your conference "ids" are, and a listing

                       ************ NOT FOR DISTRIBUTION *************







                       ******** NOT FOR DISTRIBUTION *********            7

               of the error codes returned by your UTI driver programs.

                  If at all possible, your UTI should _NOT_ added a "tag line" to the
                  bottom of the message.  This wastes space and slows down the system, and
                  erodes at the idea that messages should look like messages, no matter
                  what system they came from.  Perhaps you could have the tag line appear
                  until the person registered the UTI?












































                       ************ NOT FOR DISTRIBUTION *************







                       ******** NOT FOR DISTRIBUTION *********            8

          Appendix A

                  Format used by UTIIMPRT and UTIEXPRT


                        Line #1 : Addressee
                        Line #2 : Author
                        Line #3 : Subject
                        Line #4 : Message Number
                        Line #5 : Reference Number
                        Line #6 : Date of message
                        Line #7 : Time of message
                        Line #8 : Security on Message
                        Line #9 : Read Status
                        Line #10: Echo Flag Status (see below)
                        Line #11: TEXT:
                        Line 12 to Line n : Message text
                        Line n+1 : Next Addressee
                        Line n+2 : Next Author
                        .
                        .
                        . 
                        <eof>

                        The Addressee, Author, and Subject fields are all non-case
                        sensitive alphanumeric fields with a maximum length of 25 bytes. 
                        The message number and reference number fields may be up to 6
                        bytes long (i.e., 0 to 999999).  If the message is not referring
                        to a message, or the system does not support reference numbers, a
                        0 should be written to the line.  The Date field is in the format
                        MM/DD/YY (i.e., Jan 2, 1989 is 01/02/89).  The Time field is a
                        twenty-four hour clock and is in the format HH:MM (i.e., 2 pm is
                        14:00)  The Security field either has PRIVATE or PUBLIC in it.  A
                        message with the PRIVATE flag is readable only by the author, the
                        addressee, and those authorized by the access level to read all
                        mail (i.e., the SysOp).  Mail with PUBLIC on it is readable by
                        anyone with access to the proper Conference.  The ninth line
                        should contain a Y if the message has been read by the addressee,
                        or a N if the message has not been read.  If Read status is not
                        applicable to the message (ie, the message is to "ALL", this line
                        should contain N.  The next line, the "echo flag" line, is used to
                        control the flow of messages in a networked conference
                        environment.  If this flag is "Y", then a message should be
                        "exported" out onto the network.  If it is a "N", it should remain
                        local.  If your BBS does not support echo flags, you should always
                        put a "Y" here, and ignore the field when UTIIMPRTing.  If your
                        BBS does support this type of flag, you should write it and read
                        it on this line.  Note that the presence of the echo flag
                        OVERRIDES the /NETWORK options on the UTIIMPRT and UTIEXPRT
                        programs!  You could think of it this way : the /NETWORK parameter

                       ************ NOT FOR DISTRIBUTION *************







                       ******** NOT FOR DISTRIBUTION *********            9

                    determines what echo status the message should have if the echo
                        flag isn't specified on a message!  The next line should contain
                        TEXT:.  The reason for this is that future revisions of the UTI
                        driver specification may have more information in the header, thus
                        requiring more lines.  Starting with revision two, the text
                        segment of the message will always begin on the line after TEXT:. 
                        Therefore, when reading in a UTI text format file, one should read
                        the information that one knows will be there (given the UTI
                        revision level from UTIVER) and then read in lines until one
                        reaches TEXT: before starting to load in the text of the message. 
                        The Message text should be in lines of 72 characters or less, and
                        can be up to 2000 lines long.  The message text should be
                        terminated by a $FF character on a line by itself after the last
                        line of the message.  After the end-of-message text marker, there
                        should either be EOF, or the beginning (Addressee) of the next
                        message.



































                       ************ NOT FOR DISTRIBUTION *************







                       ******** NOT FOR DISTRIBUTION *********           10

          Appendix B

                  Format Used by UTILIST

                        UTILIST should produce a text file with three lines for each
                        conference supported through the UTI driver.  The conferences
                        should be listed in the same order that UTILSTRD produces lists of
                        last read pointers.  The first line for each conference should be
                        the UTI Conference Identifier of the conference that is used to
                        access the conference via UTIHIGH, UTILOCK, UTIUNLCK, UTIIMPRT,
                        and UTIEXPRT.  The second line should be the Name of the
                        conference (up to 15 characters).  The name is used for display
                        purposes only.  The third line should be a description, if
                        available, of the conference (70 characters or less).  If a
                        description is not available, a blank line should be written for
                        the third line.  The description is for display purposes only.  
                        For example, If you had three conferences, MAIN, SYSOP, and
                        SUPPORT, the file generated by UTILIST might look like this:

                                    0
                                    MAIN
                                    The Main Board
                                    1
                                    SYSOP
                                    A place for Sysops to Communicate with each other
                                    2
                                    SUPPORT
                                    PCRelay Product Support Forum

                        UTILIST should generate three lines for each conference.  The
                        number of conferences recognized by UTILSTRD and UTILIST should be
                        the same - mail programs will probably be using the two programs
                        together to get the necessary information.  Each conference must
                        have a unique conference name.

















                       ************ NOT FOR DISTRIBUTION *************







                       ******** NOT FOR DISTRIBUTION *********           11

          Appendix C

                  UTIIMPRT Optional Message Number Allocation

                    To enable PCRelay Networking Software and other software products
                        that keep tables of reference numbers to operate properly in
                        multi-node BBS environment, the author of UTIIMPRT has to option
                        of re-allocating the numbers on the messages passed to it in the
                        text file if they are incorrect.  For example, an application
                        would presumably call UTIHIGH to get the highest message number,
                        and then use that number to create the text file that it will pass
                        to UTIIMPRT.  On a large multi-node system, it is possible for
                        another user or utility to enter a message into the message base
                        in the interim.  If this were to occur, the message numbers in the
                        text file passed to UTIIMPRT would be too low, and can be adjusted
                        by the UTIIMPRT function.  If the third parameter passed to
                        UTIIMPRT is a filename, then the application that called UTIIMPRT
                        needs to know if any message number changing took place.  If and
                        only if message number changes occurred and a filename is
                        specified as the third parameter, UTIIMPRT should write the
                        difference between the message numbers that were written to the
                        text file by the application and the actual message numbers
                        assigned to the messages in the message base.  Note that if
                        message renumbering takes place, it is UTIIMPRT's responsibility
                        to adjust any reference numbers in the text file that need to be
                        adjusted.

                        Please note that this option is completely optional.  Currently,
                        the only penalty for not implementing this feature is that
                        occasionally, on large multi-node systems, the reference numbers
                        reported on PCRelay messages may be incorrect.  If the bulletin
                        board software that the UTI Driver is designed for does not have
                        multi-node capability, this feature should not be implemented - it
                        will only take up extra space.

















                       ************ NOT FOR DISTRIBUTION *************
