Documentation 1 of 4
QWKRR128 v5.1 Documentation - Part 1 of 4
Note:
The HTML version of QWKRR's documentation is slightly different from the distribution files. Due to space considerations in creating the .SFX files, the "Pre-QWKRR Tutorial" segment was moved to a separate file named "pre-qwkrr.doc". The HTML version includes this segment within the regular documentation, as we originally intended. On 27 August, 1997 the HTML version was updated to include and link to David Schmoll's latest version of Unzip128 (NZP12819.SFX).
On 23 May 1998 the HTML version was updated again to include and link to Errol Smith's new Unzip program that handles PKZip 2.04g files (unzp6420.prg).
QWKRR128 V5.10 Documentation
QWKRR128 Copyright 1992-97 Rod Gasson
3 July 1997
Program & Original Documentation by: Rod Gasson REYNELLA,
South Australia
Updated Docs & Support: Gaelyne
Gasson REYNELLA, South Australia
Public Docs, Edited, Compiled and Formatted by: Mark Dowsett SYDNEY, New South Wales
Introduction
Welcome to the QWKRR128's Documentation. Within these pages, you'll learn how to use QWKRR128 to read QWK format offline mail. You'll also find the answer to LTUAE (Life, The Universe And Everything), but you will have to read each and every word before you'll find this answer. ;-)
The Documentation has been updated and completely revised in a format we hope you will find easy to read, and easy to understand.
Enjoy!
Supporting Files and Programs
Before we can begin discussing using QWKRR, it's a good idea to have a grasp of the common filenames that are mentioned in the documentation. The following list contains a quick run down of the various filenames and programs that you will find while reading.
- <bbs-id>
- This is a variable name. The actual name is supplied by your BBS and can be in any case (upper, lower or a combination). Example: RodsMail
- <bbs-id>.QWK (prg/seq)
- This is the mail file you download from the BBS. It's an archived file that will contain files required by QWKRR. Example: RodsMail.QWK
- MESSAGES.DAT (prg/seq)
- CONTROL.DAT (prg/seq)
- These are the two files within an archived QWK packet that QWKRR REQUIRES. MESSAGES.DAT is the file that contains the actual messages and CONTROL.DAT is a control file (gee!) that holds the conference names and the <BBSid> and your user name.
- xxx.NDX, door.id, welcome, goodbye (prg/seq)
- These files are not used by QWKRR and need not be extracted from the mail packet.
- XXXXXXXX.ATT (prg/seq)
- Some BBS's will decode any uuencoded files from your messages and include them in your mail packet with a filename like XXXXXXXX.ATT. You will usually see a note in the message with the uuencode telling you the file was decoded and included in your packet, along with the filename. UUencodes are described more fully later in the documentation.
- <bbs-id>.MSG (seq)
- This is the basic QWK reply file. This is created when you use the <L>ink option. Example: RodsMail.MSG
- <bbs-id>.rep (prg)
- This is the "completed" or "packed" reply file that you upload to the BBS. If using the inbuilt packer, QWKRR produces this when the <Z>ip option is selected. Example: RodsMail.rep
- <bbs-id>.Rxxx (usr)
- These are the series of individual reply messages that QWKRR produces prior to linking. Example: RodsMail.R001
- <bbs-id>.fxxx (usr)
- These are the individual file attaches. The numbers relate only to the order the files were created and do not match the Reply number. Example: RodsMail.f001
- <bbs-id>.NET (usr)
- Holds the Netmail conference and format required for any particular BBS. This file is searched for and loaded whenever QWKRR is run. See the section on Netmail and Email for more details. Example: RodsMail.NET
- Q.NDX (usr)
- This is holds the data for message pointers, active conferences, number of messages and message flags. Q.NDX is only valid for the current mail packet and disk on which it was created. A new (updated) Q.NDX file is saved whenever you quit the program.
- Q.DEFAULTS (usr)
- This file contains your Options preferences including colour, printer type, Intro macro, the current drive numbers, partitions and paths. The Defaults file (if found) will load the following files when QWKRR is first run, or when you choose <O>pen from the Quit menu.
- QM.<name> - Macro definitions file
QT.<name>.<xxx> - Tagline files
QW.<name> - Twit file list
QV.<name> - VIP file list
QC.<name> - Character sets
QS.<name> - QWKRR Systems files (as described below)
QS.CHARS - System character set
QS.KEYBOARD - Keyboard definitions file - The default names QM.MACRO, QT.TAGLINES.001, QW.TWIT, QV.VIP and QC.STD are searched for and loaded when QWKRR is first run, unless redefined in the defaults file.
- QS.ADDRESSES (seq)
- This file is created by QWKRR when an Email or Netmail address is saved, and accessed every time you send Email or Netmail. This file is in ASCII format and can be edited by the user.
- QS.HIDELIST (seq)
- A list of words or partial words that if found at the beginning of a line, QWKRR can hide (or highlight) that particular line of text. This file is in ASCII format and can be edited by the user. The file must not exceed 1 disk block in size, or 255 characters, including line feeds.
- QHELP.<alpha character>
- These are QWKRR's help files, and are displayed when you press the HELP key. The file displayed depends on where you are within QWKRR.
- SMALL.DAT (seq)
- This is a utility file that QWKRR creates when you <S>tore messages. It uses the same format as the messages.dat file, and is useful for breaking a large mail packet down to a smaller packet for later use. SMALL.DAT must be renamed to "messages.dat" before it can be used. You should also use the same control.dat file that was used when the file was created.
- <bbs-id>.xxxx (seq)
- This is an ASCII text file containing the text of any messages that were "grabbed" using the <G>rab command. It consists of the <BBSID> and the date found in the control.dat file. Example: RodsMail.0222 (22nd February)
- QPX (QWK Packet Extractor)
- This was originally written by Russell Prater and has been modified by Rod to become an integral part of the QWKRR program. It allows those who download mail packets that are archived with ARC or PKPAK to dissolve the archive and load QWKRR. It requires the use of CSX128.ML (found in CSX01.SFX or CSX01.SDA). The CSX128.ML file must be on the same disk (or in the same directory) as QPX. QPX has separate documentation and should be set up before you attempt to use QWKRR.
- QPA
- This program is used to pack replies in ARC (stored) format. QWKRR accesses it after linking the replies, if the user selects QP<A> from the Quit menu. Please note the program must be configured for use prior to selecting it with QWKRR.
- TAGTHIEF
- This program will create tagline files for use with QWKRR. It has separate documentation.
- TAGCONVERT
- This is a stand-alone program by Jeff Sadler designed to convert QWKRR v3 and v4 tagline files to the format used by QWKRR v5.x. Refer to the separate documentation for instructions on its use.
- QPE (found in NZP12819.SFX)
- This program acts in a similar manner to QPX, but also dissolves PKZip v1.x archives. NZP12819.SFX is a software package created by David Schmoll that includes utilities to unzip PKZip v1.x archives and it includes QPE. It's recommended that if your files are archived in ZIP format that you make use of this program. It requires the use of CSX128.ML to dissolve PKPAK or PKARC files.
- BVZIP/BVUNZIP
- PKZip v1 compatible ZIP and UNZIP programs written by Bruce Vrieling to run under CSDOS.
- UNZIP64
- A C64 program by Bill Lucier to UNZIP IBM style ZIPS. (PKZip v1.x)
- UNZIP64v2
- A C64 program by Errol Smith to UNZIP IBM style ZIPS (PKZip 2.04g).
- CSARC/CSXARC
- Program options available under CSDOS to dissolve and create IBM style .ARCs. CSXARC, the deARCing module is available separately in a package that contains code to run in both 64 and 128 modes. The ARC modules can only be run in 128 mode under the CSDOS `SHELL'.
- CSDOS
- A very flexible operating system written for the C128 by Chris Smeets. It has as similar command structure to MS-DOS.
- CSX128.ML (found in CSX01.SFX or CSX01.SDA)
- This is a machine language file written by Chris Smeets that is used by QPX and QPE to dissolve PKARC or PKPAK style archives. CSX01 is a C64/128 stand-alone program by Chris Smeets that allows IBM ARC files to be dissolved.
- QWK
- A common MS-DOS based BBS mail packet format. There are others such as XRS and BlueWave. QWKRR128 only supports QWK packets.
- Fontigus (f128v3.sfx)
- A C128 Character set editor by Brett Tabke that can be used to create your own character sets for QWKRR.
- Desterm (des200-1.sfx through des200-5.sfx)
- A C128 term program written by Matthew Desmond. QWKRR128's character sets are compatible with Desterm's IBM sets.
Pre-QWKRR Tutorial
What is QWKRR128?
QWKRR128 is a C128 80 column QWK format Offline Mail Reader. It allows you read and reply to BBS mail offline and at your own pace. Reading BBS mail offline saves telephone bills for long distance users, and saves time online for other things such as downloading files, game playing and if your BBS is connected to the Internet, World Wide Web surfing. Sysops generally appreciate the use of an offline mail reader as it means that you're using the BBS, but it lets more users access the system while you're reading messages offline. Reading mail offline also keeps your telephone free for incoming or outgoing calls.
Hardware Requirements
You will need a C128 an 80 column monitor and at least one disk drive, although more than one disk drive is recommended. Most Commodore disk drives are compatible with QWKRR. Having a larger capacity drive is highly recommended. The following disk drives have been tested with QWKRR: 1541, 1570, 1571, and 1581. CMD (Creative Micro Designs, Inc.) devices that QWKRR is compatible with include the FD2000, FD4000, HD Series Hard Drive, and RAMLink. QWKRR128 is *NOT* compatible with RAMDOS.
Although QWKRR128 doesn't make direct use of it, in order to read BBS mail (online or off), you will need a modem.
Software Requirements:
You will need a terminal program so you can access a Bulletin Board or Internet provider to obtain the mail packet, and to send your replies back to the system.
As QWK format mail is archived, you will need software to extract the files that QWKRR requires. These are listed below.
Most offline mail readers on any platform are *NOT* stand alone programs. Almost all require that the programs to deal with archived files also exist on the same computer and can be "accessed" in some way. Many mail readers only show messages, and require an external text editor to create messages or reply to mail . QWKRR has a built-in editor for messages and will archive your replies. However, QWKRR requires the use of external programs to extract the files needed from the downloaded mail packet.
User Requirements:
As a user, you will need to be familiar with using your terminal program and with transferring files. If you aren't already familiar with uploading and downloading files, before using QWKRR, become familiar with the process. Learn what file transfer protocols can and can not be used reliably on the BBS or Internet provider that you use. This may seem insignificant, but it is essential that you master these steps before trying to use a program such as QWKRR.
You will need access to a BBS with QWK format offline mail facilities. These are usually (but not always) referred to as "Mail doors". As an alternative, you can also make use of Internet providers that offer QWK format mail utilities. Additionally, because the mail is downloaded in an archived format, you will need to ensure that the mail facility uses a compatible archive format. Last, you should be familiar with dissolving, or "unpacking" archived files.
Compatible Archive Formats
Archive types that can be used for QWK mail packets are listed below. ARC and PKZip are the preferred choices.
Archive Name / Version CBM file name Computer Mode ---------------------- ------------- ------------- LHArc 1.13 (LH-1) LHX (CS-DOS) 128 LHX64 64 mode (LHX09-64.SFX) LHA 2.xx (LH-5, LH-6) PMAUTOE.COM CP/M PKPAK 3.61 / CSX01 64/128 ARC 6.01 and 6.02 CSXARC (CS-DOS) 128 ?? CP/M PKZip 2.x UNZIP64v2 (unzp6420.prg) 64 PKZip 1.1x UNZIP64 (unzip101.sfx) 64 (or just ZIP) UNZIP128 (nzp12819.sfx) 128 (64 utils included) BVUNZIP (CS-DOS) 128 UNZIP.COM CP/M ARJ CPMUNARJ.ARK CP/M
NOTES:
- If using UNZIP in other than CP/M mode turn CRC checking OFF if possible. The files will probably give a CRC error even if dissolved correctly.
- UNZIP64v2 only handles PKZip 2.04g archives, whilst the other Zip related programs listed will only unzip PKZip 1.x archives.
- PKPAK is NOT the same as PAK. We do not have a PAK compatible unpacker.
- LOWER version numbers of the IBM programs are usually OK too, but not higher.
Mail Door Options
The offline mail program on the BBS will usually have an area where you can adjust how the mail is set up for you. It's in this area where you can choose how the mail is archived, which conferences you want included in your mail packet, and many other options. Below is a list of options you may find, along with comments concerning them.
- Packing Option:
- This is where you choose which archive type you want the mail packed using. ARC is the preferred choice, followed by Zip or PKZip.
- Packet Type:
- QWK (others may be offered).
- Protocol:
- Choose the transfer protocol you prefer to use (Zmodem, Ymodem, Xmodem etc.)
- Area Selection:
- May be labelled as Conference selection. This is where you choose the conferences that you want to download messages from.
- Use Small control.dat:
- Choose Yes if this option is available.
- Maximum # of Messages:
- This depends on your preference, as well as your disk drive capacity. (50-100 for 1541 or 1571 drives)
- # Per Conference:
- Same conditions as above.
- Split Long Messages:
- If this option exists and you know you will be receiving files through Email, set this option to "NO".
Dissolving the QWK packet
After you've downloaded your mail, you'll need to decompress (or "unpack") the .QWK file. Note that with the extension of ".QWK", you can't tell what was used to archive the mail packet. Usually when you download a mail packet, you will have an opportunity to select the archiver of your choice through options in the BBS mail door. However, not all mail doors offer this and for these situations, you have no way of knowing what program(s) to use to decompress the mail packet. This sometimes occurs with some mail doors too, and you are left with the choice of experimenting with the programs to decompress the mail.
There are a couple choices. Here are programs you can use, along with a brief description of each:
- QPX by Russell Prater, this is included in the QWKRR5-2.SFX utilities archive, and requires you to also have the files from CSX01.SDA on the same disk. This utility program dissolves files created with PKARC or PKPAK. It has separate documentation.
- QPE by David Schmoll, included in a file named NZP12819.SFX. QPE is a utility for QWKRR users that will dissolve PKZip v1.x mail packets, and mail compressed with PKARC or PKPAK, provided the files from CSX01.SDA are on the same disk as QPE. QPE, and UNZIP128 have separate documentation.
So... you'll need either QPE or QPX and probably CSX01.SDA. The download file names you will be looking for are:
- QWKRR5-2.SFX You should already have this if you downloaded all of the QWKRR128 files.
- NZP12819.SFX This contains UNZIP128 and QPE.
- CSX01.SDA This contains CSX128.ML, required by QPX and QPE to unarchive PKARC or PKPAK files.
Using QPX/QPE
The instructions that follow will assume you are using the supported functions in *EITHER* QPX or QPE. This requires that you have the following files on the same disk as QWKRR128:
QPX40 (Saves as "QPX" after you've run and saved your preferences).
CSX128.ML
OR:
QPE.BAS (Saves as "QPX").
CSX128.ML
UNZIP1.ML
UNZIP2.ML
UNZIP3.ML
Load and run QPX40. The program offers several defaults for the various drives and mail packet filename. One of the options is "MAXIMUS KLUDGE". This has been included because *some* mail packets from Maximus or EzyQWK BBS's when downloaded with Desterm can cause CSX01 to abort with an error after extracting the last file in the packet. This has been known to cause problems to RAMLink owners, but as a general rule is harmless. The disk error, however, causes QPX to quit and it negates the benefits that launching QWKRR from these programs gives. Performing this kludge on mail packets that don't need it, or on an already kludged packet will cause no harm, but it wastes time that could be spent reading mail. <g>
Once QPX (or QPE) is configured, you're ready to unpack your mail. The mail packet (archive) that you download will contain several files. The only ones of interest are the MESSAGES.DAT and CONTROL.DAT files.
The filename offered for the QWK packet will need to be changed, so press <N>o to the prompt of "Accept", and enter the filename you QWK mail packet. Note that this must be the *EXACT* name of the file you downloaded - if the name is "BBSid.QWK", and you type "bbsid.qwk", the program will not find the file on the disk.
Optimum settings:
FILE TO Un-Pack is.......bbsid.qwk (Use the name of your QWK packet) MAXIMUS KLUDGE...........n CRC CHECKING.............n INPUT DEVICE.............Disk drive # with QWKRRDOC.QWK packet INPUT path is ...........For CMD device owners. Example: 1//dirname/ OUTPUT DEVICE............Disk drive # where mail files will be placed. (Make sure it has lots of disk space) OUTPUT path is ..........For CMD device owners. Example: 1//dirname/ ALL/DAT/NDX a/d/n .......a (it extracts ALL files) Exit to OLR y/n .........y ACCEPT QWKRR DRIVES......n AUTO INDEX...............y or n (Option no longer required and is ignored by QWKRR) OLR Device is ...........Disk drive # with QWKRR program files. OLR Program Path is .....For CMD device owners. Example: 1//dirname/ Set control.dat time.....y ACCEPT Y/n...............y if you are satisfied with the changes made. SAVE NEW Defaults y/N....y The filename saved will be either QPX or QPE depending on the program you loaded).
NOTE: QWKRR no longer requires the "Auto Index" option, as it automatically indexes new mail packets.
If using QPE or QPX, and you've set this up correctly for your disk drives and the QWKRR drive, once the mail packet is dissolved, QWKRR will load and run with no further input. Otherwise simply load and run QWKRR as you would any other program.
Using QWKRR
If using a CMD device, you must have the partition containing QWKRR as the 'current' partition. Once the program has been run you can access other partitions and sub-directories for the messages, user, reply and tagline drives as required.
Drive Usage
QWKRR uses 5 predefined drives for its various input/output functions. All of these drive definitions and paths, except the QWKRR (system) drive are stored in the Q.DEFAULTS file.
- QWKRR drive:
- This should contain all the system files, such as macros, character sets, <bbs-id>.NET files, address file, hide, twit and VIP lists and Q.DEFAULTS.
- REPLY Drive:
- This is where QWKRR stores your replies (<bbs-id>.Rxxx) and looks for them when packing. It also stores your <bbs-id>.REP file on this drive.
- USER Drive:
- This is where all general input/output is performed, such as e<X>ported messages and <W>rite files. This drive can be re-selected at any time via the DOS options.
- MESSAGES Drive:
- This drive is where QWKRR expects to find the DAT files. It also stores the Q.NDX file here. For this reason you should always leave several blocks free (On a floppy system 10 blocks will be sufficient).
- TAGLINE Drive:
- This is where QWKRR expects to find your taglines (surprise) :-)
Provided there is no disk activity in progress, you can change any of the disks in any of the drives at any time. However, it is the user's responsibility to ensure that the correct disks are in the correct drive when required.
Note: It is strongly recommended that you do not change the disk in the MESSAGES.DAT or REPLY drives.
Drive Menu
QWKRR will display its Drive Menu screen showing the current definitions as outlined above. For each drive listed above the program displays a window containing the Drive usage, the Drive Number, type and the disk name. If it is a CMD device the Path name configured will also be displayed. Below these, a menu is shown containing:
Selecting M, R, T or U allows you to define the <D>rive and, if a CMD device, the <P>ath, including partition number and sub-directory name, for each set of files needed by the program. The System drive is set to the location the program was loaded from.
The selections for these drives can be saved permanently by going to the <O>ptions menu and selecting <S>ave to create or update the Q.DEFAULTS file.
If a CMD device with an RTC (Real Time Clock) is available QWKRR will scan for it and set the program clock from it. This information is displayed in the top right of the screen. If an RTC equipped device is not present you will be asked to set the clock once you have exited this screen, or after the mail packet is finished indexing.
Once the drives are selected to your satisfaction pressing <Q> or <RETURN> will leave this screen to the next section.
NOTE: You must have a disk in EVERY device configured in the window or QWKRR will not let you continue. The disk in the User device can be changed after this section is complete.
To by-pass this screen for future use, once QWKRR is loaded, move to the <O>ptions menu and press "S" to save your defaults. The next time you use QPE or QPX the drive menu will be skipped if you have the "Accept QWKRR Drives" option set to "Yes".
Once you've told QWKRR where to find the required files, it loads the required supporting files and then displays the information contained in the CONTROL.DAT file. This shows you the <bbs-id>, BBS Name and date and time of the packet amongst other items.
The date from the CONTROL.DAT and the system clock time are displayed. Using the cursor keys sets the correct time and date: the left/right cursor move you through the various fields to be selected and the up/down cursors change the value in the selected field. When this is done, press the <RETURN> key to enter the selection. Clock/date setting can also be performed with the joystick.
If you have a CMD drive equipped with an RTC (Real Time Clock), QWKRR will use this to find the current time and date.
Once you have finished the initial set-up the screen frames will be drawn and the information derived from the CONTROL.DAT file displayed in the main window and either a short menu or a Shareware reminder notice will be displayed, depending on the state of registration. If the Shareware message is present, press any key a few times to step through the messages to bring up the first menu. Once this screen has been drawn, QWKRR automatically indexes the mail packet and sets the message flags.
Global Commands
The following commands are available from most menus although they are not listed in the displayed choices:
- F1 - Taglines menu
- F3 - Twit list menu
- F5 - VIP list menu
- F7 - Macro's menu
These options are also available. Usually you need to press the C= logo or CONTROL key and the command key at the same time.
- <@>
- DOS commands
- <$>
- Displays the disk directory from the current User drive. This drive can be re-specified through the 'u' command if required.
- <O>ptions
- Takes you to the Options Menu, where configuration of colours, taglines, twit lists and much more can be done. See the section headed Options Menu. (also F2,F4,F6,F8 whilst reading messages)
Main Menu
The main menu shows the contents of the CONTROL.DAT file and has a menu displayed on the bottom of the screen.
<Q>uit <R>ead <S>election menu e<D>it reps <E>nter new msg <O>ptions
- <Q>uit
- Takes you to the Quit Menu.
- <R>ead
- Prompts for a message number at which to start reading through the mail packet. This number will generally default to the last message read, including any last read pointer stored with an index file from a previous session with the packet.
- <S>election Menu
- This menu allows you to choose to read messages from a specific conference, or to read specific types of messages, such as your personal mail, or mail from people listed in your VIP list.
- e<D>it reps
- This allows you to edit your replies before packing them for uploading.
- <E>nter
- Allows you to Enter a message other than a reply.
- <O>ptions Menu
- This brings up a full screen menu that is made up of several sub-areas. These are Colours, Printer, Misc., Files, and Formatting. This is also available from most menus (*except* the reply editor) via the F2,4,6 & 8 keys.
Reading Messages
Once you've started reading mail, the first message that matches the choices you've selected in the Selection menu (if any) will be displayed. Messages are displayed one screen full (or page) at a time. The text "<Page break>" is shown in the bottom window of the screen if the end of the message is not visible on screen. Any key except ESC, STOP, and those listed below will take you to the next `page'.
ESC or STOP These keys will abort the reading of the current message. They can be used for instance if you've read the first page and decided it is not interesting to you. Pressing either key while the <Page break> message is displayed will bring up the READ menu, pressing ESC again will move on to the next message in the direction shown as mentioned previously. STOP will have no effect.
- <SPACE>
- Moves to the next message IN THE SELECTED READING DIRECTION. This direction is displayed in the top left of the screen to the left of the message number, an Up arrow for forward and a Down arrow for backwards.
- <RETURN>
- Same as <SPACE>
- H
- (Not shown on the menu). Hides or Displays any text that matches text in the QS.HIDELIST file.
Reading Direction
- <N>ext
- This allows you to read the next higher number message that matches any conference or <S>election option used. It also establishes reading in a forward direction if it has previously been backwards.
- <P>rev
- This command will take you back to the previous message and establish the direction of reading as backwards. Once <P> has been selected you must use <N>ext to read the next higher message to re-establish the reading direction as forward.
- <A>gn
- Re-displays the current message.
- Up Arrow
- Page up. Re-read previously viewed text in a message.
- Down Arrow
- Page down.
Message Header Information
The message header area displayed at the top of the screen contains the following information, working left to right and top to bottom:
- Msg :
- The current message number. This does not relate to any message numbers used on your BBS.
- Arrow:
- Between the 'Msg' and colon there is an up or down arrow to show the current reading direction. See the section concerning <N>ext, <P>revious for more information.
- Date :
- The date the message was entered.
- Time :
- The time the message was entered. On the top right is the current time and date displayed based on the information entered by you or extracted from a CMD RTC.
- Area :
- The name of the conference the current message is from. If this appears as ">Area :" you are "locked" into this conference until you select another conference or "All" from the <S>election menu. See the <S>election menu section for more information.
- To :
- Who the current message is addressed to.
- From :
- The author of the current message.
- Flags:
- Displays the status of the current message. Details are explained in the "Message Flags" section.
- Subj :
- Subject of the current message. If you <R>eply to a message, the current subject is offered, but you can change it if you wish.
- Size:
- In the bottom right of the header window there is a number like `10/458'. This is the size of the current message in Lines/Bytes. For long messages, only the size in Kilobytes is displayed.
