| Contents | Previous Page | Next Page |
ArcTel has a comprehensive built-in scripting language designed to automate interactions with your server using the Telnet and FTP protocols. It can also perform notifications in the form of sending out emails and printing out documents, controlled by your scripts.
The (blue) script window gives a list of commands to perform in order to carry out a particular task – for example, setting up the Telnet client in order to log in properly to a particular server.
When typing a longer script, it can be useful to search for specific piece of text to find where in a program something occurs - for example, you may want to know all the places in a script where a variable called LoginPassword is used.
The Find
function searches from the current cursor position in the script, and looks for
all occurrences of a piece of text, one at a time, either backwards from that
point (towards the beginning) or forwards (towards the end). The search can take
into account the case of the text you type, or ignore it.
To access the Find function, either use the Script menu and click on the Find menu option, or use the shortcut key-combination, which is Ctrl+F.
Similarly,
if you wish to Replace the next (or all) occurrence(s) of a phrase with
something else, use the Replace function by clicking on the Script
menu and click on the Replace menu option, or use the shortcut
key-combination, which is Ctrl+R. Notice this only works in the forwards
(towards the end) direction.
This can be useful if (for example) you name a variable something, and realize later that it could be named something more appropriate. Rather than seeking out each example and changing it, you could do a global Replace.
Finally,
you may wish to go to a specific line in the program - for example, if you print
the script out, it shows line numbers on the left hand side. You may wish to
read this, and go to a specific line to cross-reference easily.
To do this, use the Goto option by choosing the Script menu and click on the Goto menu option, or use the shortcut key-combination, which is Ctrl+G. The current line number will be displayed in the text edit box in case you wish to know what the current line number is (just press the ESC key at this point if that is all you wished to find out). Just type over the edit box with the line number you wish to place the cursor on, and press the Enter key, or click on the OK button.
You can print a copy of your script out so that you have a hard copy for your records, or to examine away from the computer - just click on the Script menu and choose the Print option - alternatively, use the shortcut key combination of Ctrl+Alt+P.
Alternatively, if you wish to print a portion of the screen from a Telnet session that you are logged on to, just drag a selection by clicking in the top-left hand corner of the area that you wish to print, holding down the mouse button, and dragging down to the bottom-right hand corner of the area that you wish to print. A selection rectangle will be displayed. To print this rectangle, click on the Connection menu, and select the Print selection menu option. Alternatively, you can use the shortcut key combination of Ctrl+P. Note, you can copy the selection to the clipboard to paste into another program (or the Script window) by clicking on the Connection menu and selecting the Copy from screen option (or by using the key combination of Ctrl+Alt+C).
If you wish to print out the contents of a text file from within your script - e.g. if you wish to print the results of a log file after a report has been run, use the script command PRINT FILE filename - e.g. PRINT FILE c:\temp\arctel.log
Note that you can give the printout a specific heading by putting the heading first, followed by a comma, followed by the filename - e.g. PRINT FILE Results of Telnet Job After Completion,c:\temp\arctel.log
You can also print out the contents of the standard list built up using the LIST command using the PRINT LIST command. Note you can add a title to the end of this to give the document a heading.
' Session Parameters
CLEAR TRIGGERS
Screen Width 671
Screen Height 400
Script Visible On
Script Height 0
Auto Refresh Off
Font NAME Terminal,SIZE 9,BOLD Off,ITALIC Off
Line Height 12
Char Width 8
Auto LF Off
Local Echo Off
Upper Lock Off
OEM Charset On
Graphics Off
Rows 25
Columns 80
Char Zoom 100%
Line Zoom 100%
Auto Refresh On
Standard Keys VT100
HostName server1
Port telnet
|
'
Automatic login TRIGGER
1,login:,userid#CR#,login Connect TYPING
DISABLED Stop Login: TRIGGER
STOP 2,Password:,#DECRYPT G `¬W*-e##CR#,logged_in Logged_in: CLEAR
TRIGGERS '
Show contents of directory send
ls -alrt#CR# TYPING
ENABLED |
A TRIGGER command will wait until certain identifying text is shown on the terminal window, and will then send some text to the server in response, as if the user had typed something in, and will then jump to a specified place in the script, identified by a label.
| Description | Details |
|---|---|
| TRIGGER | The identifying word to say ‘this is a trigger command’ |
| 1 | The trigger number – start at 1 for the first trigger. You can reuse the same number once it has been triggered, or use different trigger numbers to help identify the triggers. Note that if the text is encountered later in the session by mistake, it will be triggered again. To avoid this, you can either reuse triggers, delete specific triggers after use with the TRIGGER DELETE command, or delete all triggers after use with the CLEAR TRIGGERS command. |
| Login: | When this text is displayed in the telnet window this trigger will be activated. |
| Userid#CR# |
The word ‘userid’ followed by a carriage return (equivalent of hitting the Enter key) will be sent to the server when the Login: text is encountered, as if the user had typed this into the window. Note #CR# is a macro which means that it represents another value, which upon processing, will be interpreted as something else – in this case, as the carriage-return character. All macro commands start with a # and end with a # unless nested. |
| Login | Once the text is sent, go to the label in the program, marked login: and continue the script from this point. |
Notice that this precedes the Connect command, just in case the login: text is displayed before the TRIGGER command has a chance to execute.
To generate a #DECRYPT# macro based on specific text, click on the place in the script where the text is to be used, and press Ctrl+Alt+R on the keyboard. Type in the text into the text box (they will appear as hashes for security reasons) and press Enter. The #DECRYPT# command will be placed in your text. Alternatively, if you wish to encrypt text already in the script, highlight that text, press Ctrl+Alt+R, and press Enter. The highlighted text will be replaced with the #DECRYPT# command.
The previous script suffers from a small problem, in that if it were to be shared by a number of people, the userid and password would also be shared between them. Also, if the password changes, the script would need to be changed.
TRIGGER 1,login:,#PROMPT User Id,userid##CR#,login
|
In this example, a dialog box is displayed with a title of User
Id with the default value being userid.
Whatever the user types into the text box in the dialog box will then be
subtituted fo the #PROMPT# macro command – e.g. if the user typed anonymous
then this would be interpreted as:-
TRIGGER 1,login:,anonymous#CR#,login
|
Of course, if you wish the user to type in some sensitive text, you may wish to ensure that the text typed into the box stays hidden. The following example shows you how to do this:-
TRIGGER 1,login:,#PROMPT Password,,*##CR#,logged_in
|
In this example, there is no default text, and any letter typed into the text box will be replaced by an asterisk (*) character. Note that you cannot directly use a hash character for the password text. This is because the hash is used to denote the end of the #PROMPT# macro. You would have to do the following:-
|
SET
hash=## TRIGGER 1,login:,#PROMPT Password,,&hash&##CR#,logged_in |
A variable is a named box, in which is stored a piece of information. The information in the box can be changed, and recalled later in the script. It is a method of remembering information that needs to collected and used later in the script, or which needs to be referred to a number of times in the script.
|
SET
USER=#PROMPT User Id,userid# SET
PWORD=#PROMPT Password,,&hash&# TRIGGER
1,login:,#USER##CR#,login Connect TYPING
DISABLED Stop login: TRIGGER
STOP 2,Password:,#PWORD##CR#,logged_in Logged_in: … FTP
USERNAME #USER# FTP
PASSWORD #PWORD# … |
The user is logged into the telnet session with the contents of the USER variable (denoted by the macro substitution #USER#) and PWORD variable (using macro substitution #PWORD#).
Some time later, the FTP session is set up, and as part of this, the FTP login (user and password) are set to the contents of these variables again.
Had we not used variables, we would have had to prompt the user to type the details twice.
|
SET
times=#PROMPT How many times do you wish to run this process?,1# '
run the command n times according to the prompt SET
count=1 loop: if
"#count#" NUM <= "#times#"
send mycommand #count#
inc count
goto loop endif |
This example prompts the user with the number of times a process should be run, defaulting to 1.
A counter variable is set to 1.
The contents of the count variable are numerically compared to the contents of the times variable. If the count is the same or smaller than the times variable, then the command is sent to the server with a parameter of the count number. The count variable is incremented (1 is added to its value), so it would become 2 if it was previously 1. The script then goes back to the loop: value and repeats the process until the count variable matches the times variable, and then execution will stop.
This also gives an illustration of the use of the IF command to test if something has happened, and also how the looping mechanism can be simulated in ArcTel even though specific constructs such as WHILE and REPEAT are not available. Which leads us neatly on to…
Conditional processing means that the script will only perform a set of commands if a particular condition is true – the example given above illustrates running a command multiple times.
ArcTel has two principal ways of checking whether a particular condition is true – the TRIGGER command previously described, which performs an action, and branches to a given label in the script if certain text is encountered during the terminal session.
The other command is the IF statement, which tests any other condition – typically the value of a variable, or other macro, against another value – either fixed, or another variable or macro.
The tests are numerous, and can be done either numerically or alphabetically. For example, the following script code will run because the condition evaluates to being true:-
|
if
"0003" NUM > "2"
message this executes OK
inc count endif |
This is because the use of NUM expresses the wish to treat the two values being compared as numbers. Thus, 0003 will evaluate to 3, and 3 >2 (three is larger than two) evaluates to being TRUE.
However, the following script code will not run, as the
condition evaluates to being false:-
|
if
"0003" > "2"
message this does not execute
inc count endif |
This is because the two values are not compared numerically, but alphanumerically – i.e. character-by-character. Thus, the first character of “0003” is “0” which is less than “2”, thus “0003” larger than “2” is incorrect, and evaluates to false, so the code is not run.
A further example of the use can be to test whether the session is still connected. This can be placed at the start of a script to ensure any existing session is closed before connecting to another session:-
|
IF
"#CONNECTED#"="TRUE"
DISCONNECT ENDIF |
The #CONNECTED# macro returns TRUE if a session is connected, FALSE otherwise.
The DISCONNECT command closes the active session.
|
IF
"#FTPCONNECT#"="TRUE"
FTP QUIT
WAIT 2 ENDIF |
The FTP QUIT command quits the FTP connection. A wait command is inserted to give adequate time for the connection to be closed before trying to open another connection – this pauses the script for 2 seconds.
The logging facility is not just to keep a record of the activity of the session for historical purposes. It can also be actively used by your scripts to check that an event has taken place. You can also choose the log file to use with the script.
For example, to select a particular log file, perform some tasks, and switch back to the original log file again, you could use a piece of code such as this:-
|
SET
origlog=#LOGFILENAME# SAVE
LOG LOG
NAME c:\windows\temp\temp_telnet.alf … '
Do processing to log file: temp_telnet.alf … '
Switch back to original log SAVE
LOG LOG
NAME #origlog# LOAD LOG |
The log name is then changed to c:\windows\temp\temp_telnet.alf – it is not loaded into memory, so when it gets saved back, it will contain only the current session’s details. If you used the LOAD LOG command after specifying the LOG NAME command, any data would be added to the end of the existing log details.
Processing is performed to the new log file, and saved to disk.
The original log name, originally stored in the origlog variable is then loaded back into memory again.
You can check the log to see whether something has executed correctly – for example, if you have FTPed a file, the results of the FTP are written to the log, so can be checked there.
|
… FTP
RECEIVE WAIT
2 SET
loglnno=#CALC &LOGLINES&-4# SET
logres=#logline &loglnno&# IF
"#logres#" contains "bytes received"
MESSAGE DONE OK: #logres#
TYPING ENABLED
STOP ENDIF MESSAGE
FTP FAILED DISCONNECT TYPING ENABLED |
The number of lines in the log is represented by the #LOGLINES# macro command. As the command appears inside another macro command, used to perform a mathematical calculation and return a result, the #s have been substitued for & symbols. 4 has been taken from the number of lines to gives four lines down from the last line in the log, which should contain a line of text stating that the file has been received, if the transfer has been performed successfully. This is placed in the loglnno variable.
The log line itself is retrieved using the #LOGLINE# macro command, which takes the line number of the log line to retrieve, and returns the text of that line, in this case placing it into a variable called logres.
The following few commands will print the log file quickly and easily to the standard printer:-
|
SAVE
LOG LIST OPEN #LOGFILENAME# PRINT LIST Log File Results |
Most servers that are equipped to support users logging in using the telnet protocol have also been set up to accept logins using the FTP protocol – FTP stands for File Transfer Protocol, and is used to transfer files between the server and the computer you are using. ArcTel supports synchronous (one-at-a-time) file transfers using this protocol via the scripting language. It is thus feasible to create scripts to automate the process of logging on to a server, running a program or job on that server, waiting for the job to finish, and then copying back the results of the job as a file to the local computer using an FTP session. It is even possible to then launch a program on your local computer from within the script to perform some processing on the job FTPed back to the client (local) computer – see later for examples of this. The author has used this facility to run a script on a server to interrogate the logs from an overnight batch schedule, FTP the results to a network file, and then run an Excel spreadsheet to generate a formatted file that gives details of which jobs have run OK, which ones have failed an with what error, and generate an archive file. This is in daily use by a large corporation, and has automated a manual task that would have taken two to three hours, down to two minutes. It also means that problems are picked up a lot quicker so can be rectified sooner.
|
SHELL MIN command.com /c DEL c:\windows\temp\schedule.csv WAIT 3 IF "#FTPCONNECT#"="TRUE" FTP QUIT WAIT 2 ENDIF FTP HOST NAME myftpserver.com FTP PORT ftp FTP USERNAME anonymous FTP PASSWORD blurb@simonhuggins.com FTP TIMEOUT 5 FTP HOST DIR /export/home/myaccount FTP HOST FILE schedule.csv FTP LOCAL FILENAME c:\windows\temp\schedule.csv FTP ASCII FTP RECEIVE WAIT 2 SET loglnno=#CALC &LOGLINES&-4# IF "#logline &loglnno&#" contains "bytes received" MESSAGE DONE OK: #logres# SHELL MAX "c:\program files\microsoft office\office\excel.exe" "c:\windows\temp\schedule.csv" TYPING ENABLED STOP ENDIF MESSAGE FTP FAILED TYPING ENABLED SEND exit#CR# |
The FTP TIMEOUT value is the value in seconds that a connection can be kept open before the client gives up with the transfer and quits the connection. If a file is text, it is wise to set FTP ASCII so that the text is translated correctly, as there can be differences between, for example, a Windows PC and Unix in the way carriage returns are treated. If you want to keep the file intact, use FTP BINARY instead. Note that the local filename includes the path, whereas the server’s file must have the path and filename defined separately.
Note that if you wanted to send the file to the server, the
script would be identical to above, except you would substitute the FTP
RECEIVE command with the FTP SEND
command.
|
AUTO FTP myftpserver.com,ftp,anonymous,blurb@simonhuggins.com,c:\windows\temp\schedule.csv,/export/home/myaccount/schedule.csv,ASC,R WAIT 2 SET loglnno=#CALC &LOGLINES&-4# … |
See Appendix A and the AUTO FTP command for a complete description of the use of this command.
Most emails get sent using SMTP - The Simple Mail Transport Protocol, connecting to an email (SMTP) server.
A useful facility for an automated script is to be able to notify a person or group of people of a task's completion or failure, and details (e.g. a log file) - either as part of the email, or as attachments (also useful if the task is designed to produce a file - e.g. a report).
ArcTel now supports emailing via an SMTP server. The following example should give you an idea of how to achieve this:-
|
ON ERROR MESSAGE OFF ON ERROR GOTO onerr EMAIL HOST smtp.simonhuggins.com EMAIL PORT smtp EMAIL AUTHTYPE LOGIN EMAIL USERID simonh EMAIL PASSWORD #DECRYPT w 04*+-Aa14t+|e`5# EMAIL FROM webmaster@simonhuggins.com EMAIL TO blurble@bloople.net;"Simons Junk Mail" <blurb@simon.huggins.com> EMAIL SUBJECT Test message EMAIL ATTACH c:\scandisk.log;c:\temp\email_test.asf EMAIL TEXT First line;Second Line;Third Line;Fourth line is not duplicated EMAIL MSG MERGE Fourth line is not duplicated;Fifth Line;Sixth line is deleted EMAIL MESSAGE REMOVE Sixth line is deleted;This line is ignored EMAIL BODY ADD Add this line;Fifth Line;Last line was just a test - see it is kept EMAIL MEMO ADD The following lines are opened from the script file; EMAIL TEXT ADD OPEN c:\temp\email_test.asf EMAIL TEXT ADD -----;;End of email body EMAIL OPEN MSG #EMAILRES# EMAIL SEND MSG #EMAILRES# EMAIL QUIT MSG #EMAILRES# stop onerr: if "#EMAILCONNECT#"="TRUE" EMAIL QUIT MSG Closed! end-if MSG Errored! - #EMAILERR# |
The first line turns off error messaging via dialog boxes (stops an automated process dead in its tracks!) and the second line says that if an error is found, go to the line marked onerr:
If an error is reached, then the #EMAILCONNECT# macro is checked to see if it is TRUE - ie. the script is connected to the SMTP server. If it is, then the connection is terminated using EMAIL QUIT and a message displayed saying that the connection has been closed. Finally, a message is display saying that something errored, giving the last error message.
The main information needed for an email is as follows:-
HOST - the name of the SMTP server - e.g. mail.simonhuggins.com - sometimes an IP address - e.g. 123.456.78.9
PORT - usually smtp is sufficient, but you may put a number in if your server uses a different port number for SMTP emailing (rare).
AUTHORITY TYPE - Usually PLAIN (default - most common within business intranets) or LOGIN if you are required to use a userid and password to login (e.g. if you use a dial-up internet service provider).
USER ID (if required)- User id to log into the server with - e.g. simonh
PASSWORD (if required) - Password to log in with. Typically, you would type it in, highlight it, and then turn it into a CryptString by use Shift+Ctrl+C and pressing Enter.
FROM - Who the password is coming from (and who to reply to) - typically the sender's email address.
TO - Who the email is going to. This can be an email address, or a series of email address separated by semi-colons. You can also use the standard list facility to load a set of email addresses from a file using the OPEN filename option (see section below).
SUBJECT - The subject line of text that the recipient will see in their inbox
ATTACH - The filename of the file to attach to the document, or a list of filenames separated by semi-colons. Note that you can use the standard list facility (see section below).
TEXT / BODY / MESSAGE / MEMO - The main body of the email - i.e. the text inside the email. This can be manipulated using the standard list facility (see section below).
OPEN - Use this to open a connection to the email server. If you wanted to send multiple mail messages, you could open a connection, send the email, make a few changes to the email, send it again (e.g. to someone else) etc. and then close the connection - so you can send multiple emails with one connection.
SEND - Send the email using the details supplied so far
QUIT - Close the connection to the email server - all the emails will be sent.
So it's quite easy to send an email, really!
Many commands work on a list of text items - e.g. emailed recipients, body of an email etc.
In order to build up this list, each of these commands uses a standard set of extensions.
Take the original command, and add these options:-
Single line of text - replaces the whole list with a single line of text
Items separated with semi-colons (e.g. Item 1;Item 2;Item 3) - replaces the whole list with three lines of text
DELIMITER change using DELIMchar where char is the character (instead of a semi-colon) used to separate lines of the list - e.g. (DELIM, and list could be Item 1,Item 2,Item 3).
Unchanged (Literal) text - replaces the whole list with a single line of text as is - e.g. UNCHANGED Item 1; Item 2; Item 3 will give a single line of text instead of three.
Adding lines of text - adds a line or several lines of text to the end of the existing list - e.g. ADD Item 1;Item2;Item 3
CLEAR the list - just give the command CLEAR
Add lines of text not already includes - use the MERGE command - e.g. ADD Item 1;Item 2;Item 2;Item 3;Item 1 will only produce three lines - Item 1, Item 2 and Item 3.
Remove lines of text - Use the REMOVE command - e.g. If have three items already DELETE Item 1;Item 3 will just leave Item 2
INSERT lines before a specific line in the list - first line is number 1
DELETE a specific line from the list - first line is number 1
OPEN Opens a file and replaces the list with its contents - e.g. OPEN c:\temp\log.txt - If used in conjunction with ADD (E.g. ADD OPEN c:\temp\log.txt) then adds the file's text to the end of the existing lines of text.
SAVE saves the list to a given file name without changing its contents - e.g. SAVE c:\temp\log2.txt
A combination of these commands can help you to build the list you need quickly and easily.
Note that you can work on a 'working' list to enable you to build up a list to open, save, add to, delete from etc. by using the LIST command followed by the above extensions. You can also print this list using the PRINT LIST command. Macros are also available for this standard list - #LIST# return the contents of the list as a single string, #LISTLINE lineno# returns a specific line (1 being the first) from the list, and #LISTLINES# returns the number of lines in the standard list.
The order that these commands are processed are as follows:-
DELIMchar
ADD
CLEAR
MERGE
REMOVE
INSERTlineno
DELETElineno
UNCHANGED
OPENfilename
SAVEfilename
Delimiter-Separated Data
Here's an example that adds comma-separated lines, removes line 2, merges two line 3s together and then prints the list with a heading of Test Print to show how lists work. It then saves the list to a file called c:\temp\test.txt.
Finally, the last two lines (but one) delete the second line (with the text Line2), and then insert a replacement line in the second line with the text Line 2. The result is then displayed in a dialog box.
|
LIST Line 1 LIST DELIM, ADD Line2,Line 2,Line 3 LIST REMOVE Line 2 LIST MERGE Lines 3;Line 4;;Terminated. PRINT LIST Test Print to show how lists work LIST SAVE c:\temp\test.txt ' Replace text of the second line in the list... LIST DELETE 2 LIST INSERT 2 Line 2 MSG #list# |
When automating tasks, it is sometimes useful to look at a particular section of text in a particular location on the screen, and check that it is a certain value, in order to determine what processing should be carried out next.
|
Selection TOP=280, BOTTOM=296, LEFT=6, RIGHT=62 Copy Selection IF “#CLIPBOARD#” = “CHANGED” SEND :w ENDIF |
Use the SHELL command to execute an external application. Use SHELL MAX to launch the application in a maximized state (fill the screen), or SHELL MIN to launch the application in a minimized state (visible only on the windows task bar).
|
SHELL command.com /c DEL c:\windows\temp\deleteme.txt SHELL MAX COMMAND.COM /c EDIT #SCRIPTFILENAME# |
The previous example shown in the FTP section shows where a file is deleted, received from a remote server, and then an external application launched to load / view the file.
It is possible to set up a shortcut on your desktop, or from an external scheduler to launch ArcTel to load or run a specific script. To do this, assuming you have installed the application at the standard location of c:\Program Files\Arctan Computer Ventures Ltd\ArcTel, use the executable (c:\Program Files\Arctan Computer Ventures Ltd\ArcTelc\arctel.exe) followed by a space, followed by the word RUN followed by the name of the script file to run a particular script file, or LOAD followed by the name of the script file to load but not execute a particular script file.
Include MIN in the parameters to minimize ArcTel so that it is run invisibly, or MAX to maximize ArcTel to make the window as large as possible on the screen.
Include EXEC followed by an ArcTel command to execute a specific command in ArcTel. Include EXEC LOAD followed by the ArcTel command to load the default script file, and then execute a specific command.
Finally, you can pass data into your ArcTel script by passing the SET command followed by the variable name followed by and equals sign, followed by the data (optionally enclosed in double-quotes if the data is to include spaces).
For example:-
ARCTEL.EXE SET Login=HUGGISNT SET Password=LETMEIN SET CommandToRun="ls -alrt >dir.dxt" RUN "c:\scripts\unixrun.asf"
This assumes that the script to be run is in unixrun.asf and contains commands that take the variable "Login", "Password" and "CommandToRun" and do something useful with these,
(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