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