README.SCR  6/21/90 - Detailed Instructions for Using Script Files with
	CUTCP/CUTE 2.2D,2.2TN/TC-C

Bugs to 	cutcp-bugs@omnigate.clarkson.edu


What are script files?

	Script files, or command files, instruct CUTE to connect to
	hosts, wait for data, write to the screen, message console
	or remote host, press keys and so on.

	Script files are very simple, limited in parsing and have
	special restrictions.

	sample.scr and sample2.scr are good examples of script files.

How do I activate a Script file?

	There are several ways of starting a script file.

	1. Using ALT-A, ALT-Z or ALT-V and specifying a destination
	   host of
	
			@scriptfile_name

	  where scriptfile_name is the name of the script command file.

	  Script command files have an extension of .scr, and CUTE will
	  add the .scr for you if you do not include one.

	2. Specifying  @scriptfile_name on the command line when starting
	   CUTE:
			tn3270 @vmhost

	3. Open a standard telnet/rshell/rlogin session and attaching
	   a script file using the ALT-MINUS key.

	4. Use the @ symbol for host name in your config.tel file.

		name=special
		host="@C:\myscripts\special.scr"

	  Note. this only attaches the script file to the name, it will
	  NOT activate the script file after connecting to some specified
	  IP address. Rather, your script file should contain an initial
	  telnet/rlogin/rshell command.

How are Script File Names Resolved?

	When you specify a script file name, an attempt is made to
	open a file by that name. If the open fails, the filename
	and extension (sans drive and any paths specified) are stripped
	off and attached to the 'Script Directory Name', in an attempt
	to look in the Script Directory for a script of the specified
	name. This is useful for having a single directory with all your
	script files in it.

How do you specify the Script Directory Name? (optional)

	In your config.tel file, create a host as follows:

		name=script_dir
		host="C:\scripts\"

	Set the host= parameter to the location of your script directory.
	YOU MUST INCLUDE THE TRAILING BACKSLASH.

How do Script Files Operate?

	Script files are processed a line at a time by a simple token
	processor that accepts one or more arguements. Processing halts
	if the incorrect number of arguements are specified.
	For example, the 'write' command accepts a single arguement,
	which is the string to write. If the string contains white
	space characters, than it must be enclosed in quotation marks.

	The input processor expands backslash (\) escapes within
	quoted strings only.  The standard set of escapes are supported.

		\r	- Return (dec 13)
		\n	- Line Feed (dec 10)
		\e	- escape (dec 27)
		\nnn	- Octal three digit number
		\\	- the \ character
		\; 	- the semicolon.

	The semicolon is used as a comment delimiter. Any text after a
	semicolon is ignored, unless it is within a quoted string, or
	proceeded by a backslash.

	When a script file is opened, it is scanned completely to check
	for errors. Only the commands used and the number of arguements
	are verified during the first pass. 

	If the file does not have any basic syntax errors, operation
	begins at the first line of the script file. During operation,
	the script file is kept open until the script is completed.

	Telnet/Rlogin/Rshell sessions that have attached script files will
	have a flashing status line entry at the bottom of the screen.

	An active session may have a script attached to it by pressing the
	ALT-MINUS key (described above).  An active session with 
	an active script file can have the script cancelled by pressing
	the ALT-MINUS key.

	Script commands are case insensitive.

What is the basic command structure?
	
	The script file structure is quite simple. Commands are read
	one per line. The command is executed, and if it fails, telnet
	will wait until a timeout occurs,  retrying when new data arrives.

	If a command times out without suceeding, an error operation occurs.
	There are three basic error responses:

		1. Ignore
		2. Abort
		3. Jump to a label.

	The default error operation is Abort, the default timeout is 30 seconds.

	After a jump, the error response is set to Abort to avoid loops. It
	may be reset again as required.


What are the Script commands?

	The basic script commands are listed below, in the following format:

		command_name Number_of_args NeedCon,Data - Description of command
				Examples

			Expanded Description and side effects.

		The command_name is not case sensitive. The number of
		args is the number of arguements expected by the command.
		Some arguements accept strings, which must be enclosed
		in quotes if the string contains whitespace or backslash
		macros.  

		The word 'NeedCon' indicates that an active
		connection is required for the command to be executed.

		The word 'Data' indicates that this command will be retried
		as soon as some data arrives from the remote host, or when
		a connection is established.


		Sorry these aren't sorted..
---------------------------------------------------------------------------
	timeout 1 - Specify the error timeout value

			timeout 10
			timeout 0
			timeout 9999

		sets the error timeout in seconds. 

	keymap 2 NeedCon - Loads the named keymap file for the current session
			   or for the default session.
			   args (Default, this)

		keymap Default "default.tbl"; changes table for all sessions
		keymap this "current.tbl";    changes table for this session only	

	setsname 1 NeedCon - Sets the current session name to the arg

		setsname "session1"	

		simply alters the name displayed on the status line

	write 1  NeedCon - Writes the supplied string to the active connection
			 - as if typed.

		write "Hi mommy\n"
		write "This has a ^D in it \004 and some more stuff;"

		The write command sends the supplied string to the remote host
		as if each character were individually typed at the keyboard.

		An active connection is required or the script will be aborted.

	lookfor 1 NeedCon, Data - Looks for the specified string 
				- anywhere on the screen.

			lookfor "Userid"
			lookfor "Login:"

		The lookfor command searches for the supplied string anywhere
		on the current screen. The search is normally  case
		sensitive UNLESS the 'flags nocase' command has been
		executed previously.

		A connection is required for this command. New data
		will retry the command until sucess or timeout.

	lookat 3 NeedCon, Data - Looks at the indicated location for the 
			       - supplied string.

		lookat row column string

			lookat 20 2 "Username"

			lookat 0 1  "%"

		The lookat command is similar to the lookfor command, except
		that the match is made at the specified row and column.

		A row value of zero means 'the last line on the screen'.
		(Useful if the user may have 43 line screens, etc).

		This command may or may not be case sensitive, depending on
		the use of the 'flags nocase' command.

		New data will retry this command and a connection is required.

		This command is most useful with 3278 screens.

	moveto 2  NeedCon - Moves the cursor to the indicated row and column
			  - active 3278 sessions only

		moveto row column

			moveto 20 1

	flags 1		- Sets Script operation variables

		flags takes the following possible arguements.

			debug  - enables debugging of the script to the
				 console window.
			nodebug - disables debugging data

			nocase - turns off case sensitivity for lookat and 
				 lookfor commands.

			case 	- turns case sensitivity back on.

	waitfor 1  NeedCon, Data - Waits for special signal or data

		waitfor takes the following possible arguements.

			data 	- waits for data to arrive
			connection - waits for the connection to open
					( not functional on PC-NFS version).

	label  1		- Specifies a jump to label
	
			label  mylabel

		Use the label command to indicate the target of an
		onerror jump. You may use any string as a label, except
		for the reserved words 'ignore' and 'abort'.

	echo  1	NeedCon  - Writes the supplied string to the screen

			echo "\e[2J" ; clear the screen
			echo "\e[34m" ; change foreground color
			echo "hi there silly person"

		Sends the supplied string to the screen as if sent from
		the host. The screen is always a VT102 emulator
		(even in 3278 mode ... surprise!) so you can use VT102
		escape sequences, graphics chars, etc. You can also
		turn on and off print through mode.

	message 1	- Writes the supplied string to the console

			message "\e[2J"  ; clear console screen
	
		Sends the supplied string to the console. The console
		is also a VT102 emulator. 

	presskey 1	NeedCon - Sends the keycode as if pressed.
			
			presskey 148 ; up arrow

			presskey d   ; <CR>

		Presskey accepts a single hexadecimal arguement which
		represents the keycode generated by the users keyboard.

		Do not include a leading 0x in front of the hex code.

		You can determine the proper keycode to use by running
		the testkey.exe program

		You can NOT use codes for keyboard commands, such as
		ALT-W, ALT-X, etc. These codes are normally processed at
		e higher level in the program.

	onerror 1	- Sets the error handler response typee.

		onerror accepts the following arguements:

			ignore - Ignore all subsequent errors
			abort  - immediately close the script on failure
				 ( default operation ).
			any_label - Any string that matches a label statement
				  will cause a jump to that location on
				  a timeout error.

		After a timeout jump, a 'onerror abort' is automatically
		implied. You may re-arm the onerror handler to a different
		value after the jump if you so desire.

	telnet 1	- Telnet to the named host
	rlogin 1	- Rlogin to the named host
	rshell 1	- Rshell to the named host

			telnet omnigate
			telnet "clutx.clarkson.edu 25"
			rshell "barnacle -l bkc /bin/cat /etc/password"

		These commands accept a single arguement that matches
		what you might type after an ALT-A, ALT-Z or ALT-V
		command. Be sure to put multiple arguement lines in
		quotes. If you already have an active connection, this
		command is silently ignored and the script continues.


		You may wish to use

			waitfor connection
		after the telnet/rlogin/rshell command to ensure that
		the connection is open before proceeding. 
		(waitfor connection doesn't work on the PC-NFS version).

		You may also spawn another script using the @ symbol.
		Be sure to 'onerror ignore' since the telnet/rlogin/rshell
		function returns an error on the spawning of a script
		(regardless of whether or not the script is spawned).

		Example:
			onerror ignore
			telnet "@script2"
			telnet "@C:\\myscripts\\script.fil"
			onerror abort
			telnet "real.destination"
			waitfor connection

		
	delay 1 	- Delays the specified number of seconds
			
			delay 5

	end		- Indicates the end of the script file

		A script file is automatically ended by the end of file or
		^Z. You may indicate a premature end by using the 'end'
		command. This is useful to terminate one branch of an error
		handler.

		Example:
		 	onerror jump1
			telnet "omnigate"
			waitfor connection
			end
			label jump1
			write "unable to connect to omnigate"
			close

	mark		- Not Implemented

	close		- Closes the current network connection, if there is
			  one.

	detach	 NeedCon - Detaches the current script from the current connection

		You can use the detach command to spawn several
		telnet sessions using one script file.

			telnet "host1"
			detach
			telnet "host2"
			detach
			rlogin "host3"

	attach 1	- Attaches to the specified connection
		attach "sessionname"

		This command attaches the current script to the specified
		session. You must NOT have a current active session
		otherwise this command will fail.

	ask	1  	- Prompts the user to enter a string in the console
			  window. 

		This command takes one argument, the string to prompt the
		user with. (A null string "", is ok).

		This command will switch to the console window, print the
		arguement, and read up to 79 characters from the console.

		The ask command will then switch back to the current session.

		If the user presses ESCAPE at any time during the ask
		command, the onerror function will be called as if the
		command had failed. Otherwise the command suceeds.

	show	1	- Switches the screen to the console, the current session
			  or a named session.

		This command takes the following arguements.

			console  - Shows the console window
			current  - Shows the window associated with the script.
			any_session_name - attempts to display the session
				 that matches the given name.

		If there is no current connection, or no session with the
		given name, the command fails and the onerror function
		will be called.

		Example:
			show console
			telnet "host1"
			detach
			telnet "host2"
			show "host1"	; show the first system

	send	1 NeedCon - Sends special codes and data to the remote host.
		
		This command takes the following arguements.

			myip  - sends the PC's ip address in dotted decimal form.
			password - sends the internal FTP password (ALT-W)
			ask  - Sends the result of the last ASK command
			       (fails if no ask command has been executed)

		This command sends just the data, and no <CR> or <NL>,
		you may use the 'write' command after this command to
		supply the missing CR.



Special Notes:
	
	There is an important distinction between commands that need connections,
	and the waitfor connection command.

	If you telnet to a host that requires a domain name lookup, a
	VT102 window will be created, but the Telnet connection will not be
	open for several seconds. In this case, waitfor connection fails 
	until the actual telnet connection is open. But commands that 
	'NeedCon' will proceed because the VT102 window is open.

	In summary, the NeedCon check is only made against the existance
	of the VT102 window, an not against the status of the underlying
	TCP connection. This means that a script that does not have the
	'waitfor connection' command, could proceed several steps before
	the connection might timeout, or the domain name lookup fails.
	In this case, the window will the go away (with the usual
	'Connection closed, press a key' prompt). The next command that
	is NeedCon will then fail.


	Telnet/Rlogin/Rshell to names that require a domain name lookup
	will temporily fail, then (hopefully) restart when the domain name
	is resolved. It seems to work so far.

