TSCRIPT - TriBBS-specific scripts for use
with Robocomm 4.1 or later. Tested on TriBBS
version 5.0. Includes scripts TLOGON.RS,
TMAIL.RS, TFILE.RS, & TLOGOFF.RS. Can do
uploads/downloads of both QWK packets &
archive files. Documentation included.
Includes FREE program facilitating archive
file description entries into FILE_ID.DIZ
file. Michael D. O'Connor, author.

TLOGON, TMAIL, TFILE, & TLOGOFF DOCUMENTATION

===== Improved Version =====

Tscript version 1.0
Date: Jan 1, 1994

Four files, TLOGON.RS, TMAIL.RS, TFILE.RS, and TLOGOFF.RS are scripts made
for use with Robocomm. They exist because there is no prompt definition
available for interfacing Robocomm with the TriBBS software. These scripts
are specifically designed for the BBS using the TriBBS software version 5.0.
All have been tested successfully. The scripts can be used on any other
BBS using TriBBS software, but editing the scripts for use may be necessary
for them to work properly.

The TMAIL.RS script has been improved to deal with the event that there
are no QWK messages to receive. The script will correctly answer "N"
(for No) to the "Download This Packet (Y/n)?" prompt if the number of
Total Messages to download is zero. This prevents downloading an empty
QWK packet, saving you telephone costs.

NOTE: In order to use these scripts, Robocomm 4.1 or later is required.

NOTE: The scripts were tested on a BBS loaded with TriBBS version 5.0.

IMPORTANT! The scripts will work under non-expert or expert mode on the
BBS. TriBBS has three expert modes: non-expert, expert, and
super expert. Do not set the mode to super expert mode.
For best results, set to expert mode. To do this, press "X"
in the Main Menu.

=======================================================================


General Description of Script Operation
---------------------------------------

The Capture File
----------------
Upon starting the first script (TLOGON.RS), it opens a capture file so you
can examine the history of the script's progress after hanging up. The
file is created in the root directory of the C: drive. Everytime this
script is executed, the file is overwritten with a new history. If you
want to append to this file rather than overwrite it, look for the keyword
CAPTURE in the TLOGON.RS script. On the same line is the word OVERWRITE.
Replace this word with APPEND.

The name of the capture file is set to C:\%ID%.CAP. Note that the macro
%ID% identifies the BBS ID of the currently connected BBS.

Each of the scripts have a CAPTURE command and a corresponding CLOSE command
for capturing the scripts' progress in the currently connected BBS. Only
TLOGON has an OVERWRITE parameter, which overwrites the capture file from
a previous session. The rest of the scripts have an APPEND parameter, which
appends to the previously closed capture file instead of overwriting it.
The CLOSE command closes the capture file.

If the CLOSE command is deleted in one of the scripts, the capture file
will still close upon script exit, but no message is sent to the capture
file indicating that the capture file was closed. Every time the script
is opened for capture (OVERWRITE or APPEND), an opening message is sent
to the capture file indicating a capture file opened for capture.

That's why a CAPTURE command is necessary for each of the scripts. If only
TLOGON has this command and the rest of the scripts don't have it, the
capture file will show only the progress of the TLOGON script.

The TLOGOFF script is written in a way that will allow you to capture the
user-specific personal data at log-off time.


Macros Used by the Scripts
--------------------------
Macros used by the scripts are:

%BBS##% - Translated to field number ## from the Directory-BBS record
for the currently connected BBS. See Appendix "A" of
SCRIPT.DOC (provided with Robocomm 4.1) for a complete list
of the BBS## macros.

%ID% - Translated to the BBS ID of the currently connected BBS.

%QWKDIR% - Translated to the configured directory in the
Configure/Data & Logs menu in Robocomm for mail packets.

%REPDIR% - Translated to the configured directory in the
Configure/Data & Logs menu in Robocomm for outgoing replies.

%DLDIR% - Translated to the configured download directory in the
Configure/Data & Logs menu in Robocomm for file downloads.

%UPDIR% - Translated to the configured upload directory in the
Configure/Data & Logs menu in Robocomm for file uploads.

%P##% - Translated to the text parameter number ##, which was entered
by the user when he/she creates the "execute script" agenda
item in Robocomm.


Forced Hang Up
--------------
All scripts have a conditional clause in each WAITFOR command that forces
a drop carrier if the script sits idle on a BBS prompt without responding.
This happens if part of the BBS prompt string expected by the WAITFOR
command is jumbled up due to line noise. For example, a WAITFOR command
expects "Enter Selection" but your modem receives "Eter Selection" from
the BBS.

The WAITFOR command is timed according to the TIMEOUT command, which is
set differently in each script. If the time specified by TIMEOUT
(in seconds) is exceeded while waiting for an expected string, a forced
hang up occurs with a message to Robocomm's message window saying
"Forcing Hang Up."

This will let you sleep while Robocomm runs the scripts.

*NOTE* The TMAIL script has a 4-minute timeout period. While TriBBS
zips the new messages to send to you into a packet, this timeout
period is ticking away. If you have a lot of conferences
selected for QWK packet downloading, increase this value in the
TIMEOUT command.

The following section describes script operation for each script.


TLOGON.RS
---------
This script is used to log onto the TriBBS. Nothing special about this
script. Just make sure that all required parameters in the BBS directory
menu in Robocomm is entered.


TMAIL.RS
--------
This script opens the QWK TriMail door and starts downloading all mail from
your selected conferences. Before doing so, it first renumbers all your
previous QWK files from QWK to QW1, QW1 to QW2, and so on, up to 9.

The script then asks for a download of QWK messages. While TriBBS searches
the message base for new nessages, the script watches for the string
"Total Messages: 0" result after the search. If this string is caught,
no download occurs, even if other files such as Bulletins and News are
found. A message is sent to Robocomm's message window: "No QWK Messages
to Receive."

Then, after the download (or attempted download), the script checks for
the presence of a reply packet file (.REP) in the configured upload
directory specified in Configure/Data & Logs in Robocomm. If it exists,
it immediately begins uploading it. If it does not exist, a message is
displayed in Robocomm's message window saying "No Reply Packet to Send."
The script then exits from the script to the Robocomm agenda system level,
whereupon the next script in line gets executed.

Messages sent to Robocomm's message window:

"No QWK Messages to Receive"
"No Reply Packet to Send"
"Both parameters must be entered in script"


TFILE.RS
--------
This script opens the File menu and downloads and/or uploads files specified
in the input parameters. Only one filename for each process (download and
upload) can be specified.

Two error messages and three status messages sent by this script are
possible on Robocomm's message window:

"File already exists on this BBS" - upload attempt error
"File does not exist on this BBS" - download attempt error
"No file specified for download" - empty input parameter status
"No file specified for upload" - empty input parameter status
"Sending file to Sysop only" - status message

If neither upload nor download files are specified in the input parameters,
the script will just run through with no action. If only one is specified,
the script will bypass the section which handles the other input parameter.

The script includes an option to send an upload file to the Sysop only.
See the next section "How to Load the Scripts in the Agenda in Robocomm"
under "Loading TFILE.RS" for more information.

The TriBBS system will ask for a description for the upload archive file
before commencing the upload. The script bypasses this description prompt
with a carriage return. This will cause TriBBS to search inside your upload
archive for the files FILE_ID.DIZ and DESC.SDI, whereupon, if found, the
descriptions therein will be posted in the file directory. It is therefore
prudent to include a description for your upload archive in FILE_ID.DIZ
and/or DESC.SDI, and to include these files inside your archive.

A FREE program is provided to facilitate description entries for your
archive. It's called DIZGEN, zipped in an archive and included in the
TSCRIPT.ZIP archive. For more information, see the next section "How to
Load the Scripts in the Agenda in Robocomm" under "Loading TFILE.RS" and
the section "FILE_ID.DIZ and DESC.SDI" at the bottom of this file.


TLOGOFF.RS
----------
Logs off the BBS. This script is written in a way that will allow you to
capture the user-specific personal data at log-off time.



===========================================================================


How to Load the Scripts in the Agenda in Robocomm
-------------------------------------------------

You might have guessed that TLOGON.RS must be loaded first, and TLOGOFF.RS
loaded last. TMAIL.RS and TFILE.RS can both be loaded in between these
two in any order, or only one of them can be loaded. It is ideal to load
both TMAIL.RS and TFILE.RS, since you can "disable" one of the scripts to
keep it from executing during run time. You do this by highlighing the
script in the agenda and pressing the + key on the numeric keypad until
a checkmark () appears next to it; this makes the script a completed item
as far as Robocomm is concerned, and that script won't run. This way
there's no need to delete a loaded script and re-load it when you need to.

*NOTE* When this agenda is "Reset" in Robocomm, all scripts are reset
and become active.

These script files should be located in the same directory where Robocomm
is.

You can edit the scripts as you like, but don't do it until you gain an
understanding on how the scripts work. Both TMAIL and TFILE have been
carefully programmed to work together with TLOGON and especially TLOGOFF.
See the SCRIPT.DOC (included with Robocomm 4.1) for details on developing
your own scripts.

In my opinion, the script language is not all that great. There are some
serious limitations to an automatic, script-run agenda, especially if
Robocomm has no prompt definition available for a BBS software. One
such limitation which I had to deal with is that you can't use an IF
command to determine the relationship between two strings.

The next four paragraphs show how to load the scripts. Not all the scripts
are loaded the same way. TMAIL and TFILE both have input parameters which
must be entered at load time, and TFILE's input parameters must be
re-edited for files to upload and/or download everytime it is used.


Loading TLOGON.RS
-----------------
In the Robocomm agenda editor, press the xecute Script File to enter
the TLOGON.RS file. There is nothing special about this script; it's a
short one which logs onto the BBS you're calling.


Loading TMAIL.RS
----------------
Press xecute Script File again to enter the second file TMAIL.RS. (It
doesn't matter which of TMAIL or TFILE you load first.)

Included in the TMAIL.RS script, near the top, are 2 PARAMETERs, called
Script Parameters:

PARAMETER 1 "Where is TriMail Located (M or D)?"
PARAMETER 2 "What command starts TriMail?"

Pressing to enter the TMAIL.RS script in Robocomm's agenda editor will
result in these questions being prompted for your parameters.

A pop-up box will appear asking you to fill in "Parameters" for the script
run. Press to get the cursor into the entry box. Make your entry
(see below for an explanation), then press again to save it. Use
the arrow keys to move to the other unfilled parameter, press
again, and make your entry, and then press save it. Then, press
[Esc] to return to the agenda when all parameters are set up the way you
like.

The script will ask you two very important questions. First is,

"Where is TriMail located (M or D)?"

If the BBS you are logging onto uses TriMail in the _Message_ menu,
enter "M". If it's in the _Door_ menu, enter "D". In BYTELINE BBS,
TriMail is located in the Door menu, so enter "D".

Second,

"What Command starts TriMail?"

Enter either the Door number or the Hotkey that starts it from the
Message menu. In BYTELINE BBS, the Door number is "1". Enter this
value.


*NOTE* After script parameters have been entered, you may edit them
at any time by highlighting the agenda item and pressing Alt-P.

*NOTE* Make sure you have the mail transfer protocol set up correctly
for the BBS you are calling. The protocols that are called for
use by this script are the ones defined in Robocomm's BBS
directory menu for the specific BBS ID you're calling. If there
is a difference between your Robocomm setup and the BBS setup,
the script will not execute properly.


Loading TFILE.RS
----------------
Load this script by pressing xecute Script File. A pop-up box greets you
with three input parameters:

PARAMETER 1 "Filename to Download (no path):"
PARAMETER 2 "Filename to Upload (no path):"
PARAMETER 3 "Send file to Sysop only? (Y/No entry):"

Parameters 1 and 2 should contain only the filename with no path.

Parameter 1: Enter the filename you want to download. You must know
the correct name of the file for a download operation to
be successful. If it's the wrong name or the file is not
found on the currently connected BBS, the script will
handle the error, send an error message in Robocomm's
message window, and move on to the next parameter, if it
isn't empty.

If you do not wish to download a file, leave the entry
blank.

The downloaded file will be placed in the configured
download directory specified in Robocomm's Configure/Data
& Logs menu.

Parameter 2: Enter the filename you want to upload. This file must be
in the configured upload directory specified in Robocomm's
Configure/Data & Logs menu.

If the name of the archive already exists on the currently
connected BBS, the script will handle this error, send an
error message to Robocomm's message window, and move on.

If there is no file to upload, leave this entry blank.

Parameter 3: Specify whether the file to be uploaded is to be sent to
the Sysop only. If you want it to be sent to the Sysop,
enter "Y", otherwise DO NOT enter anything. Leave it
blank if sending it for public posting.

Before commencing an upload for a file, TriBBS will ask for a description
for it. There is no way to do this from a script (except through the use
of additional input parameters, but this is a cumbersome method). But
TriBBS will automatically search the upload archive file for two files:
FILE_ID.DIZ and DESC.SDI.

These files are special files that automate file description entries for
the uploaded archive file. It makes the sysop's work easier. Before
packing the archive contents and uploading it, you should seriously
consider filling these two files with a description of your archive and
including them inside your archive. For information on how to do this,
see the section below on "FILE_ID.DIZ and DESC.SDI."


*NOTE* After script parameters have been entered, you may edit them
at any time by highlighting the agenda item and pressing Alt-P.

*NOTE* Check these parameters periodically if you're going to execute
this script; make sure you're not downloading the same file
you've already downloaded. You are protected from uploading
the archive file if you've already uploaded it previously, because
TriBBS prevents uploads of identical names. The script will
handle this error.

*NOTE* Make sure you have the file transfer protocol set up correctly
for the BBS you are calling. The protocols that are called for
use by this script are the ones defined in Robocomm's BBS
directory menu for the specific BBS ID you're calling. If there
is a difference between your Robocomm setup and the BBS setup,
the script will not execute properly.


Loading TLOGOFF.RS
------------------
Load this script the same way the TLOGON.RS is loaded. This must be the
last script in the agenda.


===========================================================================


Notes:
-----

The DOWNLOAD and UPLOAD commands in the TMAIL.RS and TFILE.RS scripts
include the USING parameters specifying "ROBORZ" and "ROBOSZ", respectively.
These are batch files provided with Robocomm. I don't know if these files
are available with the shareware version of Robocomm. These batch files
contain a one-line command which executes an external protocol engine using
DSZ.COM (or DSZ.EXE). I don't think it's provided with Robocomm.

If you have any difficulty downloading or uploading using Robocomm's
internal protocol in another BBS, try using the external protocol by
adding the USING parameter on the same lines after the DOWNLOAD and
UPLOAD script commands. How to do this is shown below.

As it is now, the script will run using Robocomm's internal protocol engine.
The commands in the script are currently written as follows:

DOWNLOAD "%QWKDIR%%ID%.QWK" USING "%BBS#%"
; USING "ROBORZ"

UPLOAD "%REPDIR%%ID%.QWK" USING "%BBS#%"
; USING "ROBOSZ"

The semicolon (;) is a delimiter which makes the line a comment. To use
the external protocol engine, swap the two USING parameters for each of
DOWNLOAD and UPLOAD commands, like this:

DOWNLOAD "%QWKDIR%%ID%.QWK" USING "ROBORZ"
; USING "%BBS#%"

UPLOAD "%REPDIR%%ID%.QWK" USING "ROBOSZ"
; USING "%BBS#%"

This will result in the use of the external protocol engine in Robocomm.
In BYTELINE BBS, either method will work.


NOTE: If using an external protocol engine, it must be in the DOS path,
or in the same directory where Robocomm is.

NOTE: DSZ uses the Zmodem protocol. Make sure the protocol is set to
Zmodem in the BBS you're calling.

For more information about the use of DSZ.COM in batch files, see the
Robocomm User's Manual.


FILE_ID.DIZ and DESC.SDI
------------------------
These files are special files that automate file description entries for
the uploaded archive file. It makes the sysop's work easier. Before
packing the archive contents and uploading it, you should seriously consider
filling these two files with a description of your archive and including
them inside your archive.

This section explains how to do this.

FILE_ID.DIZ
-----------
The text area should be no more than 10 lines long by 45 characters wide.
It is strongly suggested that you include the name of the program, the
program version, and name of the author on the first line for BBSs that
post only one-line descriptions.

Included with the TSCRIPT.ZIP archive is DIZGEN10.ZIP, which includes a
FREE program to facilitate the generation of FILE_ID.DIZ. Unzip it and
read the included short DIZGEN.DOC file.

DESC.SDI
--------
The text area should be 1 line by 60 characters wide. Use any text editor
to create it.




==========================================================================
NOTE: I am not responsible for any damages resulting from the use of the
scripts. Use them at your own risk.
==========================================================================


Michael D. O'Connor, author of QwkStor, Inventrol, Accounter, and Power.