| Contents | Previous Page | Next Page |
This section lists the different macro substitution commands that are available within the scripting language.
A macro substitution is a command contained within two hash (#) symbols which can be embedded at any point in the script.
When a script line is executed, any macro substitution commands within the line are first executed, and the results of the command replace the macro command. The script line is then executed with the replacements to the macro substitutions in place.
For example, if you wish to view the contents of the clipboard in a dialog box, you could use the following command:
|
MESSAGE
#clipboard# |
The macro command is contained between the two # characters
– the clipboard command.
For example, if the clipboard contained the text Hello
There then the command #clipboard# would be return Hello
There and therefore the command would be interpreted as:-
|
MESSAGE
Hello There |
The fact that the macro command is only interpreted once a given line is executed gives enormous flexibility to the use of macros substitutions.
Note that you cannot directly nest macro substitution – i.e. once cannot be contained within another – e.g. the following is illegal, which is attempting to use a hash character as a default to a PROMPT macro:-
|
MESSAGE
#PROMPT Enter hash or nothing,### |
In fact, what is returned is the results of the PROMPT command, followed by a hash character. The default is defined as being blank.
| SET
hashchar=## |
| MESSAGE
#PROMPT Enter hash or nothing,&hashchar&# |
In fact, later version of ArcTel allow the use of the #HASH# macro substitution to represent a hash, and the #AMPERSAND# substitution to represent an ampersand. Thus the above could be replaced by:-
| MESSAGE
#PROMPT Enter hash or nothing,&hash&# |
The following section lists all of the available macro substitution commands:-
For first level nesting of macros, where you see a #, substitute an & symbol.
[ ? 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 ]
##
#ampersand#
#char#
#number#
calc
clipboard
connected
cr
datestamp
decrypt
emailconnect
emailerr
emailres
formatdate
ftpconnect
ftpres
hash
hostname
instr
len
length
list
listline
listlines
logfilename
logline
loglines
now
port
pos
prompt
round
scriptfilename
textpos
trunc
variable
version
Return a Hash Character
|
## #HASH# |
As a hash character is used to denote the start and end of a macro substitution, use the macro substitution to represent a hash character.
Where this is inconvenient, use #HASH# to denote the hash character.
|
#number# where number is an ASCII code between 0 and 255. |
Many characters are not directly available from the keyboard. For example, a carriage return is ascii character 13 followed by ASCII character 10. This cannot be represented within a script directly.
In the below example, the words Hello, There, and Everybody are displayed on separate lines, making use of ASCII codes 13 and 10 to form a carriage return.
|
SET
cr=#13##10# |
Set
up a variable called #cr# to represent a carriage return. |
|
MESSAGE
Hello#cr#There#cr#Everybody |
Displays
Hello There Everybody where each successive word is displayed on a new
line in the dialog box. |
|
#var_name# where var_name is the name of the variable to retrieve |
Use this form of the macro to return the contents of a specified variable. If the variable has not yet been assigned to, this will return an empty string.
In the below example, the words Hello, There, and Everybody are displayed on separate lines, making use of ASCII codes 13 and 10 to form a carriage return. The codes are stored in a variable called cr and then used to separate each of the three words.
|
SET
cr=#13##10# |
Set
up a variable called #cr# to represent a carriage return. |
|
MESSAGE
Hello#cr#There#cr#Everybody |
Displays
Hello There Everybody where each successive word is displayed on a new
line in the dialog box. |
Return an Ampersand (&) Character
|
&& #AMPERSAND# |
As an ampersand character is used to denote the start and end of a nested macro substitution, use the macro substitution to represent an ampersand character when it is nested.
Where this is inconvenient, use #AMPERSAND# to denote the ampersand character.
Note that when displaying text using the MESSAGE or PROMPT commands, the ampersand is used to denote an accelerator character - e.g. &A would appears as A on the screen. To obtain an ampersand, use && or within a ## macro, use &ERSAND& twice or &ERSAND&&&
Return the result of a simple arithmetic formula
|
#CALC formula# where formula is a simple formula without parenthesis, using only the basic operators: + (addition), - (subtraction), / (division), * (multiplication), ^ (power), and % (modulus). The values can either be numbers (incl. decimal numbers) or variable names. |
Use this macro if you want to perform some arithmetic. Typically this would involve the use of variables for any useful purposes.
For example, the formula 1+2*2/3^3 would evaluate to 8. You cannot use parentheses, but if you had included them to be explicit about what this means, it would be represented as ((((1+2)*2)/3)^3) = (((3*2)/3)^3) = ((6/3)^3) = (2^3) = 8 – i.e. each successive operator works on the result of the previous operation.
In the example below, the user enters a value until they enter a value that is divisible by three.
|
loopstart: |
Start
of the loop |
|
SET
reply=#PROMPT Enter a value divisible by 3# |
Prompt
the user to enter a value
divisible by three, and place it in the reply
variable |
|
IF
“#CALC reply/3#” contains “.” |
If
the answer contains a decimal point, then it’s not whole… |
|
GOTO
loopstart |
…
so start again |
|
ENDIF |
|
|
#CHAR character# Where character is the character for which you wish to find the ASCII code |
This macro converts a specified character to its ASCII numeric code equivalent.
|
#CLIPBOARD# |
Many applications can make use of the clipboard. To place the text contents of the clipboard in a command, use this macro.
|
#CONNECT# |
Use this macro to test whether there is a session open on the telnet server. You may wish to use DISCONNECT accordingly.
|
#CR# |
Equivalent to the macro sequence #13##10#.
Returns the current date and time in a fixed format suitable for comparisons and program timings.
|
#DATESTAMP# |
This returns a date and time in the format yyyy-mm-dd hh:nn:ss:zzz where yyyy is the year padded to 4-digits, mm is the month number left-padded with zeroes, dd is the day number of the month left-padded with zeroes, hh is the hour-number (in 24-hour format) left-padded with zeroes, nn is the minute-number left-padded with zeroes, ss is the second-number left-padded with zeroes, and zzz is the number of milliseconds left-padded with zeroes.
For example, 3rd August 2002 at seven minutes past one in the afternoon, at 5 seconds past the minute, 23 milliseconds into the second would be represented as follows:-
2002-08-03 13:07:05:023
As the values are listed in longest span first and padded to an appropriate number of digits, dates can be compared as strings using the IF statement in order to determine whether one time is before or after another.
See also DATESTAMP and FORMATDATE.
Decrypt a previously encrypted string.
|
#DECRYPT encrypted_string# where encrypted_string is an encrypted string of characters. |
This macro is inserted using the Script / Insert / CryptString menu option. It decrypts the string denoted by encrypted_string and returns the unencrypted version of the string.
The algorithm used for encrypting and decrypting data is fairly simplistic, so should not be regarded as a security measure against determined hackers. However, it should deter somebody casually browsing the script. The decrypted string will not be logged in the log file, for security reasons.
A typical use of this macro would be when automating a
log-in to a system. It could be used to encrypt the password to be sent to the
system.
|
#EMAILCONNECT# #EMAILCONNECTED# |
Use this macro to test whether there is a connection open to the SMTP server. You may wish to EMAIL QUIT or EMAIL CONNECT accordingly.
Returns the result of the last SMTP Email-related command that failed, in the form of a message prefixed with a standard SMTP code.
|
#EMAILERR# #EMAILERROR# |
Many Email commands return a failure message, the left of which gives a code defined by the SMTP standard. The most recent message can be retrieved using this macro.
Generally speaking, commands that perform some interaction with the remote machine – e.g. to connect, send, and close the connection etc. will return error messages if an unexpected fault occurs.
Returns the result of the last SMTP Email-related command in the form of a message prefixed with a standard SMTP code.
|
#EMAILRES# |
Many Email commands return a success message, the left of which gives a code defined by the SMTP standard. The most recent message can be retrieved using this macro.
Generally speaking, commands that perform some interaction with the remote machine – e.g. to connect, send, and close the connection etc. will return messages.
Takes a decimal number and formats it as a date.
|
#FORMATDATE datetimeval[,formatstring]# where datetimeval is a decimal number representing a specific date and time and formatstring is an optional formatting string to show how this value should be given |
This macro will take a date / time value, represented as a decimal number, and convert it to a readable text string according to the format string given. If no format string is given, then a default format of yyyy-mm-dd hh:nn:ss:zzz is used.
See the NOW macro for how to obtain the current date and time as a decimal number.
The example below gives examples of how you can format a date/time value, and use the #calc# macro to add or subtract days/hours/minutes, or find the amount of time it took to run a program.
|
set curdt = #now# |
Set variable curdt to contain the decimal value representing the date and time now (according to the computer's internal clock) |
|
set origcurdt = #curdt# |
Remember this variable (it will be changed during the life of the program) for later |
|
list Now is #formatdate &curdt&# |
Start new
list with a line of text showing the value of curdt formatted as
standard (see DATESTAMP for standard format) |
|
set curdt = #calc curdt-1# |
Put the
value of curdt back one day exactly by subtracting 1 from its
value. |
|
list add 1 day ago is #formatdate &curdt&,ddd d mmm# |
Display this new date value with a format showing the day of the week followed by the date (with no zero-padding) followed by the month as a three-letter word. |
|
set hour = #calc 1/24# |
set variable hour to contain 1 divided by 24 - i.e. the decimal value for one hour (1 day being split into 24 hours) |
|
set curdt = #calc -2*hour+curdt# |
set value of curdt to be two hours before its previous value by multiplying the value of hour by 2, making it into a minus number (=-2/24) and then adding this to its previous value. Note that if we had tried to do #calc curdt+2*hour# then we would have taken the previous value, added 2 days onto it and then divided the date by 24, giving a vary bizarre result! |
|
list add 2 Hours ago: #formatdate &curdt&,hh:nnam/pm# |
Show the time an hour ago with a digit-hour followed by a colon (:) character, followed by the minutes (nn) as two digits, followed by an indicator showing either am or pm. |
|
set minute = #calc hour/60# |
Set value of minute to be the decimal representation of a minute - i.e. an hour divided by sixty. |
|
set curdt = #calc 45*minute+curdt# |
Calculate 45 minutes from now by multiplying value of minute by 45 and adding this to the current date. |
|
list add 45 minutes hence: #formatdate &curdt&,hh:nnam/pm# |
Add this to the list |
|
set endtm = #now# |
Put time value for end of program into endtm variable |
|
list add ...and now is #formatdate &endtm&,d mmm yyyy 'at' h:mm:ssam/pm 'and' z 'milliseconds'# |
Show the current date and time again. Note the use of single-quotes to enclose any literal text (i.e. text we want to be shown 'as-is'). |
|
list add Time for execution was #formatdate &calc endtm-origcurdt&,hh'h'mm'm'ss's'zzz'ms'# |
Show the total time of execution in hours, minutes, seconds and milliseconds by subtracting the end time from the original time, and formatting it. |
|
msg #list# |
Show the results that were added to the list in a dialog box. |
The dialog box should show something like this (depending on the date/time it is run):-
|
Now is 2002-07-11 13:34:34:969 1 day ago is Wed 10 Jul 2 Hours ago: 11:34am 45 minutes hence: 12:19pm ...and now is 11 Jul 2002 at 1:34:34pm and 979 milliseconds Time for execution was 00h00m00s010ms |
We can see that this work took the computer 10ms to complete
|
#FTPCONNECT# #FTPCONNECTED# |
Use this macro to test whether there is a connection open to the FTP server. You may wish to FTP QUIT or FTP CONNECT accordingly.
Returns the result of the last FTP-related command – either TRUE or FALSE
|
#FTPRES# |
Many FTP commands return a success indicator. The most recent indicator can be retrieved using this macro, TRUE indicating Success, and FALSE indicating Failure.
Generally speaking, commands that perform some interaction with the remote machine – e.g. to connect, send, receive, close the connection etc. will return indicators.
Return the current Telnet Host name
|
#HOSTNAME# |
This macro returns the current Telnet Host Name, as set either by the user interactively, or using the HOSTNAME command.
Return the length of a string
|
#LENGTH string# #LEN string# |
This macro returns the length of a given string.
For example, if you wanted the user to enter text which was a maximum length of 5 characters, you could do the following:-
|
loop_start: |
Starting
point of loop |
|
SET
inp_str=#PROMPT Enter string up to 5 characters length# |
Prompt
user to input data up to 5 chars in length, and return result in variable inp_str |
|
IF
“#LEN &inp_str&#” NUM> “5” |
If
the length of the contents of the inp_str
variable is numerically greater than 5… |
|
GOTO
loop_start |
…
go back to line labelled loop_start: |
|
ENDIF |
End
of if statement |
|
MESSAGE
You entered ‘#inp_str#’ |
Show
dialog box with what user entered |
Return the standard list as a single string including carriage-return characters.
|
#LIST# |
This macro will return the entire contents of the standard list as a single string value. It can be useful for debugging purposes - e.g. display the contents of the list using msg #list#
Pull out a specific line of text from the standard list
|
#LISTLINE line_number# where line_number is the line (1 being the first) to extract from the standard list |
Use this macro to extract a single line of text from the standard list - for example, to extract the third line of text from the list, use #LISTLINE 3#.
If you attempt to extract a line that does not exist, a 'list index out of bounds' error message will be generated.
Return the total number of lines in the standard list
|
#LISTLINES# |
This macro gives the total number of lines in the standard list. It can be useful for iterating (looping) through the contents of the list.
Return the full filename of the currently active log file.
|
#LOGFILE# #LOGFILENAME# |
This macro returns the full filename (including path) of the currently active log file. It is blank if the log is not saved on disk.
|
#LOGLINE linenum# |
The macro returns the log line identified by the linenum value. This can be from 1 for the 1st line in the log, to #LOGLINES# which is the most recent line on the log.
The below example checks the last ten lines to see whether the FTP PUT has transferred the file OK. It is a good example of how to implement a loop without looping constructs: -
|
LOG
DISABLED |
Disable
logging so we can do some testing on the log |
|
FTP
PUT |
Put
data to the FTP server (parameters set up already) |
|
SET
cnt=#LOGLINES# |
Set
cnt to the last line in the log |
|
SET
numlines=#cnt# |
Set
variable to number of lines for use in IF statement |
|
SET
started=F |
State
that Started Transferring line has not been found yet |
|
SET
finished=F |
State
the Finished Transferring line has not been found yet |
|
loopstart: |
Start
of loop |
|
IF
"#cnt#" NUM < "#CALC numlines-10" |
If
current log line more than 10 lines from last, go to end |
|
GOTO
loopend |
|
|
ELSIF
"#logline &cnt&#" STARTS "< 226 Transfer
complete" |
If
current log line starts with text,
then the transfer must have completed OK. Note, because working backwards
through the log, completion will be hit before start. |
|
SET
finished=T |
Set
the finished flag variable to T |
|
ELSIF
"#logline &cnt&#" CONTAINS "ASCII data connection
for filename.txt" |
If
the log line, whose number is given by the cnt variable contains the text stating that the file of the given
name has been transferred… |
|
SET
started=T |
Set
the started flag variable to T |
|
GOTO
loopend |
Finish,
as we know all we need to know |
|
ENDIF |
|
|
DEC
cnt |
Decrease
the log line number by one |
|
GOTO
loopstart |
Go
back to start of loop |
|
:loopend |
Where
to go after loop has ended. |
|
MESSAGE
Finished searching –
Started Flag: #started#, finished flag: #end# |
|
|
LOG
ENABLED |
|
Return the number of lines in the current log
|
#LOGLINES# |
This macro returns the number of lines in the log at this time. Note that it could change between execution of commands if the Telnet session is running a process that is outputting to the console.
Returns the current date and time as a decimal number to 18-digit accuracy
|
#NOW# |
Return the system clock date and time as a decimal number. 24 hours corresponds to 1 added to this value, and time is represented as a fraction of 1 (e.g. 1 hour is 1 divided by 24, 1 minute is 1 divided by 24 divided by 60 etc.)
Can be used for comparison purposes in an IF statement if compared as a
number.
Return the current Telnet Port
|
#PORT# |
This macro returns the current Telnet Port, as set either by the user interactively, or using the PORT command.
Prompt the user to enter a value, with optional default, and optional password masking character.
|
#PROMPT Message[,Default[,Pass_Char[,Options]]]# where Message is the message to prompt the user with (instructive text) and Default is the optional default value to place in the edit box and Pass_Char is the optional character to use to mask inputting (to hide the input text) and Options is a list of options to give the user in a drop-down list, separated by | characters. |
In the following example, the user is prompted to type in a User Id and then a password, and then connects using these settings.
|
SET
hash=## |
Place
the hash character in a variable called hash |
|
SET
cr=#13##10# |
Define
a carriage return in variable called cr |
|
SET
userid=#PROMPT User Id,myid# |
Set
the variable userid to be the
results of a user input, prompted with ‘UserId’ with the result being myid
by default. |
|
SET
password=#PROMPT Password,,&hash&# |
Set
the variable password using the
results of a user input, prompted with ‘Password’, with no default,
but with the input being hidden by replacing typed characters with a hash
character |
|
CONNECT |
Connect
to the telnet server |
|
SEND
#userid##cr# |
Send
userid to server with a carriage return |
|
wait
1 |
wait
for 1 second for terminal to catch up |
|
SEND
#password##cr# |
Send
password to server with a carriage return |
|
SET response=#PROMPT Are you mad?,Yes,,Yes|No# |
Ask
the user if he or she is mad, giving an option of either Yes or No, with a
default of Yes. Place the result of the query in the variable called response |
|
IF “#response#”=”Yes” |
If
Yes … |
|
Message Blurble Floop! |
…
display a mad message |
|
STOP |
…
and stop execution of the program |
|
ENDIF |
End
of IF |
|
Message Very Sensible. |
Otherwise,
tell the user is very sensible. |
Round a decimal number to the nearest whole number.
|
#ROUND
decimal_value# |
Returns a decimal value rounded to the nearest whole number - e.g. 1.5 and 1.8 would be rounded to 2, 1.3 would be rounded to 1, -2.5 would be rounded to -3. See also TRUNC to round to zero.
Return the full filename of the currently active script file.
|
#SCRIPTFILE# #SCRIPTFILENAME# |
This macro returns the full filename (including path) of the currently active script file. It is blank if the script is not saved on disk.
Return the character position of one string within another string.
|
#TEXTPOS substring IN string# #POS substring IN string# #INSTR substring IN string# where substring is the string (text) that is to be found and string is the string (text) inside which to look for the substring. |
This macro will take a string and look inside for text contained in the substring starting from the left hand side of the string. The value returned is the position of the start of the substring within the string.
For example, #POS 12 IN abc123# would give a result of 4, because the string 12 appears at character position 4 in the string abc123.
Round a decimal number towards zero.
|
#TRUNC
decimal_value# |
Returns a decimal value rounded to zero - e.g. 1.3, 1.5 and 1.8 would be rounded to 1, whereas -2.3, -2.5 and -2.8 would be rounded to -2. See also ROUND to round to the nearest whole number.
Returns the current version of ArcTel.
|
#VERSION# |
#VERSION#
Useful if using different disseminated versions of ArcTel, and wish to change the function of a script based on the version currently in use, or as an interim measure when rolling out new versions of ArcTel.
(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