OS/2 Shareware BBS: 3 Comm/03-Comm.zip/PMAC10.ZIP/PCBOARD.DOC

Text File | 1992-05-07 | 24KB | 443 lines

     ====================================================================
           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" <BBSNAM>.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 <Z>modem,
     Ymodem<G>, <K>ermit, <Y>modem-batch, Xmodem-1K<O>, <X>modem and
     Xmodem-<C>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 <Return> - 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
     [phone] voice
     [phone] FAX
     CIS: 71631,132

     The end.