The Reader Version 1.12.0
Magnum Bulletin Board System Message Reader
(c) Copyright 1990 Frank V. Castellucci
All Rights Reserved


Introduction
------------
The Reader (TRDR) Version 1.12.0 is an off-line message reader, and
mailer, application built specifically to handle RJE message downloads
from Chuck Gilmore's Magnum Bulletin Board System (MBBS).

Chuck himself has created a character based reader (POWER) that runs
in either OS/2 or DOS (FAPI). The Reader, on the other hand, is a OS/2
Presentation Manager application thereby eliminating the possibility
of running both in character mode or DOS. If you are a regular OS/2
user then you can appreciate why I made the design decision for OS/2
PM only. If you can't comment yet, try The Reader out for a little
while and then tell me what you think!

DISCLAIMER
----------
Frank V. Castellucci makes no warranty of any kind, expressed or
implied, including, but not limited to, the implied warranties of
merchantability and fitness for a particular purpose. Frank V.
Castellucci shall not be liable for errors contained herein or for
incidental or consequential damages in connection with the furnishing,
performance, or use of The Reader product or this documentation.

Registration
------------
The Reader is a No Pressure Ware (NPW) application. By NPW I mean that
there are no screens, timers, or nagging reminders that you must
register your copy of this product with the author.

If you like the product, and you want to register your copy then send
a check for $15.00 US to:

Frank V. Castellucci
RR1 265 Overlook Way
Purdys, NY. 10578

Include you name, returns address, home and work phone number, MBBS
systems that you obtained The Reader from, and your user id for this
system.

As a registered user you will receive a printed copy of the
documentation as well as a free upgrade to the next release.


Why The Reader?
---------------
If your like me you may still find yourself dropping to character mode
and even DOS just to read messages from your favorite BBS. I use
products like TAPCIS and QMAIL all the time, and I hate having to go
to DOS to do so.

I wanted something to make message reading enjoyable, as soon as Chuck
Gilmore provided message downloading and replying capable for Magnum I
jumped on it like white on rice. I hope you enjoy it as well.

Hardware Requirements
---------------------
To use The Reader you must have:

Either a 286, 386, or 486, capable of running OS/2 1.2, 1.21, or 1.3,

A mouse.

Software Requirements
---------------------
The Reader Version 1.12.0

PKZIP for OS/2 ( This product, created by Phil Katz, can be found on
most BBS systems, insure that you use the OS/2 version). You must also
insure that the directory that the PKZIP utilities reside is in your
PATH statement in CONFIG.SYS. If it is not then put it there now.

And of course you should have access to an MBBS that supports the
uploading of POW files from an RJE job, otherwise The Reader is
useless.

As The Reader Version 1.12.0 includes origination capability, your
MBBS sysop should install the updated RJE message handling functions.
You sysop can obtain this upgrade through Gilmore Systems.


Installation
------------
As you are reading this document there is little doubt that you have
not unzipped the TRDRxxxx.ZIP file.

Move the THEREADR.EXE file to a directory which will serve as it's
main directory, or create a new one.

Create a program entry in one of your desktop groups in PM, insuring
that the Working Directory option when you create the program entry
points to the directory where you have placed THEREADR.EXE.

Again, you will want to make sure that your copy of PKZIP/PKUNZIP is
in your path statement in CONFIG.SYS, otherwise The Reader won't be
able to unzip your new mail packets from MBBS.

Wipe the sweat off your brow as the hard part is over.

Configuration
-------------
Click on the little envelope icon for The Reader from the group where
you installed it.

If you have not used The Reader before a dialog box will pop up and
ask you to enter 3 directory paths:

Main Service Directory - This is somewhat redundant as The Reader
considers wherever you have set the working directory to, in the
program entry, as his Service Directory. Whenever you start The Reader
it looks for a configuration file in the directory from which he was
started from or has set as his working directory.

SUGGESTED ENTRY: Leave it as it is.

Message Work Directory - This is where The Reader will unzip any of
the MBBS message packets. The Reader also uses this for creating
indexes when you choose a packet for reading. If the entered path does
not exist you will be prompted to create one.

SUGGESTED ENTRY: Leave it as it is.

Zip/Pow In/Out Directory - This directory is where The Reader will
look for MBBS RJE message packets in their ZIP form ( i.e.
[email protected]?.ZIP where xxxxx is your MBBS user ID ). The Reader will also
place new messages for uploading in this directory.
SUGGESTED ENTRY: Where your download directory is.
You are now configured.

Upgrading From 1.0x.0 to 1.12.0
-------------------------------
Don't worry about it, The Reader will detect and adjust the config
file for you automatically.


Lets Crack This Puppy Open!
---------------------------

When you start The Reader, the first thing it does is look for his
configuration file. This file has the name TRDRCFG.CFG, and is the
standard configuration. You can create additional configuration files
and name them what you want, but The Reader will default to loading
TRDRCFG.

The Reader then checks the Zip/Pow In/Out directory that you specified
during the configuration for any files with the following mask:

U*@?.ZI?

In English this mask will return all files that start with the letter
'U', have a '@' in the seventh filename position, and an extension
that has 'ZI' as the first two characters.

When you download a message file from MBBS it is typically in the form
( Using my Gilmore systems ID ):

[email protected]

With the file mask The Reader uses you can be sure that it will find
one if it exists. The wild card character after the letter 'U' insures
that if you call into more then one MBBS, and have a different ID,
that it will find those. The wild card character at the end of the
mask extension is for terminal emulators that automatically rename a
file if it exists and it is downloading another with the same name.
The Reader will find these too.

If The Reader finds any files in the directory you will be presented
with a list box of found files. You can choose one for Unzipping if
you want, more on this later.

If The Reader does not find any ZIP files he then looks in the Message
Working directory for message files. The masked used for this search
is: *.MSG

The file extension is based on the file packet as created by the MBBS
RJE job. This is the job that created your downloaded message packet.
The wildcard in the filename portion will search for all files with
this extension. If its in the directory The Reader will find it.

If The Reader finds any files there he will prompt you with a dialog
box to open one of the message packs for reading messages, more on
this later as well!

If, when starting The Reader you are not prompted with either the
Unzip dialog or the Message open dialog then either you have no new
mail, or old message files, OR the directory settings ( at least the
Zip/Pow In/Out ) directory may not be set up correctly.

The Reader Menu Bar
-------------------
The Reader window looks like any other normal OS/2 PM window, well...
maybe. Forgetting all the little buttons you will see in the Client
window area, lets cover the menu options first.

File Menu Options
-----------------
The file menu option is where you go to directly work with either ZIP
or MSG files, as well as Exiting The Reader and opening the About
dialog box.

Unzip MBBS Message File
-----------------------
This menu option will open a dialog box which has a list of all
available MBBS zipped message files. From this dialog box you can
Unzip a file or delete a file. For either operation you must
click on the target file and then click on the operation you want
performed. If you choose to Unzip a file The Reader creates the
following:

pkunzip -o 1:\infilepath\targetfile 2:\outfilepath

Where 1 and 2 are drive letters relevant to infilepath and
outfile path, and infile path is the Zip/Pow In/Out directory and
finally the outfilepath is the directory where The Reader will
direct the resulting MSG file.

If you choose to delete the selected file, then of course it will
disappear!

Open Message File
-----------------
This menu option is used when you want to open a message file for
your current session with The Reader. As with the above mentioned
function, a dialog box will appear from which you can choose a
file for opening or deletetion. If you select to open a message
file for reading you may notice some disk activity as The Reader
indexes the messages within the file. You will then be presented
with the first message from the first conference that The Reader
has found in the file.

Close Message File
------------------
This menu option is used to close a currently opened message
file. It will also close and response (POW) file that is open as
well.

Exit
----
Which will exit The Reader.

About
-----
Standard about box for The Reader.


Configuration Menu Options
--------------------------
The configuration menu is where you can change the working
characteristics of The Reader, or create new configuration files.

Open Configuration
------------------
Here is where you can create, and afterwards, load, or delete The
Reader configuration files. You may want to create different
configuration files for various MBBS systems that you call, for
whatever the reason the option is there.

To create a new configuration file enter a unique eight character
name in the entry box above the list of available configuration
files. Then click on the Load New button. If all goes well,
assuming you are not trying to re-create an existing file, you
will be presented with the dialog that controls the directory
information for this file. Refer to the configuration section
earlier in this document for information on directory path
option.

The newly created configuration also becomes the configuration
for the current session.

To open a configuration other then the one that is currently open
then select one of the files from the dialog list and click on
the Load button. If the selected configuration is not the current
configuration then The Reader will load it, otherwise the
operation is ignored.

To delete a configuration choose a configuration file from the
dialog list and click the Delete button. If the file you are
trying to delete is either the configuration file that is
currently loaded in the session, or the TRDRCFG.CFG file, your
request will be turned down. To delete a file that is also the
same file for the current session, first Load the TRDRCFG.CFG
file.

Edit Directories
----------------
This option displays the directory paths as when you configured
The Reader. No new info here, refer to the configuration section
earlier in this document for more information.


Edit Addresses
--------------
During installation, or re-configuration if you have upgraded,
The Reader automatically begins an address book for the
configuration. By default the address book contains:

"/0Sysop"
"/-1ALL"

These two id's cannot be deleted, but any additional id's that
you add can be. Refer to the Address Control Button for more
information on adding id's to the address book.

To delete an id from the address book, click on the address id
and then click the Delete button.

Edit Taglines
-------------
Ahhhh, something new! Taglines are those little quips you may
have noticed if you use any DOS off-line readers. Tags provide a
way to add a personal signature, quote or other such nonsense, to
the end of a reply. Using this menu option you can add and delete
tags.

To add a tag to your collection, type in the new tag line and
click on the Add Tag button.

To delete a tag from the list, click on the tag victim and then
click the Delete button.

The tag messages themselves are stored with each configuration
file. So your tags will be different depending on the
configuration you are using. You can add up to 65535 tag lines
per configuration.


That concludes the description of the menu bar options, these controls
will not be used that often as once you set up a few configurations
the only functions from the menu options you will be using will be
Unzipping, Opening, and Closing message files.

That's why I reserved talking about those little buttons on the rest
of the client window until now.


The Reader Client Window
------------------------
The Reader client window is set up to resemble a MBBS message as it is
formatted in the message file. Below is the template for The Reader
client window when you are in READ mode:

FileConfiguration
---------------------------------------------------
Subject <- ->R O A
From
To
ReferenceDate
---------------------------------------------------
||
||
|Message Box|
||
|Read only text goes here|
||
||
||
---------------------------------------------------
| Conference IdentifierConfig File|
--------------------------------------------------

Below is the client window when you are in REPLY or ORIGINATION mode:

FileConfiguration
---------------------------------------------------
Subject I T S Q A
From
To
ReferenceDate
---------------------------------------------------
||
||
|Message Box|
||
|Reply text goes here|
||
||
||
---------------------------------------------------
| Conference IdentifierConfig File|
--------------------------------------------------

We will describe each button for each mode in turn.

READ Mode
---------
When you select a message file for reading, The Reader loads the file,
creates it's indexes and displays the first message from the first
conference found.

When in READ mode you can, well, read any messages from the message
file. You also have some control over which messages to read, what
conferences to read, and in what order. You will know you are in READ
mode because the text in the message window can not be deleted, nor
can you enter anything. The color of the text in the message header is
blue.

REPLY Mode
----------
Certainly no reader is complete if it did not provide some way to
reply to a message that you feel you have something to say about.

At any rate REPLY mode allows you to respond to a message, import text
from the original message, add your own personal tag to the reply, and
store it in a POW file for uploading to MBBS. You will know you are in
REPLY mode because the header message is red and you can type away in
the message box.

ORIGINATION Mode
----------------
You can also originate messages to the BBS with The Reader. To
originate a message means that you are creating a NEW message, as
opposed to replying to an OLD message.

ORIGINATION mode allows you to create a new message to any id,
including ALL and SYSOP, in your address book. The message can be
public or private, as well as having a receipt sent to you when the id
you have sent the message to has read it. You will know you are in
ORIGINATION mode because the header message is in black, and you can
type away in the message box.


Lets cover the buttons:

Subject Button - READ Mode
--------------------------
The text next to the Subject button is what the originator of the
message created, sometimes these can be self explanatory,
sometimes not.

When in READ mode, clicking on the Subject Button will invoke a
dialog box which lists all the subjects for the current
conference. The conference you happen to be in is displayed below
the message window. From the dialog you can choose a different
subject to jump to.

If you press escape from this dialog box you are returned to the
current message, otherwise you will jump to the target subject
that you selected.

Subject Button - REPLY Mode
---------------------------
The text next to the Subject Button remains the same as in READ
mode. This will be the subject of your reply.

Subject Button - ORIGINATION Mode
---------------------------------
The text next to the Subject Button will change to reflect the
subject text that you defined when creating the new message in
the ORIGINATION dialog box.

The Subject Button itself is not used in ORIGINATION mode.

From Button - READ Mode
-----------------------
The text next to the From Button displays who the current message
is from.

When in READ mode, clicking on the From Button will invoke a
dialog box which lists the names of those who have origination
messages in the current conference. Selecting any one will jump
you to the message for that name. Escape returns you to the
current message.

From Button - REPLY Mode
------------------------
The text next to the From Button will change from the originator
of the message to your name. This is because when you upload your
response the message will be from you, what did you expect...
rubber biscuit?

The From Button itself is not used in REPLY mode.

From Button - ORIGINATION Mode
------------------------------
The text next to the From Button will reflect your ID as
associated with the current message file. This is because you are
originating a new message.

The From Button itself is not used in ORIGINATION mode.

To Button - READ Mode
---------------------
The text next to the To Button displays to whom the original
message was address, this could be you!

In READ mode, clicking on the To Button will invoke the ever
faithful navigational dialog box to allow you to jump to other
messages via the To field. Escape returns you to the current
message.

To Button - REPLY Mode
----------------------
The text next to the To Button will change from the person the
original message was addressed to, to the name of the person that
originated the message. This is because when you reply to the
message you are replying TO the person who originated the
message.

The To Button itself is not used in REPLY mode.

To Button - ORIGINATION Mode
----------------------------
The text next to the To Button will reflect the recipient of the
new message, as selected from the ORIGINATION dialog box

The To Button itself is not used in ORIGINATION mode.

Reference and Date - READ Mode
------------------------------
Both these fields display the message reference number and date
of origination respectfully.

Clicking the buttons invokes the navigational list and you can
jump to another message based on reference number or date field.

Reference and Date - REPLY Mode
-------------------------------
The text is the same as in READ mode. When a reply is uploaded to
the MBBS system the Date field is ignored altogether.

Reference and Date - ORIGINATION Mode
-------------------------------------
The text will be blanked out.

The buttons do nothing in The Reader 1.12.0. In the future it
won't matter what Chuck Gilmore does as the Date and reference
number will not be determined until the message (POW) file is
uploaded to the BBS.

Message Windows
---------------
There are two (2) message windows where the body of text will reside;
the read only original message window, and the editable
reply/origination window. Only one is visible at any given time which
is based on which mode you are in. Both windows have vertical scroll
bars that work in typical scroll bar fashion.

So much for the big buttons, lets move on to the small buttons that
are in the top right corner of the client window.

Small Buttons By Design
-----------------------
During the development of The Reader, I had some basic design
decisions to face. Do I want all the controls for navigation and so
forth in menu selections, nahhh.

The "<-" Button
---------------
Besides navigating through the messages via the dialog list box
actions described above you can walk through the messages
sequentially ( i.e. the order that the messages exist in the
message files. This button allows you to go backwards from the
current message. If you attempt to backward past ( before ) the
first message a small beep will tell you that you can not.

The "->" Button
---------------
If you can go backwards through the messages you can also go
forward, and this is the button that will allow you to do so. As
with going backwards, if you attempt to go beyond the last
message for the current conference then you will be rewarded with
a warning beep.

The "R" Button
--------------
This button signals that you want to enter REPLY mode. Actually,
this is a significant button so I will explain it right after I
tell you about the "Conference" button.

The "O" Button
--------------
This button signals that you want to enter ORIGINATION mode, and
like the "R" button is significant enough to merit it's own
explanation. Read on.

The "A" Button
--------------
This button signals The Reader that you want to save the
currently displayed FROM or TO id's in your address book. This
button is only valid in READ mode. Clicking the button will
invoke a dialog box that will allow you to choose which id, the
FROM or the TO, that you want to save. You can also save both at
one time.

In the dialog window click the From button to save the id in the
FROM field, click the To button to save the id in the TO field,
or click the SAVE ALL button to save them both. If you decide
that you do not want to save an id, or have changed your mind
after making the selection, click the Cancel button.

Clicking on the OK button will confirm your selections, if any.


The "Conference" Button
-----------------------
Moving around messages within a conference is nice, but if you
can't move from conference to conference then what good would BBS
message readers be? Clicking the "Conference" button will bring
up the navigational list for moving to different conferences.


The "R" Button Revisited
------------------------
Ok, we're back. The "R" button signals The Reader that you want
to enter REPLY mode to originate a response message to the
message currently displayed on the screen.

You will notice that a few things happen when you click this guy:

The message header text color turns to red.
The From field has your name and user id in it.
The To field has the name of the recipient.
The text message area has gone blank.
And all these little buttons have changed.
Your in!

We will now cover what the little buttons have become as well as some
reply editing features. Keep in mind that the controls for editing
text in the REPLY message do not provide full word processing
features, although they should be enough to satisfy most.


The "I" (alias <- ) Button
--------------------------
The "I" button allows you to switch back to the original message
to IMPORT data from. When you use the "I" button all the other
buttons are rendered useless. To return to REPLY mode click the
"I" button again. We will discuss importing text after the
general discussions of the rest of the buttons.

The "T" (alias -> ) Button
--------------------------
After you have completed a reply, and before you save it and exit
back to READ mode, you can tag your message with one of the
custom tags. Clicking the "T" Button will display the list of
tags for the session configuration. Pick one to insert in the
current reply or escape to cancel the operation.

The "S" (alias "R" ) Button
---------------------------
When you have completed a reply, and optionally attached a tag to
it, the "S" button will save the new message to the IDxxxxx.POW
file in the Zip/Pow In/Out directory configured for the session.


The "Q" (alias "O" ) Button
---------------------------
If you want to abort the current reply and return to READ mode
without saving, the "Q" button is what you want to use. The
Reader will prompt for confirmation on the reply cancel.

Introducing "O" For ORIGINATION
-------------------------------
By clicking the "O" button while in READ mode, you are signalling
that you want to enter a NEW message for delivery. When you do
so, the following changes occur:

The buttons change from the READ mode settings, to the REPLY mode
settings.

The Message header, and configuration file text, turn to black
characters on a white background.

The ORIGINATION dialog window is invoked.

The ORIGINATION dialog window is where you enter the subject of
your new message, who the message is addressed to, and whether
the message should be private or the BBS should sent you a
receipt when the message is read.

The subject field can contain up to 60 characters of descriptive
text for your new message.

The TO combination box will allow you to choose a user id from
your address book, address to message to ALL, or just send it to
the SYSOP of the BBS.

The Conference combination box will display all the conferences
of the BBS that are available to leave a message in based on the
conferences that you scanned during your RJE download.

The Private check box can be used if you want your message to be
privately read by the user in the To field. Private is not
allowed for messages to ALL.

The Receipt Requested check box can be used if you want a receipt
when the new message is read. As with the Private check box,
receipts are not allowed in messages to ALL.

Once you have completed the information in the dialog window, you
can begin your new message. The following buttons are the only
functional buttons while in ORIGINATION mode:

The "T" Button:
---------------
Allows you to tag your new message.

The "S" Button:
---------------
Will save the new message to the POW file for uploading.

The "Q" Button:
---------------
Will abort the current new message, but not before asking you if
it is ok!

All other button functions are being placed into reserve at this
point. I hope to provide grouping id's from the address book,
archiving of messages, message printing, re-edits of replies and new
messages, and a few other nifty tricks. Stay tuned, better yet,
register your copy and send me a suggestions list.

Well that covers the schizophrenic nature of the little buttons.


There was no easy way to alleviate you from the task of entering text
for a reply, so we have to talk about the text editing features.

Editing Replies
---------------
Unless you have text you have staged for importing into the reply
message screen, you can start typing away. I won't go into details
about how to type.

Needless to say, all the cursor movement keys, Home, Page Up, Page
Down, End, Insert, Delete, etc., that you should be familiar with, as
an OS/2 PM user, are available and act exactly as expected. The only
difference, or additional knowledge you need, for The Reader is the
following.

Character Per Line Limit
------------------------
MBBS limits text lines to no longer then 72 characters.
Therefore; word wrapping is automatically set to ON, and can not
be changed. The Reader will word wrap, inserting a hard carriage
return/line feed combo when you reach the character limit per
line.

Importing Text - PRE STAGED
---------------------------
One way to import text into a message, is to retrieve it before
even entering the message mode. This is done by highlighting the
text you want to import and pressing the CNTL+INSERT keys
simultaneously. When you do this you are placing the selected
text into the PM clipboard. You can then enter the appropriate
message mode. To import the text at this point, make sure that
the cursor is blinking in the message window and press
CNTL+INSERT again. Voila, the text will be inserted into the
message box.

Importing Text - IMPORT MODE
----------------------------
If you are already in REPLY mode and you realize that you want to
go back to the original message and grab some more of it's text
then the "I" button is for you.

Click the "I" button and the message box will fill with the
original message. Select the text you want to import, press
CNTL+INSERT, click the "I" button again, position the edit cursor
where you want the imported text to go and press CNTL+INSERT
again. Zing! In comes the target text.

Additional Notes
----------------
If you enter reply mode and then attempt a save without entering a
message The Reader give you a warning and ignore the Save command and
consider it an aborted message.


Release Information
------------------
The version numbering scheme for The Reader: X.YY.Z where:

X=Major release version.
Big changes that typically or not considered
minor. For example 1.yy.x to 2.00.0

YY=Minor release version.
Uplevel maintenance release, based upon
number and severity of fix requirements.
For example 1.00.0 to 1.10.0.

Z=Maintenance release version. These are mostly
used internally for development, or documentation
changes, but on occasion ( for those quick
fixes ) they may surface. Example 1.06.2 1.06.8.



The Reader 1.12.0 Released March 24, 1991
--------------------------------------------
1. Corrected problem with reading file streams in text
mode, switched open attributes to binary and added the
changes to support the mode.


The Reader 1.10.8 Released January 17, 1991
--------------------------------------------

1. Added internal support for MBBS 3.xx Message formats

2. Another pass at the control button overwrite. I am
developing on quite a high resolution monitor so I may
be missing the problems. Of course it always works fine
for me!


The Reader 1.10.1 Released December 18, 1990
--------------------------------------------

1.Corrected invalid ID abend in reading, replying, and
address book.


The Reader 1.10.0 Released December 13, 1990
--------------------------------------------

1.Added Origination Mode Functions.

2.Added Address Book, and supporting control.

3.Added Private and Receipt flags for original
messages.

4.Enhanced dialog window controls and capability.

5.Extended The Reader to support MBBS 2.0 Message
formats. Previously I would die on the vine trying to
read them.

6.I HOPE the control button overwrite has been taken
care of, I am sure I will hear about it if it isn't.
Mine works okay (grin).

7.Some documentation clean up, although everyone should
know I HATE DOCUMENTATION. Guess I'll put in on-line
help in a future public version.

The Reader 1.02.0 Released December 4, 1990
-------------------------------------------

1.Corrected control button overwrite. The parameters
in the bounding rectangle for refreshing the subject
field were set to high.

2.Increased word wrapping limit in REPLY mode. When
importing text lines that exceeded bounding wrap length
the word break would add additional lines.

3.Dialog message if attempting to exit The Reader or
load another message base while in REPLY mode.
Previously the system would drop you like a hot rock.

4.Corrected subject field processing if MBBS has
dynamically added the (R)ead by id in to field. The
Reader will remove this if found during the Reply Save
processing.

The Reader 1.00.0 Released December 2, 1990
-------------------------------------------
Original release version


ACKNOWLEDGMENT
----------------

To Chuck Gilmore for providing both a wonderful Bulletin Board System
as MBBS, and for providing me with useful information during the
development of The Reader.

To Alan Duboff, who I know will one day release his Qmail PM reader
and allow me to ignore those nagging voices in my head saying "Go
ahead, develop it". Gung hai fa choi Alan ( excuse the spelling).

To Mark Ryland, for his 1001 suggestions. Hey Mark, did you write that
cartoon about all those spotted dogs?

To Bunny, Lizard, and Lumpy, for general reasons.

Frank V. Castellucci (914) 277-4312
December 1990.

The Reader (c) 1990 Frank V. Castellucci