========================================
GENERAL COMMENTS AND TIPS ON PCP.MEX USE
=======================================

I had a wonderful time writing this script.  I especially enjoyed 
writing and using the two features that I feel make it particularly 
unique: (1) the time routines and displays and (2) the use of free 
memory bytes to give it the ability to "remember" all relevant 
information even if the user completely exits from MexPlus.
This is, I believe, the only publicly available CP/M-compatible 
MexPlus script with either of these features.  

The amount of information displayed in the "time display box" is 
quite extraordinary and it has been a pleasure for me to look at and 
work with in the many months of development.  I hope that all the 
wonderful and abundant work being done now for CP/M-compatible 
datestamping by Bridger Mitchell, Carson Wilson, Eugene Nolan, 
Cameron Cotrill, Bruce Morgen and Hal Bower continues in the future. 
Let's hope, with the new time-supporting DOSes coming out or already 
available, that the era of CP/M programs being written without 
internal time and date support is over.  Brian Moore's recent 
release of ARK03.LBR is most hopeful in this regard.  I have very 
much enjoyed being a part of this "time wave" that is slowly making 
a 2nd revolution for CP/M-compatible computers (the first, of 
course, being ZCPR3).  I hope you enjoy using this time-supporting 
script as much as I did writing it, and will improve on what I did 
with your own ideas.

The implementation of the TIME function in your personal MEX.COM 
will have been done either through one of the native clock overlays 
from INSTALL.LIB or, for those using DateStamper as I am (my clock 
is not included in INSTALL.LIB), through assembling and overlaying 
Jim Lill's wonderful MXC-DS10.ASM.  PCP.MEX is set up very nicely to 
display and continually update the time in reverse video while you 
wait the (often interminable) time for PCP to connect to your city 
node.  It also very nicely displays one dot for each attempt (check 
out my coding for that; I'm proud of it), and constantly updates you 
on the number of attempts made so far.  The main display screen has 
many, many more uses of the time and date functions; I think you 
will find it quite attractive and informative.  I hope this script 
becomes part of a pattern for future CP/M and ZCPR3 programs of 
fully utilizing and displaying this kind of information.

A feature that I really enjoyed putting in is the ability (through a 
separate script, TIMEON.MEX) to display how many minutes you've been 
connected to a BBS.  It was meant to deal particularly with the 
following situation which continually frustrated me:  You're on a 
BBS running Tim Gary's Heavy Metal software or its Z-System 
adaptation, Z-Msg, reading messages sequentially with the RN 
command.  You've been on a long time and are thinking you might be 
approaching the hour limit, at which time you will unceremoniously 
be booted off.  Perhaps you want to download a file from the files 
section and you had better immediately exit the message section to 
do so.  If you do, however, there's no coming back; it's fairly 
disastrous to exit your sequential read because the pointer is lost 
and the knowledge of which threaded messages you've read along with 
it.  How can you find out how long have you been on?  The Z-Msg 
software has no provision for telling you this WHILE INSIDE A 
SEQUENTIAL READ.

Solution: simply ESC-E from terminal mode and run the script 
TIMEON.MEX.  You'll be pleasantly surprised.   When done, simply 
return to terminal mode.

PCP.MEX allows the user to exit MexPlus completely in order to do 
whatever you need to on your own system: write a message to be 
uploaded, check for the existence of a file, whatever.  If when you 
return you're still connected to the BBS, fine.  Just re-enter 
terminal mode.  No information will be lost.  If you've logged off a 
BBS but are still connected to Telenet/PC-Pursuit, fine again.  
Often you'll be in a situation where you want to reload PCP.MEX 
while still logged on to Telenet/PC-Pursuit, usually to log on to 
another BBS.  By default PCP.MEX will dial Telenet, so to keep it 
from doing so put a "c" (stands for "connected") parameter after the 
name of your BBS.  My old PCP.MEX used to ask you each time if 
you're connected; it no longer does.  For instance, if you've just 
logged off Ladera Z-Node and want to now call Newton Centre Z-Node, 
enter "PCP NEWTON C" from the MEX prompt or simply 'NEWTON C' from 
the O/S command line.

Of all the things I was able to automate with this script, I remain 
frustrated that I couldn't figure out how to feed information to it 
regarding whether the modem is connected to a carrier.  I pored 
through my U.S. Robotics Courier 2400 manual and could not find any 
way for the modem to test for the presence of a carrier.  Too bad.  
So, we do it with a 'C' parameter.

PCP.MEX can "sense" if the BBS you are currently dialing is in the 
same PCP node as the previously-called BBS.  If so, it will not 
disconnect from the node.

A special feature of PCP.MEX is the ability to "sense" when a PCP 
node can accept 2400 bps operation or only 1200.  See PEEKPOKE.NOT 
on this, my comments upon coding this feature.  Briefly, if a PCP 
node can only accept 1200 bps operation, the call to the local 
Telenet modem must likewise be (have been) at 1200 bps and not at 
2400.  If, however, the previously-called node accepted 2400 bps 
operation, our connection to the local Telenet modem will have been 
at this higher speed.  PCP.MEX adjusts for this difference in what 
calls to PCP technicians confirmed to me is the only proper way of 
dealing with it: by disconnecting and redialing the local Telenet 
in-dial modem at the correct speed.  I'm quite proud of this feature 
and had a lot of fun (and tearing my hair out!) coding it.

PCP.MEX is set up to know which of the PCP nodes are capable of 2400 
bps operation.  As of this writing (early September 1988) there 
are exactly ten.  As more are added you should simply add the new 
PCP codes at LABEL BEGIN.

I hope you like the "dot loop" displayed while you're dialing the 
PCP node.  I had just learned about "AND"-ing the day before, and 
had a feeling that would provide the solution.  It was a very 
exhilirating learning experience.

In my beta issuance of this script I eliminated the menu.  After 
using my menu-based April 1987 script for a while I found myself 
almost always using command-line-driven mode.  This is a natural 
development in the use of any program as one becomes more acquainted 
with it.  I was especially concerned to free up as much TPA as 
possible for the more unique features of this script: the fully 
developed time routines, its ability to "remember" information from 
previous logons, automatic sensing of the necessity for switching 
baud rates, sensing when a called BBS is in the same PCP node as the 
previous, etc.  As I added these features I yearned for the TPA 
taken up by the menu, and I bade it a hearty if not merry good-bye.

From comments from beta-testers, however, and having thought about 
it for a bit I realized that a menu is a great help for beginning 
users who are not yet familiar with the BBS names and using them as 
parameters.  But how to add it without taking up precious TPA?  Tony 
Parker came up with the brilliant idea of nesting the entire MEX 
script within a ZCPR3 MENU.COM shell!  The MENU.MNU file would 
contain and display the choices, the user would make his selection, 
and MENU.COM would generate the appropriate MEX command line and 
feed it to MEX.

It was brilliant in conception, and it worked well.  Until, that is, 
I realized that I was running into the same problem that I did when 
I experimented a year and a half ago with using the GLOBAL READ 
command with PCP.MEX.  As soon as the user would exit MEX FOR ANY 
REASON MENU.COM would reassert itself.  And of course -- this is 
what a ZCPR3 shell does.  The problem is that one often wants to 
exit MEX for many reasons while still logged on to a BBS: to write a 
message, check for disk space, search for the existence of a file on 
one's system, etc.  After doing so, a user wants to return to the 
BBS.  Under this scheme, however, these activities would no longer 
be possible.

The solution was really quite simple.  It never hit me before 
because I had always thought of the menu as being a routine WITHIN 
PCP.MEX, as an intrinsic part of the primary script.  I resolved the 
problem quite simply, with what I think is an ideal solution.  I 
wrote a short, separate MENU.MEX that does nothing but query the 
user for his/her choices, then chains to PCP.MEX.  (We assume TPA is 
freed when chaining.)  Beginning users can use the MENU, and when 
they get more comfortable with the script they can use PCP directly!

This brings up another issue for me.  At various times in the 
script's development, and hearing the suggestions of and seeing 
the scripts of others, I toyed with the idea of breaking the 
script into several smaller pieces.  It seems most scripts of this 
nature follow this pattern.  For one thing, it saves TPA.  I am 
leaving mine as it is, however.  I am used to it, I find it at least 
as easy to maintain one rather than many files, and even with the 
large number of features TPA has not been that much of a problem.  I 
would appreciate hearing from those for whom this script presents 
TPA or other difficulties.

Users of ZCPR33 and ARUNZ will find inserting the enclosed 
PCPMEX.CMD file into their ALIAS.CMD a very nice way to call a BBS 
directly from the ZCPR command line.  It uses the "multiple alias 
name" feature of ARUNZ.  To call a BBS from the ZCPR command line 
simply enter its name.  In other words, to call Lillipute Z-Node 
simply ensure that its name is in PCPMEX.CMD (or rather, the 
relevant line in your ALIAS.CMD) and a label exists for LILL.  Then 
simply enter "LILL<CR>" from the command line.

Additionally, I suggest using -- and PCPMEX.CMD makes provision for 
-- Bruce Morgen and Jay Sage's superb MEX2Z program, which allows 
"shelling" to one's own computer to execute a command and then 
automatically back to MEX.  

To save code I eliminated the error trapping that you previously got 
if, while inside MEX, you entered 'PCP BBSNAME' where BBSNAME was an 
invalid BBS name, i.e. there was no label for it.  Just make sure 
your typing is accurate!

PCP.MEX will now go into Racal-Vadic mode if the BBS is busy.  The 
R-V status reporting is better and its redialing much faster.  This 
is important in today's dog-eat-dog world.  

My coding of the R-V routine is a little buggy.  It takes a bit of 
time before it gets off the ground, but once it does it works fine.  
I'm too lazy to fix it right now.  I probably should redo it to 
not rely on the Racal-Vadic retry feature but instead do a WAIT 
STRING for "BUSY!" and display number of retries to the user.  
Let me know if you think it would be more attractive this way.  I 
just thought it would be nice to let PCP do some of the work for 
a change.  I had to use a trick to overcome the stupid R-V limit 
of 9 retries per dial.

This version is of course updated for the new PC-Pursuit node syntax 
('CASAF' instead of '415').

MexPlus has an unfortunate way of dealing with comments in the 
script: they are loaded into the TPA along with the actual code.  
This means that whenever TPA is a concern all comments must be 
stripped out.  PCP.MEX itself has NO comments in it.  I have 
included the file PCP-CMNT.MEX in the library strictly for purposes 
of seeing my commented code; unless you have a million k TPA (maybe 
this will run on MEX-PC on a DOS machine -- why not?) I wouldn't 
advise using it as a script.  However, please note that it is the 
commented code from a beta-test version and may not be completely 
up to date on some items.

Studying PCP-CMNT.MEX will be especially helpful in understanding 
how I use the various POKEs and PEEKs to store and access 
information.

My routine for dealing with the situation when you get a MANUAL 
ANSWER message from PCP (previous caller left it in R-V mode) is not 
the best.  The script just sits it out and eventually gets it OK.  
It's hard to debug because it happens so infrequently!  I think John 
Shotsky has understood better how to deal with the problem; see his 
script.

I have made liberal use in PCP.MEX of various terminal attributes 
and straight-line graphics characters.  For those whose terminal 
overlay supports them you know how extraordinarily beautiful they 
are and how much of a difference they make in your computing.  These 
kinds of things are a lot of fun to play with and I urge you to 
experiment to make beautiful and attractive displays.  Ron Fowler 
has done a superb job of providing the means to standardize these 
among terminals; he has in fact done a MUCH better job on this than 
those who put together the basic TCAP structure for ZCPR3.  Many of 
the developers of ZCPR3 seem to have an unfortunate negative and 
apathetic attitude towards beautifying our screen displays.  

In the ZCPR3 world we have actually had available for about 2 years 
a fully developed set of assembly language routines to display 
straight-line graphics windows and pop-up menus; in the 2 years they 
have been available ONE (1!) program has come out that takes 
advantage of them!  The MexPlus terminal overlays are a perfect 
example of how it _is_ possible to overcome the very severe 
limitation that we in the CP/M-compatible world have been bequeathed 
of having to deal with a large number of incompatible terminals.  
They furthermore show how much we actually do have but simply don't 
take advantage of in CP/M.

The utilitarian attitude among many in the CP/M and ZCPR3 programmer 
community is especially unfortunate because an alleged "lack of 
graphics capability" is one of the strongest reasons given by so 
many who switch to the MS-DOS world.  Ron's work with MexPlus 
terminal overlays is probably the pre-eminent example we have in the 
CP/M world of taking care to please the eye as well as the mind.

The "Elapsed time" display is not really accurate; it doesn't really 
count the minutes exactly from your first PCP attempt but rather 
updates the time each time the minute mark is passed.

One can't help but agree with John Shotsky's comments regarding, and 
wish list for MexPlus in the doc file to his excellent MEXPCP21.LBR. 
As he does, I would especially like more string variables.  I found 
trying to live with only 6 a severe limitation, though I think I did 
a pretty good job reusing some within the script!  (It's called 
ecological computering, a knack one quickly develops in 
CP/M-compatible programming...)  I especially would have liked to 
have had one more string variable to store the telephone number of 
the dialed BBS.  I originally stored this in a string variable but 
remembered that I could still use the standard way of dialing a 
number even when using PCP: with the PHONE command.  This freed up a 
string variable which I was very glad to use for other purposes.  I 
used the shortest possible string for the PHONE <name>, always 
keeping in mind to save TPA: simply the letter "n".

The only problem with this approach developed in the routine which 
redials in Racal-Vadic mode, in which I need to use the "n" above as 
a simple string, unattached to the DIAL or CALL commands.  It 
apparently can be done, in a fashion.  The command line

                           sendout "d "n

seems to send out a "d" by itself, then later the phone number 
represented by "n" PRECEDED BY THE LETTER "T".  So if the number is 
867-3847 the string 'T826-3847' gets send out.  You'll see what I 
mean first time your BBS is busy.  Why does this happen?  God only 
knows.  The PCP modem in RV mode doesn't seem to mind and the call 
gets through; I suspect it just ignores any alpha characters 
preceding the numerics.  I'm probably pressing matters using that 
'n' as a string variable anyway; [  sendout n  ] by itself doesn't 
work, nor does [  sendout "d ",n   ] (note the comma), the way you'd 
normally sendout a hard string and a variable together.  I'm just 
grateful I got away with it to the extent I did.

Anyone who's worked with it to the extent of getting their 
fingernails dirty knows that MexPlus is rather on the buggy side and 
there's nothing any of us users can do about it.  At some point 
around the 267th PCP attempt you will start getting "Argument 
errors" for no logical reason.  Why it can go 266 loops through my 
BUSYLOOP routine without an error and then start getting hot and 
bothered under the collar is a mystery beyond my understanding of 
computers.  That Ron Fowler is no longer writing for Z80 computers 
is beyond a shadow of a doubt; whether he might be persuaded to fix 
some bugs is _perhaps_ another matter.

MexPlus bugs are like human viruses: they mutate when a cure for 
them is discovered.  In my time routines I need to check for whether 
the minutes field of the current time is a single digit (less than 
10); if so I need to add a leading "0" so you get "10:03 am" rather 
than "10:3 am".  I initially did as "if %x < 10" and it seemed to 
work for a while.  Then at some point I started getting strange 
"arguments error"'s.  I couldn't figure out why.  I isolated the 
routine (as when doctors isolate a serum in order to better study 
it) and the error persisted.  Perhaps it depends on the exact value 
of %x but I am not at all persuaded it is that logical.  I actually 
think it's either entirely random or dependent on some completely 
unrelated factor.

I changed it to "if %x <= 9" and it seems to have stabilized.  
Except one time when the argument error started creeping in.  It
hasn't come back generally but I can almost guarantee that at some 
point in your operation of the script you're going to find yourself 
suddenly being told that you've been dialing PCP for

          64332Argument errorArgument errorStack underflow

minutes.  When it does, simply CTL-C and retry; it'll probably be 
OK.  MexPlus gives a new meaning to the phrase about nothing being 
certain but death and taxes.

Another anomaly: normally the dial routine will cause a call to the 
requested PCP node to be made approximately once every 4 seconds.  
Sometimes, however, I have noticed that it will be dialing fine at 
this speed and then all of a sudden slow down to one call once every 
20 seconds or so -- and then pick up again!  Thank God computers do 
strange things as these to keep life from getting boring.  I really 
don't know why it happens.  When I was initially working on the 
script, before I knew you couldn't call a 1200 bps node when your 
Telenet connection had been made at 2400, this was the behavior I 
noticed when I had done that.  I certainly _hope_ this is not 
somehow happening, but "computer science" is still an art and not 
really what it claims to be...

There are probably some commands and routines in the script that 
don't need to be there; they are vestiges of previous PCP.MEX 
lifetimes that I have been too lazy to exorcise.

Reverse video and blink both occupy a space character on my Qume 102 
terminal, so I have to put an extra 'say " "' after every use of 
these terminal attributes and an extra space character at the 
beginning of each string to be blink'ed or reverse video'ed.  If 
these are noticeable to you, hunt them down and take them out.

                               * * *

Although with this version 2.0 it is looking less and less like it, 
the initial design for PCP.MEX was George Sipe's wonderful LI.MEX 
included on the original MEXPLUS distribution disk from the immortal 
Ron Fowler, I.H.H.F.H.H.I.M.W. (I Hope He's Finding His Happiness in 
the MS-DOS World).
 
My PCP.MEX follows in the tradition of David Cornwall's PCPIMP and 
John Shotsky's superb PCP.MEX (well, what else can you call it?) 
script inside his PCPMEX21.LBR.  John has done wondrous things with 
putting extremely sophisticated things into a number of different 
overlays.  His menus are beautiful!  My script, unlike John's or 
PCPIMP, has the capability to log into BBS's with full opening id 
sequences, waiting for prompts from the BBS before sending out 
passwords, ^K's to bypass bulletins, etc.  John's point is well 
taken that since sysops frequently change their opening messages one 
oftens has to re-edit the script, but to me this is too much part of 
the fun!  It wouldn't seem right without this ability.  I often use 
John's script and am very impressed.  It is much better than mine 
for 'exploring' the air waves and seeing what's out there.  He has 
many (all?) PCP area codes built in to the script and available for 
immediate use along with a very good sampling of various BBS's 
within each area code.  It's quite enjoyable to just call around and 
see what you can find.  With my script you have to explicitly add 
labels at the bottom of the script when you want to add new BBS's.

John and I (I don't know of any others writing PCP scripts for 
MexPlus -- are there any out there?) should probably do something 
better to coordinate the releases of our respective LBR's so that 
users can distinguish the names!  John's latest release is 
PCPMEX21.LBR; I have used the string 'MX+' in "PCPMX+20.LBR" and all 
associated files instead of John's 'MEX' to aid in this 
differentiation.  (But what else but PCP.MEX can you call the actual 
script?...)

I haven't studied in detail the routine John uses to redial a 
PC-Pursuit node when it's busy, but I've noticed that it seems to go 
to disk for each retry.  Mine doesn't; the redials are done 
completely in memory.

I think my PEEKs and POKEs serve approximately the same purpose as 
John's REMEX, which clones a new version of MEX with all the same 
numeric variables, string variables, STAT settings, etc.

I very much like the way John's screen displays from the different 
overlays overlap onto each other, so that the word "Not" and the 
"[area code]" seem to come falling into place like pieces in a 
jigsaw puzzle.  It's a very nice visual effect.

How excellent that we have so many programs from which to choose.

Enjoy PCP.MEX.  I'm always tempted to write a note in my doc files: 

       PCP.MEX is NOT a "free" program.  It is put into the 
       public domain with the expectation that all users 
       will at least contact me by mail, phone or BBS and 
       let me know how they liked it and what they'd like to 
       see in the future.  Any other use is a violation of 
       U.S. law and my own labor and is strictly illegal.

but I'm told that's tacky.  That is, however, how I feel.

Write me at 1165 Shotwell, San Francisco 94110, call by voice at 
(415) 826-9448, or by modem at any of the major Z-Nodes nationwide. 
I'd very much enjoy hearing from you.

                                  Rick Charnes,
                                  San Francisco, September 5, 1988