====== QWK File Format ======

QWK is a common protocol for offline message readers and BBS software. This is a quick synopsis on how to implement support into your product (reader, processor, or BBS).

===== Files in a QWK zip =====

Even though the files are zipped, the file extension is renamed to .QWK for the download from the BBS software, and .REP for the zip uploading messages to the BBS.

  - CONTROL.DAT (a string list file)
  - MESSAGES.DAT (a 128 block ASCII file)
  - *.NDX (an array of binary bytes)

===== CONTROL.DAT =====

Each line is CRLF 0x0D 0x0A (#13#10) (\r\n) delimited.

^Line 1 |BBS name|
^Line 2 |BBS city and state|
^Line 3 |BBS phone number|
^Line 4 |BBS Sysop name|
^Line 5 |Mail door registration #, BBSID|
^Line 6 |Mail packet creation time|
^Line 7 |User name (upper case)|
^Line 8 |Name of menu for Qmail, blank if none|
^Line 9 |? Seem to be always zero|
^Line 10 |Total number of messages in packet|
^Line 11 |Total number of conference minus 1|
^Line 12 |1st conf. number|
^Line 13 |1st conf. name (13 characters or less) Modern QWK BBSes send Full Conference Names|
^Line 14 |next conf. number|
^Line 15 |next conf. name (13 characters or less) Modern QWK BBSes send Full Conference Names|
^2nd from last|Welcome screen file|
^Next from last|BBS news file|
^Last Line|Log off screen|

Some BBS systems will have additional lines after those above:

^Next Section |? always a zero|
^Screen length on the BBS |25|
^User name in uppercase |OZZ NIXON|
^User first name in mixed case |Ozz|
^User city information |Crestview, Fl|
^User data phone number |850-123-4567|
^User home phone number |850-555-1212|
^Security level |110|
^Expiration date |00-00-00|
^Last log on date |11-16-19|
^Last log on time |13:24:59|
^Log on count |134|
^Current conference number on the BBS |8|
^Total KB downloaded |0|
^Download count |0|
^Total KB uploaded |0|
^Upload count |0|
^Minutes per day |459|
^Minutes remaining today |439|
^Minutes used this call |20|
^Max. download KB per day |10240000|
^Remaining KB today |10240000|
^KB downloaded today |0|
^Current time on BBS |13:27:03|
^Current date on BBS |11-17-19|
^BBS network tag-line |FSXNet BBS|

===== MESSAGES.DAT =====

Messages file starts with a 128 byte product information. Like:

  * Produced by Qmail...Copyright (c) 1987 by Sparkware.  All Rights Reserved. (padded with spaces)
  * QWK Packet Produced by PCBoard v15.0 (padded with spaces)

That block is followed by messages using PCBoard 12.0 format.

In Pascal:
<code pascal>
    type
       MsgHeaderRec=Packed Record
          TypeID:String[1];
          MsgID:String[7];
          DateStr:String[8];
          TimeStr:String[5];
          MsgTo:String[25];
          MsgFrom:String[25];
          MsgSubj:String[25];
          Reserved:String[12];
          MsgRefer:String[8];
          Chunks:Longint;
          Attributes:String[6];
       End;
</code>

In C:

<code C>
    struct QwkHeader {
	unsigned char Msgstat;     /* Message status       */
	unsigned char Msgnum[7];   /* Message number       */
	unsigned char Msgdate[8];  /* Message date MM-DD-YY*/
	unsigned char Msgtime[5];  /* Message time HH:MM   */
	unsigned char MsgTo[25];   /* Message To:          */
	unsigned char MsgFrom[25]; /* Message From:        */
	unsigned char MsgSubj[25]; /* Message Subject:     */
	unsigned char Msgpass[12]; /* Message password     */
	unsigned char Msgrply[8];  /* Message reply to     */
	unsigned char Msgrecs[6];  /* Length in records    */
	unsigned char Msglive;     /* Message active status*/
	unsigned char Msgarealo;   /* Lo-byte message area */
	unsigned char Msgareahi;   /* Hi-byte message area */
	unsigned char Msgofflo;
	unsigned char Msgoffhi;
	unsigned char Msgtagp;
    } __attribute__((packed));
</code>

Of course to populate that structure you will BlockRead 128 bytes, them move from offset to length to each field.

^Offset  |^Length  |^Description|
|1||1||Message status flag (unsigned character)|
^ |^ ||#32 = (space) public, unread|
^ |^ ||'-' = public, read|
^ |^ ||'+' = private, unread|
^ |^ ||'*' = private, read|
^ |^ ||'~' = comment to Sysop, unread|
^ |^ ||'`' = comment to Sysop, read|
^ |^ ||'%' = password protected, unread|
^ |^ ||#94 = (carrot) password protected, read|
^ |^ ||'!' = group password, unread|
^ |^ ||'#' = group password, read|
^ |^ ||'$' = group password to all|
|2||7||Message number (in ASCII)|
|9||8||Date (''mm-dd-yy'', in ASCII)|
|17||5||Time (24 hour ''hh:mm'', in ASCII)|
|22||25||To (uppercase, left justified)|
|47||25||From (uppercase, left justified)|
|72||25||Subject of message (mixed case)|
|97||12||Password (space filled)|
|109||8||Reference message number (in ASCII)|
|117||6||Number of 128-bytes blocks in message ((including the header, in ASCII; the lowest value should be 2, header plus one block message; this number may not be left flushed within the field))|
|123||1||Flag ((ASCII 225 means message is active; ASCII 226 means this message is to be killed))|
|124||2||Conference number (unsigned word)|
|126||2||Logical message number in the current packet ((this number will be 1 for the first message, 2 for the second, and so on. unsigned word))|
|128||1||Indicates whether the message has a network tag-line or not. ((A value of '*' indicates that a network tag-line is present; a value of ' ' (space) indicates there isn't one.  Messages sent to readers (non-net-status) generally leave this as a space. Only network software need this information.))|


==== MESSAGE BODY ====

Instead of carriage return and line feed combination, each line in the message end with an ASCII 227 (pi character) symbol. If a message does not completely occupy the 128-bytes block, the remainder of the block is padded with space or null.

===== Index files (*.NDX) =====

The index files contain a list of pointers pointing to the beginning of messages in the MESSAGES.DAT file.  The pointer is in terms of the 128-bytes block logical record that the MESSAGES.DAT file is in. Each
conference has its own xxx.NDX file, where xxx is the conference number left padded with zeroes. Some mail programs offer the user the option to not generate index files. So the mail readers need to create the index files if they are missing.

^Offset  |^Length  |^Description|
^1|^4|^Record number pointing to corresponding message in MESSAGES.DAT. [1]|
^5|^1|^Conference number of the message (same as filename, e.g. USELESS)|

[1] = This number is in the Microsoft MKS$ BASIC format.

In Pascal:

    Type
       BSingle:Array[0..3] of Byte;
    
    Procedure LONG2MSB(Index:LongInt;Var MS:BSingle);
    Var
       Exp : Byte;
    Begin
       If Index <> 0 Then Begin
          Exp := 0;
          While Index And $800000 = 0 Do Begin
             Inc (Exp);
             Index := Index SHL 1;
          End;
    
          Index := Index And $7FFFFF;
       End
       Else Exp := 152;
       MS[0] := Index AND $FF;
       MS[1] := (Index SHR 8) AND $FF;
       MS[2] := (Index SHR 16) AND $FF;
       MS[3] := 152 - Exp;
    End;

In C:

    int ieee_to_msbin(float *src4, float *dest4) {
	unsigned char *ieee = (unsigned char *)src4;
	unsigned char *msbin = (unsigned char *)dest4;
	unsigned char sign = 0x00;
	unsigned char msbin_exp = 0x00;
	int i;
	/* See _fmsbintoieee() for details of formats   */
	sign = ieee[3] & 0x80;
	msbin_exp |= ieee[3] << 1;
	msbin_exp |= ieee[2] >> 7;
	/* An ieee exponent of 0xfe overflows in MBF    */
	if (msbin_exp == 0xfe) return 1;
	msbin_exp += 2; /* actually, -127 + 128 + 1 */
	for (i = 0; i < 4; i++) msbin[i] = 0;
	msbin[3] = msbin_exp;
	msbin[2] |= sign;
	msbin[2] |= ieee[2] & 0x7f;
	msbin[1] = ieee[1];
	msbin[0] = ieee[0];
	return 0;
    }

==== Personal index (PERSONAL.NDX) ====

There is a special index file named PERSONAL.NDX. This file contains pointers to messages which are addressed to the user, i.e. personal messages. Some mail door and utility programs also allow the selection of other messages to be flagged as personal messages.

**NOTE** I have found that not all BBS software generate this file, for example PCBoard 15.x