7/4/94
Documentation for 'Session.Info' drop (gasp) file format.
This is the first spec for the 'Session.Info' file format.
A 'drop file' (that name makes me wanna gag, my apologies to
the person who came up with that name) provides information
about the current BBS session to a door program.
The 'Session.Info' file was developed so that there would
be a universal file format which could be used by everyone.
In a less Microsoft-centric world we could use better methods
than a file stored on a disk to pass the information, but the
author of this proposal realizes the world is less than perfect
so he concedes a file is needed. Also, seeing that OS/2 runs
a veritable potpourri of software, a file is a good comprimise.
Session.Info File Name Convention
---------------------------------
There is none! This file can be called whatever you like. The
BBS should pass the name of the 'Session.Info' file to the door
program via a command line switch. OS/2 has allowed long file
names since.. what was it? 1.2 in 1989?, and Adept BBS requires
long filenames, so I'm using one: Session.Info
The contents of the file should meet the following conventions
though.
Session.Info Format
-------------------
The 'Session.Info' file is a text file. Each line of the text file
contains a keyword, followed by space(s), followed by data. Like so:
KEYWORD Data
The only thing defined in this file are the Keywords, and a suggestion
on how the data should be formatted for each keyword. The first
non-space character after the keyword is considered the beginning
of the data.
Lines in 'Session.Info' can be in any order. The keyword describes
the data which is contained on the line. If the door program does
not need certain data it can simply skip the line, and continue
to search for Keyword/Data combinations it needs.
Likewise, if the BBS program does not define data pertaining to certain
keywords it should not include a line with that keyword. Not every BBS
programmer believes certain data is needed, or uses data in a different
format.
The door programmer should accept the fact that some keywords may not exist
in the 'Session.Info' file! The programmer should also accept that there
will be lines in the 'Session.Info' that they have never heard of!
Sesson.Info Lines
-----------------
Line length is 300 characters max. This is based on a keyword, spaces, and
a maximum length long filename in OS/2.
Comment lines can be inserted into the file. A comment line must begin with
a semi-colon ';'
Session.Info Data formats
------------------------
All numbers are in decimal format. ie: 2315456
Dates are in the format YY/MM/DD (Year/Month/Date)
Times are in the format HH:MM (Hour:Minute) 24 hour format
Boolean (true/false) data 1 = yes 0 = no
Data can be of mixed case: mIxEd CaSe
Session.Info Keywords
---------------------
The door programmer should check the BBS type and version
to make a determination as to what data and possible
formatting to look for.
The programmer should check the full key word, not just the
first few characters.
Some keywords may be necessary for DOS based programs and not for OS/2
based programs, and vice-versa. I'll note typical use.
Keywords should be in upper case.
Keyword Data
------- ------------------------
BBSTYPE Name of BBS type (REQUIRED)
BBSVERSION Version of BBS (REQUIRED)
SYSOPNAME Name of system operator
SYSOPHANDLE Handle of system operator
BBSNAME Name of BBS
BBSPATH Path to BBS files
DTERATE This the speed of the computer to modem connection
(speed to open port at for DOS systems, OS/2 doors
don't need to deal with the speed of the port)
If the user is local, then use the LOCAL keyword,
don't waste space by setting the DTE rate to 0
BPSRATE This is the speed of the modem to modem connection
(typically used to calculate transfer times, DOS & OS/2)
PORTNAME This is the name of the com port (DOS) If this is
a device name, then the name should end with ':'
to keep with device name conventions. ie. COM1:
Same thing here.. if the user is local don't waste
space by setting the com port to COM0 or some such.
Use the LOCAL keyword.
PORTHANDLE This is the number of the file handle which accesses
the port (OS/2 uses passed file handles for OS/2
doors to access the com port. OS/2 doors don't need
PORTNAME) Handle may be comm device or named pipe.
To determine handle type, use API DosQueryHType
PARITY Type of parity (NONE, EVEN, STOP, MARK, SPACE)
DATABITS Number of data bits (5, 6, 7, 8)
STOPBITS Number of stop bits
0 = default stop bits. For 5 data bits, this
would be 1.5 stop bits. For 6, 7, and 8
data bits, this would be 1 stop bit.
1 = 1 stop bit.
2 = 2 stop bits.
LINENUMBER Line or Node number of current session
USERNUMBER User file record number
NAME Name of current user
HANDLE Handle of current user
ADDRESS Address of user. Multiple ADDRESS lines are okay.
Let's not get crazy though, so three (3) address
lines max.
CITY City user is located in
STATE State/Province located in
ZIPCODE ZIP/Postal code
COUNTRY Country user is located in
HOMEPHONE Home phone number of user
DATAPHONE Data phone of user
FAXPHONE FAX phone of user
BUSPHONE Business phone of user
Valid dialing characters only, don't put in characters
which the BBS program uses to calculate delays and such.
PASSWORD Password of user. Some BBS programs don't store a password
as a string! They store a numerical representation of the
password. In this case use PASSNUMBER
PASSNUMBER Numerical representation of password.
(define how this representation is calculated....)
SECNUM Security number
SECNAME Security name
TIMESON Number of times user has called.
DATELASTON Date of last call (YY/MM/DD)
TIMELASTON Time of last call (HH:MM)
TIMEON Time of this call (HH:MM)
SECSLEFT Seconds left this session
MINSLEFT Minutes left this session
EXPIREDATE Date when registration expires (YY/MM/DD)
SCREENLENGTH Number of rows of user screen
SCREENWIDTH Number of columns on user screen
BIRTHDAY Birth date (YY/MM/DD)
CONFERENCE Conference user was in when they exited to door.
PROTOCOL Letter of file transfer protocol (ie. X, Y, Z, etc)
UPLOADS Number of files uploaded
DOWNLOADS Number of downloads
DLTODAY Number of files downloaded today
MAXDLTODAY Maximum number of files that can be downloaded today
DLKTODAY Kilobytes downloaded so far today
MAXDLKTODAY Maximum kilobytes that can be downloaded today
ULTODAY Number of files uploaded today
MAXULTODAY Maximum number of files that can be uploaded today
ULKTODAY Kilobytes uploaded so far today
MAXULKTODAY Maximum kilobytes that can be uploaded today
ULBYTES Total bytes uploaded
DLBYTES Total bytes downloaded
ULKBYTES Total K-bytes uploaded
DLKBYTES Total K-bytes downloaded
EVENTTIME Time of next event (HH:MM)
LASTNEWFILESCAN Date of last new files scan (YY/MM/DD)
TIMECREDIT Time credits for this session (positive or negative)
BANKTIME Time in bank
(user may withdraw time from bank, but check to see
if the withdrawl would interfere with an upcoming
BBS event)
TIMESPOSTED Number of times user has posted a message
COMMENT Comment on user
LOCAL Local mode (no com port in use) (1=yes 0=no)
LOCKING Use file locking (1=yes 0=no)
DISPLAY local display of BBS (1=yes 0=no)
PRINTER print actions of user (1=yes 0=no)
SYSOPPAGE SysOp paging okay (1=yes 0=no)
EXPERT Expert node (1=yes 0=no)
NOVICE Novice mode (1=yes 0=no)
ARQCONNECT Modem error connecting connection (1=yes 0=no)
ANSICOLOR ANSI color mode (1=yes 0=no)
ANSIMONO ANSI cursor movement only, no color (1=yes 0=no)
HIGHASCII High ASCII (128-255) chars okay (1=yes 0=no)
MSGAREA Last message area user in
FILEAREA Last file area user in
FOSSIL Use FOSSIL driver (1=yes 0=no) DOS based programs
should be able to autodetect a FOSSIL driver in any
case.
SYSOP System Operator? (1=yes 0=no) How the SYSOP flag
is set is up to the BBS programmer. Keep in mind
that the door programmer may allow access to certain
parts of their program when the SYSOP flag is true.
This is the first set of defined keywords. I consider most of them
generic in nature.
I realize that BBS programs are not created equally (things wouldn't
be very interesting if they were) so not all data are created
equally. Some BBS programs either do not support some of that data,
they support more data than that, or they support the same data in
different formats from those above.
Because of this is, the BBS programmer does not need to support
all keywords, or they may create special keywords which may contain
data specific to the BBS program.
Once again, the door programmer should check the BBSTYPE and BBSVERSION
data to determine how it should interpret certain data. For instance
for certain BBS programs the door might want to look for a security
level NAME rather than a security level NUMBER. Other BBS programs
are not conference based, so you might not want to look for the
CONFERENCE keyword, but rather the MSGAREA or maybe FILEAREA keywords.
You get the idea.
BBS programmers, as mentioned above, if the user is in local mode
(not calling over the modem, so no modem connection is needed) then
don't put in the modem parameters (speed, port name, etc.) use the
LOCAL keyword instead!
Don't Go Crazy
--------------
Don't go crazy with your own interpretation of the keyword/data
concept. If something isn't clear to you in this file, contact me!
If I get a complaint from someone about someone else interpretation
of this file, and I agree with them, I'll contact you to see about
clearing up the problem.
I am wary of this because I have seen how the DORINFO file spec
has been hacked to death.. and there are umpteen DORINFO
'standards' out there these days. (I know the guy who created
the DORINFO standard.. and I don't think anyone follows the
spec exactly.. it's a shame) If you aren't sure how to
create this file contact me! I'll be more than happy to
help you out.. and everyone will benefit.
Special Keywords
----------------
If you want to create you own keywords, then I suggest the following
convention. Start the keyword with a name signifying the BBS program,
then an underscore, then a keyword which describes the data. For example
you could use:
BBSNAME_KEYWORD
Then document these keywords!
If the data you specify for a certain keyword does not match up to the
above then either document the format of the data, or create a new
keyword.
Don't make the door programmer guess at the keywords and formats of your
special keywords!
Returning changes to the BBS program
------------------------------------
A door program may change some of the data passed to it. To return the
change preceed the line with a '!' exclamation mark. This usually means
you'll have to rewrite the file. Use the same file name as was passed
to your program. Say your door program was passed the number of downloads
a user has made, and that changes in your program.
You were passed:
DOWNLOADS 37
The user then download 5 files in your program. You would rewrite the
line as:
!DOWNLOADS 42
The BBS program should look for a line that starts with an exclamation
mark, and then change the data accordingly.
Remember door programmers, the BBS programmer may ignore any changes you
have made to the 'Session.Info' file. Write the changes anyway.. you
might get lucky.
Required Keywords
-----------------
There are only two keywords which are required. BBSTYPE and BBSVERSION.
They are necessary to identify data associated with the file, and to
give the door programmer a clue as to what to look for. They should be
included at or near the beginning of the text file.
Other data that would be nice is NAME and MINSLEFT or SECSLEFT.
DOS based doors may require more information, such as: PORTNAME, DTERATE,
PARITY, DATABITS, STOPBITS, etc.
More sophisticated doors require more info.
Example Session.Info File(s)
----------------------------
Possible bare-bones Session.Info file
-------[cut here]--------
BBSTYPE Adept
BBSVERSION 0.22
LINENUMBER 2
NAME Joe User
HANDLE Forrest Gump
MINSLEFT 35
-------[cut here]--------
A little more texture
-------[cut here]--------
BBSTYPE RBBS-PC
BBSVERSION 17.4a
NAME Joe User
MINSLEFT 23
PORTNAME COM1:
DTERATE 38400
DATABITS 8
PARITY NONE
STOPBITS 1
FOSSIL 1
LINENUMBER 1
BANKTIME 12
LASTNEWFILESCAN 94/07/01
DATELASTON 94/07/02
TIMELASTON 13:56
TIMEON 16:39
CITY Anytown
HIGHASCII 1
ANSICOLOR 1
ARQCONNECT 1
SECNUM 10
LOCKING 1
-------[cut here]--------
Same as above, only in local mode
-------[cut here]--------
BBSTYPE RBBS-PC
BBSVERSION 17.4a
NAME Joe User
MINSLEFT 23
LOCAL 1
LINENUMBER 1
BANKTIME 12
LASTNEWFILESCAN 94/07/01
DATELASTON 94/07/02
TIMELASTON 13:56
TIMEON 16:39
CITY Anytown
HIGHASCII 1
ANSICOLOR 1
ARQCONNECT 1
SECNUM 10
LOCKING 1
-------[cut here]--------
How To Reach Me
---------------
I support this to the best of my ability. There are several different
ways of contacting me.
Mail:
John Morris
1718 Woodhaven Ln.
Sparks, NV 89434
Compuserve: 71562,3235
Netmail:
RBBS-Net 8:919/1 or 2 -or- Fidonet 1:213/760 or 761
BBS:
The Abandoned Land
(702) 359-1138
(702) 359-0629
Voice:
(702) 359-1303
