💾 Archived View for spam.works › mirrors › textfiles › programming › qwk.txt captured on 2023-07-22 at 20:45:35.
⬅️ Previous capture (2023-06-16)
-=-=-=-=-=-=-
QWK Mail Packet File Layout
by Patrick Y. Lee
Version 1.0 - February 23, 1992
First release.
Version 1.1 - March 15, 1992
Minor fixes here and there to make everything just right.
Version 1.2 - May 31, 1992
Added a few items to the DOOR.ID file that is being supported by Qmail
DeLuxe? version 1.25.
Version 1.3 - July 6, 1992
Added changes to the QWK format adopted by Qmail door. Specifically
line 10 of CONTROL.DAT file and bytes 126-127 of MESSAGES.DAT file.
Please refer to the appropriate section for the changes.
This document is Copyright 1992 by Patrick Y. Lee.
The QWK-format is Copyright 1987 by Sparkware.
All program names mentioned in this document are either Copyright or Trade-
mark of respective owner(s).
The author provides this file as-is without warranty of any kind, either
expressed or implied. You are using the information in this file at your
own discretion. The author assumes no responsibilities for damages, either
physically or financially, from the use of this information.
This document may be freely distributed by any means (electronically, pa-
per, etc.), provided that it is distributed in its entirety. Portions of
this document may be reproduced without credit.
Table of Contents
1. Introduction
1.1. Intent
1.2. History
1.3. Questions, corrections, etc.
2. Conventions & overview
2.1. The BBS ID
2.2. Packet compression
2.3. Packet transfer & protocols
2.4. Limitations
3. QWK files
3.1. Naming convention
3.2. Control file (CONTROL.DAT)
3.3. Welcome file
3.4. Goodbye file
3.5. News file
3.6. Qmail DeLuxe? menu file
3.7. New uploads listing (NEWFILES.DAT)
3.8. Bulletin file(s) (BLT-x.y)
3.9. Message file (MESSAGES.DAT)
3.10. Index files (*.NDX)
3.10.1. Conference indices
3.10.2. Personal index (PERSONAL.NDX)
3.11. Pointer file
3.12. SESSION.TXT
4. REP files
4.1. Naming convention
4.2. Message file (BBSID.MSG)
4.3. Door control messages
4.3.1. DOOR.ID file
4.3.2. Qmail
4.3.3. MarkMail
4.3.4. KMail
4.3.5. RoseMail
4.3.6. Complete Mail Door
4.4. Turning off the echo flag
4.5. Tag-lines
5. Net mail
A. Credits & contributions
B. Sample Turbo Pascal and C code
C. Sample message
D. Sample index file
-=-=-=-=-=-=-<>-=-=-=-=-=-=-
To search for a specific section, look for "[x.x]" using your editor or
viewer. For example, to jump to the tag-lines portion of this file, search
for "[4.5]" with your editor or text viewer.
-=-=-=-=-=-=-<>-=-=-=-=-=-=-
[1] Introduction
[1.1] Intent
This document is written to facilitate programmers who want to write
QWK-format mail doors or readers. It is intended to be a comprehen-
sive reference covering all areas of QWK-format mail processing.
Detailed break down of each file is included, as are implementation
information. In addition, door and reader specific information may be
included, when such information are available to me.
[1.2] History
The QWK-format was invented by Mark "Sparky" Herring in 1987. It was
based on Clark Development Corporation's PCBoard version 12.0 message
base format. Off-line mail reading has become popular only in recent
years. Prior to summer of 1990, there were only two QWK-format off-
line mail reader programs. They were Qmail DeLuxe by Mark Herring and
EZ-Reader by Eric Cockrell. Similarly for the doors, there were only
two -- Qmail by Mark Herring and MarkMail by Mark Turner. They were
both for PCBoard systems.
A lot has changed in both off-line reader and mail door markets since
summer 1990. Now, there are more than a dozen off-line mail readers
for the PC. Readers for the Macintosh, Amiga, and Atari exist as
well. There are over a half dozen doors for PCBoard, and QWK-format
doors exist for virtually all of the popular BBS softwares. All of
these happened in less than two years! More readers and doors are in
development as I write this, keep up the excellent work. In addition
to doors, some BBS softwares has QWK-format mail facility built in.
Off-line mail reading is an integral part of BBS calling. Conference
traffic and selection on all networks have grown dramatically in re-
cent years that on-line reading is a thing of the past. Off-line mail
reading offers an alternative to reading mail on-line -- It offers
speed that cannot be achieved with on-line mail reading.
The reason why QWK-format readers and doors seem to have gained popu-
larity is probably dued to its openness. The format is readily avail-
able to any programmer who wishes to write a program that utilize it.
Proprietary is a thing of the past, it does not work! Openness is
here to stay and QWK-format is a part of it.
[1.3] Questions, corrections, etc.
Most of the message networks today have a conference/echo devoted to
discussion of off-line readers and mail doors. The ones I know are on
FidoNet, ILink, Intelec, and RIME. If you have questions after read-
ing anything in here, feel free to drop by any of the above conference
/echo and I am sure other QWK authors will try to help.
I can be reached in the Off-line conferences on RIME, ILink, and In-
telec, as well as the Common conference on RIME. Mail can be routed
to node RUNNINGB. I can be reached on the Internet at
"p.lee@green.cooper.edu". Any corrections, extensions, comments, and
criticisms are welcomed.
[2] Conventions & overview
All offsets referenced in this document will be relative to 1. I am
not a computer, I start counting at one, not zero!
Words which are enclosed in quotes should be entered as-is. The quota-
tions are not part of the string unless noted.
You may have noticed I use the phrase "mail program" or "mail facili-
ty" instead of mail doors. This is because some BBS softwares offer
the option of creating QWK-format mail packets right from the BBS.
With those, there is no need for an external mail door.
[2.1] The BBS ID
The BBS ID (denoted as BBSID) is a 1-8 characters word that identifies
a particular BBS. This identifier should be obtained from line 5 of
the CONTROL.DAT file (see section 3.2.1).
[2.2] Packet compression
Most mail packets are compressed when created by the mail door in
order to save download time and disk space. However, many off-line
reader programs allow the user to unarchive a mail packet outside of
the reader program, so the reader will not have to unarchive it. Upon
exit, the reader will not call the archiver to save it. It is up to
the user to archive the replies. This is useful if the user has limit-
ed memory and cannot shell out to DOS to run the unarchive program.
For readers based on non-PC equipment, the user may be using less
common compression program that does not have command line equivalent.
[2.3] Packet transfer & protocols
There is no set rule on what transfer protocol should be used. Howev-
er, it would be nice for the mail program on the BBS to provide the
Sysop with options as to what to offer. This should be a configura-
tion option for the user.
[2.4] Specifications & limitations
There aren't many known limits in the QWK specification. However,
various networks seem to impose artificial limits. On many of the PC-
based networks, 99-lines appears to be the upper limit for some soft-
wares. However, most of the readers can handle more than that. Read-
er authors reading this may want to offer the option to split replies
into n lines each (the actual length should be user definable so when
the network software permits, the user can increase this number).
[3] QWK files
[3.1] Naming convention
Generally, the name of the mail packet is BBSID.QWK. However, this
does not have to be the case. When the user downloads more than one
mail packet at one time, either the mail program or the transfer proto-
col program will rename the second and subsequent mail packets to
other names. They will either change the file extension or add a
number to the end of the filename. In either case, you should not
rely on the name of the QWK file as the BBSID. The BBSID, as men-
tioned before, should be obtained from line 5 of the CONTROL.DAT file.
In addition, mail packets do not have to end with QWK extension ei-
ther. The user may choose to name them with other file extensions.
[3.2] Control file (CONTROL.DAT)
The CONTROL.DAT file is a simple ASCII file. Each line is terminated
with a carriage return and line feed combination. All lines should
start on the first column.
Line #
1 My BBS BBS name
2 New York, NY BBS city and state
3 212-555-1212 BBS phone number
4 John Doe, Sysop BBS Sysop name
5 20052,MYBBS Mail door registration #, BBSID
6 01-01-1991,23:59:59 Mail packet creation time
7 JANE DOE User name (upper case)
8 Name of menu for Qmail, blank if none
9 0 ? Seem to be always zero
10 999 Total number of messages in packet
11 121 Total number of conference minus 1
12 0 1st conf. number
13 Main Board 1st conf. name (13 characters or less)
14 1 2nd conf. number
15 General 2nd conf. name
.. 3 etc. onward until it hits max. conf.
.. 123 Last conf. number
.. Amiga_I Last conf. name
.. HELLO Welcome screen file
.. NEWS BBS news file
.. SCRIPT0 Log off screen
Some mail doors, such as MarkMail, will send additional information
about the user from here on.
0 ?
25 Screen length on the BBS
JANE DOE User name in uppercase
Jane User first name in mixed case
NEW YORK, NY User city information
718 555-1212 User data phone number
718 555-1212 User home phone number
108 Security level
00-00-00 Expiration date
01-01-91 Last log on date
23:59 Last log on time
999 Log on count
0 Current conference number on the BBS
0 Total KB downloaded
999 Download count
0 Total KB uploaded
999 Upload count
999 Minutes per day
999 Minutes remaining today
999 Minutes used this call
32767 Max. download KB per day
32767 Remaining KB today
0 KB downloaded today
23:59 Current time on BBS
01-01-91 Current date on BBS
My BBS BBS network tag-line
0 ?
Some mail doors will offer the option of sending an abbreviated con-
ference list. That means the list will contain only conferences the
user has selected. This is done because some mail readers cannot
handle more than n conferences at this time. Users using those read-
ers will need this option if the BBS they call have too many confer-
ences.
[3.3] Welcome file
This file usually contains the log on screen from the BBS. The exact
filename is specified in the CONTROL.DAT file, after the conference
list. This file may be in any format the Sysop chooses it be -- usu-
ally either in plain ASCII or with ANSI screen control code. Some
Sysops (notably PCBoard Sysops) may use BBS-specific color change code
in this file as well. Current mail programs seem to handle the trans-
lations between BBS-specific code to ANSI based screen control codes.
Even if the CONTROL.DAT file contains the filename of this file, it
may not actually exist in the mail packet. Sometimes, users will
manually delete this file before entering the mail reader. Some off-
line readers offer the option to not display this welcome screen; some
will display this file regardless. Some doors, similarly, will offer
option to the user to not send this file.
[3.4] Goodbye file
Similar to the welcome file above, the filename to the goodbye file is
in the CONTROL.DAT file. This is the file the BBS displays when the
user logs off the board. It is optional, as always, to send this file
or to display it.
[3.5] News file
Many mail doors offer the option to send the news file from the BBS.
Most will only send this when it has been updated. Like the welcome
and goodbye files, the filename to the news file is found in the CON-
TROL.DAT file. It can be in any format the Sysop chooses, but usually
in either ASCII or ANSI. Like the welcome screen, current mail facil-
ities seem to handle translation between BBS-specific control codes to
ANSI screen control codes.
[3.6] Qmail DeLuxe? menu file
This file is of use only for Qmail DeLuxe? mail reader by Sparkware.
The filename is found on line 8 of the CONTROL.DAT file.
[3.7] New uploads listing (NEWFILES.DAT)
Most mail programs on the BBS will offer the option to scan new files
uploaded to the BBS. The result is found in a file named
NEWFILES.DAT. The mail program, if implementing this, should update
the last file scan field in the user's profile, if there is such a
field, as well as other information required by the BBS. The mail
program should, of course, scan new files only in those areas the user
is allowed access.
[3.8] Bulletin files (BLT-x.y)
Most mail programs will also offer the option to include updated bulle-
tin files found on the BBS in the mail packet. The bulletins are
named BLT-x.y, where x is the conference/echo the bulletin came from,
and y the bulletin's actual number. The mail program will have to
take care of updating the last read date on the bulletins in the user
record.
[3.9] Message file (MESSAGES.DAT)
The MESSAGES.DAT file is the most important. This is where all of the
messages are contained in. The QWK file format is based on PCBoard
12.0 message base format from Clark Development Corporation (maker of
PCBoard BBS software).
The file has a logical record length of 128-bytes. The first record
of MESSAGES.DAT always contain a copyright notice saying "Produced by
Qmail...Copyright (c) 1987 by Sparkware. All Rights Reserved". The
rest of the record is space filled. Actual messages consist of a 128-
bytes header, plus one or more 128-bytes block with the message text.
Actual messages start in record 2. The header block is layed out as
follows:
Offset Length Description
------ ------ ----------------------------------------------------
1 1 Message status flag (unsigned character)
' ' = public, unread
'-' = public, read
'+' = private, unread
'*' = private, read
'~' = comment to Sysop, unread
'`' = comment to Sysop, read
'%' = password protected, unread
'^' = password protected, read
'!' = group password, unread
'#' = group password, read
'