Telnet Script Selection for the Psion 3a
========================================

Author:    Jochen Siegenthaler [100127,3167]
Date:      Sunday 27 August 1995
Version    1.10

Introduction
============
The enclosed files are a selection of telnet scripts for
use with CompuServe's TELNET service and the Psion 3a and
ReadCIS v1.5.
Of special interest is the Web script, which will telnet
you to a public World Wide Web browser that is Psion-
friendly.
These scripts have been included in their original form
to allow you to edit and customize them as necessary.
All scripts must first be translated to create a run-time
version (.sco) before they can be used.
After translation, you can copy the .sco script filess to
the directory where the other ReadCIS files are located -
this makes selecting the script from within an online
session easier. The supplied telnet scripts will look in
the ReadCIS directory first for the files, and then in
the SCO directories.
The 3user, Web and Esc scripts are ready to be used as
soon as they are translated, but the Telnet, Teloff and
Srvrdown scripts all require editing to work with your
Psion 3a and the host that you may wish to communicate
with. For this reason the scripts have been supplied in
their original (source) .scr form and you will have to
edit and translate the scripts on your Psion 3a.

New in Version 1.10
===================
Just after I uploaded version 1.00 of my script
selection, I found a way to improve the scripts and
remove much of the editing requirements. So here's the
improvements in v1.10...
*  The scripts now work correctly with "brief" prompts
   set in CIS and also with the brief prompt _not_ set
   in CIS.
*  The scripts will now automatically find the location
   of the installed ReadCIS logoff script (ReadCIS v1.5
   must be correctly installed as per ReadCIS v1.5
   instructions).
   The logoff scripts are searched for in the following
   drives / directories and in the order shown:
   M:APP\READCIS\
   A:APP\READCIS\
   B:APP\READCIS\
*  The 3user script will also automatically find the web
   and telnet scripts.
   The web and telnet scripts are searched for in the
   following drives / directories and in the order
   shown:
   M:APP\READCIS\
   A:APP\READCIS\
   B:APP\READCIS\
   M:SCO\
   A:SCO\
   B:SCO\
   This allows you to store the translated scripts in
   the \APP\READCIS\ directory where the ReadCIS v1.5
   files are stored and allows you to easily access the
   script files from within a ReadCIS / CIS session.
*  An error in some of the scripts prevented the beep
   from sounding at the end of the script.
*  The problem with a long "trailing" beep at the end of
   the script has been fixed.
*  The scripts that send GO TELNET have been changed to
   send GO CIS:TELNET.
*  This readme.txt file has been updated to reflect the
   above changes.



The 3user, Esc and Web Scripts
------------------------------
These scripts are the only scripts that you can install
and use immediately without any initial setting up.
IMPORTANT: you _must_ translate the scripts to produce
.sco files before you can run then. See "Translating
Scripts" below.
The 3user script is the link between ReadCIS and the web
and telnet scripts.
The Esc script allows you to send an escape character
(^]) as required by CIS to abort a telnet session and
return to CIS.
The Web script will connect you to a Psion-friendly World
Wide Web public browser site that supports linemode
operation (linemode is required for the Psion 3a TTY
terminal emulator).

The Telnet and Teloff Scripts
-----------------------------
These scripts must be first set up by you for the
application that you require.
These scripts are designed to log you on to an internet
host and connect you to a server on the host. I use it to
connect to my computor at work and then to transfer files
using the srvrdown script.
A prime requirement for these scripts is a valid user id
and password, ie: you must be a registered user of the
host computor.
If you are not registered on a host anywhere then the
telnet and teloff scripts will not be of any immediate
use to you.
However, they may still prove useful to you as a basis
for writing new scripts.

The Srvrdown Script
-------------------
This script allows you to enter up to five files to
transfer from a UNIX server to your Psion 3a.
You must first be connected to the server before you run
the script.
The server first zips the files to reduce their size and
then transfers them to the Psion 3a.
Note: the server must support the UNIX zip and the sz
utilities otherwise the script will fail.
Contact the system administrator of the server to get
these utilities installed if necessary.


Included Files
==============
3user.scr      to "kick-start" your own scripts after a
               ReadCIS session (ie: after retrieving
               mail and forum messages).
telnet.scr     to telnet to a host
srvrdown.scr   to download files from the server or host
esc.scr        to send a ^] (telnet escape) character
teloff.scr     to logoff from the host
web.scr        to telnet to a web site
readme.txt     this documentation file


Installation
============
1) Copy all .scr files to the \SCR\ directory on your
   default drive in the Psion 3a.
2) If you do not already have the script editor
   installed, do so now with Psion-I, select Disk C and
   File Name script.als. Press Enter to complete the
   installation.
4) Read the rest of this file to understand how to use
   the scripts and customize the telnet, teloff and
   srvrdown scripts.


Customization
=============
The 3user, web and esc scripts require no initial
customization of the script itself - they can be
installed, translated and used straight away, however
read the descriptions of the switches below to find out
what you can select before the scripts are run.
The telnet, teloff and srvrdown require initial
customization before they will work for you.
Before you customize a script, make a copy of it for safe-
keeping.
Note that all scripts have comments and notes written in
them to make understanding them a lot easier. Refer at
all times to your 3Fax or 3Link user manual for an
explanation of the script language.
I recommend that you print the scripts and then study
them on paper to familiarise yourself with the script
procedures, as this makes for much easier editing.

1) Setting Switches
All switches can be set in ReadCIS with Psion-I. The
scripts look for switches (the switches are actually 0-
byte files) in the internal drive, ie:
m:\cis\switch\alarm.on

user.on    For ReadCIS to call the 3user script, you must
           set the switch user.on.
           Use this as the main switch to enable or
           disable the web and telnet scripts (and any
           other user scripts that you may care to
           create).

web.on     If on, the user menu in 3user.scr is bypassed
           and the 3user script calls the web script
           directly.
           Use this if you wish to go directly to the
           web after connecting to CIS.
           Note: this switch overrides telnet.on

telnet.on  If on, the user menu in 3user.scr is bypassed
           and the 3user script calls the telnet script
           directly.
           Use this if you wish to go directly to the
           telnet script after connecting to CIS.
           Note: this switch is overridden by web.on

alarm.on   Used to sound a beep when exiting the telnet
           script, and at the end of the web and
           download scripts.
           This switch is also used by ReadCIS.

server.on  Used in telnet and teloff scripts. If on, the
           scripts will log on to a server after logging
           on to  host, and log off from the server
           before logging off from the host.

kansas.on  Used in the web script. Bypasses the web menu
           and goes straight to the University of Kansas
           web site in the USA.

weborg.on  Used in the web script. Bypasses the web menu
           and goes straight to the CERN web site in
           Switzerland.
           Note: Cern appear to be having problems with
           their hosts at time of writing (6 August
           1995) but I have left this option in the
           script for the future.

3) Setting prompts
As hosts and servers vary tremendously in their prompt
format, you will also need to edit the expected prompt in
the telnet, teloff and srvrdown scripts.
On my machines that I connect to I have a prompt set
where the last three characters are ">: ", and the
scripts are set to detect this.
If your prompt is different, you will need to edit every
SENDWAIT or ON REPLY  command where the sequence ">: "
occurs.
To aid you in detecting and setting the prompts for your
server/host, you should first logon manually with capture
set to on and with "Show control chars" set to yes. You
will find these settings in the Comms application. After
the logon, view the resultant capture text file and write
down the required server prompts.
Then edit the SENDWAIT and ON REPLY commands to reflect
the correct prompts.
If you have any difficulty, please contact me and I will
help you get your script up and running.

4) Setting names
ReadCIS v1.5 names are used only in the telnet script.
The names used are:

Network Login      a valid user id for the host
Network Password:  a valid password for the host
Network Address:   the internet address of the host
User Name 1:       a valid name for the server
User Name 2:       a valid user id for the server
User Name 3:       a valid password for the server

5) Translating Scripts
Translate each script from the script editor with Psion-
T. This will create a run-time version of the script,
which will have the .sco extension and be located in the
\SCO\ directory on your default drive.


Step-by-Step Web Script Installation
====================================
For those of you who have no experience in editing
scripts, here's a step-by-step set of instructions to get
your web script up and running.

1)   Copy the 3user.scr and web.scr files to the \SCO\
     directory on the internal drive.
2)   Open the 3user.scr file with the script editor - if
     the script editor is not installed, you can install
     it as follows:
     2.1) Connect 3Fax or 3Link
     2.2) Press Sytsem to go to system screen
     2.3) Press Psion-I
     2.4) Select Disk C
     2.4) Select File Script.als
     2.5) Press Enter
3)   Press Psion-T to translate the 3user.scr script
4)   Press Psion-O and select the web.scr script
5)   Press Psion-T to translate the script
6)   Press Psion-X to exit the script editor
7)   Start ReadCIS v1.5
8)   Press Psion-I and create a switch called user.on

Read the following section "Using 3user Script" before
you run your first online session.


Using 3user Script
==================
Ensure switch user.on is set and start a normal CIS
session with ReadCIS.
It is better to start ReadCIS with either "Connect and
Read Waiting Only" (Psion-W) or with Connect to
CompuServe (Psion-O). The "Remain Online" option controls
the logoff script and if selected leaves you still
connected to CompuServe after the script has finished.
After ReadCIS has performed its selected online tasks,
the 3user script is called and a menu "Choose a Script"
will be displayed.
Choose an option with the arrow keys and press <Enter>.
the appropriate script will then be called:
If World Wide Web is chosen, web.sco is called
If Telnet is chosen, telnet.sco is called
If Logoff (Disconnect) is chosen, logoff.sco is called

Note that the switch web.on will cause this menu to be
bypassed and the 3user script calls the web script
directly.
The same is true if a telnet.on switch is set.
If both web.on and telnet.on are set, then web.on has
priority and telnet.on is ignored.


Using Web Script
================
A menu "Choose a Web Site" appears and you can select the
web site to use.
Select "University of Kansas, USA" to use the Lynx
browser in the University of Kansas.
Select "Web org, Switzerland" to use the CERN browser in
Geneva. NOTE: untested due to CERN computer problems.

Note that the switch kansas.on will cause this menu to be
bypassed and the web script connects to the University of
Kansas directly.
The same is true if a weborg.on switch is set.
If both kansas.on and weborg.on are set, then kansas.on
has priority and weborg.on is ignored.

You can then use the web browser as instructed on the
screen.
After you are finished using the web browser, quit, wait
for the CIS prompt and then press Psion-E, choose Logoff
and press enter. ReadCIS will then log you off from
CompuServe.


Using Telnet Script
===================
The telnet script will connect you to a host specified in
the ReadCIS name "Network Address", using the login ID
set in "Network Login" and the password set in "Network
Password".

If a switch server.on is set, then the script will try to
connect to a server whose name is set in "User Name 1"
with a login ID set in "User Name 2" and with a password
as set in "User Name 3".

Note that this script has been written to work with UNIX
machines. It can easily be changed to work with other
systems as required.


Using Srvrdown Script
=====================
The srvrdown script will download 1 to 5 files from the
server or host (running UNIX) to your Psion 3a.
This script uses a zip tool on the host to first compress
the selected files into a "download.zip" file, and then a
sz tool to send the download.zip file to the Psion in Y-
Modem (1K) protocol.
Warning: you should make sure that no file with the name
download.zip exists on your UNIX before using this script
for the first time.
One or more filenames can be entered when prompted.
The files are stored in the Psion as "download.zip" in
the "m:\unzip\" directory, which must exist.
To unzip the files on the Psion, you will need the
unzip.img unzip utility, available in the Palmtop forum
on CompuServe.

Note that this script has been written to work with UNIX
machines, and it requires the tools "zip" and also "sz"
to be installed on the UNIX, and also unzip.img to be
installed on the Psion.


Using Teloff Script
===================
The teloff script logs you off from the server/host that
you connected to with the telnet script.

If a switch server.on is set, then the script will try to
log off from the server first before it logs off from the
host.

Note that this script has been written to work with UNIX
machines. It can easily be changed to work with other
systems as required.


Using Esc Script
================
The esc script simply sends a ^] (telnet escape)
character, required by CIS to abort any current telnet
session.
This script was written as it was difficult to generate
the ^] from the Psion keyboard.
(^] is hex character 1D).
You may wish to copy the translated version (the esc.sco
file) into the \APP\readcis directory where you have the
other ReadCIS files located so that you can run the esc
script easily at any time with Paion-E from within Comms.


Support
=======
Please contact the author for any support required:

Jochen Siegenthaler
CIS:           100127,3167
Internet:      100127.3167@compuserve.com


Acknowledgements
================
Many thanks to Dennis Lefebvre [71660,1273] for his
continual professional assistance and guidance in the
Psion script language.

