ArcTel - Appendix A: Scripting Keywords

Index of Commands

[ ? A B C D E F G H I J K L M N O P Q R S T U V W X Y Z ]

'
--
//
auto ftp
auto lf
auto refresh
bye
call script
char width
char zoom
clear log
clear script
clear triggers
clear var
clear vars
connect
copy
copy selection
dec
decrement
default log
default script
disconnect
else
elsif
empty log
endif
error
email attachments
email authtype
email body
email close
email connect
email disconnect
email end
email files
email finish
email from
email host
email memo
email message
email open
email password
email port
email quit
email reply
email send
email signon
email subject
email text
email to
email userid
exec
execute
exit
font
ftp abort
ftp ascii
ftp binary
ftp connect
ftp disconnect
ftp get
ftp host dir
ftp host file
ftp host name
ftp local file
ftp password
ftp port
ftp put
ftp quit
ftp receive
ftp send
ftp timeout
ftp transmit
ftp username
ftp wait
goto
graphics
hostname
if
inc
increment
line height
line zoom
list
load log
load script
local echo
log
log append
log commands
log errors
log line
log name
log screen
lower
lpad
max
message
min
msg
oem charset
pause
port
print file
print list
quit
refresh screen
rem
return from script
rows
run
save log
screen height
screen width
script height
script name
script return
script visible
selection
send
set
shell
standard keys
std keys
stop
system
trigger
trigger delete
trim
typing
upper
upper lock
wait

AUTO FTP

FTP (copy)  a file from one machine to another, setting up session on one line of script

This command incorporate many of the other FTP commands into one line of script. It is particularly useful if wishing to transfer a file using the EXEC statement of the command-line parameters (i.e. when executing ArcTel).

With this command, you set all the important information required to perform a file transfer, and then state which direction the file is going (Transferred to Remote machine or Received from Remote machine). The machines are then connected, and the transfer commenced. On completion, the transfer is closed

  E.g. Call ArcTel with the following command to send transmit.txt to remote machine:-

AUTO LF

  Set whether to automatically add a line feed at the end of each new line.

Some terminals require the emulator to add a line feed at the end of each line. If you terminal seems to be running lines one after the other, instead of putting them onto separate line, enable this option.

AUTO REFRESH

  Set whether to automatically refresh the screen when making any settings changes to the terminal.

Changing many of the terminal settings affects the way the terminal looks. If making a series of changes, you may wish the screen to remain unchanged until the last change has taken place, in order to cut down the time spent needlessly updating the screen. Turn this option off to achieve this, or ON to make sure any such change gets automatically updated on the screen.

CALL SCRIPT

  Load and execute another script, with a view to returning execution to the same point.

This Loads and executes a script from within the current script, but keeping details of the current script in memory.

When execution of the called script terminates with the SCRIPT RETURN or RETURN FROM SCRIPT command, the called script is removed from memory, and execution resumes with the next line of the calling script.

It is possible to run other scripts from within a script, and when finished with that script, return control to the original script. This is a little like procedure calling in many programming languages.

Calls to scripts may be nested – there is no fixed limit to the depth of nesting. Be careful that you do not accidentally call a calling script from a called script, unless you have a specific exit condition to prevent two scripts infinitely calling each other.

Any triggers, variables, etc. that are set up in the called script, will be retained in memory.

This makes a called script useful as standard script that can be reused in other scripts, for example to set up a session and commonly used variables.

In the below example, the standard script login_prod.asf is called to log into a terminal, and then a task is performed (writing the directory contents to a file) before closing the session.

Calling Script

Script: login_prod.asf

CHAR WIDTH

  Sets the width of each character column on the terminal.

If you increase the size of the font, it will also be necessary to increase the size of the character width, otherwise the font will be cut off in width.

You can also use this option to increase the spacing between character columns to make them more readable.

CHAR ZOOM

  Sets the amount to increase the spacing between each character on the terminal.

If you find the characters are not wide enough, making the screen look narrow, then you may like to increase the character zoom – e.g. 2 or 200% (for 200%) would make the characters twice as wide, and 0.5 or 50% (for 50%) would make them twice as small. See also LINE ZOOM.

COLUMNS

Define the number of character columns displayed on the terminal screen

This is generally set at 80 characters wide. Only increase / decrease it if you seem to miss columns of data or have too many blank columns at the right of the screen. Maximum column width is 132.

CLEAR LOG           EMPTY LOG

  Clear the output log so that it is empty.

To clear the log so that any future telnet activity is recorded from a ‘clean slate’, use either of the above commands, both of which perform the same function. 

CLEAR SCRIPT

  Clear the script from screen.

This will remove all lines from the script on the screen. This may be useful to put at the end of your default script, so that the script edit box is clear to do further work.

CLEAR TRIGGERS

  Clears all triggers in memory

This will remove all triggers from memory, so that no text being displayed will cause an event to be triggered.

This is useful for clearing up after the end of a script that uses triggers, or as a ‘make sure’ to put in at the beginning of a script that is to use a brand new set of triggers.

CLEAR VAR

Remove a specified variable from memory.

This will remove any reference to the variable from memory. Attempting to retrieve the variable when it has been removed from memory will generate an error and cause the script to halt.

CLEAR VARS

  Remove all variables from memory.

  This will remove all user-defined variables from memory. Attempting to retrieve the variable when it has been removed from memory will generate an error and cause the script to halt.

CONNECT

  Log onto remote computer using the previously defined HOSTNAME and PORT.

On connection, most telnet services will prompt the user for a user name and password. To automate the login for these, see the section on Logon Automation in the Common Tasks section of this manual.

COPY

  Copy a portion of one string and place it in another string

  Use this command to copy from a portion of the contents of a source data to a destintion variable. This is useful for extracting specific parts of some given text.

For example, if you apply the command COPY hello,2,3 TO dest this will start from the second character (e) and copy three characters (e, l, and l) and place this into the variable called dest, so that dest now contains ell.

DEC      DECREMENT

  Decrement (take 1 from) variable value

For some purposes, you may want to  decrement a numeric value stored in a variable during a process, for example if you are emulating a loop. Use this command to achieve this purpose.

The example below shows a message box for numbers 5 through to 1 in a loop, then quits the loop.

COPY SELECTION

  Copy the text inside the terminal selection rectangle to the clipboard.

If you wish to copy specific text from a given selected rectangle on the terminal, use this command. The text enclosed in the selection rectangle will be copied to the clipboard. You can access the text contents of the clipboard using the #clipboard# macro substitution.

The selection is set either by the user dragging around some given text using the mouse, or programatically using the SELECTION command.

DEFAULT LOG

  Make the current log filename the default.

  This will make the current log filename (e.g. previously loaded or previously set using LOG NAME command) the default to be loaded up automatically when ArcTel I opened.

DEFAULT SCRIPT

Make the current script filename the default

This will make the current script filename (e.g. previously loaded or previously set using SCRIPT NAME command) the default to be loaded up automatically when ArcTel is opened.
Nb. if you want the script to be automatically loaded up each time, but do not wish it to be automatically run, make sure the first line of the script is NORUN

DISCONNECT

Disconnect (log off) from the remote computer that you are currently connected to.

 It is always good practice to log off cleanly if possible. Most telnet environments have a disconnection option which allows the remote host to clean up before disconnection – common command-line keywords in the host environment include exit    bye    quit    q    system

EMAIL ATTACH[MENT[S]]  |  EMAIL FILE[S]

Specify a file or list of files using their filenames, to be sent with the email as attachment(s).

The file names must all exist and be valid files on or accessible by your PC.

Note that you can use a single filename, or a list of filenames separated by semi-colons. It is also possible to add to, merge into, delete from, load and save this list using the standard list-building facilities of Arctel, explained here.

EMAIL AUTHTYPE

This defines the authorization type required in order to log into the server.  

If you do not need to login to your email server using a password (generally true for computers within an organization - i.e. on an Intranet) then use the PLAIN option.

If you need to login to an email using a password, you would generally use the LOGIN option (generally true for computers connected to an external server on the Internet - e.g. an Internet Service Provider).

If you do use the LOGIN option, you will also need to use the EMAIL USERID and EMAIL PASSWORD options. 

EMAIL CLOSE | EMAIL FINISH | EMAIL END | EMAIL DISCONNECT | EMAIL QUIT

Close a connection - i.e. log off - the SMTP (Email sending) server previously logged in to.

This will log you off the server previously logged onto using the EMAIL OPEN command, having sent all the emails you wish to using the EMAIL SEND command. 

EMAIL FROM

Specify the email address from which the message was sent, and to which a reply should be sent.

The email address must be in the correct format to be transmitted across the Internet - e.g. webmaster@simonhuggins.com - note that you can use any email address, so you should be extra careful to use an address that actually exists - i.e. check for spelling mistakes etc. Note if you wish replies to go to an alternative address, use the EMAIL REPLY [TO] command after using the EMAIL FROM command.

EMAIL HOST [NAME]

Define the email host name or IP address of the SMTP server from which you wish to send an email

You need to specify the host name prior to connecting to the server. See the EMAIL SEND command for an example of sending an email.

EMAIL OPEN  |  EMAIL CONNECT

Open a connection - i.e. log on to - the SMTP (Email sending) server previously specified.

This will log you on to the server specified in the EMAIL HOST command using the EMAIL PORT port, authenticating the login using the user id and password specified in the EMAIL USERID and EMAIL PASSWORD commands (if the EMAIL AUTHTYPE LOGIN command was used). You can then send as many emails as you required before loggin off the server again using the EMAIL CLOSE command.

EMAIL PASSWORD

Specify the Password that authenticates the User ID, required to log into the SMTP email server in order to send an email.

Required if you use the EMAIL LOGIN command to specify that you need to log in to your email server with an ID and Password to authenticate your rights to use the server. You will also need to use the EMAIL USERID command to specify the login account name. 

EMAIL PORT

Define the port number to be used to connect to the SMTP server from which you wish to send an email

If you do not know the port number, use the default smtp - the majority of SMTP servers use this for connection. 

EMAIL REPLY [TO]

Specify the email address to which any replies should be sent.

The email address must be in the correct format to be transmitted across the Internet - e.g. webmaster@simonhuggins.com - note that you can use any email address, so you should be extra careful to use an address that actually exists - i.e. check for spelling mistakes etc. Note make sure you use this command after using the EMAIL FROM command.

EMAIL SEND

Send an email having specified the various details about the email 

You need to have opened a connection to the SMTP server prior to issuing this command using the EMAIL OPEN command. You can send several messages, but must then issue an EMAIL CLOSE command to show that the last email has been sent (even if it was only a single email).

The following is an example of sending an email to a server with authentication:-

EMAIL SIGNON

Define the sign-on string to be used for a server. You can use this to determine specific data about a server.  

You will not usually need to use this command when sending an email. 

EMAIL SUBJECT

Specify the subject line text that will appear in the recipient's inbox.

This is a single line of text used by the recipient to identify in their inbox the subject matter of the email. It should be kept concise, and explain clearly the content of the email in order to allow the recipient to appropriately prioritise its importance.

EMAIL TEXT | EMAIL MSG | EMAIL MESSAGE | EMAIL BODY | EMAIL MEMO

Specify the main body of text to be used for the email message. 

The body text is made up of several lines of text to relay the main detailed information of your email message.

Note that you can use a single line of text, or a number of lines separated by semi-colons. It is also possible to add to, merge into, delete from, load and save these lines using the standard list-building facilities of Arctel, explained here. Note also that a comprehensive example of using the list-building facility to build up the body of the email  is included with the EMAIL SEND command.

EMAIL TO

Specify the email address(es) of the recipients for the email message. I.e. where the email is to be sent.

The email address(es) must be in the correct format to be transmitted across the Internet - e.g. webmaster@simonhuggins.com.

Note that you can use a single email address, or a list of addresses separated by semi-colons. It is also possible to add to, merge into, delete from, load and save this list using the standard list-building facilities of Arctel, explained here.

EMAIL USERID

Specify the account name (User ID) required to log into the SMTP email server in order to send an email.

Required if you use the EMAIL LOGIN command to specify that you need to log in to your email server with an ID and Password to authenticate your rights to use the server. You will also need to use the EMAIL PASSWORD command to specify the login password.

ERROR

  Display a user-defined error message.

Use this command to display a specific error message, log it (if error logging is turned on) and terminate execution of the script.

FONT

  Change the font style of the terminal

Use this command to set the terminal font, size, and style. 

FTP ABORT

  Close the connection to the remote computer for FTP irrespective of whether the connection is busy.

Use this command only if you wish to terminate an FTP transfer, or the connection cannot be shut down otherwise using the FTP QUIT command.

FTP ASCII

  Set FTP mode to ASCII TRANSFER.

Any files FTPed after using this command will be transferred in ASCII MODE. Use this mode to transfer text files.

FTP BINARY

  Set FTP mode to BINARY TRANSFER.

Any files FTPed after using this command will be transferred in BINARY MODE, ie. the destination file will be an exact copy of the source file.

FTP CONNECT

  Establish a connection with the remote computer in order to FTP files.

Use this command to establish a connection between the local computer and the remote computer.

When you wish to transfer a file using FTP, you will need to set the HOST, PORT, USERNAME, PASSWORD, and specify the files to ftp to / from. You can then execute the FTP CONNECT command, use FTP GET or FTP PUT to transfer the file, and FTP QUIT to disconnect from the FTP server.

Note that the TRANSMIT and RECEIVE commands will automatically open a connection, so there is usually no need to use this command. However, if you use the GET or PUT commands, this will be necessary. For multiple transfers, using CONNECT/GET or PUT/QUIT will speed up the transfer by eliminating the need to form a new connection for each transfer.

FTP GET

  Transmit the file from the remote computer to the local machine when a connection has already been established.

Use this command to transmit the file on the remote FTP server defined by the FTP HOST DIR and FTP HOST FILE to a file on the local machine defined by the commands FTP LOCAL FILENAME command. A connection must already have been established with the FTP CONNECT command. Use the FTP RECEIVE command if you wish to connection to be created and dropped automatically with each file transferred.

The sample script below shows how to transfer two files in one connection to avoid having to reconnect to the server: -

FTP HOST DIR

Set the current directory on the host machine.

Use this command to set the directory on which the file is to be transferred from / to on the remote computer. When you log in to a remote computer, you will be placed in a specific directory, most often not the root. Any directory you specify will be relative to this directory.

FTP HOST FILE[NAME]

Set the filename of the file to transfer from / to on the remote computer

Use this command to set the file that you are wished to transfer from, or into on the remote computer. Note that you should not include the directory or path in this name – use the FTP HOST DIR command to set this. The filename is usually case-sensitive.

FTP HOST NAME

Set the Host name or IP address for the remote FTP computer.

Use this command to specify the IP address or host name of the remote computer to log onto in order to transfer files.

If you have DNS services available, this can be in the form of (for example) ftp.myorg.co.uk or alternatively, in the form of  an IP address –e.g. 120.130.140.1

FTP LOCAL FILE[NAME]

Set the local filename of the file to transfer to / from the remote FTP computer.

Use this command to set the file that you are wished to transfer from, or into on the local computer (the one you are running ArcTel from). Note that you should also include the directory or path in this name. The filename/path is usually case-sensitive.

FTP PASSWORD

  Set the password for the user account on the remote computer to FTP to/from

  When you wish to transfer a file using FTP, you will need to set the HOST, PORT, USERNAME, PASSWORD, and specify the files to ftp to / from.

The computer you are logging into will have different accounts set up with different authorities to restrict what different users can do. Each account is identified with a username and authenticated with a password.

This command sets the password for the account to log into on the remote FTP computer.

FTP PORT

  Set the port of the machine to FTP to/from

When you wish to transfer a file using FTP, you will need to set the HOST, PORT, USERNAME, PASSWORD, and specify the files to ftp to / from.

The computer that you are logging into uses different ports for different processes. If you wish to use the default FTP port, set port to ftp otherwise, set port to the number of the port from which the telnet service is available.

FTP PUT

Transmit the file from the local machine to the remote computer, given that a connection to the FTP server has already been established.

Use this command to transmit the file defined by the FTP LOCAL FILENAME command to a file on the remote FTP server defined by the FTP HOST DIR and FTP HOST FILE commands, given that a connection to the FTP server has already been established using the FTP CONNECT command. Use the FTP QUIT command afterwards to manually close the connection. Note, to create and close the connection automatically with each transfer, use the FTP TRANSMIT command.

FTP QUIT  | FTP DISCONNECT

Close the connection to the remote computer for FTP

  After you have finished copying files, use this command to close the connection to the remote FTP server. This is only relevant to the FTP GET and FTP PUT commands.

FTP RECEIVE

Transmit the file from the remote computer to the local machine.

Use this command to transmit the file on the remote FTP server defined by the FTP HOST DIR and FTP HOST FILE to a file on the local machine defined by the commands FTP LOCAL FILENAME command. The sample script below shows a typical set of commands for retrieving a file from a remote FTP server: -

FTP TIMEOUT

  Set the length of time before an inactive connection is disconnected. 

This command sets the length of time in seconds before the remote computer will be disconnected when the connection is inactive (e.g. because the connection has been lost or is on a very slow link).

FTP TRANSMIT  |   FTP SEND

Transmit the file from the local machine to the remote computer.

Use this command to transmit the file defined by the FTP LOCAL FILENAME command to a file on the remote FTP server defined by the FTP HOST DIR and FTP HOST FILE commands.

FTP USERNAME

Set the user name of the user account on the remote computer to FTP to/from

  When you wish to transfer a file using FTP, you will need to set the HOST, PORT, USERNAME, PASSWORD, and specify the files to ftp to / from.

The computer you are logging into will have different accounts set up with different authorities to restrict what different users can do. Each account is identified with a username and authenticated with a password.

This command sets the user name of the account to log into on the remote FTP computer.

FTP WAIT

  Waits until the last SEND or RECEIVE has completed before continuing.

The example below shows the setup of a sample FTP session, and how to download a file from a remote computer. Typically, this is unnecessary as file transfers are usually synchronous (happen one after the other, rather as a background process). 

GOTO

  Divert execution to a labelled line in the script.

To skip to another part of the script, place a line containing a line_label followed by a colon (:) and jump to it by using GOTO line_label. If you are using a macro-substitution in line_label, there is a possibility that the line label won’t be found, in which case, specify an alt_line_label to jump to in case it isn’t found.

Take the below sample, which prompts the user for an IP address, but only allows either 123.456.789.0 or 321.321.321.1 otherwise a message is displayed. 

GRAPHICS

Sets whether to translate and draw graphics characters (e.g. boxes around text etc.)

  Many remote applications make use of graphics characters – for example, boxes to section off different areas of the screen, divide columns of data etc. If you find that these divisions appear as non-standard characters (e.g. Ĥ etc.) instead of lines, then enable this option.

HOSTNAME

  Name of Computer to log onto.

This identifies the remote computer that you wish to log onto.

This is stored in the system registry, which means that it will be available next time you start ArcTel.

If you wish to clear the host name after disconnecting, just use the command HOSTNAME with a space after it, which will make the hostname blank next time ArcTel is started.

If you have DNS services available, this can be in the form of (for example) telnet.myorg.co.uk or alternatively, in the form of  an IP address –e.g. 120.130.140.1

IF ... [ELSIF] ... [ELSE] ... ENDIF

  Executes a block of instructions if a particular condition is met

If you prefix an operator with the word NUM then the two conditions will be treated as numbers instead of strings for the purposes of comparison.

Note that only the =, <>, <, >, <= and >= operators and their equivalents can treat the conditions as numeric. Any other operator defaults to comparing the conditions as strings.

This command is used to execute a block of instructions (between the IF statement and the ENDIF statement) based on whether a simple comparison is true.

For example, IF “HELL” IN “HELLO” would yield true, but IF “12”<”09” would yield false.

In general, you would use this in conjunction with the available macro substitution codes.

The comparison is not case-sensitive, so you can compare “HeLlO” and “HELLO” as if they were the same.

  Note that IF statements are NOT currently nestable. This means you cannot have an IF statement between another IF … ENDIF block.

However, you can have further alternative conditions using any number of ELSIF commands within the IF and ENDIF block. To specify a final default alternative condition - ie. instructions that should be executed if none of the IF or ELSIF conditions have been satisfied, use the ELSE command.

The available conditions are described below:

  In the below example, if the clipboard text start with the text “LOGIN” then connect to a session. If the text contains “LOGOUT” then disconnect from the session. Otherwise display a message.

INC      INCREMENT

  Increment (add 1 to) variable value

For many purposes, you may want to  increment a numeric value stored in a variable during a process, for example if you are emulating a loop. Use this command to achieve this purpose.

The example below shows a message box for numbers 1 through to 5 in a loop, then quits the loop.

LINE HEIGHT

  Sets the height of each line of text on the terminal.

If you increase the size of the font, it will also be necessary to increase the size of the line height, otherwise the font will be cut off in height

You can also use this option to increase the spacing between lines of text to make them more readable.

LINE ZOOM

  Sets the amount to increase the spacing between each row on the terminal.

If you find the characters are not deep enough, making the screen look squashed, then you may like to increase the line zoom – e.g. 2 or 200% (for 200%) would make the characters twice as deep/high, and 0.5 or 50% (for 50%) would make them twice as shallow / half as high. See also LINE WIDTH.

LIST

Manipulate (add to, delete from, merge into, load or save) standard list of strings

Use this command to use the standard list for creating a list of strings, saving to and loading from it etc.  You can use the PRINT LIST command to print the contents of the standard list.

Note that you can use a single line of text, or a list of text lines separated by semi-colons. It is also possible to add to, merge into, delete from, load and save this list using the standard list-building facilities of Arctel, explained here.

LOAD LOG

  Load (Retrieve) the currently named log.

If no filename has been previously specified (e.g. using the LOG NAME command), a dialog box is displayed for the user to select a log to load from.

You can also use this command to revert to the previously saved version of the current log file.

LOAD SCRIPT

Load, but don’t execute a script from a file. Replace the current script.

  Use the command to terminate the current script and load into memory another script, loaded in from a specified file.

The current script is not stored so that execution can return to the script after the called script has finished. Instead, the loaded script replaces the current script.

Effectively, this terminates execution once the script is loaded.

LOCAL ECHO

  Sets whether the user’s input should be echoed to the console locally.

Some terminals do not send back the user’s keyboard input, and rely on the local terminal emulator to do this. If you are finding that the text you type is never appearing on the screen, enable this option.

LOG

  Turns logging on or off

This will turn logging on or off.

This overrides logging of commands / errors / terminal activity.

Thus you need to use this option in order for logging to work at all. The only exception is if you use the LOG LINE command to explicitly add a specific line of text to the log.

Nb. This setting is retained even after closing the ArcTel program, so will remain active when you next execute the ArcTel program.

LOG APPEND

  Turns on or off whether the log is appended to between sessions

This will turn appending of the log between sessions on or off.

When append logging is enabled, the default log will be opened when the ArcTel program is started, and any further logging will be added to the end of this log. If it is disabled, then logging will start anew each time the ArcTel program is started.

As the log is saved automatically when the user exits ArcTel, the effect of this is to either keep the log going ad-infinitum if this option is enabled, or only contain details from the last session if the option  is disabled.

Nb. This setting is retained even after closing the ArcTel program, so will remain active when you next execute the ArcTel program.

LOG COMMANDS

  Turns on or off logging of script lines

This will turn logging of script lines on or off.

When logging of commands is enabled, a script line is added to the log just prior to it being executed, prefixed with the text: <COMMAND> Line lineno: where lineno is the line number of the line from the start of the script.

This command is useful if you want to trace the flow of execution within the script whilst debugging.

Nb. This setting is retained even after closing the ArcTel program, so will remain active when you next execute the ArcTel program.

LOG ERRORS

  Turns on or off logging of errors

This will turn logging of errors on or off.

When logging of errors is enabled, any errors encountered will be logged with the line number they occurred on in the log file.

Nb. This setting is retained even after closing the ArcTel program, so will remain active when you next execute the ArcTel program.

LOG LINE

Adds a line of text to the log

  This will output a line of text to the log. Each successive LOG LINE command starts a new line of text in the log.

This command is useful for placing flags at key points in a script in order to log ‘milestones’ in the script’s execution.

LOG NAME

Set the filename for the log file, to which telnet activity will be saved.

  This command only changes the log filename. It does not save the contents of the log to the file immediately. This only happens either when the ArcTel program is closed, when the user selects the Log | Save menu option, or when the SAVE LOG command is executed.
Alternatively, if you wish to load and use a specific log, use this command followed by the LOAD LOG command.

LOG SCREEN

  Turns on or off logging of data received from the Remote Computer.

  This will turn logging of the terminal data on or off.

This includes any special Telnet-related codes (see Appendix VI for further information). Nb. Any special characters (e.g. ASCII below 32) are displayed as the hexadecimal equivalent, enclosed in chevrons (<>).

Nb. This setting is retained even after closing the ArcTel program, so will remain active when you next execute the ArcTel program.

LOWER

  Changes the upper case letters in a variable to lower case, so variable contains only lower-case letters.

  It is often useful to ‘normalise’ a string, for example for string comparison purposes. For example, if you had an input string which was one of “Yes”, “YES”, and “yes”, then this command would change it to “yes” which is much easier to compare. It can also be used to make a string less prominent – e.g. a string that was previously mainly in capitals.

  The example below prompts the user for some text, and converts it into lower case, with a capital letter for the first letter of the sentence:-

LPAD

  Pad a variable with leading characters to a given length

Use this command to force a string to a given length by inserting characters to the left of the existing string. This is useful when you wish to produce text which aligns correctly.

In the below example, a string is input by the user and padded to the left to a 5 character width with leading 0s:- 

MAX

  Maximize the ArcTel window

  Use any word starting with MAX (e.g. MAX or MAXIMIZE or MAXIMISE) to maximize the ArcTel window – i.e. make it fit to the size of the screen.

MESSAGE     MSG

Display a message in a dialog box.

Use this to display a message in a dialog box. Useful for notifying a user of an event.

MIN

  Maximize the ArcTel window

Use any word starting with MIN (e.g. MAX or MINIMIZE or MINIMISE) to minimize the ArcTel window – i.e. make it disappear from the scren, and only display in the Windows task bar. This is useful where you are calling Telnet to run a process which you wish to be invisible to the user.

OEM CHARSET

  Enables translation of characters to ISO 8859 compliant ASCII codes.

This will only affect non-standard characters (from 80H upwards) – i.e. those using ASCII codes above the standard range of ASCII characters.

PAUSE      WAIT

Pause for a specified period of time before executing the next script line.

Use this to pause execution for a given period of time before continuing on to the next script line.

Can specify up to 1/1000s of a second accuracy – e.g. 0.001 is smallest time possible to pause.

This function is useful if you wish to wait a specified period of time for the terminal session to complete a given task.

PORT

Port of Computer to use.

The computer that you are logging into uses different ports for different processes. If you wish to use the default telnet, port, set port to telnet otherwise, set port to the number of the port from which the telnet service is available.

PRINT FILE

Print the contents of a file immediately to a printer as a formatted report.

This command will print the contents of a text file specified by a given filename to the default printer. The default title is taken from the filename of the script currently being run, if you do not specify one.

The report is printed with page numbers and headers.

PRINT LIST

Print the contents of the standard list immediately to the printer as a formatted report.

This command will print the contents of the standard list (generated using the LIST command) to the default printer. The default title is taken from the filename of the script currently being run, if you do not specify one. See the script-writing section for more details on generating lists.

The report is printed with page numbers and headers.

QUIT      EXIT      SYSTEM      BYE

Exit from the ArcTel program completely. Disconnects from the open session first, if applicable.

Use any one of these commands to quit the ArcTel program from within a script.

If you are automating a process using a script, then you may wish to start ArcTel, run the appropriate script, and then exit from ArcTel automatically.

REFRESH SCREEN

  Refresh the screen to bring any changes that have been made to settings into view.

Use this option if you have AUTO REFRESH disabled, and you only wish to update a number of changes to terminal settings in one go. This will save unnecessary reprocessing of the screen.

REM      --      //      ’

Remark line for documenting the operation of a script.

Use any of these three forms to specify some descriptive text to document the operation of the script. The computer will not perform any action on these lines, with the exception of a line ending with a  colon (:) which could potentially be treated as a label for a GOTO statement. 

RETURN FROM SCRIPT      SCRIPT RETURN

Return from a script called by the CALL SCRIPT command.

This closes the current (called) script, and returns execution to the calling script.

It is possible to run other scripts from within a script, and when finished with that script, return control to the original script. This is a little like procedure calling in many programming languages.

Calls to scripts may be nested – there is no fixed limit to the depth of nesting. Be careful that you do not accidentally call a calling script from a called script, unless you have a specific exit condition to prevent two scripts infinitely calling each other.

ROWS

  Define the number of rows displayed on the terminal screen

This is generally set at 24 or 25 lines of text. Only increase / decrease it if you seem to miss lines of data or have too many blank lines at the bottom of the screen.

Note the bottom of the terminal display is denotes by a horizontal line. Max no. of rows is 50.

RUN      EXEC      EXECUTE

Load and execute a script from a file, replacing the current script.

Use the command to terminate the current script and start execution of another script, loaded in from a specified file.

Note that this differs from the CALL SCRIPT function in that the current script is not stored so that execution can return to the script after the called script has finished. Instead, the loaded script replaces the current script.

Thus, if you call a script using CALL SCRIPT, and then from that script, execute another script using RUN or EXEC or EXECUTE, then you can still use SCRIPT RETURN to return to the original calling script.

Example of Calling Script, EXECUTING script, then returning to original script.

	Step 1

	Step 2
	Step 3
	Step 4

 

SAVE LOG

  Save the log currently being used.

If no filename has been previously specified (e.g. using the LOG NAME command), a dialog box is displayed for the user to select a log to save to. 

SCREEN HEIGHT

Change the height of the ArcTel window.

As part of your session setup, you may wish to show the screen as a particular height, to just fit in the height of the terminal given the settings you have chosen, for example. Use this command to achieve this.

SCREEN WIDTH

  Change the width of the ArcTel window.

 As part of your session setup, you may wish to show the screen as a particular width, to just fit in the width of the terminal given the settings you have chosen. Use this command to achieve this.

SCRIPT HEIGHT

Change the height of the Script box.

As part of your session setup, you may wish to set the size of the script edit box. Increasing the size of the script box will decrease the size of the terminal box and vice versa.

To hide the script box, but still keep it available using the drag-bar, set height to 0.

SCRIPT NAME

  Set the filename for the current script file.

This command only changes the script filename. It does not save the contents of the script to the file immediately. This only happens either when the ArcTel program is closed, or when the user selects the Script | Save menu option.

SCRIPT VISIBLE

Hide or show the script box.

As part of your session setup, you may wish to hide the script edit box, so the user cannot see the contents of the script that is running. To hide the script box, so that it is unavailable even using the drag-bar, enable this command.

SEND

Send data to the remote terminal.

For Carriage returns, tab stops etc. within the text string, use macro substitution – e.g. #13##10# for ASCII code 13 followed by ASCII code 10, which is equivalent to a Carriage Return / Line Feed (or the user press the Enter key). See Appendix  II regarding macro substitution. 

SELECTION

Set the bounding rectangle for selected text on the terminal.

Use the SELECTION command when you want to place a selection box around a particular region of the terminal screen. You can use the COPY SELECTION command to copy the text within this region to the clipboard, and then refer to the contents of the box using the #clipboard# macro substitution.

This could be useful when you wish to test to see whether a particular area of the screen contains the text you expect.

When writing the program, draw the rectangle where you would like it to be in the program, and use the option from the Script/Insert menu to insert a Selection Rectangle Command into the script.

In the following example, the program will display “Found” if the word “INSERT” is found on line 25 towards the right hand side of the screen.

SET

  Sets the value for a user-defined variable

Variables currently have limited functionality. They can only be used as macro substitutions (e.g. if you place #varname# into your script, it will be substituted with a value of varname when the line is executed).

SHELL

  Execute an external Windows or DOS based program.

This executes a specified application and returns control immediately to the calling script.

If no directory path is specified, the following directories are searched, in this order:

1. The directory from which the application loaded

2. The current directory

3. The Windows system directory

4. The Windows directory

5. The directories listed in the PATH environment variable

  You can run the application in a minimized state (showing as an icon in the Windows taskbar) by using the MIN option, or in a maximized state (taking up the whole of the screen) by using the MAX option.

The SHELL option is useful if you want to carry out further processing beyond the scope of the script commands used in ArcTel.

STD KEYS      STANDARD KEYS

Set the standard keyboard definition according to terminal type.

Different terminal types are set up to respond to different keystrokes. Ie. The keyboard (including function keys) is set up to respond in a particular way according to the terminal type.

Define the keyboard layout using one of these options – e.g. STD KEYS VT100.

STOP

Halts execution of the script at the current line.

This halts execution of the script at the current line. If a trigger has been activated, it may restart execution at another point in the script, even after a STOP command has been executed. This makes it ideal to use after defining a trigger, where you want to wait until a specified piece of text activates the trigger and [optionally] recommences execution.

TRIGGER

Create a new trigger.

Triggers identify an action to take when a particular sequence of characters is displayed on the terminal. For example, to automate a login sequence, you may set up a trigger on the word ‘login’ which then automatically sends the login name to the terminal, and then jumps to a part of the script which generates a new trigger on the word ‘password’ etc. etc. Below is an example of this:- 

TRIGGER DELETE

Deletes a specified trigger

   This will remove a specific trigger from memory.

It is worth removing triggers after use, in case the trigger text is inadvertently displayed later in the terminal session – e.g. if login was your trigger text, and later you edit a document with the word ‘login’ in it, this would activate the trigger with potentially unpredictable results.

You can also remove all triggers after use by using the CLEAR TRIGGERS command.

TRIM

  Removes leading and trailing spaces and control characters from the contents of a given variable.

For comparison or display purposes, it is often useful to remove any extraneous spaces or other control characters from the start and end of a piece of text. Use this command for this purpose.

TYPING

  Sets whether it is possible for the user to type into the telnet session

 You may wish to prevent the user from typing into the Telnet session whilst a script is running, as it may affect its operation. To do this, use this option to disable this. N.b. ensure that you do this after connecting to the telnet session using the CONNECT command. Enable it again when the job stops, or when it is safe for the user to interact with the session, otherwise the user will not be able to interact with any session until the application has been closed and restarted.

UPPER

Changes the lower case letters in a variable to upper case, so variable contains only upper-case letters.

It is often useful to ‘normalise’ a string, for example for string comparison purposes. For example, if you had an input string which was one of “Yes”, “YES”, and “yes”, then this command would change it to “YES” which is much easier to compare. It can also be used to make text more prominent. Also, some terminals expect text to be in UPPER CASE 

The example below prompts the user for some text, and converts it into lower case, with a capital letter for the first letter of the sentence:-

UPPER LOCK

  Set whether keyboard input should be locked to upper case (same as CAPS LOCK key).

If you wish to ensure that anything input by keyboard is in CAPITAL LETTERS, use this option. Certain terminals only recognize upper case, and some applications assume the use of input in capitals, thus it would be useful to enable this option in these cases.   

(c) Copyright 2001-2 Arctan Computer Ventures Ltd.   All Rights Reserved.
If you have any issues regarding this on-line help, please contact the author by clicking here.
Alternatively, you can leave a voice message on 00 44 (0)7050-618-297 or fax on 00 44 (0)7050-618-298
This Page was last updated: 15 January 2004 15:01