Shareware 1 2 the Maxx/sw_1.zip/sw_1/COMM/SCR104A.ZIP/GENERATE.DOC

Text File | 1992-01-11 | 23KB | 541 lines

(C) Gale Green, Databeat Limited, Aylesbury, Bucks, HP21 8QP.

N.B. The program GENERATE.EXE plus its associated files and
documentation may be distributed only as part of the Scripta
package.

GENERATE.EXE MAY NOT BE DISTRIBUTED ON ITS OWN.


The Scripta GENERATE Program
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Overview
~~~~~~~~

GENERATE combines a set of parameter files with information
supplied by yourself to produce a Scripta script (.CMD) file.

This initial release contains four generators -

       WC2TC2 - for BBSs running Wildcat plus Tomcat at version 2
       WC3TC3 - for BBSs running Wildcat plus Tomcat at version 3
       PCBQM4 - for BBSs running PCBoard plus Qmail at version 4
       RARAM3 - for BBSs running RemoteAccess plus RAMail at version 3

I know of far more Wildcat 3 boards than any other type with the
result that WC3TC3 has received much wider exposure than the other
two.

RARAM3 is very new and has only been used on one board. By the next
release of Scripta, it will be suitable for any RemoteAccess board
running RAMail 3 but for the time being scripts may need a little
tweaking. The instructions given below were written before the
RARAM3 generator was ready so, just for this release, follow the
instructions given for PCBoard/Qmail scripts. It will quickly become
obvious which bits don't apply to RAMail, when you come to generate
the script.

Although it cannot be guaranteed that *every* script will work for
*every* board, you should find that the scripts need only very minor
tweaking in order to work on any BBS of the given type. *Most* scripts
should work unchanged on *most* boards of any type.

I personally use Scripta-generated scripts, unchanged, on
18 WC3TC3 boards, 2 WC2TC2 boards, 2 PCBQM4 boards and 1 RARAM3
board.

I will be exceedingly grateful for ALL feedback on the script
generators - I want to make them absolutely fool-proof as
quickly as possible.

If you have problems which you cannot resolve, perhaps because
you're not the programming type, then please message me via any
of the nets and BBSs listed in the Scripta documentation. I will
be more than pleased to *make* the generators work for you.

Very soon, these generators will be made to work for *any* WCTC,
RARAM or PCBQM board and other board/door combinations will be
added as I find the time to do the work.

If you do have to tweak a script to make it work, please let me
know what you had to do - I can then automate that step for a
future release.

The scripts, as generated, will automatically log on, upload and
download both files and messages, and then log off. If you wish
to spend more time online, perhaps browsing bulletins or
whatever, then you can quit a script at any time while it is
running by pressing the Esc key. The remainder of the online
session is then conducted manually with yourself in full control.

To generate your first script, please follow carefully the steps
outlined below. After that, you will find that script generation
is very straightforward and you will probably never need to refer
to these instructions again.

How GENERATE works
~~~~~~~~~~~~~~~~~~
If a bulletin board has telephone number 123-456-789 then a
script used to access this board will contain somewhere within it
the command

                 DIAL "123-456-789"

Obviously, such a script may be used only to call that particular
board because the telephone number is unique.

GENERATE uses Template scripts which contain commands like the
following

                 DIAL "@numberA"

and then, on demand, it generates 'real' scripts in which the
@numberA syntax in the Template is replaced by a real telephone
number.

The telephone number is used here as an example but there are
several items of information which are treated in exactly the
same manner: Username, Password, mail packet name, and so on.
Anything, in fact, which is likely to be unique to a single
BBS.

This initial release of GENERATE contains three template scripts
named WC2TC2.TEM, WC3TC3.TEM and PCBQM4.TEM.

The first of these may be used to generate scripts for boards
which run Wildcat! plus Tomcat! at version 2; the second may
be used for boards which run Wildcat! plus Tomcat! at version 3;
the third may be used for boards running PCBoard plus Qmail at
version 4.

Associated with each .TEM (template) file is a .PAR (parameter)
file. This contains a list of all the @keywords which may be used
in the .TEM file.

In order to generate a script, the GENERATE program needs a
further file, a .CFG (Configuration) file, which contains the
list of real values which are to be used to replace the @keywords
in the template.

Given such a file, named e.g., MYBBS.CFG, the GENERATE program
will produce MYBBS.CMD, a fully-working Scripta script file.

As examples, the GENERATE package includes .CFG files to enable
the generation of the script files listed in the Scripta sample
Dialling Directory. If you look at these examples, and generate
one or two scripts, you'll see that the process is really very
straightforward.

You may automate the entire process of BBS script generation by
invoking the supplied Scripta script named MAKE. This in turn
will invoke one of the sub-scripts: MAKETC2.CM0, MAKETC3.CM0 or
MAKEQM4.CM0.

These scripts will prompt you for the information they require,
create a .CFG file, and then call GENERATE to create a .CMD file.

To run the 'MAKE' script, first run Scripta, then press Alt/S.
This will display the Script Selection Menu. Highlight the
name of the MAKE script then press the Return key.

You will first be asked for the QWK packet name used on the
BBS for which you want to generate a script. This name is used
to form the name of the script file so GENERATE can check
straight away to see if you already have a script for this
BBS.

If a script already exists, you will next be allowed to edit the
associated .CFG file, preparatory to optionally generating a new
script. Otherwise, you will be asked whether the BBS is of Qmail,
Tomcat or Tomcat v2 type. Press Q, T or 2. MAKE will then call the
appropriate sub-script to create a new .CFG file.

The sub-script will first ask you for all the information it needs,
then generate a new .CFG file and finally generate the .CMD file
by calling the GENERATE program.

In order to generate a script for any given BBS, unless you
already know the relevant details, you will first need to call
the BBS manually. This is because one of the vital pieces of
information needed to generate the script is the name used by
the BBS for its mail (.QWK) packets and you can only find this
out by logging on and downloading a packet. Mail packet names
always have an extension of .QWK so typical names are
MYBOARD.QWK, SOMEBBS.QWK, and so on.

GENERATE needs to know the first part of this name, e.g.,
MYBOARD, SOMEBBS, etc., in order to generate a script. This name
is also used to form the names of the .CFG and .CMD files.

Note that, to generate a script from one of the supplied .CFG
files, say THENET.CFG, run the MAKE script as described above
and, when asked for the 'packet name used by the BBS', just enter
the .CFG file name, e.g., THENET.

Thereafter, the fields which you need to fill in will be marked
with six asterisks - ******.

*******************************************************************
It is highly recommended that you print out this document for
reference before proceeding with the steps outlined below.

Once you have generated your first few scripts, you will find
it a very straightforward process. Until then, it will be best
to follow these instructions to the letter. This will avoid
making silly errors which will put you off script generation
for life.
*******************************************************************

So, for instance, suppose that you want to generate a script to
automate access to a Bulletin Board named The Dogs' Home.

You already have its telephone number so arm yourself with pen
and paper, write down the telephone number for later use and then
dial the board and log on. To dial the number, run Scripta and
then press Alt/D. This will take you to the dialling directory
where you can either set up a new entry or just press N to enter
and dial the number manually.

The next thing to note on your piece of paper is whether or not
you have to pass through a 'gateway' or 'drawbridge' in order to
reach the BBS. If after connection you are told to "press Esc
twice to enter The Dogs' Home", or something similar, then this
is a gateway.

Before pressing any keys, make a note of some unique and
recognisable string of characters in the gateway prompt and also
write down the response it has asked you to type. In the present
example, you might write down

          Home      EscEsc

'Home' is a recognisable part of the prompt and 'EscEsc' is what
you have been asked to type.

In fact, you should write ^[^[ rather than EscEsc because Scripta
uses the character pair ^[ to represent the Esc key. Literally,
^[ represents the action of holding down the Ctrl key and
simultaneously pressing the [ key.

Try it now. You've been asked to 'press Esc twice'. Instead, hold
down the Ctrl key and press the [ key twice. It will be just as
though you had pressed Esc twice.

The 'recognisable string' that you choose should contain characters
which are all displayed in the same colour. For instance, in the
present example, we have chosen the string 'Home'. If the 'H'
were displayed in red and the 'ome' in yellow then 'Home' would not
do - some other string would have to be chosen, perhaps 'ome'.

The reason for this is that colours are changed using ANSI Escape
Sequences which, while invisible, are still there and would
confound any attempt at matching a string.

As you log into the BBS, the opening screens should tell you the
type and version of the BBS. e.g., PCBoard, Wildcat! 3.00, and
so on.

Remember that you can only use GENERATE for Wildcat and PCBoard
BBSs. For other BBS types, you will have to use the

                  SCRIPTA //<script_name>

option to generate simple scripts until you learn to write your
own scripts or I release a .TEM file for that type.

Something to remember for later, when you're more used to BBSs,
is that you will find scripts much more reliable and efficient,
on any BBS, if you select the 'Expert' mode online. For PCBoard,
just press X and then a Carriage Return, at the Main Menu. On
Wildcat boards, press H (for Help level) at the Main Menu and
then press E for Expert mode.

When you have entered the bulletin board proper and logged in, the
board will display its Main Menu. This is simply a menu from which
you can select items which cause you to leap into other parts of
the Bulletin Board. The part we are interested in is the mail
door - we need to find out the name that the board uses for its
mail packets.

If this is your first call to a Wildcat board then during the
login sequence you will be asked whether you want to use Hot
keys. Answer Yes. If you don't, then any scripts that you
generate will not work.

If you are calling a PCBoard BBS, you will also be asked
whether you require ANSI graphics. On your piece of paper,
write down Y if you have a colour monitor or N otherwise.
Then press the key you have written down followed by a
Carriage Return.

Whilst still at the Main Menu, and before you press any keys,
and if this is a Wildcat! version 2.nn BBS, note down the last
few characters at the foot of the menu. They will be some kind
of prompt like > or >> or : or maybe a word like Next? or,
depending on the help level you have set, you may not see a proper
menu, you may just see a line saying something like 'MAIN MENU:'.
Whatever you see, note down the final few characters (say, two to
ten characters). Later, when you create your script and then run
it, Scripta will use these characters to recognise menus during
automatic BBS runs.

Again, only if this is a Wildcat version 2.nn BBS, press F.
This will take you to the Files Menu where once again you
should note down the prompt at the foot of the menu. Then,
press Q to return to the Main Menu.

Next, on Wildcat boards of any version, press M. This will
take you to the Messages Menu. If it is a Wildcat! version 2.nn
BBS, note down the prompt at the foot of the menu, just as you
did at the Main and Files Menus.

Then, read the menu, note down the key that you have to press
to enter the Tomcat! mail door, usually T for Tomcat or O for
Offline mail, and then press that key.

On PCBoard boards, first of all note down something recognisable
from the last line of the Main Menu, as described for Wildcat
2.nn boards, and then scan the main menu for a reference to 'mail
door', 'Qmail door', 'offline mail' or something similar. Note
down what you have to type to enter the door, and then type it.
It will probably be a command like QMAIL or MAIL, or an
instruction to open a door, like OPEN 7. If you can't see
anything helpful, just type OPEN and press Return. You will be
shown a list of door numbers. Note down the word OPEN followed
by the number of the Qmail door, as shown on-screen. Then,
type in the door number and press Return.

Once you have reached the mail door, either Tomcat or Qmail,
press C for Configure. If it is a Qmail door, you'll also have to
press Return after the C.

At the Configuration Menu, select all the conferences that you
wish to be included in your mail packets and reset the pointers
in those conferences to a fairly high number so that you don't
download hundreds of messages on this, your first, download.

It is worth spending a bit of time at the Configuration Menu.
Accessing the board in future, using GENERATE scripts, will be
very fast and very cheap so it's worth the time now to make sure
that the door is set up the way you want it.

If there are Configuration items that you don't understand LEAVE
THEM ALONE! Do not fiddle with things unnecessarily, you can
always come back at a later date if things aren't quite right.

In Qmail doors, do not set any options which involve logging off.
For example, there is an option to log off after uploads. If you
set this option, your scripts will not work properly. Once set
up, your scripts will handle all logging on and logging off.

In Qmail doors, you should set the default protocol to Zmodem. In
Tomcat doors, set the Transfer Protocol either to Zmodem or to
'Select each time'.

When you have finished at the Configuration Menu, press Q to
Quit. Again, in Qmail doors, you will have to press Q followed by
the Return key.

You will now return to the proper mail door menu where you should
press D for Download. (D<return> in Qmail doors).

The mail door will now assemble your mail packet in a file called
something.QWK and initiate a download so that you can transfer
the packet from the BBS into your own computer.

When the mail door is ready to download, it will display a
message something like the following:

Prepare to download something.QWK

First, make a note of the 'something'. Continuing the earlier
example, a mail packet from The Dogs' Home BBS will probably be
called DOGS.QWK, or HOME.QWK or DOGSHOME.QWK

Next, if you have Auto Zmodem set in Scripta configuration, the
mail packet will be downloaded automatically. Otherwise, do it
manually by pressing the PgDn key, followed by Z for Zmodem and
then a Carriage Return.

               PgDn Z <return>

When the download has finished, press G for Goodbye (G followed
by a Carriage Return if this is a Qmail door).

Your piece of paper now contains all the information you need to
generate a script to access The Dogs' Home BBS.

Still within Scripta, press Alt/S. This will display the script
selection menu. Highlight the name 'MAKE' and press Return.

You will then be asked which generator to use - press 'Q' for
Qmail, 'T' for Tomcat! version 3 or '2' for Tomcat! version 2.

A further screen will be displayed in which you can enter the
information from your piece of paper (plus some more odds and
ends like your username and password on the BBS for which the
script is being generated). When you have finished entering the
information, the script will be generated.

If you have several pieces of paper, from several BBSs of the
same type, then you can generate all your scripts at this screen,
one after the other. When you have finished, press Esc or Return
on a blank field to exit back to Scripta.

If you now press Alt/S again, you will see that DOGSHOME, or
whatever the .QWK packet name was, has miraculously appeared in
your script selection menu from where you can run it as often as
you wish.

Once a script has been generated in this manner, it may be run in
several ways. You can press Alt/S at the Scripta Command Mode
Screen, to call up the Script Selection screen, as above. You can
also enter the following at the DOS prompt:

                SCRIPTA <script_name>

Or finally, you can set up an entry in the Scripta Dialling
Directory. Just press Alt/D within Scripta to call up the
Dialling Directory and then press Ins to Insert a new entry.

Summary of Script Generation Process
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This has been quite a lengthy description of what is really a
very straightforward process. In summary, to generate a script,
do the following:

  1. Write down the phone number(s) of the BBS.

  2. Log onto the BBS and find out if there is a gateway. If
     there is, note the prompt and the required response.

  3. Still online, go to the mail door, configure it, ask for a
     download and note the .QWK packet name.

     If it is a Wildcat! version 2 BBS, remember on your way
     to the mail door to note the prompts at the Main Menu and
     Messages Menu.

     Whatever kind of BBS it is, note down what you have to type
     to enter the mail door (from the Messages Menu on Wildcat!
     boards or from the Main Menu on PCBoard boards).

  4. In Scripta, press Alt/S, highlight 'MAKE' and press Return.

  5. Enter the information from your piece of paper and generate
     the script.

If you want to generate one of the example scripts included with
the package then miss out steps 1 to 3 above. Just run the 'MAKE'
script and, when it asks for the BBS mail packet name, just tell
it the name of the .CFG file from which you want a script to be
generated.

Then, keep pressing Return until you are asked whether to continue
with script generation. Then, press Y.

What the generated scripts do
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
A generated script called say SOMEBBS.CMD, when executed by Scripta,
performs the following actions:

  1. Dial the BBS, log on, and go to the Main Menu.

  2. Check for the existence (in your Scripta directory) of files
     named SOMEBBS.FUL or SOMEBBS.FDL.

     If SOMEBBS.FUL exists, upload all the files whose DOS pathnames
     are listed within it. Each such pathname may contain * or ? DOS
     wildcard characters.

     If SOMEBBS.FDL exists, download to the Scripta default download
     directory all the files whose simple names are listed within it.

  3. Enter the online mail door.

  4. If SOMEBBS.PTR exists in your default Scripta upload directory,
     then upload it to the mail door.

  5. If SOMEBBS.REP (a mail reply file) exists in your default
     Scripta upload directory then upload it to the mail door.

  6. Download SOMEBBS.QWK (a mail packet) to your Scripta default
     download directory.

  7. Log off.

If you are a Power-QWK user then SOMEBBS.FDL is created automatically
when you pick filenames off the new files listing by pressing D for
Download or out of a message by pressing Ctrl/F for Filename.

Debugging scripts
~~~~~~~~~~~~~~~~~
If you run a script which then 'hangs' when online then this usually
means one of two things: either the script has been set up to expect
a string from the remote which has not been received, or, the expected
string has been received too early, usually because the Sysop has
included a vital string in some piece of text like a welcome screen.

When a script 'hangs', press F3. This will cause Scripta to show you
what strings it is currently waiting for. By comparing these with
what has actually been received (this will still be on-screen),
you will be able to deduce what the script *should* be waiting for
and be able to edit the script accordingly.

Remember, the scripts are not guaranteed to work unchanged on all
BBSs. They will work unchanged on *many* BBSs and will require
minor change in order to work on other BBSs.

F3 is the most useful key at your disposal in the debugging of new
scripts.

If you need to look back over the current session, press Alt/v.
Unless you are running a script from within Power-QWK, this will
display the review buffer, containing all that has been sent to
or received from the remote system during the current session.

If you want to record a session in a disc file so that you can
peruse it later, press Alt/L to switch logging ON, before you
run the script.

Note
~~~~
In the script generator screens, there are spaces to enter up to
four telephone numbers. There must be NO GAPS in the spaces
used. In other words, you can enter items 1, 2 and 3 but NOT
items 1, 3 and 4 (leaving item 2 blank).

To blank out a telephone number, just set the first character
to * (asterisk).

And finally...
~~~~~~~~~~~
I hope you like this program. It has been designed to make life
as easy as possible for the BBS newcomer and expert alike.

The script generator will become more and more robust as time
passes and more and more people use it to access different BBSs.

If you find that a generated script won't work on a particular
board, PLEASE let me know so that I can make the necessary
changes to ensure that it works in future releases.

In the fulness of time, I will be producing more templates for
other BBS/mail door combinations. If YOU produce a template for a
particular combination then by all means send it in for inclusion
in the GENERATE package. I will acknowledge you in the
documentation and you will get warm glows from knowing that you
have helped someone else to enjoy their BBSing a little bit more.

If you're an experienced telecommunicator, remember how
frustrating were your own early days and how expensive it can be
getting to know a BB system like PCBoard. Any way that newcomers
can be helped will ensure that our hobby expands and thereby
becomes more interesting for us all.

If you have any comments on the product, or requests for
additional facilities then, again, please let me know. If you
don't ask, you don't get!

Gale Green (author).