Category : OS/2 Files
Archive   : PMAC10.ZIP
Filename : PCBOARD.DOC

====================================================================
PCBOARD.CMD, Copyright 1992 Brad Berson, Psycho Psoftware
v1.10 April 28, 1992
====================================================================

Warranties...

Hahaha! Did you really think I'd do THAT? Enter at your own risk.
Being responsible for my own problems is enough, thank-you. And
please RTFM (read the, ahem, manual!).

This documentation sucks. "Oh well."

This document assumes you have at least some basic knowledge of
Multi-Net's PMcomm (1.09 or later), IBM OS/2 (1.30 or later), the
REXX/2 procedural language, the Qmail off-line mail system and
recent versions of PCBoard (R) BBS software. If it's really not
enough then write or call. And then register!

What it is!

PCBOARD.CMD is "script" file for PMcomm combining PMcomm and REXX
commands to allow automated sign-ons to bulletin boards using PCBoard
(R) software. With some minor editing, PCBOARD.CMD will also allow
automated use of Sparkware's Qmail door (v4) and perform multiple
automatic file uploads and downloads to PCBoard. PCBOARD.CMD is
designed to be universal from one PCBoard bulletin board to the next,
so there's no need to clutter your hard disk with a different file
for each PCBoard bulletin board you use.

"You have some explaining to do, young man!"

The first thing you need to do is make sure that PMcomm knows where
to find your script files. This is in the PMcomm setup under the
Options/Paths menu. Then you need to modify your dialing entries
for PCBoard BBS', inserting "PCBOARD.CMD" in the Dial Script field.
Minimally, you'll also need to know how each BBS identifies itself
when you connect to it. Read on...

What about passwords?

When you connect to a PCBoard BBS, the software returns the modem
connect strings found when you connected, then a line identifying
whose BBS you connected to, and then a line identifying the version
of the PCBoard software in use. PCBOARD.CMD examines the identifi-
cation line and then looks up your password for that BBS via the
text in that line. You must edit lines in the end of PCBOARD.CMD
to indicate a unique string of characters to look for in the
identification line, and a password to use for that BBS. There are
a few examples in the file as supplied. If PCBOARD.CMD could not
figure out what password to use, it will ask you to type one in.
Qmail configuration will not be performed for that session but any
pending file transfers will be.

To prepare for this feat...

You will need to edit ten lines near the top of PCBOARD.CMD:

* The first is your first and last names.

* The second is the directory where you keep your Qmail packets
(with the trailing backslash, or leave alone if not applicable).

* The third sets the verbosity of the contents of the activity log
file (if you have specified a file name for it), and takes values
from 1 to 4. You would normally use 1 (least) to 3 (most). Use
4 to turn on the wait-loop debugging, which writes indicators on
the screen every time PCBOARD.CMD sees the various text strings
that it's searching for. Looks messy but is very useful.

* The fourth indicates whether or not you want PCBOARD.CMD to auto-
matically disconnect you after a Qmail or file transfer session
('YES' or 'NO').

* The fifth indicates whether or not you want to delete Qmail .REP
and .QWK files after a successful Qmail session.

* The sixth line indicates whether or not you want to implement
PCBOARD.CMD's own automatic repeat mail scans for multiple mail
packet downloads when maximum packet size has been reached.

* The seventh line decides if you want PCBOARD.CMD to watch for the
text "NO CARRIER" after the script has been interrupted. There
are several limitations to this feature so use 'YES' only if you
*need* to log total connect time regardless of whether or not the
script has been halted.

* The eighth line is the full drive\path\filename of the command
file used for automatic file uploads and downloads.

* The ninth line is the full drive\path\filename of the file used
for the activity log (logfile='' to disable the activity logging).

* The tenth line resets the up/download path when the script ends.
This should be set to match the configuration in PMcomm under
Options-Paths menus.

The configuration as delivered was tailored to my directory setup,
which keeps the Deluxe2 mail reader in C:\COMM\QMAIL along with any
mail packets, and keeps uploads, downloads, list and log files in
C:\COMM\UPDOWN. It defaults to the most verbose logging level,
automatic logoff, automatic deletion of un-needed mail packets,
automatic repeat scanning turned on, and wait for "NO CARRIER" off.

You'll need to edit the "GetBbs:" code near the end of PCBOARD.CMD
as well. An example of the first few lines of text received when
you call a bulletin board running PCBoard (R) software are:
===================================================================
CARRIER 9600 PROT: ERROR-CONTROL/LAP-B CONNECT 19200
CONNECT 9600 / 05-07-92 (13:26:00)
(Error Correcting Modem Detected)
Invention Factory BBS / Connected to a Hayes 9600 V series.
PCBoard (R) v14.5a/U - Node 11 - UFE4875A3965
Do you want graphics (Enter)=no?
===================================================================
There's a message indicating the details of the modem connection,
then two lines identifying the BBS you've connected to and then the
version of PCBoard software in use. It's that identification line
that we'll rely on to figure out what password to use, and whether
or not that board will be used for Qmail4 mail transfers.

Sometimes the ID line is different on various nodes of the same
BBS, and sometimes SYSOPs change that line from time to time in
subtle or not-so-subtle ways. Choose a part of the text as a key
in ID line that you can rely on to uniquely identify the BBS and
still be impervious to minor changes. When you enter the code in
PCBOARD.CMD, be sure to use capital letters for the variables in-
side the paired single-quotes. An example:

WHEN Pos('INVENTION',line)\=0 THEN DO
pword='INVPW1' /* your password for BBS */
qmail='YES INV-FAC Z' ; END /* YES, packet name, protocol */
WHEN Pos('DARK SIDE',line)\=0 THEN DO
pword='DSPW1'
qmail='YES DARKSIDE G' ; END
WHEN Pos('WISHBONE',line)\=0 THEN
pword='WISHPW1' /* this fmt for BBS w/o Qmail */

The examples set up the Invention Factory BBS for Qmail, whose mail
packets look like "INV-FAC.QWK", using Zmodem for the mail transfer
protocol. It then sets up the Dark Side of the Moon BBS for Qmail,
whose mail packets look like 'DARKSIDE.QWK', using Ymodem-G for the
mail transfer protocol. And lastly it sets up the Wishbone BBS as
*not* having Qmail4 (and whose password is "WISHPW1").

You can ask your SYSOP what the packet name will be if you don't
already know, or find out by firing up the Qmail4 door and trying
an upload or download and seeing what name it sends/looks for.
Remember to match your protocol to the Qmail4 "P" configuration.
When adding entries to the GetBbs: section, it's easiest to just
copy existing lines (group of 3 for Qmail4 entries, group of 2 for
boards w/o Qmail4) and then edit your data into the copied lines.

Overall execution logic:

PCBOARD.CMD checks for .QWK & .REP files when it starts and behaves
accordingly. It also deletes files in a manner which suited my work
pattern. You control what the script does by what files exist.

Here is how it works:
====================================================================
File(s) exist Behaviour on Qmail configuration
====================================================================
.QWK .REP .LST Ul's .REP, dels .REP & .QWK, does xfers, logs off.
.QWK .LST Logs in, does file xfers and logs off.
.REP .LST Dl's .QWK, ul's & dels .REP, does xfers, logs off.
.LST Downloads .QWK, does xfers, logs off.
.QWK .REP Uploads .REP, deletes .REP and .QWK, logs off.
.QWK Logs in and leaves you at Main Board Command.
.REP Dl's .QWK, uploads and deletes .REP and logs off.
none Downloads .QWK, logs off.
====================================================================
File(s) exist Behaviour on no-Qmail configuration
====================================================================
.LST Logs in, does file xfers and logs off.
none Logs in and leaves you at Main Board Command.

If for example, you wanted PCBOARD.CMD to sign onto a board that has
been configured with Qmail, but only perform some unattended file
transfers and disconnect unattended, you would create UPDOWN.LST to
perform the transfers and then create a "dummy" .QWK file to
fool PCBOARD.CMD into skipping the mail download.

About file transfers...

After mail transfers have been done, the file transfer commands in
the auto upload/download file will be performed (if exists). The
file has the following format:

0 D Z C:\COMM\UPDOWN\THISFILE.ZIP
6 U G C:\COMM\UPLOADS\THATFILE.ZIP This is the upload file comment
0 D O C:\COMM\UPDOWN\DIR??.ZIP
0 D Z C:\COMM\TEMP\INCOMPLT.ZI?

Downloads file THISFILE.ZIP into directory C:\COMM\UPDOWN using
Zmodem, then uploads file THATFILE.ZIP into conference 6 from the
directory C:\COMM\UPLOADS using Ymodem-G, then downloads all files
on the BBS's main conference matching "DIR??.ZIP" using Xmodem-1K,
then attempts a Zmodem error-recovery on an incomplete download
that was left in the directory C:\COMM\TEMP.

Generally, four items/line for downloads and five items for uploads.
The first is the conference in which to perform the transfer (0 is
the Main Board), D for download or U for upload, the protocol letter
which conforms to PCBboard convention, the full drive\path\filespec
for the file to upload or download, and for uploads a file comment.
PCBoard's multi-line comments are supported automatically. The
conference-specific up/download support exists for systems which
have special or restricted areas maintained for certain files. In
typical use the conference should be 0. To speed multi-conference
transfers, you should group transfers by conference (in any order
but beginning with 0).

"Um, there's something you should know..."

The script is most easily interrupted at any time by clicking on the
PMcomm script icon (an "open book"). You can do this at any time,
although the delay between sections (login, mail, files) is a handy
time. A line will be added to the log file indicating interruption
by user, and you will not have a record of total connect time or
what time you logged off. There is alternate code to avoid this and
provide a record of total connect time but it slows down the screen
response, relies on the modem sending the text "NO CARRIER" when the
carrier is no longer found and can be fooled by that text appearing
and not having come from the modem. To use the alternate code, just
set the variable 'waitnc' from 'NO' to 'YES'. There is a one-hour
timeout for "NO CARRIER", and can be increased or decreased to suit
your needs. This also works if the script was just used to log-in
and left you at the "Main Board Command". The major restriction to
using this feature is that file transfers and certain other things
will cause an error condition in the script, which will then break
your connection in several seconds. And the script can't be aborted
before breaking connection because PMcomm thought the script was
aborted when you first clicked on the script icon!

Conferences should be specified in UPDOWN.LST by number. By name
should work but is untested. Supported protocols are modem,
Ymodem, ermit, modem-batch, Xmodem-1K, modem and
Xmodem-RC. Wildcard uploads are not supported. Wildcard file-
spec downloads are supported but may not be reliable depending on
the PCBoard software version. Auto-repeat wildcard downloads for
non-batch protocols may or may not work depending on the version of
PCBoard and the position of the planets. Zmodem error recovery may
fail ("file exists") if you resume an aborted transfer via the file
transfer list. The workaround: specify a wildcard in the filename,
which causes that error-checking to be over-ridden. For example,
instead of "0 D Z FILENAME.ZIP", try "0 D Z FILENAME.ZI?".

Detection of the BBS name may fail on connections which involve an
error-correcting modem and a non-error-correcting modem. This is
due to the characters lost during protocol negotiation attempts but
may be helped by the SYSOP of the BBS increasing the time delay or
number of 'NUL's transmitted before sending the negotiation/BBSID/
PCBoard-version message.

Qmail4 should be configured with extended prompts on, auto-repeat
downloads off, expert mode on. Qmail4's auto-repeat downloads are
not supported, however PCBOARD.CMD supports its own repeat-scanning
by the 'autorep' variable. Make sure the protocol configuration
and packet name matches the setup in the GetBbs: section.

With PMcomm 1.11, entries in your .FON file can be dialed from a
script by referring to them by name. I may revise PCBOARD.CMD to
make use of this. One side-benefit would be better resistance to
modem negotiation problems as mentioned above, and the other would
be the capability to have PCBOARD.CMD or maybe another "master"
control script loop through calling several BBS's unattended and
time-shifted to late-evening discount calling times. Stay tuned
for developments, and feel free to get in touch with me with your
ideas and viable requests.

A note on mail readers 🙂

Note that if you use DELUXE2, it extracts the packet's .PTR file and
leaves it in the directory DELUXE2 with your .REP and .QWK packets.
Use DELUXE2's "command to perform on exit" to either delete the .PTR
file or better yet, move it to a safe holding directory. This way
PCBOARD.CMD won't find it and reset your pointers every time you do
a mail transfer (this could be counter-productive!). PCBOARD.CMD
looks for and transfers .KEY and .PTR files in your mail directory.
By default, after uploading a .PTR file PCBOARD.CMD will reset your
message-read pointers to the state they were in *after* the download
of the packet the .PTR file came from.

In emergency, break glass.

In general, errors in script execution are all logged in the file
PCBOARD.LOG (or whatever name you have chosen). Inspect the file
for the error and the line at which it occurred. Major errors are
also posted on the screen in red letters. Those messages will be
more informative than the error log. I recommend using the log file
as it records errors in mail scanning and file transfers in detail,
as well as general errors. It also allows you to see what activity
costs you the most and account for your activity for business and
the like.

One of the most likely troubles to occur is that of "timeouts".
That is, where the script is waiting to see specific data coming in
from the BBS, and doesn't see it after a programmed time period.
Unusually long welcome screens at low baud rates, slow mail systems
and large numbers of conferences for Qmail4 to scan may cause such
a problem. To allow for extra time in a specific section, look for
this in the appropriate section: "CALL Read_timeout 'n000',port".
Modify 'n' is the number of seconds to wait as used in subsequent
"CALL Wait_fore..." statements.

Similar trouble is caused by the operators of the BBS deciding that
they can write better prompts for the PCBoard software than what it
comes with. While this configurability is nice, it means you can't
always depend on exactly what a given version of PCBoard will look
like. If "Main Board Command" has been changed to "Sock it to me",
the script will sit there waiting for "rd Command", and encounter
a timeout condition. If you try to edit PCBOARD.CMD to work with a
particular BBS, be careful not to "break" it for other BBS's. Or
if you are desperate, "COPY PCBOARD.CMD PCBOARD1.CMD", make all the
necessary changes to PCBOARD1.CMD and update the dialing entry to
refer to PCBOARD1.CMD instead.

I've been using this script in its various intermediate forms for
many months and done much testing of all the various functions in
as many combinations as possible, but now and then something slips
through. If you have a persisent problem that you can't fix, set
the logging level to 4, send me a capture log of the session, the
applicable section of the activity log file, and a copy of the
script (erase your passwords!) if you've made modifications. I'll
do my best to figure out the trouble.

Nitty Gritty...

Read this before you actually use the script. It may provide some
useful insight. It will also prove useful if you encounter errors
or the script chokes on something or times out.

Start: Handles language, graphics and first name prompts.

Inam: Completes log-in with name and password, and abandons any
conference auto-joined from previous connections. The
following block determines forthcoming activities. All
other activities are subroutines called from this block!

Qmail: Several blocks which handle Qmail4 dialogue, uploading
key and pointer files (if existing) and transferring .QWK
and .REP files. Also handles deleting mail files.

Quitmail: Exits Qmail4 door, supports password requests.

CheckMail: Detects mail files to determine mail block logic.

Logoff: Attempts quick-logoff. Supports logoff notices and
questionnaires and calls error routine to drop DTR and
hang-up if timed-out.

PcbXfer: Reads transfer file list, parses commands and calls
routines to join conferences and set up file transfers.

JoinConf: Joins conference. Causes transfers to be bypassed if the
join failed for any reason.

XferCmds: Handles all file upload and download dialogue. Calls
DoXfer to perform actual transfers.

DoXfer: Performs individual file transfers.

GetFnam: For use with batch downloads using non-batch protocols
such as Xmodem. Scans the scrollback buffer for the name
of the file about to be sent.

RexxErr: Error handler for unrecoverable errors in REXX code.
Terminates connection by dropping DTR line to modem.
Makes flatulent sound when called.

HostErr: Error handler for recoverable errors encountered in
script execution. Makes flatulent sound when called.
Script continues to execute.

Errh: Error handler for unrecoverable errors that are due to
unexpected conditions or timeouts in execution. Makes
irritating beeping sound and drops DTR.

ExitScr: Called when script is interrupted by Ctrl-Break or by
clicking on script icon (an "open book") on the PMcomm
status line. Control is returned to keyboard and the
modem is left on-line.

GetBbs: Routine which searches scrollback buffer to determine
name of connected BBS. Sets password, Qmail4 file xfer
protocol and packet names where applicable. Will ask you
you to type in password manually if it fails. Type in
password. Don't press - just wait 20 seconds
for script to continue.

Flush: Flushes pending data from active COM port buffer.

WriteLog: Allows simplified writing to activity log file. Stamps
the date and time and appends a CR/LF to the argument
and writes it to the logfile (if opened). Writes entry
only if variable 'loglvl' is equal to or greater than
the verbosity level argument.

ScrDeb: If log verbosity is set to 4, writes a section and index
value in brackets on the screen every time PCBOARD.CMD
finds text that it's looping for.

Delay: Performs delay in number of seconds. Makes clinking
sound with each second.

"And now for something you'll REALLY like!"

I hate to ask for money, so I'm going to DEMAND it instead! But
really, this software is delivered under the Shareware premise.
That is, if it worked and feel happy with what it does for you,
then you should register it! At least to pay for all those late-
night twinkies, if nothing else.

Seriously folks, I didn't do all this just for me. All the hit-
and-miss testing cost a few large with NYTEL and AT&T, and I've
put LOTS of hours and twinkies into making sure it's all as smooth
and reliable and full-featured as I can make it. I'd like to
think that $10 isn't too much to ask, and if you've used QMtoPM
and/or PrintDir then $15 will register all three programs. Pretty
Fair, I think. Technical support is available through CIS, the
OS/2 conference on Ilink and SmartNet and via Multi-Net BBS.

Warning!

Violation of the license agreement (as it were) is illegal and
immoral. Perpetrators will fall victim to the unbridled wrath of
the Binary Gods, and their hard disks and CPU's will degenerate
into smoldering, useless masses of aluminum and silicon.

"Your love gives me such a thrill, but it won't pay my bills..."

Brad Berson
Psycho Psoftware
#2 Chaparral Road
Chestnut Ridge, NY 10977
(212) 887-4216 voice
(212) 887-2154 FAX
CIS: 71631,132

The end.