SCRIPT

ver. 4.4

Introduction:

Script is a native windows scripting program for Windows 98, ME, 2000 and XP. It allows automation of tasks through the use of files containing command scripts and supports simple programming constructs similar to DOS batch files but is much more powerful. It is self contained apart from the scripts. Except for standard operating system support, no external dll's, ocx's, registry entries or .ini files are required.

Script provides an extensive set of internal commands, analogous in concept to the DOS internal commands. However, Script can't be all things to all people, so external programs can be used where Script can't provide the required functions.

The internal commands that are provided cover:

program execution - run and control external commands
user interface - various windows dialog boxes
local variables - hold and manipulation script data
string commands - manipulation of text strings
environment variables - access to process environment
byte manipulation - get, replace, fill, search
file associations - get, set, delete, find
file handling - copy, move, delete, info, find
directory handling - get, set, create, delete
disk handling
registry - get, set, create, delete,find
printing - print file, get, set, find
multimedia - play, pause, stop, info
shortcuts - get, set, create
system tray - iconise script
clipboard commands - get, set, clear
internet commands - geturl, ping
execution control - goto, gosub, case, if
windows information - time, date, system info
windows control - activate, flash, logoff, shutdown,
general commands - delay, suspend, beep, random no.
script control - report, step, priority, compile

Installing Script:

To install Script, just copy SCRIPT.EXE to an appropriate directory. By default, scripts are stored in the same directory, or in the directory \SCRIPTS, otherwise the full pathname must be specified. If no file extension is specified, .SCF (Script Command File) then .SCRIPT will be tried.

In order to prevent any confusion with other file extensions, it is recommended to use .SCRIPT as the extension for script files.
The SCRIPT.EXE executable can be renamed. It will then pick up the like named script automatically. In this case, the script file name is not specified on the command line.

Alternatively, Script supports a pseudo-compiler that will produce a standalone executable, apart from any external programs called by the script.

Invoking a script:

The script to be executed is specified as the first argument on the command line - either at a command prompt or in a shortcut. Up to 4 additional arguments can be passed from the command line. The name of the script executable and the script path, filename and extension are also passed. The invocation syntax is:

script [path]filename.ext arg1 arg2 arg3 arg4

For renamed or compiled executables, the syntax is:

executable arg1 arg2 arg3 arg4

The command line arguments can be accessed by using %1 to %4 in the script file. The name of the executable file is passed in %0. %X contains the path of the script file, %Y contains the name of the script file and %Z contains the extension of the script file actually run after applying the search rules above. For a compiled executable, %X contains the path of the compiled executable, and %Y and %Z are blank.

Examples:
SCRIPT TEST.SCF
This command will attempt to load TEST.SCF from the current directory, or from \SCRIPT if not found.

SCRIPT TEST
This command will attempt to load in order, either TEST, TEST.SCF or TEST.SCRIPT from the current directory, then TEST, TEST.SCF or TEST.SCRIPT from \SCRIPT if not found in the current directory.

SCRIPT TEST.SCF TEST.DOC 1234
This will attempt to load TEST.SCF from the current directory, or from \SCRIPT if not found. It will also pass TEST.DOC and 1234 to internal variables 1 and 2. These can be referenced in the script by using %1 and %2.

BLAH.EXE (renamed from SCRIPT.EXE)
This will automatically load BLAH.SCF or BLAH.SCRIPT from the current directory or from \SCRIPT.

BLAH.EXE HELLO THERE
This will automatically load BLAH.SCF from the current directory or from \SCRIPT and assign HELLO and THERE to internal variables 1 and 2.

Alternatively, Script can be run without command line arguments in which case, a dialog box will be displayed allowing a script to be selected and run.

Using Scripts:

The script file is a text file that can be created and modified with any editor. Command syntax is simple. Each command occupies one line. There are no commands that spread out over multiple lines. A command consists of a keyword followed by zero or more parameters, separated by comma (,) characters as follows:

command para1,para2,para3,para4,para5,para6

Generally, the parameters are arranged so that the source of data is specified first, followed by the destination, followed by any qualifiers, types or flags that might modify or customise the command. Of course, not all commands have all of these elements and in many commands, some of the parameters are optional. Compulsory parameters will usually appear in the command syntax before optional ones. Sometimes, a parameter may logically have multiple parts to it. In this case, the parts are separated by a vertical tab (|) character.

A single comma or tab can be used instead of the space immediately following the command if preferred. Any number of spaces and/or tabs can be used before the command if desired. This can be useful to indent lines for readability. Blank lines and lines whose first non blank character is a semicolon (;) are ignored.

Lines which begin with a colon (:) are labels and may not contain commands. Note that spaces can be used and are counted as part of the label. This also includes leading and trailing spaces.

Commands are not case sensitive - start, Start, START and sTaRt are equivalent.

Some commands allow for a flag to modify the operation of the command. Where the flag can take on a number of values, only as many characters of the value that will uniquely determine the flag are required.

When a script is invoked, the entire script will be scanned for syntax errors before attempting to execute. If an error is found, a message box describing the error will be displayed and processing will stop.

Script Command Summary:

The commands that can be used in a script file are summarised below:

Program Execution commands:

start or ! program,flag,xy,wh,title start an external program note (1) (2)

dos command,flag,xy,wh,title execute a dos command note (1) (2)

wait windowtitle,timeout wait for a window to open note (1) (2)

while windowtitle wait for a window to close note (1)

sendkey windowtitle,textstring send keystrokes to a window

sendmsg destination,message send a message to another PC note (1) (2)

User Interface & Information Display commands:

msgbox title,msg,btns,style,margin display a message box note (1) (4)

filebox title,localvar,template,dir display a file selection box note (1) (4)

dirbox text,localvar,root display a directory selection box note (1) (4)

editbox title,message,localvar,preset,xy,wh display an edit box for text entry note (1) (4) (6)

passbox title,message,localvar,preset,xy,wh display a password box for password entry note (1) (4) (6)

infobox title,filespec,xy,wh load and display a text file note (1)

menubox title,message,text,xy,wh display a menu box note (1) (4)

listbox title,msg,text,localvar,xy,wh display a list box note (1) (4)

radbox title,message,text,xy,wh display a radio button box note (1) (4)

tickbox title,message,text,xy,wh display a tick box note (1) (4)

numbox title,msg,localvar,preset,xy,wh display a numeric entry box note (1) (4)

chrbox title,msg,localvar,preset,xy,wh display a character entry box note (1) (4))

calbox title,msg,localvar,range,xy,wh display a calendar box note (1) (4)

ipbox title,msg,localvar,preset,xy,wh display an IP address entry box note (1) (4)

timebox title,msg,localvar,preset,xy,wh display a time entry box note (1) (4)

datebox title,msg,localvar,preset,xy,wh display a date entry box note (1) (4)

picbox title,msg,file, type,xy,wh display a bitmap, or icon note (1) (3)

console title,text,flags,xy,wh,localvar display text in a scrollable console note (1) (4)

conoff removes a console

banner text,xy,wh,b,flags display a banner panel note (1)

banoff remove a banner panel

progress title,text,value,xy,wh display a progress indicator note (1)

progoff remove a progress indicator

setfont fontname,size,attribute set font for user interface boxes note (1)

getfont localvar1,localvar2,localvar3 get font for user interface boxes

Local Variable commands:

setvar localvar,value set the value of a local variable note (1)

incvar localvar,value increments a local variable by value note (1)

addvar localvar,value adds value to a local variable note (1)

decvar localvar,value decrements a local variable by value note (1)

subvar localvar,value subtracts value from a local variable note (1)

mulvar localvar,value multiplies a local variable by value note (1)

divvar localvar,value divides a local variable by value note (1)

convar localvar,base1,base2 converts a local variable from number base1 to base2 note (1)

andvar localvar,value,base logical bitwise AND a local variable by value note (1)

orvar localvar,value,base logical bitwise OR a local variable by value note (1)

xorvar localvar,value,base logical bitwise XOR a local variable by value note (1)

notvar localvar,value,base logical bitwise NOT a local variable note (1)

upvar localvar converts a local variable to uppercase

lovar localvar converts a local variable to lowercase

trimvar localvar,flag trims left and right whitespace and optionally brackets from a local variable

ltrmvar localvar trims left whitespace from a local variable

rtrmvar localvar trims right whitespace from a local variable

appvar localvar,value appends value to a local variable note (1)

textvar localvar,type,flag converts HTML or RTF in a local variable to text note (1)

formvar localvar,tabs,char,flag formats text in a local variable to the specified tab stops note (1)

execute localvar execute the script command contained in local var

String commands:

findstr text,localvar returns first line in string to a local variable note (1) (2)

nextstr text,localvar returns next line in a string to a local variable note (1) (2)

lenstr text,localvar returns length of text in local variable note (1)

substr text,pos,length,localvar returns substring in text to local variable note (1)

srchstr text,string,localvar returns position of string in text to local var note (1) (2)

spltstr text,char,localvar1,localvar2 split text at char and return each half to local vars note (1) (2)

scanstr text,char,num,localvar returns n-th token from text to local var note (1) (2)

sortstr text,char,localvar,flag sorts text delimited by char and returns to local var note (1) (2)

replstr text,string,pos,localvar replaces text at pos with string and stores in local var note (1)
insrtstr text,string,pos,localvar inserts string in text at pos and stores in local var note (1)

grepstr text,chr,repchr,localvar,num replaces char in text with repchr and stores in local var note (1)

delstr text,pos,length,localvar deletes from text at pos of length and stores in local var note (1)

parspath text,var1,var2,var3,var4,var5 parses text for a valid path name and stores in local vars note (1)

parsip text,var1,var2,var3,var4 parses text for a valid IP address and stores in local vars note (1)

parsdate text,var1,var2,var3 parses text for a valid date and stores in local vars note (1)

parstime text,var1,var2,var3 parses text for a valid time and stores in local vars note (1)

Byte manipulation commands:

srchbyte localvar1,byte,localvar2 searches for given byte and returns position index in localvar2 note (1)

replbyte localvar1,pos,num,localvar2 replaces num bytes in localvar1 at pos using bytes from localvar2 note (1)

fillbyte localvar,byte,pos,num fills num bytes in localvar1 at pos with the specified byte note (1)

getbyte localvar1,pos,num,localvar2 gets num bytes in localvar1 at pos and copies them to localvar2 note (1)

conbyte localvar, flag converts between value in localvar between byte and hexadecimal string note (1)

grepbyte localvar,byte1,byte2,num,size replaces num occurrences of specified byte in localvar1 note (1)

Environment Variable commands:

getenv localvar,envvar get an environment variable note (1)

putenv envvar,value store an environment variable note (1)

File Association commands:

getassoc ext,localvar1,cmdtype,localvar2 get a file association and command note (1) (2)

setassoc ext,filetype,cmdtype,command set a file association and command note (1) (2)

delassoc ext deletes a file association and all associated commands note (1) (2)

fndassoc localvar finds the first registered file association note (1) (2)

nxtassoc localvar finds the next file association note (1) (2)

File commands:

copyfile source,destination,flag copies a file or files note (1) (2) (6)

movefile source,destination moves or renames a file note (1) (2) (6)

readdata filename,localvar1,flag,localvar2,localvar3 reads first data block from a file to a local variable note (1) (2)

nextdata filename,localvar,flag,localvar2 reads next data block from a file to a local variable note (1) (2)

readline filename,localvar reads a line from a file to a local variable note (1) (2)

nextline filename,localvar reads next line from a file to a local variable note (1) (2)

savetext text,filename,flag saves text to a file note (1) (2)

savedata data,filename,flag,localvar1,localvar2 saves data to a file note (1) (2)

sortfile source,destination,col,flag saves text to a file note (1) (2)

delfile filename deletes a file note (1) (2) (6)

findfile pathname,localvar returns first file matching pathname note (1) (2)

nextfile localvar returns next matching file note (2)

filetime filename,localvar,time,flag returns file times to a local variable note (1)

setftd filename,date,time,flag sets the file date and time note (1)

filesize filename,localvar returns file size to a local variable note (1)

getattr filename,localvar,flag returns file attributes to a local variable note (1)

setattr filename,attr sets file attributes note (1)

filesrch filename,text,localvar,flag returns first instance of text to a local variable note (1) (2)

nextsrch filename,text,localvar,flag returns next instance of text to a local variable note (1) (2)

filescan filename,text,localvar,flag returns number of occurrences of text to a local variable note (1) (2)

Directory commands:

setdir dirname sets the current directory note (1) (2)

getdir localvar gets current dir to a local var

makedir dirname creates a directory note (1) (2)

deldir dirname deletes an empty directory note (1) (2)

Disk commands:

getdisk localvar gets current drive to a local var note (2)

finddisk localvar copies first installed drive letter to a local variable note (2)

nextdisk localvar copies next installed drive letter to a local variable note (2)

disksize disk,localvar copies total disk size in bytes to local variable note (1)

diskfree disk,localvar copies disk free size in bytes to local variable note (1)

diskused disk,localvar copies disk used size in bytes to local variable note (1)

disktype drive,localvar,flag gets info about a disk to a local var note (1) (2)

load drive load media into drive letter specified note (1)

eject drive eject media from drive letter specified note (1)

Registry commands:

setreg keyvalue,type,data saves data to a registry key value note (1) (2)

getreg keyvalue,localvar gets data from a key value to a local var note [1] (2)

delreg keyvalue deletes a key value note (1) (2)

findreg key,localvar finds the first value of a registry key note (1) (2)

nextreg key,localvar finds the next value of a registry key branch note (1) (2)

makekey key creates a registry key note (1) (2)

delkey key deletes a registry key note (1) (2)

findkey key,localvar finds the first subkey of a registry key note (1) (2)

nextkey key,localvar finds the next subkey of a registry key note (1) (2)

Printing commands:

print file print a file on the default printer using wordpad note (1) (2)

getprint localvar copies default printer name to local variable

setprint printer sets default printer to name specified note (1)

findprnt localvar copies name of first printer to local variable note (2)

nextprnt localvar copies name of next printer to local variable note (2)

Multimedia commands:

open device,source,flag open a sound file or cd audio note (1) (2)

seek device,position move to a position note (1) (2)

play device,position play sound file or CD note (1) (2)

pause device pause play note (1) (2)

resume device resume play note (1) (2)

stop device stop play note (1) (2)

getmedia device,localvar,flag copy media info to a local variable note (1) (2)

Shortcut commands:

makelink linkname,filename,flag create a shortcut note (1) (2)

getlink linkname,localvar,info get info about a shortcut note (1) (2)

setlink linkname,info,value set info about a shortcut note (1) (2)

System Tray commands:

puttray text,label,icon,click put an icon in the system tray note (1) (2)

modtray text,label,icon,click modify an icon in the system tray note (1) (2)

deltray delete script icon from system tray note (2)

Clipboard commands:

getclip localvar,flag get text from the clipboard note (1) (2)

setclip data,flag copy text to the clipboard note (1)

clrclip clear the clipboard note (2)

Internet commands:

geturl url,localvar get text from an internet url note (1) (2)

ping host,timeout,size,ttl ping a host computer note (1) (2)

Execution control commands:

goto label unconditional branch note (1)

gosub label branch to a subroutine note (1)

return return from a subroutine

casemsg labels branch to label corresponding to button pressed note (1) [5]

ifmsg button,label branch if message box button pressed note (1) [5]

ifnmsg button,label branch if message box button not pressed note (1) [5]

iferror label branch if error (start, dos, wait etc.) note (1) [3]

ifnerror label branch if not error note (1) [3]

ifbit localvar,bit,label branch if bit set in local variable note (1)

ifnbit localvar,bit,label branch if bit clear in local variable note (1)

ifexist filename,label branch if file exists note (1)

ifnexist filename,label branch if file does not exist note (1)

ifvar localvar,value,label branch if local variable same as value note (1)

ifnvar localvar,value,label branch if local variable not same as value note (1)

ifevar localvar,value,label branch if local variable same as integer value note (1)

ifgvar localvar,value,label branch if local variable greater than integer value note (1)

iflvar localvar,value,label branch if local variable less than integer value note (1)

casevar localvar,values,labels branch to label corresponding to value of local variable note (1)

Windows Information commands:

getname localvar copies computer name to local variable

getuser localvar copies user name to local variable

gettime localvar,flag,format copies system time to local variable note (1)

getdate localvar,flag,format copies system date to local variable note (1)

settime hour,min,sec sets the system time note (1)

setdate day,mth,year sets the system date note (1)

rawdate date,time,localvar converts date and time to raw date note (1)

winver localvar,flag copies windows version to local variable

windir localvar copies windows directory to local variable

sysdir localvar copies system directory to local variable

specdir folder,localvar copies directory path of special folder to local variable note (1)

memsize localvar copies memory size in Mbytes to local variable

getscrnx localvar copies screen width to local variable

getscrny localvar copies screen height to local variable

Windows Control commands:

setscrn width,height,depth sets screen width, height and colour depth note (1)

logoff flag logoff the user note (2)

shutdown flag shutdown the system note (2)

poweroff flag shutdown and power off the system note (2)

restart flag restart the system note (2)

scrnsave invokes configured screen saver

lockpc locks the PC (Win 2000)

activate windowtitle bring a window to the foreground note (1)

minimise windowtitle minimise a window to the taskbar note (1)

maximise windowtitle maximise a window to full screen note (1)

restore windowtitle restore a window to normal display note (1)

flash windowtitle flashes a window note (1)

getwind localvar returns the window title of the active window note (1)

close windowtitle closes a window note (1)

destroy windowtitle force closes a window note (1)

setdesk filename sets desktop wallpaper to filename note (1)

setbgnd red,grn,blu sets screen background colour note (1)

General commands:

delay number delay for a set period note (1)

suspend hh:mm:ss,DD/MM/YYYY suspend until specified time and date note (1)

idle idle indefinitely

quit quit the script immediately

beep value play a beep or system sound note (1)

random value,localvar generate a random number note (1)

Script related commands:

report flag report script errors

step flag show each command before it is executed

debug flag control display of debug messages note (1)

dbgbox message show a message for debugging controlled by debug flag note (1)

version localvar copies script version to local variable

compile script,executable,flag compiles the script specified to a standalone file note (1)

priority level sets execution priority note (1)

varsize size sets the size of script internal variables note (1)

inseq flag guarantees script commands executed in sequence note (1)

Notes:

(1) these commands allow substitution for command line parameters and local variables

(2) these commands set internal error flag if error occurs - test using iferror, ifnerror

(3) these commands check the state of the internal error flag

(4) these commands return a message value - access using %M, test using casemsg, ifmsg, ifnmsg

(5) these commands check the state of the message value

(6) these commands return a count value - access using %N

Special character sequences:

Parameters can contain special command sequences if they are surrounded by an accent (`) as lead-in and lead-out characters. Many of these command sequences only have meaning for the Sendkey command. The following sequences are supported.

Char Description Meaning

@ Alt Character following is alt-char

^ Control Character following is a control character

\n newline line feed or enter (0Ah)

\r return carriage return or ctrl-enter (0Dh)

\t tab tab character (09h)

\[ esc escape character (1Bh)

\> right cursor right arrow

\< left cursor left arrow

\^ up cursor up arrow

\v down cursor down arrow

\h home cursor home key

\e end cursor end key

\u pgup cursor page up key

\d pgdn cursor page down key

\, comma Must be escaped or will be interpreted as a separator

\\ backslash Must be escaped or will be interpreted as an escape

\? question mark Must be escaped or will be interpreted as a wildcard

\* asterisk Must be escaped or will be interpreted as a wildcard

\$ dollar sign Must be escaped or will be interpreted as a function key

\# hash sign Must be escaped or will be interpreted as a hex preamble

\% percent sign Must be escaped or will be interpreted as a local variable

The escape character will be interpreted in the order it is encountered from left to right. Processing of special characters is part of syntax checking prior to running the script.

Local Variables:

As previously described, there are four local variables %1 to %4 which are preloaded with any command line arguments, plus %0, %X, %Y and %Z which contain the script executable name and the script file path, name and extension respectively. A further 12 local variables can be used within the script by using %A to %L.

Two special local variables, %M and %N are used to return results of some commands. %M is a message return value which returns information about buttons pressed or list values selected, depending on the command. %N is a number count value that returns information about files or characters processed, depending on the command.

Local variables are treated as text strings. Local variable operations, including numeric operations, can be used on all local variables except for %M, %N, %0, %X, %Y and %Z which can only be read.

Where a parameter refers directly to a local variable, just the letter or number designation is used. Where the value of a local variable is needed, the % is used immediately preceding the designation. For example, the Setvar command is used to set the value of a local variable:

setvar A,This is a test
setvar B,%A

The first setvar command sets the value of local variable A to "This is a test". The second setvar command sets local variable B to the value contained in local variable A. So, B will also be set to "This is a test".

If the percent (%) character is required on it's own as part of a text string, it should be escaped by preceding it with a backslash (\) character. That is, the sequence \%A will be treated as %A and not expanded as a local variable. However, the sequence \\%A will be treated as \%A with %A expanded as a local variable. See special characters. Note that unlike special characters, local variable expansion is performed at run time when the value of the local variable is known. Therefore, the % character is processed independently of accent lead-in and lead-out characters.

Using Strings and Local Variables:

Script provides many commands to manipulate text, under the grouping of Local Variable Commands and String Commands. Most of the relevant commands are in the String group. Here, the text source may be explicitly contained in the command, or may be implied by the value in a local variable, using the %A parameter substitution method described above. The result is returned in a designated local variable.

The Local Variable commands operate directly on the contents of a local variable, modifying it to a new value. This is used for manipulations where it is not sensible to specify text explicitly, and the source is almost certainly already in a local variable. The trim group of commands, which remove whitespace from either the start, end or both of a string are a good example.

The remaining local variable commands are used for arithmetic and logical manipulation of numbers, rather than text. There is no requirement within the Script commands to nominate a data type. Where the context of the command expects numbers to be used, they are entered and returned as text, though internally, they are treated as true numbers.

Script programming constructs:

Script directly supports only very simple IF programming constructs. More complicated constructs are built from IF and GOTO commands with the addition of local variables as flags and counters The most common are the FOR, WHILE and REPEAT constructs.

The FOR construct
In a FOR construct, a group of statements is processed in a loop for a given number of times. An example of a FOR construct is given below:

;
; Example of a FOR programming construct
;
; Local variables used as follows:
; A = for loop counter
; B = end point
;
report on
;priority low
debug off

setvar A,1
setvar B,5

:startFOR
ifgvar B,%A,continue
;
; body of FOR goes here
;
banner A = %A
delay 10
;
incvar A
goto startFOR

:continue
msgbox FOR example,Finished,0

Note that the IF must include a test to exit the loop, in this case, the ifgvar command. It is good practice to base the exit test on a range of values not being met, rather than a single value. In the IF command above, the loop exits when the value of A is 5 or greater. A test to check when A is equal to 5 will also work, by using the ifvar command. However, suppose that A is changed such that it never EQUALS 5, but still exceeds 5. This could happen if A was incremented by 2. The greater than test will still suceed, but the equality test will fail, meaning that the loop may never exit.

The WHILE construct
In a WHILE construct, a group of statements is processed in a loop until some exit condition is met that allows for control to exit from the loop. An example of a WHILE construct is given below:

;
; Example of a WHILE programming construct
;
; Local variables used as follows:
; A = while exit flag
;
report on
;priority low
debug off

setvar A,0

:startWHILE
ifnvar A,0,continue
;
; body of WHILE goes here
;
banner In WHILE
delay 30
banner Now exiting
delay 10
setvar A,1
goto startWHILE

:continue
msgbox WHILE example,Finished,0

Note again that the IF provides the test to exit the loop and again, the exit test is based on a range rather than a single value. In the IF command above, the loop exits when the value of A is anything other than 0.

The REPEAT construct
A REPEAT construct is similar to a WHILE in that a group of statements is processed in a loop until the exit condition is met, but unlike a WHILE, the exit test in a REPEAT is at the end of the loop, rather than the start, meaning that the commands in the loop must be executed at least once before the loop can exit. An example of a REPEAT construct is given below:

;
; Example of a REPEAT programming construct
;
; Local variables used as follows:
; A = repeat exit flag
;
report on
;priority low
debug off

setvar A,0

:startREPEAT
;
; body of REPEAT goes here
;
banner In REPEAT
delay 30
banner Now exiting
delay 10
setvar A,1
ifvar A,0,startREPEAT

:continue
msgbox REPEAT example,Finished,0

Designing user interfaces:

Script has a large number of simple pop up boxes that can be used to construct a user interface, but unlike a normal windows program, there is no way to construct a compound window with a mixture of elements. Therefore, user interfaces in Script need to be developed as a series of inputs, akin to asking a series of questions. Each "question" corresponds to a pop up box of one type or another.

Typically, a script might start with a banner to display the name of the program, followed by a delay 15 and banoff to display the banner for a short time. A delay value of 15 (i.e. 1.5 seconds) is usually sufficient. The actual user inputs follow, which may be something like a filebox for file selection, or an editbox for text input, or maybe a menubox or listbox to select from a series of options. A tickbox or radbox may then be needed to define parameters (multiple parameters for a tickbox, mutually exclusive parameters for a radbox). Finally, a msgbox or another banner may be needed to confirm selections and commence processing.

There are also a number of specialist input boxes, covering such things as numbers only (numbox), single characters (chrbox), dates and times (datebox and timebox), calendar selection (calbox), and ip addresses (ipbox).

User output can be performed using a msgbox or for more complicated outputs, a console or infobox may be more suitable. The picbox can be used to display bitmaps and icons.

The setfont and getfont can be used to get and set the display font, size and enhancement (eg. bold, italic) to be used for text display in the user interface boxes.

Program Execution Commands:

START or !
Start is used to run an external windows program. The full path name and the file extension of the program to be run must be supplied. Command line options for the program may be included after the executable, including program switches. There must be at least one space between the end of the program name and any forwardslash. The exclamation mark ! can be used as a shorthand instead of Start. This also aids readability of the script.

Start may be followed by further options:

max causes the window to open normally (default).

min causes the window to open minimized (an icon).

x|y sets the x and y offset from the top lefthand corner of the screen

w|h sets the width and height of the displayed window.

title sets the title of the window (where possible).

The window can be centred in either direction by using C instead of a numeric x or y value. The window can be aligned with the left edge of the screen using L or the right edge using R instead of a numeric x value. Similarly, the window can be aligned with the top or bottom using T or B instead of the numeric y value. The window can also be moved offscreen without minimising it by using X for both the x and y values. This is useful to allow the window title text to be read by the WHILE and WAIT commands.

An internal error flag will be set if Start is unable to run the specified program. This flag can then be tested using IFERROR or IFNERROR.

Any DOS command or DOS batch file can be executed by using start c:\command.com /c followed by the DOS command line. Use the min option to prevent the DOS command box from being displayed (see example below and also Dos command).

syntax:
start program [parameters][,flag,xy,wh,title]

example:
start c:\windows\notepad.exe,,30|30,500|300
start command.com /c h:\temp\test.bat,min
start cmd.exe /c h:\temp\test.bat,min (WinNT/2000 only)

DOS
Dos is used to execute a DOS command. It is a special case of the start command and is provided as a programming convenience. In effect, it prepends "command.com /c " for Win 9x/ME or "cmd.exe /c" for Win 2000/XP to the specified DOS command name and executes a start command as above.

Dos may be followed optionally by min or max which will cause the window to open minimized (an icon) or normally. The default is max. Use the min option to prevent the DOS command box from being displayed (see example below).

Note that the script environment will be passed to the DOS command. Any desired variables can be set (see PUTENV command) prior to the DOS command and will be available, but changes made to the environment by the DOS command will not be passed back.

The text output from a command can be accessed by redirecting to a temporary file on disk, then using the READLINE command to read back the file contents. The WAIT and WHILE commands should be used prior to the READLINE command to ensure the DOS command has completed.

If the simplier COMMAND.COM is required on an 2000/XP system, use the Start command (see example)

syntax:
dos command [parameters][,flag],x|y,,title

example:
dos copy test.txt test2.txt

WAIT
Wait will cause the program to wait for a window whose title text matches the text string which follows the wait command. An optional timeout value may be specified in 0.1 second increments. If this value is not given then the default value is "wait forever". If a timeout occurs the internal error flag is set to true. IFERROR or IFNERROR can be used to branch to a handler.

The string IS case sensitive and must match EXACTLY. The exception to this is the use of the two wild card characters, question mark (?) and asterisk (*).

The question mark is a single character wild card and will match any character appearing in the same position, i.e. a?b?c will match a1b2c or aabbc, but not abc or a11b11c. The asterisk is an n character wild card and will match 0 or more characters appearing in the same position, i.e. a*b*c will match abc, alphabet cup, or aabbc.

Note: two windows with exactly the same title text (e.g. Test.txt - Notepad) are not distinguishable and the command will act on the first one encountered in the task list which may not produce the expected results. WAIT with a timeout of 0 and IFERROR/IFNERROR can be used to test if a program is already running.

syntax:
wait windowtitle[,timeout]

example:
wait readme.txt - Notepad
wait Microsoft Word - Document1,100

WHILE
While waits for a window to close. The text of the window must match the text following the while command exactly, except where the wild card characters, question mark (?) and asterisk (*) are used.

The question mark is a single character wild card and will match any character appearing in the same position, i.e. a?b?c will match a1b2c or aabbc, but not abc or a11b11c. The asterisk will match 0 or more characters appearing in the same position, i.e. a*b*c will match abc, alphabet cup, or aabbc.

syntax:
while windowtitle

example:
while Untitled - Notepad

SENDKEY
SendKey is used to send characters to a window whose title text matches the text string which follows the send command.

Special characters contained in the text string must be escaped (, \ % ^ ? *). The string IS case sensitive and must match EXACTLY. The exception to this is the use of the two wild card characters, question mark (?) and asterisk (*).

The question mark is a single character wild card and will match any character appearing in the same position, i.e. a?b?c will match a1b2c or aabbc, but not abc or a11b11c. The asterisk is an n character wild card and will match 0 or more characters appearing in the same position, i.e. a*b*c will match abc, alphabet cup, or aabbc.

The string sent is the last parameter on the line. Special characters contained in the text string must be escaped (, \ @ ^ ? * $ #). The unescaped at (@) and caret (^) characters have special meaning. The @ will cause an Alt-key sequence to be sent and the ^ will cause the character immediately following to be converted to a control character.

The unescaped dollar ($) character indicates that the two characters following it are a function key number. The two characters MUST be numeric in the range of 1-12 inclusive. The unescaped hash (#) character indicates that the two characters following it are a hexadecimal representation. Legal values are 0-9, A-F, and a-f.

Additional escape sequences are defined: \n send a new line (line feed 0Ah), \r will send a return (carriage return 0Dh) and \t will send a tab (09h). ? and * must be escaped even though they have no special meaning here.

Note: two windows with exactly the same title text (e.g. Test.txt - Notepad) are not distinguishable and the command will act on the first one encountered in the task list which may not produce the expected results. WAIT and IFERROR/IFNERROR can be used to test if a program is already running.

syntax:
sendkey windowtitle,textstring

example:
sendkey readme - Notepad,This is a line`\r\n`and this is the second line
sendkey readme - Notepad,`@Fx`

SENDMSG
SendMsg is used to send a message to another PC. The message appears in a pop-up message box. The destination PC can be specified either as an IP address or computer name.

syntax:
sendmsg destination,textstring

example:
sendmsg 192.168.0.1,The coffee is ready

Information Display Commands:

MSGBOX
Msgbox displays single or multiple lines of text in a standard message box. The message box will be sized automatically to suit. The title text should be brief so as not to make the message box too wide. The default title is Message.

Multiple lines of message text can be specified using \n or the vertical tab (|) to indicate a new line in the message box text. Text lines can also be selectively centred and an overall left and right margin applied. Use !syserr for the message text to print the descriptive text of the last system error.

The default display mode is MB_OK | MB_SYSTEMMODAL. Legitimate values are any (sensible) combination of the options shown in the table below. The desired button, icon and default button values should be added to form a numeric sum. This is used as the button parameter (default is 0).

Type Control Value

Button OK 0

OK, Cancel 1

Abort, Retry, Ignore 2

Yes, No, Cancel 3

Yes, No 4

Retry, Cancel 5

Cancel, Try Again, Continue 6

Icon STOP or ERROR 16

QUESTION MARK 32

EXCLAMATION or WARNING 48

INFORMATION 64

(USER ICON 128)

Default BUTTON1 0

BUTTON2 256

BUTTON3 512

BUTTON4 768

Mode APPLMODAL 0

SYSTEMMODAL 4096

TASKMODAL 8192

HELP BUTTON 16384

Text is normally left justified but can be centred by specifying C as the style parameter. When centring is applied, any line in the message text starting with a full stop will be left justified - the full stop will be stripped from the displayed text. An overall left and right margin can be set with the margin parameter. Values up to about 50 will produce sensible results.

The button that was clicked is returned as a message value as follows:

Button Value

OK 1

CANCEL 2

ABORT 3

RETRY 4

IGNORE 5

YES 6

NO 7

TRY AGAIN 10

CONTINUE 11

This value can be tested using the CASEMSG, IFMSG and IFNMSG commands.

syntax:
msgbox [title,]message[,buttons][,style][,margin]

example:
msgbox this is a test,3
msgbox .Please note:,This is a test\nLine 2\nLine 3,3,C,10

FILEBOX
Filebox displays a filename dialog box and returns the file selected to the local variable specified. The title parameter sets the file open window title. The template parameter sets one or more file descriptor file template pairs. Multiple file templates can be specified for a single descriptor by separating the file templates with a semi-colon. The dir parameter specifies a default directory. The button that was clicked to close the filebox can be tested using the CASEMSG, IFMSG and IFNMSG commands. Only the OK and Cancel buttons are valid.

syntax:
filebox title,localvar,template,dir

example:
filebox Open Doc File,A,Doc files|*.doc,c:\My Documents
filebox Open File,A,Doc files|*.doc|All files|*.*,c:\My Documents
filebox Open Script,A,Script files|*.scf;*.script|All files|*.*,c:\script

DIRBOX
DirBox displays a Browse for Folder dialog box and returns the directory (folder) selected to the local variable specified. The text parameter sets explanatory text displayed above the folder selection window.

The root parameter specifies the starting root directory as follows:

Value Description

ALLP(ROGRAMS) Program folder for all users

ALLS(TARTMENU) Start menu folder for all users

DE(SKTOP) Desktop folder

DR(IVES) Drives folder

N(ETWORK) Network folder

P(ROGRAMS) Programs folder

S(TARTMENU) Start menu folder

The button that was clicked to close the dirbox can be tested using the CASEMSG, IFMSG and IFNMSG commands. Only the OK and Cancel buttons are valid.

syntax:
dirbox text,localvar,root

example:
dirbox Select the installation folder,A,drives

EDITBOX
Editbox displays a text entry dialog box and returns the text entered to the local variable specified when the OK button is clicked or the enter key is pressed. A null value is returned if Cancel is clicked. The button that was clicked to close the edit box can be tested using the CASEMSG, IFMSG and IFNMSG commands. Only the OK and Cancel buttons are valid.

The optional preset parameter is used to set a limit on the number of characters that can be entered and also to pass initial text to edit box. These parts are separated by a vertical tab (|). The limit is a value between 1 and 80 - otherwise, the limit will default to 80. The actual number of characters entered is returned in the %N (number count) local variable.

The optional x|y parameter sets the position of the top left hand corner of the editbox. Either direction can be centred by using C instead of a numeric value. The editbox can be aligned with the left edge of the screen using L or the right edge using R instead of a numeric x value. Similarly, the editbox can be aligned with the top or bottom using T or B instead of the numeric y value. The optional w|h parameter sets the width and height of the editbox. The default width or height can be specified by leaving it blank or using D instead of a numeric value.

syntax:
editbox title,prompt,localvar,preset,x|y,w|h

example:
editbox Text Entry,Enter a name,A
editbox Text Entry,Enter a name,A,20|initial text,L|C,300|100

PASSBOX
Passbox displays a dialog box for password entry. The characters entered are displayed as asterisks. The password is returned as text to the local variable specified when the OK button is clicked or the enter key is pressed. A null value is returned if Cancel is clicked. The button that was clicked to close the edit box can be tested using the CASEMSG, IFMSG and IFNMSG commands. Only the OK and Cancel buttons are valid.

The optional preset parameter is used to set a limit on the number of characters that can be entered and also to pass initial text to pass box (displayed as asterisks). These parts are separated by a vertical tab (|). The limit is a value between 1 and 80 - otherwise, the limit will default to 80. The actual number of characters entered is returned in the %N (number count) local variable.

The optional x|y parameter sets the position of the top left hand corner of the passbox. Either direction can be centred by using C instead of a numeric value. The passbox can be aligned with the left edge of the screen using L or the right edge using R instead of a numeric x value. Similarly, the passbox can be aligned with the top or bottom using T or B instead of the numeric y value. The optional w|h parameter sets the width and height of the passbox. The default width or height can be specified by leaving it blank or using D instead of a numeric value.

syntax:
passbox title,prompt,localvar,x|y,w|h

example:
passbox Text Entry,Enter a name,A
passbox Text Entry,Enter a name,A,20|secret password,L|C,300|100

INFOBOX
Infobox displays the specified text file in a dialog box and allows the text to be scrolled vertically. By default, the file will be assumed to be in the current directory unless a full pathname is given. The infobox is cleared by clicking the OK button. Text files up to 32K in size can be displayed. Files larger than this will be truncated. The file is assumed to contain text. No checking of the file contents is performed so results will be unpredictable if a binary file is inadvertantly specified.

The optional x|y parameter sets the position of the top left hand corner of the infobox. Either direction can be centred by using C instead of a numeric value. The infobox can be aligned with the left edge of the screen using L or the right edge using R instead of a numeric x value. Similarly, the infobox can be aligned with the top or bottom using T or B instead of the numeric y value. The optional w|h parameter sets the width and height of the infobox. The default width or height can be specified by leaving it blank or using D instead of a numeric value.

syntax:
infobox Title,filespec,x|y,w|h

example:
infobox PLEASE NOTE,readme.txt
infobox PLEASE NOTE,readme.txt,10|10,400|300

MENUBOX
Menubox displays a set of configurable buttons and returns a value based on the button clicked. The Title is specified in the first parameter. A multiline explanatory message is specified in the second parameter and appears above the buttons. Text for up to 7 buttons is specified in the third parameter, separated by vertical tab (|) characters. The box will be autosized to accomodate the number of buttons specified.

The optional x|y parameter sets the position of the top left hand corner of the menubox. Either direction can be centred by using C instead of a numeric value. The menubox can be aligned with the left edge of the screen using L or the right edge using R instead of a numeric x value. Similarly, the menubox can be aligned with the top or bottom using T or B instead of the numeric y value. The optional w|h parameter sets the width and height of the menubox. The default width or height can be specified by leaving it blank or using D instead of a numeric value.

Menubox returns a value of 1 for the first button, 2 for the second etc. A value of 0 is returned if the Cancel button is clicked. This value can be checked with the IFMSG, IFNMSG and CASEMSG commands.

syntax:
menubox Title,Message,Text1|Text2|...|Text7,x|y,w|h

example:
menubox Process document,Please select a document type:,Txt|Rtf|Doc
casemsg exit|doTxt|doRtf|doDoc

LISTBOX
Listbox displays a configurable list of items and returns a value based on the item selected when the OK button is clicked, or when the item is double clicked.

The Title is specified in the first parameter. A multiline explanatory message is specified in the second parameter and appears above the list.

Text for the list items is specified in the third parameter, separated by vertical tab (|) characters. By default, the list items are displayed in the same order. However, by specifying a vertical tab as the first character, the list items will be displayed in sorted order.

The optional x|y parameter sets the position of the top left hand corner of the listbox. Either direction can be centred by using C instead of a numeric value. The listbox can be aligned with the left edge of the screen using L or the right edge using R instead of a numeric x value. Similarly, the listbox can be aligned with the top or bottom using T or B instead of the numeric y value.

The optional w|h parameter sets the width and height of the listbox. The default width or height can be specified by leaving it blank or using D instead of a numeric value.

Listbox returns a numeric value of 1 for the first item, 2 for the second etc. A value of 0 is returned if the Cancel button is clicked. This value can be checked with the IFMSG and IFNMSG commands. If a local variable is specified, Listbox also copies the text of the item selected to the variable.

syntax:
listbox Title,Message,Text1|Text2|...|TextN,localvar,x|y,w|h

example:
listbox Process document,Please select a document type:,Txt|Rtf|Doc,A

RADBOX
Radbox displays a set of radio buttons with configurable text and returns a value based on the button selected. The Title is specified in the first parameter. A multiline explanatory message is specified in the second parameter and appears above the buttons. Text for up to 7 buttons is specified in the third parameter, separated by vertical tab (|) characters.

The optional x|y parameter sets the position of the top left hand corner of the menubox. Either direction can be centred by using C instead of a numeric value. The menubox can be aligned with the left edge of the screen using L or the right edge using R instead of a numeric x value. Similarly, the menubox can be aligned with the top or bottom using T or B instead of the numeric y value. The optional w|h parameter sets the width and height of the menubox. The default width or height can be specified by leaving it blank or using D instead of a numeric value.

Radbox returns a value of 1 for the first button, 2 for the second etc. A value of 0 is returned if the Cancel button is clicked. This value can be checked with the IFMSG, IFNMSG and CASEMSG commands.

syntax:
radbox Title,Message,Text1|Text2|...|Text7,x|y,w|h

example:
radbox Process document,Please select a document type:,Txt|Rtf|Doc
casemsg exit|doTxt|doRtf|doDoc

TICKBOX
Tickbox displays a set of tick boxes with configurable text and returns a value based on the tick box(es) selected. The Title is specified in the first parameter. A multiline explanatory message is specified in the second parameter and appears above the buttons. Text for up to 7 tick boxes is specified in the third parameter, separated by vertical tab (|) characters.

The optional x|y parameter sets the position of the top left hand corner of the menubox. Either direction can be centred by using C instead of a numeric value. The menubox can be aligned with the left edge of the screen using L or the right edge using R instead of a numeric x value. Similarly, the menubox can be aligned with the top or bottom using T or B instead of the numeric y value. The optional w|h parameter sets the width and height of the menubox. The default width or height can be specified by leaving it blank or using D instead of a numeric value.

Tickbox returns an aggregated sum for the boxes selected, corresponding to the bit positions. The sum is 1 if the first box is ticked plus 2 for the second ticked, plus 4 for the third, plus 8 for the fourth up to plus 64 for the 7th. Thus if all boxes are ticked, a value of 127 will be returned. A value of 0 is returned if the Cancel button is clicked. This value can be checked by testing bits in the %M variable using IFBIT and IFNBIT.

syntax:
tickbox Title,Message,Text1|Text2|...|Text7,x|y,w|h

example:
tickbox Options,Please select required options:,Show hidden files|Show system files|Show read only files
ifvar M,0,doRest
setvar A,%M
:checkHidden
ifnbit A,0,checkSystem
;
;processing for hidden files
;
:checkSystem
ifnbit A,1,checkReadOnly
;
;processing for system files
;
:checkReadOnly
ifnbit A,2,doRest
;
;processing for read only files
;
:doRest

NUMBOX
Numbox displays a numeric entry box. The Title is specified in the first parameter. A multiline explanatory message is specified in the second parameter. The number entered is returned in the local variable.

The optional preset parameter allows the lower limit, initial value and upper limit to be set, separated by vertical tabs (|). Otherwise, the lower limit is 0, initial value is blank and upper limit is 1000.

The optional x|y parameter sets the position of the top left hand corner of the numbox. Either direction can be centred by using C instead of a numeric value. The numbox can be aligned with the left edge of the screen using L or the right edge using R instead of a numeric x value. Similarly, the numbox can be aligned with the top or bottom using T or B instead of the numeric y value. The optional w|h parameter sets the width and height of the numbox. The default width or height can be specified by leaving it blank or using D instead of a numeric value.

syntax:
numbox Title,Message,localvar,preset,x|y,w|h

example:
numbox Numeric entry,Please enter a value:,0|50|100,A

CHRBOX
ChrBox displays a single character entry box, intended to be used for specifying a drive letter or single character. The Title is specified in the first parameter. A multiline explanatory message is specified in the second parameter. The character entered is returned in the local variable.

The optional preset parameter allows the initial value to be set. Otherwise, the initial value is blank.

The optional x|y parameter sets the position of the top left hand corner of the box. Either direction can be centred by using C instead of a numeric value. The box can be aligned with the left edge of the screen using L or the right edge using R instead of a numeric x value. Similarly, the box can be aligned with the top or bottom using T or B instead of the numeric y value. The optional w|h parameter sets the width and height of the box. The default width or height can be specified by leaving it blank or using D instead of a numeric value.

syntax:
chrbox Title,Message,localvar,preset,x|y,w|h

example:
chrbox Character entry,Please enter a drive letter:,A,A

CALBOX
CalBox displays a calendar box, intended to be used for specifying a single date or range of dates. The Title is specified in the first parameter. A multiline explanatory message is specified in the second parameter. The date(s) entered is returned in the local variable.

The optional range parameter allows the maximum selection range to be set. Otherwise, the initial value is one - only a single day can be selected.

The optional x|y parameter sets the position of the top left hand corner of the box. Either direction can be centred by using C instead of a numeric value. The box can be aligned with the left edge of the screen using L or the right edge using R instead of a numeric x value. Similarly, the box can be aligned with the top or bottom using T or B instead of the numeric y value. The optional w|h parameter sets the width and height of the box. The default width or height can be specified by leaving it blank or using D instead of a numeric value.

syntax:
calbox Title,Message,localvar,range,x|y,w|h

example:
calbox Date Selection,Please select a day:,A,1
calbox Date Selection,Please select the required date range:,A,7,L|T

The date selected is returned in the local variable specified in the form DD/MM/YYYY with leading zeros if necessary to guarantee character positions. The SubStr command can be used to extract the day, month and year portions as required. When a range is selected, it is returned in the form DD/MM/YYYY - DD/MM/YYYY to specify the start and end dates respectively of the selected range.

IPBOX
IPbox displays an IP address entry box. The Title is specified in the first parameter. A multiline explanatory message is specified in the second parameter. The IP address entered is returned in the local variable.

The optional preset parameter allows an initial address to be set for each octet separated by period (.) characters. The action of the edit controls can be customised by preceding each part with a control letter as follows:

Letter Description

E Entry by typing into the edit box only. The spin control is disabled

S Entry via the spin control only. Typing into the edit control is disabled

D No entry allowed. Both typing and spin control are disabled

Any part of the preset can be set to blank by using a space character instead of a value. If the preset is left completely blank, the initial address is set to blank.

The optional x|y parameter sets the position of the top left hand corner of the IPbox. Either direction can be centred by using C instead of a numeric value. The IPbox can be aligned with the left edge of the screen using L or the right edge using R instead of a numeric x value. Similarly, the timebox can be aligned with the top or bottom using T or B instead of the numeric y value. The optional w|h parameter sets the width and height of the IPbox. The default width or height can be specified by leaving it blank or using D instead of a numeric value.

syntax:
IPbox Title,Message,localvar,preset,x|y,w|h

example:
IPbox IP Address entry,Please enter an address:,A,10.0.0.1,100|100

TIMEBOX
Timebox displays a time entry box. The Title is specified in the first parameter. A multiline explanatory message is specified in the second parameter. The time entered is returned in the local variable in the format hh:mm:ss.

The optional preset parameter allows an initial time to be set with hours, minutes and seconds separated by colon (:) characters. The action of the edit controls can be customised by preceding each part with a control letter as follows:

Letter Description

E Entry by typing into the edit box only. The spin control is disabled

S Entry via the spin control only. Typing into the edit control is disabled

D No entry allowed. Both typing and spin control are disabled

Any part of the preset can be set to blank by using a space character instead of a value. If the preset is left completely blank, the initial time is to the current time.

The optional x|y parameter sets the position of the top left hand corner of the timebox. Either direction can be centred by using C instead of a numeric value. The timebox can be aligned with the left edge of the screen using L or the right edge using R instead of a numeric x value. Similarly, the timebox can be aligned with the top or bottom using T or B instead of the numeric y value. The optional w|h parameter sets the width and height of the timebox. The default width or height can be specified by leaving it blank or using D instead of a numeric value.

syntax:
timebox Title,Message,localvar,preset,x|y,w|h

example:
timebox Time entry,Please enter a value:,A,10:30:00,100|100

DATEBOX
Datebox displays a date entry box. The Title is specified in the first parameter. A multiline explanatory message is specified in the second parameter. The date entered is returned in the local variable in the format dd/mm/yyyy.

The optional preset parameter allows an initial date to be set with days, months and years separated by forward slash (/) characters in the format dd/mm/yyyy. The action of the edit controls can be customised by preceding each part with a control letter as follows:

Letter Description

E Entry by typing into the edit box only. The spin control is disabled

S Entry via the spin control only. Typing into the edit control is disabled

D No entry allowed. Both typing and spin control are disabled

Any part of the preset can be set to blank by using a space character instead of a value. If the preset is left completely blank, the initial date is to the current date.

The optional x|y parameter sets the position of the top left hand corner of the datebox. Either direction can be centred by using C instead of a numeric value. The datebox can be aligned with the left edge of the screen using L or the right edge using R instead of a numeric x value. Similarly, the datebox can be aligned with the top or bottom using T or B instead of the numeric y value. The optional w|h parameter sets the width and height of the datebox. The default width or height can be specified by leaving it blank or using D instead of a numeric value.

syntax:
datebox Title,Message,localvar,preset,x|y,w|h

example:
datebox Date entry,Please enter a value:,A,10/4/2000,100|100

PICBOX
Picbox displays a picture - either a bitmap or icon. The Title is specified in the first parameter. A multiline explanatory message is specified in the second parameter. The file to be displayed is specified in the third parameter.

The type parameter specifies the file type as follows:

Type Description

B Bitmap file

I Icon file

The optional x|y parameter sets the position of the top left hand corner of the picbox. Either direction can be centred by using C instead of a numeric value. The picbox can be aligned with the left edge of the screen using L or the right edge using R instead of a numeric x value. Similarly, the picbox can be aligned with the top or bottom using T or B instead of the numeric y value. The optional w|h parameter sets the width and height of the picbox. The default width or height can be specified by leaving it blank or using D instead of a numeric value.

syntax:
picbox Title,Message,file, type,x|y,w|h

example:
picbox Picture,View of entry hall,hall.bmp,B,100|100

CONSOLE
Console displays a scrollable console with the title and text specified. The console will remain on screen by default, until removed with the Conoff command. The console can be used to display details or progress during script execution. Text is added to the console by subsequent console commands. By default, text is appended to the last line. New lines can be added by using \r\n or a vertical tab (|) character in the text.

The flags parameter is specified as follows:

Flag Description

C Clear previous text in console

E Allow text in console to be edited

Q Quit the script when console is closed

W Wait in console until console is closed

Multiple flags can be specified in any order, separated by a vertical tab (|) character. The C flag is called on subsequent calls to an open console to clear previous text. Note that unlike most of the other user interface boxes, script execution is not paused, but continues as soon as the text is added to the console to allow other processing to proceed. This behaviour can be changed with the Wait flag, which when specified, will cause execution to wait until the close [X] button is pressed on the console.

When the console is the only user interface box required, but other subsequent processing is required, an IDLE command can be used as the last command to keep the script running, and the Q flag specified so that the script will be terminated when the console is closed via the close [X] button. The E flag can be used to allow the user to edit the text in the console. This can be used for limited multi-line text entry.

When the E flag is set, Console returns a value of 0 if there have been no changes or 1 if the text has been modified. This value can be checked with the IFMSG, IFNMSG and CASEMSG commands.

The optional x|y parameter sets the position of the top left hand corner of the console. Either direction can be centred by using C instead of a numeric value. The console can be aligned with the left edge of the screen using L or the right edge using R instead of a numeric x value. Similarly, the console can be aligned with the top or bottom using T or B instead of the numeric y value. The optional w|h parameter sets the width and height of the console. The default width or height can be specified by leaving it blank or using D instead of a numeric value.

The optional localvar parameter returns up to 4096 characters from the text in the console. This is useful when used with the W and E flags to return text entered by the user.

syntax:
console title,text,flags,x|y,w|h,localvar

example:
console Backup progress,Starting backup
delay 50
conoff

CONOFF
Conoff removes a console.

BANNER
Banner displays a banner panel with the text specified. The banner will remain on screen until removed with the Banoff command. A Delay or Wait command can be used to determine how long the banner is displayed. The banner text font and size can be set with a prior SetFont command. By default, only a single line of text can be displayed in a banner, centred both vertically and horizontally.

The optional x|y parameter sets the position of the top left hand corner of the banner. Either direction can be centred by using C instead of a numeric value. The banner can be aligned with the left edge of the screen using L or the right edge using R instead of a numeric x value. Similarly, the banner can be aligned with the top or bottom using T or B instead of the numeric y value. The optional w|h parameter sets the width and height of the banner. The default width or height can be specified by leaving it blank or using D instead of a numeric value. The optional b parameter sets the thickness of the border. The optional flags parameter allows control over the text display as follows:

Flag Description

A sets the banner to always on top

T aligns text to the top of the banner

L aligns text to the left of the banner

C aligns text to the centre of the banner (default)

R aligns text to the right of the banner

Multiple parameters are separated by a vertical tab (|) character and may be placed in any order. When aligned to the top of the banner, multiple lines of text can be displayed.

syntax:
banner text,x|y,w|h,b,flags

example:
banner Loading - please wait....
delay 50
banoff

banner Now is the time for all good people to come to the aid of the party,R|T,,10,A|T|L
msgbox Message,Press OK to clear banner,0
banoff

BANOFF
Banoff removes a Banner.

PROGRESS
Progress displays a progress indicator with the title and text specified. The progress indicator will remain on screen until removed with the Progoff command. The size parameter sets the position of the progress bar and is specified as an integer between 0 and 100.

The optional x|y parameter sets the position of the top left hand corner of the indicator. Either direction can be centred by using C instead of a numeric value. The indicator can be aligned with the left edge of the screen using L or the right edge using R instead of a numeric x value. Similarly, the indicator can be aligned with the top or bottom using T or B instead of the numeric y value. The optional w|h parameter sets the width and height of the indicator. The default width or height can be specified by leaving it blank or using D instead of a numeric value.

syntax:
progress title,text,size,x|y,w|h

example:
progress Progress Meter, Loading\, please wait....,20,10|10
delay 50
banoff

PROGOFF
Progoff removes a progress indicator.

SETFONT
Setfont sets the font used in the user interface boxes as follows:

User Box Description

EditBox Text entry area

PassBox Password entry area

InfoBox Text display area

ListBox List entries

NumBox Number entry area

Console Console display text

Banner Banner text

The fontname parameter is a valid font registered on the system. If the specified font is not found, the closest available font will be substituted. The default system font can be specified by using the font name DEFAULT.

The font size is a point size, typically between 8 and 72. Generally, the user boxes will not resize, so the font size should not be made too large. The default size is 8 pt.

The attribute parameter allows one or more of the following:

Attribute Description

T Thin text

B Bold text

H Heavy bold

I Italics

U Underlined

S Strikeout

Multiple attributes can be specified in any order, separated by vertical tab (|) characters. Not all fonts support all attributes and/or combinations. The default attribute is normal text.

syntax:
setfont fontname,size,attributes

example:
setfont Arial,10,B|U

GETFONT
GetFont gets the current font used in the user interface boxes as for SetFont. The fontname, size and attributes in that order are passed to the local variables specified. The attributes are returned in the same format as for SetFont. Any of the local variables may be omitted if that value is not required.

syntax:
getfont localvar1,localvar2,localvar3

example:
getfont A,B,C

Local Variable Commands:

SETVAR
SetVar sets the value of a local variable. The value is a string of up to 255 characters. The local variable is specified as either A throught to L or 1 through to 4. Note that local variables 1, 2, 3 and 4 will be pre-loaded with any command line parameters.

syntax:
setvar localvar,value

example:
setvar A,test 1 2 3

INCVAR or ADDVAR
IncVar or AddVar increments the local variable by the value specified. If value is omitted, 1 will be assumed. Parameter substitution allows value to be taken from another local variable. Although local variables are stored as strings, the result will treated as representing an integer and stored as a new string. Integer values and results between -2147483648 and +2147483647 (2^-31 and 2³¹-1) are supported.

syntax:
incvar localvar,value
addvar localvar,value

example:
setvar A,0
incvar A
incvar A,10
incvar A,%B

Note that IncVar and AddVar are functionally identical.

DECVAR or SUBVAR
DecVar or SubVar decrements the local variable by the value specified. If value is omitted, 1 will be assumed. Parameter substitution allows value to be taken from another local variable. Although local variables are stored as strings, the result will treated as representing an integer and stored as a new string. Integer values and results between -2147483648 and +2147483647 (2^-31 and 2³¹-1) are supported.

syntax:
decvar localvar,value
subvar localvar,value

example:
setvar A,0
decvar A
decvar A,10
decvar A,%B

Note that DecVar and SubVar are functionally identical.

MULVAR
MulVar multiplies the local variable by the value specified. Parameter substitution allows value to be taken from another local variable. Although local variables are stored as strings, the result will treated as representing an integer and stored as a new string. Integer values and results between -2147483648 and +2147483647 (2^-31 and 2³¹-1) are supported.

syntax:
mulvar localvar,value

example:
setvar A,0
mulvar A,10
mulvar A,%B

DIVVAR
DivVar divides the local variable by the value specified. If value is 0, the division will be ignored and the local variable will remain unchanged. Parameter substitution allows value to be taken from another local variable. Although local variables are stored as strings, the result will treated as representing an integer and stored as a new string. Integer values and results between -2147483648 and +2147483647 (2^-31 and 2³¹-1) are supported.

syntax:
divvar localvar,value

example:
setvar A,100
divvar A,10
divvar A,%B

CONVAR
ConVar converts a number in the local variable specified from one number base to another. Although local variables are stored as strings, the value will treated as representing a number in the the base1 parameter specified. The result in base2 will be stored as a new string in the local variable.

The base parameters allows the following number bases:

Base Description

B(IN) Binary

D(EC) Decimal

H(EX) Hexadecimal

O(CT) Octal

When a base is not specified, Decimal will be used by default.

syntax:
convar localvar,base1,base2

example:
convar A,HEX,BIN
convar A,OCT
convar A,,HEX

ANDVAR
AndVar performs a bitwise logical and of the local variable with the value specified. Parameter substitution allows value to be taken from another local variable. Although local variables are stored as strings, the values will treated as representing a number in the the base parameter specified. The result in the same base will be stored as a new string in the local variable.

The base parameter allows the following number bases:

Base Description

B(IN) Binary

D(EC) Decimal

H(EX) Hexadecimal

O(CT) Octal

When a base is not specified, Decimal will be used by default.

syntax:
andvar localvar,value,base

example:
setvar A,100
andvar A,10
andvar A,1F,HEX
andvar A,17,OCT
andvar A,10110011,BIN
andvar A,%B

ORVAR
Orvar performs a bitwise logical OR of the local variable with the value specified. Parameter substitution allows value to be taken from another local variable. Although local variables are stored as strings, the values will treated as representing a number in the the base parameter specified. The result in the same base will be stored as a new string in the local variable.

The base parameter allows the following number bases:

Base Description

B(IN) Binary

D(EC) Decimal

H(EX) Hexadecimal

O(CT) Octal

When a base is not specified, Decimal will be used by default.

syntax:
orvar localvar,value,base

example:
setvar A,100
orvar A,10
orvar A,1F,HEX
orvar A,17,OCT
orvar A,10110011,BIN
orvar A,%B

XORVAR
Xorvar performs a bitwise logical XOR of the local variable with the value specified. Parameter substitution allows value to be taken from another local variable. Although local variables are stored as strings, the values will treated as representing a number in the the base parameter specified. The result in the same base will be stored as a new string in the local variable.

The base parameter allows the following number bases:

Base Description

B(IN) Binary

D(EC) Decimal

H(EX) Hexadecimal

O(CT) Octal

When a base is not specified, Decimal will be used by default.

syntax:
xorvar localvar,value,base

example:
setvar A,100
xorvar A,10
xorvar A,1F,HEX
xorvar A,17,OCT
xorvar A,10110011,BIN
xorvar A,%B

NOTVAR
Notvar performs a bitwise logical NOT of the local variable. Although local variables are stored as strings, the value will treated as representing a number in the the base parameter specified. The result in the same base will be stored as a new string in the local variable.

The base parameter allows the following number bases:

Base Description

B(IN) Binary

D(EC) Decimal

H(EX) Hexadecimal

O(CT) Octal

When a base is not specified, Decimal will be used by default.

syntax:
notvar localvar,base

example:
setvar A,100
notvar A,10
notvar A,1F,HEX
notvar A,17,OCT
notvar A,10110011,BIN
notvar A,%B

UPVAR
Upvar converts the local variable specified to upper case.

syntax:
upvar localvar

example:
setvar A,test
upvar A

LOVAR
Lovar converts the local variable specified to lower case.

syntax:
lovar localvar

example:
setvar A,TEST
lovar A

TRIMVAR
TrimVar trims left and right whitespace (spaces and tabs) from the text in the local variable specified. If the flag parameter is set to B, the first and last non-whitespace characters will also be removed. This is useful for removing any bracketing characters from the string.

syntax:
trimvar localvar

example:
setvar A,` TEST `
trimvar A

LTRMVAR
LtrmVar trims left whitespace (spaces and tabs) from the text in the local variable specified.

syntax:
ltrmvar localvar

example:
setvar A,` TEST`
ltrmvar A

RTRMVAR
RtrmVar trims right whitespace (spaces and tabs) from the text in the local variable specified.

syntax:
rtrmvar localvar

example:
setvar A,`TEST `
rtrmvar A

APPVAR
Appvar appends the value to a local variable. The value is a string of up to 255 characters or another local variable via command line substitution.

syntax:
appvar localvar,value

example:
appvar A,test 1 2 3
appvar A,%B

TEXTVAR
Textvar converts the HTML or RTF contents of a local variable to plain text. The conversion strips all HTML or RTF information leaving just the text. The only formattting recognised is to provide carriage return/line feeds. The result is returned in the local variable, The type parameter is set to either HTML or RTF. The flag parameter when set to C indicates whether Textvar should continue on from a previous invocation. This is useful when multiple lines of text are being processed.

syntax:
textvar localvar,type,flag

example:
textvar A,RTF
textvar B,HTML,C

FORMVAR
FormVar formats the text in a local variable to the tab stops specified. This is useful for lining up multiple lines of text into columns. The result is returned in the local variable, The tabs parameter is set to the required tabs stops as follows:

Tab    Description

nn    single tab at column nn

n1|n2|n3    tabs at columns n1, n2 and n3

nn!    tab stops every nn columns

(blank)    tab stops every 8 columns

The char parameter sets the character on which to tab. If left blank, this is set to the standard tab character (ie. `\t`). The flag parameter when set to T truncates over-width text to the next tab coulmn.

syntax:
formvar localvar,tabs,char,flag

example:
formvar A
formvar B,10!,,T
formvar B,10|30|45,$,T

EXECUTE
Execute takes the text in the local variable specified and executes it as a script command.

syntax:
execute localvar

example:
execute A

String Commands:

FINDSTR
FindStr finds the first line in text and stores the line in the local variable. Parameter substitution allows text to be taken from another local variable. The internal error flag will be set if the source variable is empty. This can be tested with IFERROR and IFNERROR.

syntax:
findstr text,localvar

example:
findstr %A,B

NEXTSTR
NextStr finds the next line in text and stores the line in the local variable. Parameter substitution allows text to be taken from another local variable. The internal error flag will be set if the source variable is empty. This can be tested with IFERROR and IFNERROR.

syntax:
nextstr text,localvar

example:
nextstr %A,B

LENSTR
Lenstr stores the length of the specified text in a local variable. Parameter substitution allows text to be taken from another local variable.

syntax:
lenstr text,localvar

example:
lenstr This is a test,B
lenstr %A,B

SUBSTR
Substr copies a substring of the specified text in a local variable. The start parameter indicates the starting position of the substring where first character in text is position 1. If the start parameter is specified as E, the substring will be taken from the end of the string.

The length parameter specifies the number of characters to copy to the substring. If the end parameter is specified as E, the substring will be taken from the start character to the end of the string. Parameter substitution allows text, start and/or length to be taken from other local variables.

syntax:
substr text,start,length,localvar

example:
substr This is a test,6,4,B
substr %A,%B,5,C

SRCHSTR
Srchstr locates the starting position of a substring in the specified text and stores it in a local variable. The first character in text is position 1 and the search is case sensitive. If the string is not found, 0 is returned and the internal error flag is set. This can be tested with IFERROR or IFNERROR. Parameter substitution allows text and/or string to be taken from other local variables.

syntax:
srchstr text,string,localvar

example:
srchstr This is a test,is,B
srchstr %A,%B,C

SPLTSTR
SpltStr locates the first occurrence of char in the specified text. The text preceeding it is stored in local variable 1. The succeeding text to the end of the string is stored in local variable 2. The split character is case sensitive. If mutiple characters are specified, the split occurs at the first occurrence of any of the characters.

If the split character(s) is not found, 0 is returned and the internal error flag is set. This can be tested with IFERROR or IFNERROR. Parameter substitution allows text and/or char to be taken from other local variables.

syntax:
spltstr text,char,localvar1,localvar2

example:
spltstr This is a test,e,A,B
spltstr %A,%B,C,D

SCANSTR
ScanStr locates the n-th (num) occurrence of char in the specified text. The text between it and the previous occurrence of char (or the start of text for the first occurrence) is stored in the local variable. The split character is case sensitive. If mutiple characters are specified, the split occurs at the n-th occurrence of any of the characters.

If the n-th occurrence is not found, 0 is returned and the internal error flag is set. This can be tested with IFERROR or IFNERROR. Parameter substitution allows text, char and/or num to be taken from other local variables.

syntax:
scanstr text,char,num,localvar

example:
srchstr This is a test,i,2,A
srchstr %A,%B,%C,D

SORTSTR
Sortstr sorts a string by splitting it into substrings delimited by a specified character. For example, the delimiter could be a line feed, returning a string sorted line by line, or a vertical tab for sorting list box items. The sorted string is stored in a local variable. Parameter substitution allows text, char and/or flag to be taken from other local variables.

The flag character specifies the type of sort as follows:

Flag Description

TA Text ascending, case sensitive

TD Text descending, case sensitive

UA Text ascending, case insensitive

UD Text descending, case insensitive

NA Numeric ascending

ND Numeric descending

The numeric sort tests each character from the start of each substring for a valid digit and builds a number until a non valid digit is found. If the first character is not a digit, the substring is assumed to represent zero.

The flag is not case sensitive, so TA or ta is acceptable. If no flag is specified, TA is assumed.

syntax:
sortstr text,char,localvar,flag

example:
sortstr banana apple egg drink cherry, ,A,TD
sortstr %A,%B,C

REPLSTR
Replstr replaces the text starting at pos with string and stores it in a local variable. Parameter substitution allows text, string and/or pos to be taken from other local variables.

syntax:
replstr text,string,pos,localvar

example:
replstr This is a test,joke,11,B
replstr %A,%B,%C,D

INSRTSTR
Insrtstr inserts string in text at pos and stores it in a local variable. Parameter substitution allows text, string and/or pos to be taken from other local variables.

syntax:
insrtstr text,string,pos,localvar

example:
insrtstr This is a test,really good,11,B
insrtstr %A,%B,%C,D

GREPSTR
Grepstr replaces occurrences of char in text with repchr and stores it in a local variable. The source char is replaced num times. If num is omitted, all occurrences will be replaced. Parameter substitution allows text, char, repchr and/or num to be taken from other local variables.

syntax:
grepstr text,char,repchr,localvar,num

example:
grepstr aaabacadaeafagaaa,a,x,B,5

DELSTR
Delstr deletes text at pos for length and stores it in a local variable. If length is set to A for all or 0, the text will be truncated at pos. Parameter substitution allows text, pos and/or length to be taken from other local variables.

syntax:
delstr text,pos,length,localvar

example:
delstr This is a really good test,11,12,B
delstr %A,%B,%C,D

PARSPATH
ParsPath scans the specified text for a valid pathname and returns the components in the local variables specified. Var1 contains the disk or computer name, var2 contains the path, var3 contains the file name and var 4 contains the file extension - that is, the portion following the first dot to the end of the filename or a second dot. Where the filename has a further extension following a second dot, such as a shortcut of the form filename.ext.lnk, the further portion will be returned in var5. Any or all of the local variables may be specified, depending on what parts of the pathname are required. Parameter substitution allows text to be specified from another local variable.

syntax:
parspath text,var1,var2,var3,var4,var5

example:
parspath c:\windows\media\chimes.wav,A,B,C,D
parspath \\server\c\test.txt,A,,B
parspath c:\windows\media\chimes.wav,A,B,C,D

PARSIP
ParsIP scans the specified text for a valid IP address and returns the components in the local variables specified. Var1 contains the first octet, var2 the second and so on. Any or all of the local variables may be specified, depending on what parts of the address are required. Parameter substitution allows text to be specified from another local variable.

syntax:
parsip text,var1,var2,var3,var4

example:
parsip 10.0.0.1,A,B,C,D

PARSDATE
ParsDate scans the specified text for a valid date and returns the components in the local variables specified. Var1 contains the day, var2 the month and var3 the year. Any or all of the local variables may be specified, depending on what parts of the date are required. Parameter substitution allows text to be specified from another local variable.

syntax:
parsdate text,var1,var2,var3

example:
parsdate 23/4/2001,A,B,C

PARSTIME
ParsTime scans the specified text for a valid time and returns the components in the local variables specified. Var1 contains the hour, var2 the minute and var3 the second. Any or all of the local variables may be specified, depending on what parts of the time are required. Parameter substitution allows text to be specified from another local variable.

syntax:
parstime text,var1,var2,var3

example:
parstime 10:15:35,A,B,C

Byte Manipulation Commands:

SRCHBYTE
SrchByte searches for the specified byte in localvar1 and returns a position index in localvar2. The first byte is at position 1.

syntax:
srchbyte localvar1,byte,localvar2

example:
srchbyte A,$,B

REPLBYTE
ReplByte replaces num bytes in localvar1 with those in localvar2 starting at position pos in localvar1. The first byte is at position 1.

syntax:
replbyte localvar1,pos,num,localvar2

example:
replbyte A,4,6,B

FILLBYTE
FillByte replaces num bytes in localvar1 with the specified byte starting at position pos in localvar1. The byte is specified as an integer between 0 and 255. If num is not specified, 1 is assumed. The first byte is at position 1.

syntax:
fillbyte localvar1,byte,pos,num

example:
fillbyte A,0,6,1

GETBYTE
GetByte gets one or more byte values from the specified local variable and copies them to the second local variable. The first byte is at position 1.

syntax:
getbyte localvar1,pos,num,localvar2

example:
getbyte A,3,5,B

CONBYTE
ConByte converts a byte value in a local variable to a decimal string and vice versa. The flag specifies how to convert the value in the local variable as follows:

Flag Description

S(TR) convert byte value to a decimal string

B(YTE) convert decimal string to a byte

syntax:
conbyte localvar1,flag

example:
conbyte A,s

GREPBYTE
GrepByte replaces num occurences of byte1 in localvar with byte2 for the data size specified, starting at the first byte in localvar. Byte are specified as an integer between 0 and 255. If num is not specified, 1 is assumed. If size is not specified, VARSIZE is assumed.

syntax:
grepbyte localvar,byte1,byte2,num,size

example:
fillbyte A,0,6,1

Environment Variable Commands:

GETENV
Getenv retrieves the value of the specified environment variable and stores it in the specified local variable.

syntax:
getenv localvar,envvar

example:
getenv A,TEMP

PUTENV
Putenv stores the specified value in the environment. The environment variable name should be a string containing letters and numbers with no spaces and preferably in capitals. The value is also a string which may contain spaces. The name plus value is limited to 255 characters or the available space left in the environment, whichever is smaller. An existing environment variable can be deleted by using the name with no value specified.

Note that environment variables created will exist only for the life of the script.

syntax:
putenv envvar,value

example:
putenv TEMP,c:\temp
putenv TEMP,

File Association Commands:

GETASSOC
GetAssoc retrieves the file association for the specified file extension and optionally the command for the specified command type. The file type is returned in localvar1 and the command is returned in localvar2.

syntax:
getassoc ext,localvar1,cmdtype,localvar2

example:
getassoc .txt,A,open,B

SETASSOC
SetAssoc sets the file association for the specified file extension and optionally the command for the specified command type. If the cmdtype and command are set, the cmdtype will appear in the rightclick menu for the file and the command will be executed if selected.

syntax:
setassoc ext,filetype,cmdtype,command

example:
setassoc .txt,txtfile,open,notepad.exe

DELASSOC
DelAssoc deletes the file association for the specified file extension and optionally the command for the specified command type.

syntax:
delassoc ext,filetype

example:
delassoc .txt

FNDASSOC
FndAssoc finds the first registered file association and returns it in the local variable specified. The find will fail and the internal error flag set if no association can be found. This can be checked with the IFERROR and IFNERROR commands.

syntax:
fndassoc locavar

example:
fndassoc A

NXTSSOC
NxtAssoc finds the next registered file association and returns it in the local variable specified. The find will fail and the internal error flag set if no further association can be found. This can be checked with the IFERROR and IFNERROR commands.

syntax:
nxtassoc locavar

example:
nxtassoc A

File Commands:

COPYFILE
Copyfile copies a source file or directory to a destination file or directory. Copyfile will first assume that the source and destination are files. If this fails, the destination will be assumed to be a directory. If this still fails, both source and destination will be assumed to be directories and all files in the source directory will be copied into the destination directory. Wild cards may be specified for the source file, but the destination should specify a directory.

When multiple files are copied, the names of the files that are copied can be obtained by opening a console prior to starting the copy. In this situation, the file names will be supplied to the console automatically. The number of files copied is returned in the %N (number count) local variable.

The option flag parameter determines whether the destination file will be overwritten if it already exists. If flag is set to YES, the destination file will be overwritten. If flag is set to NEW, the destination file will only be overwritten if the source file is newer. Otherwise, the destination file will not be overwritten.

syntax:
copyfile source,destination[,flag]

example:
copyfile test1.txt,test2,YES
copyfile c:\dir1\*.txt,c:\dir2,NEW

MOVEFILE
Movefile moves a source file or directory to a destination file or directory. Movefile will first assume that the source and destination are files. If this fails, the destination will be assumed to be a directory. If this still fails, both source and destination will be assumed to be directories and all files in the source directory will attempt to be moved into the destination directory. Wild cards may be specified for the source file, but the destination should specify a directory. The move will fail if the destination pathname already exists.

When multiple files are moved, the names of the files that are moved can be obtained by opening a console prior to starting the move. In this situation, the file names will be supplied to the console automatically. The number of files moved is returned in the %N (number count) local variable.

syntax:
movefile source,destination

example:
movefile temp.txt,test.txt
movefile c:\temp\test.txt,c:\files\test.txt
movefile c:\temp\temp.txt,c:\files\test.txt

READDATA
ReadData copies a block of data from a source file to a local variable, limited to VARSIZE bytes. If flag is E, the data will be read from the end of the file. If flag is omitted, the first block of data will be read.

The localvar2 parameter specifies the number of bytes to be read, up to VARSIZE. If omitted, VARSIZE bytes will be read. The localvar2 parameter also returns the actual number of bytes read.

The localvar3 parameter specifies the point in the file at which to read the requested bytes. If omitted, bytes will be read from the start or end of file determined by the flag parameter. If the E flag is specified, the localvar3 parameter effectively specifies the end of the block to be read, as the block is from that point back towards the start of the file. The localvar3 parameter also returns a pointer to the physical start of the block within the file. This can be used to save a modified block of data back to the file.

The read will fail and the internal error flag will be set if the source file doesn't exist or there is no data to read. This can be checked with the IFERROR and IFNERROR commands.

syntax:
readdata source,localvar,flag,localvar2,localvar3

example:
readdata test1.txt,A
readdata test1.txt,A,E

NEXTDATA
NextData copies the next block of data from a source file to a local variable, limited to VARSIZE bytes. If flag is E, the next block data from the end of the file will be read. If flag is omitted, the next block of data from the start of the file will be read. This command should not be used without a preceding READDATA command or the data returned will be unpredictable.

The localvar2 parameter specifies the number of bytes to be read, up to VARSIZE. If omitted, VARSIZE bytes will be read. The localvar2 parameter also returns the actual number of bytes read.

The read will fail and the internal error flag will be set if the source file doesn't exist or there is no data to read. This can be checked with the IFERROR and IFNERROR commands.

syntax:
nextdata source,localvar,flag,localvar2

example:
nextdata test1.txt,A
nextdata test1.txt,A,E

READLINE
ReadLine copies a line of text from the specified file to a local variable, limited to the first 2048 characters. It is only intended for small amounts of data. By default, the first line is returned, unless the linenum parameter is specified.

The read will fail and the internal error flag will be set if the source file doesn't exist or there are no lines to read. This can be checked with the IFERROR and IFNERROR commands.

syntax:
readline filename,localvar,linenum

example:
readline test1.txt,A
readline test1.txt,A,8

NEXTLINE
NextLine copies the next line of a source file to a local variable, limited to the first 2048 characters. This command is only valid after a READLINE command. The read will fail and the internal error flag set if the source file doesn't exist or there are no more lines to read. This can be checked with the IFERROR and IFNERROR commands.

syntax:
nextline filename,localvar

example:
nextline test1.txt,A

SAVETEXT
SaveText copies the text in the first parameter to the destination file specified in the second parameter. The parameter can also be a local variable by using %A, %B, etc. The save will overwrite the file if it already exists unless flag is A, in which case the text will be appended.

syntax:
savetext text,destination,flag

example:
savetext This is some text,test.txt
savetext Line1\r\nLine2\r\nLine3,test.txt
savetext %A,test.txt,A

SAVEDATA
SaveData copies the data in the first parameter to the destination file specified in the second parameter. The data can be text or binary. The data can also be a local variable by using %A, %B, etc. The save will overwrite the file if it already exists unless flag is A, in which case the data will be appended.

The flag character specifies the type of save as follows:

Flag Description

C Create a new file, erasing any previous file of that name (default)

A Append data to the end of the file

O Overwrite the previous data in the file

The localvar1 parameter specifies the number of bytes to be saved, up to VARSIZE. If omitted, VARSIZE bytes will be saved. The localvar1 parameter also returns the actual number of bytes saved.

The localvar2 parameter specifies the point in the file at which to save the specified bytes. If omitted, bytes will be saved to the start or appended determined by the flag parameter. The localvar2 parameter also returns a pointer to the physical start of the block within the file.

syntax:
savedata parameter,destination,flag,localvar1,localvar2

example:
savedata This is some data,test.txt,,17
savedata %A,test.txt,A,256

SORTFILE
Sortfile sorts a text file line by line. The sorted file is copied to the destination file leaving the source in its original state. The column parameter specifies the column to base the sort on. Columns are numbered starting at 1 (the default). If a line is shorter than the specified column, the last character in the line will be used as the sort character.

The flag character specifies the type of sort as follows:

Flag Description

TA Text ascending, case sensitive

TD Text descending, case sensitive

UA Text ascending, case insensitive

UD Text descending, case insensitive

NA Numeric ascending

ND Numeric descending

The numeric sort tests each character starting from the specified column of each line for a valid digit and builds a number until a non valid digit is found. If the first character is not a digit, the line is assumed to represent zero.

The flag is not case sensitive, so TA or ta is acceptable. If no flag is specified, TA is assumed.

syntax:
sortfile source,destination,column,flag

example:
sortfile input.txt,output.txt
sortfile input.txt,output.txt,5,NA

DELFILE
Delfile deletes the specified file.
Delfile deletes a file or directory. Movefile will first assume that the specified name is a file. If this fails, the name will be assumed to be a directory. Wild cards may be specified. The delete will fail if the filename does not exist or is read only.

When multiple files are deleted, the names of the files can be obtained by opening a console prior to starting the deletion. In this situation, the file names will be supplied to the console automatically. The number of files deleted is returned in the %N (number count) local variable.

syntax:
delfile name

example:
delfile test1.txt
delfile c:\temp

FINDFILE
Findfile finds the first file that matches the specified pathname and stores it in the local variable. The find will fail and the internal error flag will be set if the file can't be found. This can be checked with the IFERROR and IFNERROR commands.

syntax:
findfile pathname,localvar

example:
findfile c:\temp\*.*,A

NEXTFILE
Nextfile finds the next file that matches the pathname specified in the previous Findfile command and stores it in the local variable. The find will fail and the internal error flag will be set if the file can't be found. This can be checked with the IFERROR and IFNERROR commands.

syntax:
nextfile localvar

example:
nextfile A

FILETIME
Filetime returns time/date info about the specified file to a local variable as determined by the time parameter. The flag parameter specifies the format and depends on the time required.

info Description

A Last Access Time

C Creation time

W Last write time

flag Description

R(AW) Raw elapsed file time

T(IME) Time in hh:mm:ss format

DAT(E) Date in dd/mm/yyyy format

H(OUR) Hours

MIN Minutes

S(EC) Seconds

DAY Day of month

W(DAY) Day of week

MON Month

Y(EAR) Year

The raw file time is the elapsed time in seconds since 1st Jan 1601. This can be used to compare file dates and times.

syntax:
filetime filename,localvar,time,flag

example:
filetime test.txt,A,C,DATE

SETFTD
SetFTD sets the file time/date stamp for the specified file as determined by the time and date parameters. The date parameter is specified in the format dd/mm/yyyy. The four digit date should be 1980 or greater. The time parameter is set in the form hh:mm:ss in 24 hour format. The flag parameter specifies the particular time/date stamp to be changed.

flag Description

A Last Access Time

C Creation time

W Last write time

The date and time parameters default to the current time and date. The flag parameter must be specified - there is no default.

syntax:
setftd filename,date,time,flag

example:
setftd test.txt,1/1/2002,8:00:00,W

FILESIZE
Filesize returns the size of the specified file in bytes to a local variable.

syntax:
filesize filename,localvar

example:
filesize test.txt,A,

GETATTR
Getattr returns the attributes for the specified file to a local variable. The attribute value returned is interpreted as follows:

Attribute Value

Normal 0

Read only 1

Hidden 2

System 4

Directory 16

Archive 32

Compressed 128

Temporary 256

These values are added together, so that a file with system, hidden and read only attributes set will return a value of 7. The flag parameter can be used to test if a particular attribute is set, regardless of the others as follows:

Attribute Value

Read only R

Hidden H

System S

Directory D

Archive A

Compressed C

Temporary T

In this case, the value returned will be non-zero (set to the value above) if the specified attribute is set, or zero if it is not, even if other attributes are set.

syntax:
getattr filename,localvar,flag

example:
getattr test.txt,A,R

SETATTR
Setattr sets the attributes for the specified file. The attribute value is specified as follows:

Attribute Value

Normal 0

Read only 1

Hidden 2

System 4

Archive 8

Offline 16

Temporary 32

These values are added together, so that a value of 7 will set system, hidden and read only attributes. Alternatively, individual attributes can be set as follows:

Attribute Value

Normal N

Read only R

Hidden H

System S

Archive A

Offline O

Temporary T

In this case, only one attribute can be set at a time.

syntax:
setattr filename,attr

example:
setattr test.txt,R

FILESRCH
Filesrch searches the specified file and returns the first occurrence of the given text to a local variable. By default, the search is case sensitive. Case is ignored if the flag parameter is i(gnore).

Filesrch also supports the use of the two wild card characters, question mark (?) and asterisk (*). The question mark is a single character wild card and will match any character appearing in the same position, i.e. a?b?c will match a1b2c or aabbc, but not abc or a11b11c. The asterisk is an n character wild card and will match 0 or more characters appearing in the same position, i.e. a*b*c will match abc, alphabet cup, or aabbc. Note that wild cards must be enclosed within delimiter ` characters.

The search will fail and the internal error flag will be set if the text can't be found. This can be checked with the IFERROR and IFNERROR commands.

syntax:
filesrch filename,text,localvar,flag

example:
filesrch test.txt,hello there,A
filesrch test.txt,`he?? there`,B,I
filescrh test.txt,`h*e`,B,I

NEXTSRCH
Nextsrch searches the specified file and returns the next occurrence of the given text to a local variable. By default, the search is case sensitive. Case is ignored if the flag parameter is i(gnore).

Nextsrch also supports the use of the two wild card characters, question mark (?) and asterisk (*). The question mark is a single character wild card and will match any character appearing in the same position, i.e. a?b?c will match a1b2c or aabbc, but not abc or a11b11c. The asterisk is an n character wild card and will match 0 or more characters appearing in the same position, i.e. a*b*c will match abc, alphabet cup, or aabbc. Note that wild cards must be enclosed within delimiter ` characters.

The search will fail and the internal error flag will be set if the text can't be found. This can be checked with the IFERROR and IFNERROR commands.

syntax:
nextsrch filename,text,localvar,flag

example:
nextsrch test.txt,hello there,A
nextsrch test.txt,`he?? there`,B,I
nextsrch test.txt,`h*e`,B,I
test.txt,hello there,B,I

FILESCAN
FileScan scans the specified file and returns the total number of occurrence of the given text to a local variable. By default, the search is case sensitive. Case is ignored if the flag parameter is i(gnore).

FileScan also supports the use of the two wild card characters, question mark (?) and asterisk (*). The question mark is a single character wild card and will match any character appearing in the same position, i.e. a?b?c will match a1b2c or aabbc, but not abc or a11b11c. The asterisk is an n character wild card and will match 0 or more characters appearing in the same position, i.e. a*b*c will match abc, alphabet cup, or aabbc. Note that wild cards must be enclosed within delimiter ` characters.

The search will fail and the internal error flag will be set if the text can't be found. This can be checked with the IFERROR and IFNERROR commands.

syntax:
filescan filename,text,localvar,flag

example:
filescan test.txt,hello there,A
filescan test.txt,`he?? there`,B,I
filescan test.txt,`h*e`,B,I

Directory Commands:

SETDIR
Setdir changes the current directory to that specified. The directory must exist or the set will fail.

syntax:
setdir directoryname

example:
setdir temp
setdir c:\temp

GETDIR
Getdir copies the name of the current directory to the local variable specified.

syntax:
getdir localvar

example:
getdir A

MAKEDIR
Makedir creates the specified directory. If a relative name is specified, the directory will be created from the current directory. The operation will fail if the directory already exists.

syntax:
makedir directoryname

example:
makedir temp
makedir c:\test\temp

DELDIR
Deldir deletes the specified directory. The directory must be empty or the delete will fail.

syntax:
deldir directoryname

example:
deldir temp
deldir c:\temp
delfile c:\test\*.*
deldir c:\test

Disk Commands:

GETDISK
Getdisk retrieves the current disk drive or computer resource to the local variable specified. The internal error flag will be set if no drive is found. This can be tested with the IFERROR or IFNERROR commands.

syntax:
getdisk localvar

example:
getdisk A

FINDDISK
Finddisk returns the drive letter of the first installed disk to the local variable specified. The internal error flag will be set if no drive is found. This can be tested with the IFERROR or IFNERROR commands.

syntax:
finddisk localvar

example:
finddsik A

NEXTDISK
Nextdisk returns the drive letter of the next installed disk to the local variable specified. The internal error flag will be set if no further drive is found. This can be tested with the IFERROR or IFNERROR commands.

syntax:
nextdisk localvar

example:
nextdsik A

DISKSIZE
Disksize causes the total disk size in bytes for the disk specified to be stored in the local variable. A directory can also be specified to determine the size of the directory.

syntax:
disksize disk,localvar

example:
disksize c,A
msgbox Disk Size,Total disk size for drive C: is %A bytes,0

DISKFREE
Diskfree causes the free disk size in bytes for the disk specified to be stored in the local variable. Note that this may be different to that displayed in the disk properties dialog as this dialog itself consumes a small amount of disk space when invoked.

syntax:
diskfree disk,localvar

example:
diskfree c,A
msgbox Disk Size,Free disk size on drive C: is %A bytes,0

DISKUSED
Diskused causes the used disk size in bytes for the disk specified to be stored in the local variable. Note that this may be different to that displayed in the disk properties dialog as this dialog itself consumes a small amount of disk space when invoked.

syntax:
diskused disk,localvar

example:
diskused c,A
msgbox Disk Size,Used disk size on drive C: is %A bytes,0

DISKTYPE
Disktype copies info about a disk drive to the local variable specified. The info is returned as a number or descriptive text as follows:

Value Desc Meaning

-1 Undefined Operating system returned undefined info

0 Unknown Disk is unknown

1 No root Disk has no root directory

2 Removable Disk is removable

3 Fixed Disk is a fixed drive

4 Network Disk is a network or remote drive

5 CD-ROM Disk is a CD-ROM

6 RAM Disk is a RAM drive

By default, the number is returned. The flag parameter is set to v for verbose to return the descriptive text. Parameter substitution allows drive letter and/or flag to be taken from other local variables.

syntax:
disktype drive,localvar,flag

example:
disktype C,A,v

LOAD
Load media into the drive letter specified. This can be used to close the tray of a CD-ROM drive. Parameter substitution can be used to allow the drive letter to be taken from a local variable. The drive letter can include a colon if desired.

syntax:
load drive

example:
load E
load d:

EJECT
Eject media from the drive letter specified. This can be used to eject a CD-ROM from a drive. Parameter substitution can be used to allow the drive letter to be taken from a local variable. The drive letter can include a colon if desired.

syntax:
eject drive

example:
eject E
eject d:

Registry Commands

SETREG
Setreg saves data to a registry key value. The keyvalue consists of a mnemonic for the root branch, followed by the full path of the key, followed by the value name. The data to be saved can be either binary, dword or string.

The root branch mnemonics are:

Mnemonic Key Root Branch

HKCR HKEY_CLASSES_ROOT

HKCC HKEY_CURRENT_CONFIG

HKCU HKEY_CURRENT_USER

HKLM HKEY_LOCAL_MACHINE

HKU HKEY_USERS

Key Value data type is specified as follows:

Data Type Meaning Notes

B Binary specified as hexadecimal pairs which may be optionally separated by spaces

D Double word specified as a single hexadecimal number between 0 and FFFFFFFF

S String specified as plain text

E Expanded String specified when the data contains a system variable enclosed with percent (%) characters

M Multivalued String specified by separating the individual strings with a vertical tab (|) character

The key must exist or the set will fail will fail and the internal error flag will be set. This can be checked with the IFERROR and IFNERROR commands.

If the value name doesn't exist, it will be created under the specified key. The default value for the specified key can be set by using the value name default in brackets, ie. (default)

syntax:
setreg keyvalue,type,data

example:
setreg HKCU\Control Panel\Colors\Button Text,S,test
setreg HKCU\Network\RestoreDiskChecked,D,1
setreg HKCU\RemoteAccess\DialUI,B,02 00 00 00

GETREG
Getreg copies the data in a registry key value to the local variable specified. The key value is specified as for Setreg but no data is required. The get will fail and the internal error flag will be set if the keyvalue can't be found. This can be checked with the IFERROR and IFNERROR commands.

The data retrieved is stored in the local variable. String data is stored directly. Dword and binary data is converted to a string. The default value for the specified key can be retrieved by using the value name default in brackets, ie. (default)

syntax:
getreg keyvalue,localvar

example:
getreg HKCU\Control Panel\Colors\Button Text,A
getreg HKCU\Network\RestoreDiskChecked,A
getreg HKCU\RemoteAccess\DialUI,A

DELREG
Delreg deletes the specified keyvalue. The delete will fail and the internal error flag will be set if the key can't be found. This can be checked with the IFERROR and IFNERROR commands.

syntax:
delreg keyvalue

example:
delreg HKCU/test1/test2/value

FINDREG
FindReg finds the first occurrence of a keyvalue in the specified registry key and returns its name to the local variable. Note that the default value is not included.

The find will fail and the internal error flag will be set if a keyvalue can't be found. This can be checked with the IFERROR and IFNERROR commands.

syntax:
findreg key,localvar

example:
findreg HKCU/test1/test2,A

NEXTREG
NextReg finds the next occurrence of a keyvalue in the specified registry key and returns its name to the local variable. Note that the default value is not included. Also note that values are not returned in any particular order.

The find will fail and the internal error flag will be set if a further keyvalue can't be found. This can be checked with the IFERROR and IFNERROR commands.

syntax:
nextreg key,localvar

example:
nextreg HKCU/test1/test2,A

MAKEKEY
Makekey creates the specified key or subkey branch.

If the make fails, the internal error flag will be set. This can be checked with the IFERROR and IFNERROR commands.

syntax:
makekey keybranch

example:
makekey HKCU/test1/test2/test3

DELKEY
Delkey deletes the specified key or subkey.

If the delete fails, the internal error flag will be set. This can be checked with the IFERROR and IFNERROR commands.

syntax:
delkey keybranch

example:
delkey HKCU/test1/test2

FINDKEY
FindKey finds the first occurrence of a subkey in the specified registry key and returns its name to the local variable.

The find will fail and the internal error flag will be set if a subkey can't be found. This can be checked with the IFERROR and IFNERROR commands.

syntax:
findkey key,localvar

example:
findkey HKCU/test1/test2,A

NEXTKEY
NextKey finds the next occurrence of a subkey in the specified registry key and returns its name to the local variable. Note that subkeys are not returned in any particular order.

The find will fail and the internal error flag will be set if a further subkey can't be found. This can be checked with the IFERROR and IFNERROR commands.

syntax:
nextkey key,localvar

example:
nextkey HKCU/test1/test2,A

Printing Commands:

PRINT
Print is used to print a file. It is a special case of the start command and is provided as a programming convenience. In effect, it prepends "write.exe /p " to the specified file name and executes a start command as above. This will execute Wordpad with the /p command line option to print the file.

The same optional parameters for Start may be specified but will be ignored because Wordpad with the /p option executes without a window.

If Notepad (with a /p option) is required instead of Wordpad, use the Start command as above.

syntax:
print filename

example:
print script.txt

GETPRINT
Getprint retrieves the name of the default printer and stores it in the local variable specified.

syntax:
getprint localvar

example:
getprint A
msgbox Default Printer,Default printer is %A,0

SETPRINT
Setprint sets the default printer to the name specified. This name corresponds to the name of the printer as set in the Control Panel.

syntax:
setprint printername

example:
setprint Generic / Text only printer

FINDPRNT
Findprnt copies the name of the first installed printer to the local variable specified. This name corresponds to the name of the printer as set in the Control Panel. The internal error flag will be set if no printer name is found. This can be tested with the IFERROR or IFNERROR commands.

syntax:
findprnt localvar

example:
findprnt A
msgbox Installed Printer,First installed printer is %A,0

NEXTPRNT
Nextprnt copies the name of the next installed printer to the local variable specified. This name corresponds to the name of the printer as set in the Control Panel. The internal error flag will be set if there are no more printers found. This can be tested with the IFERROR or IFNERROR commands.

syntax:
nextprnt localvar

example:
findprnt A
setvar B,1
:loop
iferror end
msgbox Printer %B,%A,0,c
incvar B
:next
nextprnt A
goto loop
:end

Multimedia Commands:

OPEN
Open prepares a multimedia device for use. This command should be used when the script needs to retain full control over the running media through to completion. The device parameter is specified as follows:

Value Description

wav the wave device

mp3 the mpeg device

seq the midi sequencer device

cd the cd audio device

The source parameter specifies what to open. For the wave device, specify the name of a wave file. Use the full path if necessary. For the mpeg device, specify the name of an mp3 file. Use the full path if necessary. For the midi sequencer, specify the name of a mid or rmi file. Use the full path if necessary. For the CD, specify an initial track number - track 1 by default.

syntax:
open device,source,flag

example:
open wav,c:\windows\media\chime.wav
open mp3,c:\windows\media\test.mp3
open seq,c:\windows\media\canyon.mid
open cd,5

SEEK
Seek sets the position of a multimedia device. The device parameter is specified as for the OPEN command. The seek will stop a currently playing device. The position parameter specifies where to seek to. For the wave and mp3 devices, specify a position in milliseconds. For the sequencer, specify a position in units of one sixteenth of a note. For the CD, specify a track number.

Note: Set priority to low when using the multimedia commands, especially for mp3 files.

syntax:
seek device,position

example:
seek wav,1000
seek mp3,1000
seek seq,100
seek cd,4

PLAY
Play plays a previously opened device. The device parameter is specified as for the OPEN command. Play also supports playing devices that have not been opened. In this case, the script has no further control and the file or CD is played through to completion, or until the script terminates. A position or track number can be optionally specified.

syntax:
play device,position

example:
play wav
play mp3
play seq
play cd

or where the device was not previously opened:

play wav,c:\windows\media\chime.wav
play mp3,c:\windows\media\test.mp3
play seq,c:\windows\media\canyon.mid
play cd,5

PAUSE
Pause temporarily suspends a playing device. The device parameter is specified as for the OPEN command.

syntax:
pause device

example:
pause wav
pause mp3
pause seq
pause cd

RESUME
Resume restarts a device after a pause. The device parameter is specified as for the OPEN command.

syntax:
resume device

example:
resume wav
resume mp3
resume seq
resume cd

STOP
Stop terminates a device. If the same file and device are required again in the script, another OPEN command should be performed. The device parameter is specified as for the OPEN command.

syntax:
stop device

example:
stop wav
stop mp3
stop seq
stop cd

GETMEDIA
Getmedia gets information about media opened on a device and stores it in a local variable. The device parameter is specified as for the OPEN command. The flag parameter specifies the information to be retrieved as follows:

Flag Description Possible values

c(urrent) current track number

n(umber) number of tracks number

s(tatus) status of device stopped, playing

m(edia) media available true, false

p(osition) current position in time units as for SEEK command

p|n position in track n in time units as for SEEK

l(ength) total length in time units as for SEEK

l|n length of track n in time units as for SEEK

t(ime) time format tsmf, milliseconds, song pointer

The localvar parameter specifies the local variable to receive the returned value.

syntax:
getmedia device,localvar,flag

example:
getmedia wav,A,l
getmedia mp3,A,s
getmedia cd,A,n
getmedia cd,B,l|4

Shortcut Commands:

MAKELINK
Makelink creates a shortcut to the specified file. The linkname parameter is the relative or absolute pathname of the shortcut and must have a .lnk extension.. If an extension is not specified, .lnk will be used. Any other extension will prevent the shortcut being created. The filename parameter is a relative or full pathname to the target.

The flag parameter, controls the creation of the shortcut. If specified as Y or YES, an existing shortcut will be overwritten. If not specified, an existing shortcut will be preserved and an error returned. This can be used to test for the existence of a shortcut.

The internal error flag will be set if the shortcut cannot be created. This can be tested with the IFERROR or IFNERROR commands.

syntax:
makelink linkname,filename,flag

example:
makelink c:\test.lnk,c:\bootlog.txt

GETLINK
Getlink gets information about the specified shortcut. The linkname parameter is the relative or absolute pathname of the shortcut and must have a .lnk extension. If an extension is not specified, .lnk will be used. Any other extension will cause an error.

The info parameter specifies the particular shortcut parameter to be retrieved as follows:

Info Description

a(rg) command line arguments for the shortcut target

d(esc) shortcut description

h(ot) hotkey to activate the shortcut

i(con) location and index of the shortcut icon

p(ath) path to the shortcut target

s(how) show command when displayed

w(ork) working directory for the target to the shortcut

The d(esc) parameter is an internal description stored with the shortcut that is not normally visible to a user. It can contain any text up to 1000 characters.

The h(ot) parameter is specified as a number

The internal error flag will be set if the specified information cannot be retrieved. This can be tested with the IFERROR or IFNERROR commands.

syntax:
getlink linkname,localvar,info

example:
getlink c:\test.lnk,A,path

SETLINK
Setlink sets information for the specified shortcut. The linkname parameter is the relative or absolute pathname of the shortcut and must have a .lnk extension. If an extension is not specified, .lnk will be used. Any other extension will cause an error.

The info parameter specifies the particular shortcut parameter to be set as follows:

Info Description

a(rg) command line arguments for the shortcut target

d(esc) shortcut description

h(ot) hotkey to activate the shortcut

i(con) location and index of the shortcut icon

p(ath) path to the shortcut target

s(how) show command when displayed

w(ork) working directory for the target to the shortcut

The d(esc) parameter is an internal description stored with the shortcut that is not normally visible to a user. It can contain any text up to 1000 characters.

The h(ot) key parameter is specified as a number which is the addition of the key code and modifier keys as follows:

Key Key code

0 - 9 48 - 57

A - Z 65 - 90

Shift 256

Ctrl 512

Alt 1024

The hotkey should contain at least two modifiers to ensure that it doesn't clash with normal keystrokes used in applications.

The value parameter is the value that should be set.

The internal error flag will be set if the specified information cannot be set. This can be tested with the IFERROR or IFNERROR commands.

syntax:
setlink linkname,info,value

example:
setlink c:\test.lnk,d,Test shortcut

System Tray Commands:

PUTTRAY
PutTray creates an icon representing the running script and puts it in the system tray. When the mouse is positioned over the icon, the text specfied in the first parameter is displayed in a tooltip. When the icon is clicked, execution branches to the label specified in the second parameter. Two different clicks can be set, branching to two different labels. When a second click is required, the labels must be separated with a | character. The icon can be specified in the third parameter as follows:

Icon Description

A Application window icon

E Exclamation mark icon

I Information icon

F Icon file

L Windows logo icon

Q Question mark icon

S Script icon

X Red X icon

If F is specified, the name of the icon file should follow immediately after (eg. Ftest.ico). If no icon is specified, the script icon will be used.

The fourth parameter can be used to set the mouse click as follows

Click Description

LC Left mouse click

LD Left mouse double click

RC Right mouse click

RD Right mouse double click

When a second click is required, they must be separated with a | character. If no click is specified, the left mouse double click will be used.

syntax:
puttray text,label1|label2,icon,click1|click2

examples:
puttray Scheduled Backup,exit
puttray Scheduled Backup,exit,X
puttray Scheduled Backup,exit,X,RD
puttray Scheduled Backup,settim|exit,X,LD|RC

MODTRAY
ModTray modifies an icon previously created with PUTTRAY. The tooltip text, label, icon and click parameters can be changed as for the PUTTRAY command. If any parameter is not specified, it will remain as previously set.

syntax:
modtray text,label,icon,click

example:
modtray Scheduled Backup,,,RC

DELTRAY
DelTray removes the script icon from the system tray.

syntax:
deltray

example:
deltray

Clipboard Commands:

GETCLIP
GetClip gets the contents of the windows clipboard and stores it in the local variable specified, up to varsize. The flag parameter specifies the type of data to be retrieved. Default is plain text.

Flag Description

B(ITMAP) Windows bitmap file

H(TML) HTML Formatted file

M(SHTML) Microsoft HTML Formatted

R(TF) Rich Text Formatted text

TE(XT) Plain text

TI(FF) Picture file in TIFF format

W(AVE) Wave audio file in standard format

When the HTML flag is used, the data is copied from the clipboard "as is". The MSHTML flag will automatically look for and remove header and trailer information around the data that conforms to the Microsoft convention for HTML formatted fragments. This flag can be used when copying data placed on the clipboard by Microsoft applications, or any other applications using this convention, where you want to retrieve just the fragment.

The internal error flag will be set if there is no data to retrieve. This can be tested with the IFERROR or IFNERROR commands.

syntax:
getclip localvar,flag

example:
getclip A,RTF
getclip B

SETCLIP
SetClip copies the specified data to the windows clipboard. Parameter substitution can be used to copy from a local variable, up to varsize. The flag parameter specifies the type of data to be stored. Default is plain text.

Flag Description

B(ITMAP) Windows bitmap file

H(TML) HTML Formatted file

M(SHTML) Microsoft HTML Formatted

R(TF) Rich Text Formatted text

TE(XT) Plain text

TI(FF) Picture file in TIFF format

W(AVE) Wave audio file in standard format

When the HTML flag is used, the data is placed on the clipboard "as is" and so should be well formatted HTML - that is, contain all starting and ending tags. The MSHTML flag will automatically put header and trailer information around the data that conforms to the Microsoft convention for HTML formatted fragments. HTML put on the clipboard using this flag is suitable for pasting into Microsoft applications, or any other applications using this convention.

The internal error flag will be set if the data cannot be set. This can be tested with the IFERROR or IFNERROR commands.

syntax:
setclip data,flag

example:
setclip This is a test
setclip %B,RTF

CLRCLIP
ClrClip clears the windows clipboard.

syntax:
clrclip

example:
clrclip

Internet Commands:

GETURL
GetURL retrieves the text contents of an Internet URL. The text is stored in a temporary file whose name is returned in the local variable specified.

The internal error flag will be set if there is no text to retrieve. This can be tested with the IFERROR or IFNERROR commands.

syntax:
geturl url,localvar

example:
geturl http://www.melbpc.org.au/index.html,A

PING
Ping checks for a connection to a host computer using the internet ICMP standard. The host can be specified as a dot separated four part numeric address, or as host name. The optional timeout value sets how long to wait in seconds for a reply from the host - default value is 2 secs. The optional size value sets the no of bytes in the test packet - default size is 32 bytes. The TTL sets the time to live in milliseconds for the test packet - default is 1000 msec or 1 sec.

The internal error flag will be set if there is no response from the host, or the response is invalid. This can be tested with the IFERROR or IFNERROR commands.

syntax:
ping host,timeout,size,TTL

example:
ping 192.168.0.1,5
ping www.test.com.au,10,64,250

Execution Control Commands

GOTO
Goto allows unconditional branching. Control is transferred to the label name contained in the goto line. Labels can be before or after the current line. If a label appears more than once, control will be transferred to the first occurrence of the label.

syntax:
goto label

example:
goto exit
.
.
.
:exit

GOSUB
Gosub allows branching to subroutine. Control is transferred to the label name contained in the gosub line. This is similar to the GOTO command except that the command following the GOSUB is saved so that execution can resume at that command after return from the subroutine. Only one level of subroutine is allowed.

Labels can be before or after the current line. If a label appears more than once, control will be transferred to the first occurrence of the label.

syntax:
gosub label

example:
gosub test
goto exit
:test
Msgbox Message,In subroutine,0
return
:exit

RETURN
Return is used at the end of a subroutine to return to the command immediately following the calling GOSUB. If RETURN is encountered without a calling GOSUB, the RETURN will be ignored and execution will continue with the command following the RETURN.

syntax:
return

example:
return

CASEMSG
Casemsg allows conditional branching based on the message value returned by the previous command. Control is transferred to the label name corresponding to the message value.

The following commands return a message value.

Command Description Value

MSGBOX OK
Cancel
Abort
Retry
Ignore
Yes
No
Try Again
Continue 1
2
3
4
5
6
7
10
11

MENUBOX Cancel
Selected item in menu 0
1..7

LISTBOX Cancel
Selected item in list 0
1..n

EDITBOX OK
Cancel 1
2

FILEBOX OK
Cancel 1
2

Labels can be before or after the current line.

syntax:
casemsg label1|label2|label3|...|labeln

example:
editbox Test
casemsg exit|ok|cancel
.
.
.
:exit

IFMSG, IFNMSG
Ifmsg and Ifnmsg allow conditional branching based on the message value returned by the previous command. Control is transferred to the label name contained in the Ifmsg/Ifnmsg line if the result specified matches/doesn't match the button pressed in the last message box displayed. The buttons are represented by either the following text or numbers:

Text Number

OK 1

Cancel 2

Abort 3

Retry 4

Ignore 5

Yes 6

No 7

Try Again 10

Continue 11

Labels can be before or after the current line.

syntax:
ifmsg result,label
ifnmsg result,label

example:
msgbox Test,Click a button,2
ifmsg cancel,exit
.
.
.
:exit

IFERROR, IFNERROR
Iferror and Ifnerror allow conditional branching based on the results of a previous command. Control is transferred to the label name contained in the Iferror or Ifnerror line. Labels can be before or after the current line.

syntax:
iferror label
ifnerror label

example:
iferror exit
.
.
.
:exit

IFBIT, IFNBIT
Ifbit and Ifnbit allow conditional branching based on the value of a bit in the local variable specified. If the bit is set (Ifbit) or clear (Ifnbit), control is transferred to the line containing the label name. The bit is specified as 0 for the least significant bit through to 31 for the most significant bit. Labels can be before or after the current line.

syntax:
ifbit localvar,bit,label
ifnbit localvar,bit,label

example:
ifbit A,3,exit
.
.
.
:exit

IFEXIST, IFNEXIST
Ifexist/Ifnexist checks for the file specified. If the file exists/doesn't exist, control is transferred to the label whose name appears immediately after the filename. Special characters (, \ % ^ ? * $ #) which appear in the filename string must be escaped.

syntax:
ifexist filename,label
ifnexist filename,label

example:
ifexist c:\winnt\notepad.exe,loop

IFVAR, IFNVAR
Ifvar and Ifnvar check the string value of a local variable and branch on the result. Parameter substitution can be used to compare one local variable with another.

syntax:
ifvar localvar,value,label
ifnvar localvar,value,label

example:
ifvar A,test,exit
.
.
.
:exit

IFEVAR, IFGVAR, IFLVAR
Ifevar, Ifgvar and Iflvar check the integer value of a local variable against the value specified and branch if the local variable is respectively equal, greater or less. Parameter substitution can be used to compare one local variable with another.

syntax:
ifevar localvar,value,label
ifgvar localvar,value,label
iflvar localvar,value,label

example:
ifgvar A,%B,exit
.
.
.
:exit

CASEVAR
CaseVar allows conditional branching based on the value in the supplied local variable. The values parameter is a list of possible values, separated by a vertical tab (|) character. The labels parameter is a matching list of labels, also separated by vertical tabs. Control is transferred to the label name corresponding to the value matching the contents of the local variable.

Labels can be before or after the current line. If no match is found, execution continues with the next command following the casevar command.

syntax:
casevar localvar,value1|value2|...|valuen,label1|label2|...|labeln

example:
editbox Test,Enter the name of a fruit,A
casevar A,apple|banana|orange|mango,goapple|gobanana|goorange|gomango
goto nomatch

Windows Information Commands

GETNAME
Getname causes the computer name to be stored in the local variable specified.

syntax:
getname localvar

example:
getname A
msgbox Computer name,Computer name is %A,0

GETUSER
Getuser causes the current user name to be stored in the local variable specified.

syntax:
getuser localvar

example:
getuser A
msgbox User name,Current user is %A,0

GETTIME
Gettime causes the system time to be stored in the local variable specified. The flag parameter is used to specify which part of the time is required as follows:

Flag Description

c complete (default if flag is omitted)

h hours

m minutes

s seconds

f AM or PM

The complete time is stored in hh:mm:ss format, padded with leading zeros for single digit parts.

The format parameter is used to indicate whether hours should be stored in 12 or 24 hour format as follows:

Format Description

y 24 hour (default if format parameter omitted)

n 12 hour

If 12 hour format is specified and flag is c (or omitted), AM or PM will be appended to the complete time.

syntax:
gettime localvar,flag,format

example:
gettime A
msgbox Time,System time is %A,0

GETDATE
Getdate causes the system date to be stored in the local variable specified. The flag parameter is used to specify which part of the date is required as follows:

Flag Description

c complete (default if flag is omitted)

w day of week

d day of month

m month of year

y years

The complete date is stored in DD/MM/YY or DD/MM/YYYY format, padded with leading zeros for single digit parts.

The format parameter is used to control the display format based on the flag as follows:

Flag Format Description

c s year number in short 2 digit format

l year number in long 4 digit format (default)

w n Displayed as a number 0=Sun, 1=Mon etc. (default)

s name of day in short format (first 3 letters)

l name of day in long format (full name)

m n number 1=Jan, 2=Feb, etc. (default)

s name of month in short format (first 3 letters)

l name of month in long format (full name)

y s number in short 2 digit format

l number in long 4 digit format (default)

syntax:
getdate localvar,flag,format

example:
getdate A
msgbox Date,System date is %A,0

SETTIME
SetTime sets the local system time to the values specified. Hours should be specified in 24 hour form. Any part of the time not specified will be set to 0. Any part set to an invalid value will be ignored.

syntax:
settime hours,mins,secs

example:
settime 10,23,45
settime 22,30

SETDATE
SetDate sets the local system date to the values specified. Years should be specified in 4 digit form. All parts of the date must be specified. Any part set to an invalid value will be ignored.

syntax:
setdate days,mons,years

example:
setdate 10,2,2003

RAWDATE
RawDate converts a date and time to a "raw" date suitable for date calculations. The raw date is the number of elapsed seconds from 1 Jan 1601 and is returned in the local variable. If the time component is omitted, midnight is assumed.

syntax:
rawdate dd/mm/yyyy,hh:mm:ss,localvar

example:
rawdate 10/2/2003,10:30:00,A
rawdate 10/2/2003,,A

WINVER
Winver causes the windows version information to be stored in the local variable specified. The information stored is set by the flag value as follows:

Flag Description Possible values

f family 9X,NT

p platform 95,98,ME,NT,2000

m major version no. 3,4,5...

n minor version no. 51,0,10...

x extra info service pack for NT/2000
revision level for 95/98/ME

If flag is null or omitted, p will be assumed.

syntax:
winver localvar,flag

example:
windir A,p
msgbox Windows Version,Running Windows %A,0

WINDIR
Windir causes the windows directory name to be stored in the local variable specified.

syntax:
windir localvar

example:
windir A
msgbox Windows Directory,Windows directory is %A,0

SYSDIR
Sysdir causes the system directory name to be stored in the local variable specified.

syntax:
sysdir localvar

example:
sysdir A
msgbox System Directory,System directory is %A,0

SPECDIR
Specdir causes the directory path of a special folder to be stored in the local variable specified. The folder is specified as follows:

Folder Description

ALLD(ESKTOP) File system directory that contains files and folders that appear on the desktop for all users.

ALLF(AVORITES) File system directory that serves as a common repository for all users' favorite items.

ALLP(ROGRAMS) File system directory that contains the directories for the common program groups that appear on the Start menu for all users.

ALLSTARTM(ENU) File system directory that contains the programs and folders that appear on the Start menu for all users.

ALLSTARTU(P) File system directory that contains the programs that appear in the Startup folder for all users.

AP(PDATA) File system directory that serves as a common repository for application-specific data.

C(OOKIES) File system directory that serves as a common repository for Internet cookies.

D(ESKTOP) File system directory used to physically store file objects on the desktop

F(AVORITES) File system directory that serves as a common repository for the user's favorite items.

H(ISTORY) File system directory that serves as a common repository for Internet history items.

I(NTERNETCACHE) File system directory that serves as a common repository for temporary Internet files.

N(ETHOOD) File system directory containing objects that appear in the network neighborhood.

PE(RSONAL) File system directory that serves as a common repository for documents (My Documents).

PRI(NTHOOD) File system directory that serves as a common repository for printer links.

PRO(GRAMS) File system directory that contains the user's program groups (which are also file system directories).

RECE(NT) File system directory that contains the user's most recently used documents.

RECY(CLEBIN) File system directory containing file objects in the user's Recycle Bin.

SE(NDTO) File system directory that contains Send To menu items.

STARTM(ENU) File system directory containing Start menu items.

STARTU(P) File system directory that corresponds to the user's Startup program group. The system starts these programs whenever any user logs onto Windows NT or starts Windows 95.

T(EMPLATES) File system directory that serves as a common repository for document templates.

The full physical path of the specified folder is returned in the local variable.

syntax:
specdir folder,localvar

example:
specdir desktop,A
msgbox Desktop Directory,Directory is %A,0

MEMSIZE
Memsize causes the physical memory size in megabytes to be stored in the local variable specified.

syntax:
memsize localvar

example:
memsize A
msgbox Memory Size,System memory size is %A Mbytes,0

GETSCRNX
Getscrnx causes the screen width to be stored in the local variable specified.

syntax:
getscrnx localvar

example:
getscrnx A
msgbox Screen width,Screen width is %A,0

GETSCRNY
Getscrny causes the screen height to be stored in the local variable specified.

syntax:
getscrny localvar

example:
getscrny A
msgbox Screen height,Screen height is %A,0

Windows Control Commands

SETSCRN
Setscrn sets the screen width, height and colour depth. The width and height are specified in pixels. The colour depth is specified in bits. Parameter substitution can be used to allow values to be taken from local variables. This command is intended to be used to temporarily change the screen size and colour depth to suit a program run by the script. The original size and depth is restored when the script terminates.

syntax:
setscrn width,height,depth

example:
setscrn 1024,768,24
setscrn %A,%B,%C

LOGOFF
Logoff logs off the user. The flag parameter, if set to F, will force all open applications to terminate. This may lead to loss of data if applications have not been saved.

syntax:
logoff flag

example:
logoff
logoff F

SHUTDOWN
Shutdown shuts down the system. The flag parameter, if set to F, will force all open applications to terminate. This may lead to loss of data if applications have not been saved.

syntax:
shutdown flag

example:
shutdown
shutdown F

POWEROFF
Poweroff shuts down and if supported, powers off the system. The flag parameter, if set to F, will force all open applications to terminate. This may lead to loss of data if applications have not been saved.

syntax:
poweroff flag

example:
poweroff
poweroff F

RESTART
Restart shuts down and restarts the system. The flag parameter, if set to F, will force all open applications to terminate. This may lead to loss of data if applications have not been saved.

syntax:
restart flag

example:
restart
restart F

SCRNSAVE
Scrnsave invokes a configured screensaver. This can be used to lock a workstation if the screensaver is set with a password.

syntax:
scrnsave

example:
scrnsave

LOCKPC
LockPC locks a PC workstation. This works only for Windows 2000.

syntax:
lockpc

example:
lockpc

ACTIVATE
Activate brings a window to the foreground.

The text of the window must match the text specified in the windowtitle parameter exactly, except where the wild card characters, question mark (?) and asterisk (*) are used. The question mark is a single character wild card and will match any character appearing in the same position, i.e. a?b?c will match a1b2c or aabbc, but not abc or a11b11c. The asterisk will match 0 or more characters appearing in the same position, i.e. a*b*c will match abc, alphabet cup, or aabbc.

syntax:
activate windowtitle

example:
activate Untitled - Notepad

MINIMISE
Minimise minimises a window to the taskbar.

The text of the window must match the text specified in the windowtitle parameter exactly, except where the wild card characters, question mark (?) and asterisk (*) are used. The question mark is a single character wild card and will match any character appearing in the same position, i.e. a?b?c will match a1b2c or aabbc, but not abc or a11b11c. The asterisk will match 0 or more characters appearing in the same position, i.e. a*b*c will match abc, alphabet cup, or aabbc.

syntax:
minimise windowtitle

example:
minimise Untitled - Notepad

MAXIMISE
Maximise maximises a window to fill the screen.

The text of the window must match the text specified in the windowtitle parameter exactly, except where the wild card characters, question mark (?) and asterisk (*) are used. The question mark is a single character wild card and will match any character appearing in the same position, i.e. a?b?c will match a1b2c or aabbc, but not abc or a11b11c. The asterisk will match 0 or more characters appearing in the same position, i.e. a*b*c will match abc, alphabet cup, or aabbc.

syntax:
maximise windowtitle

example:
maximise Untitled - Notepad

RESTORE
Restore restores a window either from the taskbar or from a full screen.

The text of the window must match the text specified in the windowtitle parameter exactly, except where the wild card characters, question mark (?) and asterisk (*) are used. The question mark is a single character wild card and will match any character appearing in the same position, i.e. a?b?c will match a1b2c or aabbc, but not abc or a11b11c. The asterisk will match 0 or more characters appearing in the same position, i.e. a*b*c will match abc, alphabet cup, or aabbc.

syntax:
restore windowtitle

example:
restore Untitled - Notepad

FLASH
Flash flashes the specified window.

The text of the window must match the text specified in the windowtitle parameter exactly, except where the wild card characters, question mark (?) and asterisk (*) are used. The question mark is a single character wild card and will match any character appearing in the same position, i.e. a?b?c will match a1b2c or aabbc, but not abc or a11b11c. The asterisk will match 0 or more characters appearing in the same position, i.e. a*b*c will match abc, alphabet cup, or aabbc.

syntax:
flash windowtitle

example:
flash Untitled - Notepad

CLOSE
Close closes the specified window. The associated program may still intervene to prompt the user to save changes of for other user confirmation .

The text of the window must match the text specified in the windowtitle parameter exactly, except where the wild card characters, question mark (?) and asterisk (*) are used. The question mark is a single character wild card and will match any character appearing in the same position, i.e. a?b?c will match a1b2c or aabbc, but not abc or a11b11c. The asterisk will match 0 or more characters appearing in the same position, i.e. a*b*c will match abc, alphabet cup, or aabbc.

syntax:
close windowtitle

example:
close Untitled - Notepad

DESTROY
Destroy force closes the specified window. The associated program will be closed immediately without opportunity for user confirmation.

The text of the window must match the text specified in the windowtitle parameter exactly, except where the wild card characters, question mark (?) and asterisk (*) are used. The question mark is a single character wild card and will match any character appearing in the same position, i.e. a?b?c will match a1b2c or aabbc, but not abc or a11b11c. The asterisk will match 0 or more characters appearing in the same position, i.e. a*b*c will match abc, alphabet cup, or aabbc.

syntax:
destroy windowtitle

example:
destroy Untitled - Notepad

SETDESK
SetDesk changes the desktop wallpaper to the filename specified.

syntax:
setdesk filename

example:
setdesk picture.bmp

SETBGND
SetBgnd changes the screen background colour the Red, Green and Blue values specified. The values should be a number between 0 and 255.

syntax:
setbgnd red,green,blue

example:
setbgnd 50,100,150

General Commands

DELAY
Delay causes the script to pause for the number of 0.1 second increments specified after the delay command.

syntax:
delay number

example:
delay 50

SUSPEND
Suspend causes the script to pause until the specified time and date is reached. The minimum requirement is to specify an hour between 0 and 23. Minutes and seconds are optional and will be set to 0 if not specified. If the first parameter is specified as H(our), the hour will be set to the next hour. If the first parameter is set to M(inute), the hour will be set to the current hour and the minute will be set to the next minute.

The date is optional. All or part of the date can be specified from left to right. Alternatively, a day of the week can be specified as SUN, MON, TUE, WED, THU, FRI or SAT.

syntax:
suspend hh:mm:ss,DD/MM/YYYY

example:
suspend 2 (suspend until 2am)
suspend H (suspend until start of next hour)
suspend 13:20 (suspend until 1:20pm)
suspend 2,15 (suspend until 2am on the 15th of the month)
suspend 3,sat (suspend until 3am Saturday)

IDLE
Idle causes the script to pause indefinitely. This command can be used with the tray commands to pause until the tray icon is clicked. It can also be used with the CONSOLE command.

syntax:
idle

example:
idle

QUIT
Quit causes the script to immediately end execution. This command is useful to end execution at a point in the script where subroutines follow or to ignore the rest of the script while testing or debugging.

syntax:
quit

example:
quit

BEEP
Beep plays a sound specified by the parameter value as follows.

Parameter Description

0 Beep through internal speaker

1 Sound for OK icon

2 Sound for Hand icon

3 Sound for Question icon

4 Sound for Exclamation icon

5 Sound for Asterisk icon

syntax:
beep value

example:
beep 1

RANDOM
Random generates a random number between 1 and the value specified. The random number is returned in the local variable.

syntax:
random value,localvar

example:
random 10,A

Script Related Commands

REPORT
Report sets the level of reporting if an error is encountered. By default, no reporting is performed. When enabled, errors are reported in a message box. The reporting level is set by the parameter as follows:

Parameter Description

exit the first error is reported and further script processing stops

on errors are reported and script processing continues

off no errors are reported

Reporting is intended to be used to assist in testing the operation of a script.

syntax:
report [off|on|exit]

example:
report exit
report on
report off

STEP
Step shows each command in a message box before it is executed. Clicking the OK button executes the command and steps to the message box for the next command. Clicking the Cancel button executes the command and turns off Step, allowing the script to continue uninterrupted until the next step on command is encountered. By default, step is off.

syntax:
step [off|on]

example:
step on
step off

DEBUG
Debug sets the status of the debug flag, allowing or preventing debug messages being displayed. By default, debug is off.

syntax:
debug [off|on]

example:
debug on
debug off

DBGBOX
Dbgbox displays a line of text in a message box for debugging purposes, controlled by the status of the debug flag. It is also a programming convenience to allow debug messages to be clearly identified in the script. The message box will be sized automatically to suit. The title text is set to Debug.

syntax:
dbgbox message

example:
dbgbox Value of A is %A

VERSION
Version causes the Script version number to be stored in the local variable specified.

syntax:
version localvar

example:
version A
msgbox Script Version,Script is running version %A,0

COMPILE
Compile causes the script file specified to be compiled into a standalone executable file. If the executable file name is not specified, the same name as the script file will be used. Full pathnames should be specified, otherwise the current directory will be assumed. The flag parameter, when set to YES, overwrites an existing executable.

Note that any external program called by the script will still be required as a separate file.

syntax:
compile script,executable,flag

example:
compile test.script,test.exe

PRIORITY
Priority sets the execution priority of the script. By default, priority is normal. This means that the next line in a script will be scheduled to execute as soon as the current line completes. If the level parameter is set to low, each line will be executed as set by the system timer. This depends on the operating system, but typically is every 55 msec for Win 9x/Me and every 10 msec for Win NT/2000. Low priority is intended to be used for scripts that contain loops waiting for some external event or to prevent a script consuming too much processing time.

syntax:
priority level

example:
priority low
priority normal

VARSIZE
Varsize sets the size of internal script variables. This applies to local variables and the length of command parameters but not parameters passed on the command line. The new size will apply from the time it is encountered in the script. The contents of local variables and command parameters will be preserved up to the length of the new varsize. Therefore, it is best to set Varsize at the start of the script.

By default, Varsize is 2048 or 2K characters. In general, Varsize should be set to a power of 2 (eg. 1024, 2048, 4096, 8192, etc.) and should only be changed if a particular script requires additional space for variables.

syntax:
varsize size

example:
varsize 4096

INSEQ
Inseq ensures that script commands are executed in sequence. Normally, the next script command will be scheduled for execution as quickly as possible, meaning that a given command may begin execution prior to the previous command completing. When Inseq is on, each command is completed before the next command begins execution. The flag parameter is specified as on or off (default).

syntax:
inseq flag

example:
inseq on

NOTE: Script is freeware. You can copy it, pass it on or use it as you please provided you adhere to the following requirements:

This help file must be distributed with the Script executable
Script must not be sold on it's own (but you can include it as part of your own package)

Please email any comments, bugs or constructive criticisms to jsim@melbpc.org.au

Program Execution commands:
start or !	program,flag,xy,wh,title	start an external program note (1) (2)
dos	command,flag,xy,wh,title	execute a dos command note (1) (2)
wait	windowtitle,timeout	wait for a window to open note (1) (2)
while	windowtitle	wait for a window to close note (1)
sendkey	windowtitle,textstring	send keystrokes to a window
sendmsg	destination,message	send a message to another PC note (1) (2)

User Interface & Information Display commands:
msgbox	title,msg,btns,style,margin	display a message box note (1) (4)
filebox	title,localvar,template,dir	display a file selection box note (1) (4)
dirbox	text,localvar,root	display a directory selection box note (1) (4)
editbox	title,message,localvar,preset,xy,wh	display an edit box for text entry note (1) (4) (6)
passbox	title,message,localvar,preset,xy,wh	display a password box for password entry note (1) (4) (6)
infobox	title,filespec,xy,wh	load and display a text file note (1)
menubox	title,message,text,xy,wh	display a menu box note (1) (4)
listbox	title,msg,text,localvar,xy,wh	display a list box note (1) (4)
radbox	title,message,text,xy,wh	display a radio button box note (1) (4)
tickbox	title,message,text,xy,wh	display a tick box note (1) (4)
numbox	title,msg,localvar,preset,xy,wh	display a numeric entry box note (1) (4)
chrbox	title,msg,localvar,preset,xy,wh	display a character entry box note (1) (4))
calbox	title,msg,localvar,range,xy,wh	display a calendar box note (1) (4)
ipbox	title,msg,localvar,preset,xy,wh	display an IP address entry box note (1) (4)
timebox	title,msg,localvar,preset,xy,wh	display a time entry box note (1) (4)
datebox	title,msg,localvar,preset,xy,wh	display a date entry box note (1) (4)
picbox	title,msg,file, type,xy,wh	display a bitmap, or icon note (1) (3)
console	title,text,flags,xy,wh,localvar	display text in a scrollable console note (1) (4)
conoff		removes a console
banner	text,xy,wh,b,flags	display a banner panel note (1)
banoff		remove a banner panel
progress	title,text,value,xy,wh	display a progress indicator note (1)
progoff		remove a progress indicator
setfont	fontname,size,attribute	set font for user interface boxes note (1)
getfont	localvar1,localvar2,localvar3	get font for user interface boxes

Local Variable commands:
setvar	localvar,value	set the value of a local variable note (1)
incvar	localvar,value	increments a local variable by value note (1)
addvar	localvar,value	adds value to a local variable note (1)
decvar	localvar,value	decrements a local variable by value note (1)
subvar	localvar,value	subtracts value from a local variable note (1)
mulvar	localvar,value	multiplies a local variable by value note (1)
divvar	localvar,value	divides a local variable by value note (1)
convar	localvar,base1,base2	converts a local variable from number base1 to base2 note (1)
andvar	localvar,value,base	logical bitwise AND a local variable by value note (1)
orvar	localvar,value,base	logical bitwise OR a local variable by value note (1)
xorvar	localvar,value,base	logical bitwise XOR a local variable by value note (1)
notvar	localvar,value,base	logical bitwise NOT a local variable note (1)
upvar	localvar	converts a local variable to uppercase
lovar	localvar	converts a local variable to lowercase
trimvar	localvar,flag	trims left and right whitespace and optionally brackets from a local variable
ltrmvar	localvar	trims left whitespace from a local variable
rtrmvar	localvar	trims right whitespace from a local variable
appvar	localvar,value	appends value to a local variable note (1)
textvar	localvar,type,flag	converts HTML or RTF in a local variable to text note (1)
formvar	localvar,tabs,char,flag	formats text in a local variable to the specified tab stops note (1)
execute	localvar	execute the script command contained in local var

String commands:
findstr	text,localvar	returns first line in string to a local variable note (1) (2)
nextstr	text,localvar	returns next line in a string to a local variable note (1) (2)
lenstr	text,localvar	returns length of text in local variable note (1)
substr	text,pos,length,localvar	returns substring in text to local variable note (1)
srchstr	text,string,localvar	returns position of string in text to local var note (1) (2)
spltstr	text,char,localvar1,localvar2	split text at char and return each half to local vars note (1) (2)
scanstr	text,char,num,localvar	returns n-th token from text to local var note (1) (2)
sortstr	text,char,localvar,flag	sorts text delimited by char and returns to local var note (1) (2)
replstr	text,string,pos,localvar	replaces text at pos with string and stores in local var note (1)
insrtstr	text,string,pos,localvar	inserts string in text at pos and stores in local var note (1)
grepstr	text,chr,repchr,localvar,num	replaces char in text with repchr and stores in local var note (1)
delstr	text,pos,length,localvar	deletes from text at pos of length and stores in local var note (1)
parspath	text,var1,var2,var3,var4,var5	parses text for a valid path name and stores in local vars note (1)
parsip	text,var1,var2,var3,var4	parses text for a valid IP address and stores in local vars note (1)
parsdate	text,var1,var2,var3	parses text for a valid date and stores in local vars note (1)
parstime	text,var1,var2,var3	parses text for a valid time and stores in local vars note (1)

Byte manipulation commands:
srchbyte	localvar1,byte,localvar2	searches for given byte and returns position index in localvar2 note (1)
replbyte	localvar1,pos,num,localvar2	replaces num bytes in localvar1 at pos using bytes from localvar2 note (1)
fillbyte	localvar,byte,pos,num	fills num bytes in localvar1 at pos with the specified byte note (1)
getbyte	localvar1,pos,num,localvar2	gets num bytes in localvar1 at pos and copies them to localvar2 note (1)
conbyte	localvar, flag	converts between value in localvar between byte and hexadecimal string note (1)
grepbyte	localvar,byte1,byte2,num,size	replaces num occurrences of specified byte in localvar1 note (1)

Environment Variable commands:
getenv	localvar,envvar	get an environment variable note (1)
putenv	envvar,value	store an environment variable note (1)

File Association commands:
getassoc	ext,localvar1,cmdtype,localvar2	get a file association and command note (1) (2)
setassoc	ext,filetype,cmdtype,command	set a file association and command note (1) (2)
delassoc	ext	deletes a file association and all associated commands note (1) (2)
fndassoc	localvar	finds the first registered file association note (1) (2)
nxtassoc	localvar	finds the next file association note (1) (2)

File commands:
copyfile	source,destination,flag	copies a file or files note (1) (2) (6)
movefile	source,destination	moves or renames a file note (1) (2) (6)
readdata	filename,localvar1,flag,localvar2,localvar3	reads first data block from a file to a local variable note (1) (2)
nextdata	filename,localvar,flag,localvar2	reads next data block from a file to a local variable note (1) (2)
readline	filename,localvar	reads a line from a file to a local variable note (1) (2)
nextline	filename,localvar	reads next line from a file to a local variable note (1) (2)
savetext	text,filename,flag	saves text to a file note (1) (2)
savedata	data,filename,flag,localvar1,localvar2	saves data to a file note (1) (2)
sortfile	source,destination,col,flag	saves text to a file note (1) (2)
delfile	filename	deletes a file note (1) (2) (6)
findfile	pathname,localvar	returns first file matching pathname note (1) (2)
nextfile	localvar	returns next matching file note (2)
filetime	filename,localvar,time,flag	returns file times to a local variable note (1)
setftd	filename,date,time,flag	sets the file date and time note (1)
filesize	filename,localvar	returns file size to a local variable note (1)
getattr	filename,localvar,flag	returns file attributes to a local variable note (1)
setattr	filename,attr	sets file attributes note (1)
filesrch	filename,text,localvar,flag	returns first instance of text to a local variable note (1) (2)
nextsrch	filename,text,localvar,flag	returns next instance of text to a local variable note (1) (2)
filescan	filename,text,localvar,flag	returns number of occurrences of text to a local variable note (1) (2)

Directory commands:
setdir	dirname	sets the current directory note (1) (2)
getdir	localvar	gets current dir to a local var
makedir	dirname	creates a directory note (1) (2)
deldir	dirname	deletes an empty directory note (1) (2)

Disk commands:
getdisk	localvar	gets current drive to a local var note (2)
finddisk	localvar	copies first installed drive letter to a local variable note (2)
nextdisk	localvar	copies next installed drive letter to a local variable note (2)
disksize	disk,localvar	copies total disk size in bytes to local variable note (1)
diskfree	disk,localvar	copies disk free size in bytes to local variable note (1)
diskused	disk,localvar	copies disk used size in bytes to local variable note (1)
disktype	drive,localvar,flag	gets info about a disk to a local var note (1) (2)
load	drive	load media into drive letter specified note (1)
eject	drive	eject media from drive letter specified note (1)

Registry commands:
setreg	keyvalue,type,data	saves data to a registry key value note (1) (2)
getreg	keyvalue,localvar	gets data from a key value to a local var note [1] (2)
delreg	keyvalue	deletes a key value note (1) (2)
findreg	key,localvar	finds the first value of a registry key note (1) (2)
nextreg	key,localvar	finds the next value of a registry key branch note (1) (2)
makekey	key	creates a registry key note (1) (2)
delkey	key	deletes a registry key note (1) (2)
findkey	key,localvar	finds the first subkey of a registry key note (1) (2)
nextkey	key,localvar	finds the next subkey of a registry key note (1) (2)

Printing commands:
print	file	print a file on the default printer using wordpad note (1) (2)
getprint	localvar	copies default printer name to local variable
setprint	printer	sets default printer to name specified note (1)
findprnt	localvar	copies name of first printer to local variable note (2)
nextprnt	localvar	copies name of next printer to local variable note (2)

Multimedia commands:
open	device,source,flag	open a sound file or cd audio note (1) (2)
seek	device,position	move to a position note (1) (2)
play	device,position	play sound file or CD note (1) (2)
pause	device	pause play note (1) (2)
resume	device	resume play note (1) (2)
stop	device	stop play note (1) (2)
getmedia	device,localvar,flag	copy media info to a local variable note (1) (2)

Shortcut commands:
makelink	linkname,filename,flag	create a shortcut note (1) (2)
getlink	linkname,localvar,info	get info about a shortcut note (1) (2)
setlink	linkname,info,value	set info about a shortcut note (1) (2)

System Tray commands:
puttray	text,label,icon,click	put an icon in the system tray note (1) (2)
modtray	text,label,icon,click	modify an icon in the system tray note (1) (2)
deltray		delete script icon from system tray note (2)

Clipboard commands:
getclip	localvar,flag	get text from the clipboard note (1) (2)
setclip	data,flag	copy text to the clipboard note (1)
clrclip		clear the clipboard note (2)

Internet commands:
geturl	url,localvar	get text from an internet url note (1) (2)
ping	host,timeout,size,ttl	ping a host computer note (1) (2)

Execution control commands:
goto	label	unconditional branch note (1)
gosub	label	branch to a subroutine note (1)
return		return from a subroutine
casemsg	labels	branch to label corresponding to button pressed note (1) [5]
ifmsg	button,label	branch if message box button pressed note (1) [5]
ifnmsg	button,label	branch if message box button not pressed note (1) [5]
iferror	label	branch if error (start, dos, wait etc.) note (1) [3]
ifnerror	label	branch if not error note (1) [3]
ifbit	localvar,bit,label	branch if bit set in local variable note (1)
ifnbit	localvar,bit,label	branch if bit clear in local variable note (1)
ifexist	filename,label	branch if file exists note (1)
ifnexist	filename,label	branch if file does not exist note (1)
ifvar	localvar,value,label	branch if local variable same as value note (1)
ifnvar	localvar,value,label	branch if local variable not same as value note (1)
ifevar	localvar,value,label	branch if local variable same as integer value note (1)
ifgvar	localvar,value,label	branch if local variable greater than integer value note (1)
iflvar	localvar,value,label	branch if local variable less than integer value note (1)
casevar	localvar,values,labels	branch to label corresponding to value of local variable note (1)

Windows Information commands:
getname	localvar	copies computer name to local variable
getuser	localvar	copies user name to local variable
gettime	localvar,flag,format	copies system time to local variable note (1)
getdate	localvar,flag,format	copies system date to local variable note (1)
settime	hour,min,sec	sets the system time note (1)
setdate	day,mth,year	sets the system date note (1)
rawdate	date,time,localvar	converts date and time to raw date note (1)
winver	localvar,flag	copies windows version to local variable
windir	localvar	copies windows directory to local variable
sysdir	localvar	copies system directory to local variable
specdir	folder,localvar	copies directory path of special folder to local variable note (1)
memsize	localvar	copies memory size in Mbytes to local variable
getscrnx	localvar	copies screen width to local variable
getscrny	localvar	copies screen height to local variable

Windows Control commands:
setscrn	width,height,depth	sets screen width, height and colour depth note (1)
logoff	flag	logoff the user note (2)
shutdown	flag	shutdown the system note (2)
poweroff	flag	shutdown and power off the system note (2)
restart	flag	restart the system note (2)
scrnsave		invokes configured screen saver
lockpc		locks the PC (Win 2000)
activate	windowtitle	bring a window to the foreground note (1)
minimise	windowtitle	minimise a window to the taskbar note (1)
maximise	windowtitle	maximise a window to full screen note (1)
restore	windowtitle	restore a window to normal display note (1)
flash	windowtitle	flashes a window note (1)
getwind	localvar	returns the window title of the active window note (1)
close	windowtitle	closes a window note (1)
destroy	windowtitle	force closes a window note (1)
setdesk	filename	sets desktop wallpaper to filename note (1)
setbgnd	red,grn,blu	sets screen background colour note (1)

General commands:
delay	number	delay for a set period note (1)
suspend	hh:mm:ss,DD/MM/YYYY	suspend until specified time and date note (1)
idle		idle indefinitely
quit		quit the script immediately
beep	value	play a beep or system sound note (1)
random	value,localvar	generate a random number note (1)

Script related commands:
report	flag	report script errors
step	flag	show each command before it is executed
debug	flag	control display of debug messages note (1)
dbgbox	message	show a message for debugging controlled by debug flag note (1)
version	localvar	copies script version to local variable
compile	script,executable,flag	compiles the script specified to a standalone file note (1)
priority	level	sets execution priority note (1)
varsize	size	sets the size of script internal variables note (1)
inseq	flag	guarantees script commands executed in sequence note (1)

(1)	these commands allow substitution for command line parameters and local variables
(2)	these commands set internal error flag if error occurs - test using iferror, ifnerror
(3)	these commands check the state of the internal error flag
(4)	these commands return a message value - access using %M, test using casemsg, ifmsg, ifnmsg
(5)	these commands check the state of the message value
(6)	these commands return a count value - access using %N

Char	Description	Meaning

@	Alt	Character following is alt-char
^	Control	Character following is a control character
\n	newline	line feed or enter (0Ah)
\r	return	carriage return or ctrl-enter (0Dh)
\t	tab	tab character (09h)
\[	esc	escape character (1Bh)
\>	right	cursor right arrow
\<	left	cursor left arrow
\^	up	cursor up arrow
\v	down	cursor down arrow
\h	home	cursor home key
\e	end	cursor end key
\u	pgup	cursor page up key
\d	pgdn	cursor page down key
\,	comma	Must be escaped or will be interpreted as a separator
\\	backslash	Must be escaped or will be interpreted as an escape
\?	question mark	Must be escaped or will be interpreted as a wildcard
\*	asterisk	Must be escaped or will be interpreted as a wildcard
\$	dollar sign	Must be escaped or will be interpreted as a function key
\#	hash sign	Must be escaped or will be interpreted as a hex preamble
\%	percent sign	Must be escaped or will be interpreted as a local variable

max	causes the window to open normally (default).
min	causes the window to open minimized (an icon).
x\|y	sets the x and y offset from the top lefthand corner of the screen
w\|h	sets the width and height of the displayed window.
title	sets the title of the window (where possible).

Type	Control	Value

Button	OK	0
	OK, Cancel	1
	Abort, Retry, Ignore	2
	Yes, No, Cancel	3
	Yes, No	4
	Retry, Cancel	5
	Cancel, Try Again, Continue	6

Icon	STOP or ERROR	16
	QUESTION MARK	32
	EXCLAMATION or WARNING	48
	INFORMATION	64
	(USER ICON	128)

Default	BUTTON1	0
	BUTTON2	256
	BUTTON3	512
	BUTTON4	768

Mode	APPLMODAL	0
	SYSTEMMODAL	4096
	TASKMODAL	8192
	HELP BUTTON	16384

Button	Value

OK	1
CANCEL	2
ABORT	3
RETRY	4
IGNORE	5
YES	6
NO	7
TRY AGAIN	10
CONTINUE	11

Value	Description

ALLP(ROGRAMS)	Program folder for all users
ALLS(TARTMENU)	Start menu folder for all users
DE(SKTOP)	Desktop folder
DR(IVES)	Drives folder
N(ETWORK)	Network folder
P(ROGRAMS)	Programs folder
S(TARTMENU)	Start menu folder

Letter	Description

E	Entry by typing into the edit box only. The spin control is disabled
S	Entry via the spin control only. Typing into the edit control is disabled
D	No entry allowed. Both typing and spin control are disabled

Flag	Description

C	Clear previous text in console
E	Allow text in console to be edited
Q	Quit the script when console is closed
W	Wait in console until console is closed

Flag	Description

A	sets the banner to always on top
T	aligns text to the top of the banner
L	aligns text to the left of the banner
C	aligns text to the centre of the banner (default)
R	aligns text to the right of the banner

User Box	Description

EditBox	Text entry area
PassBox	Password entry area
InfoBox	Text display area
ListBox	List entries
NumBox	Number entry area
Console	Console display text
Banner	Banner text

Attribute	Description

T	Thin text
B	Bold text
H	Heavy bold
I	Italics
U	Underlined
S	Strikeout

Base	Description

B(IN)	Binary
D(EC)	Decimal
H(EX)	Hexadecimal
O(CT)	Octal

Tab	Description

nn	single tab at column nn
n1\|n2\|n3	tabs at columns n1, n2 and n3
nn!	tab stops every nn columns
(blank)	tab stops every 8 columns

Flag	Description

TA	Text ascending, case sensitive
TD	Text descending, case sensitive
UA	Text ascending, case insensitive
UD	Text descending, case insensitive
NA	Numeric ascending
ND	Numeric descending

Flag	Description

S(TR)	convert byte value to a decimal string
B(YTE)	convert decimal string to a byte

Flag	Description

C	Create a new file, erasing any previous file of that name (default)
A	Append data to the end of the file
O	Overwrite the previous data in the file

flag	Description

A	Last Access Time
C	Creation time
W	Last write time

Attribute	Value

Normal	0
Read only	1
Hidden	2
System	4
Directory	16
Archive	32
Compressed	128
Temporary	256

Value	Desc	Meaning

-1	Undefined	Operating system returned undefined info
0	Unknown	Disk is unknown
1	No root	Disk has no root directory
2	Removable	Disk is removable
3	Fixed	Disk is a fixed drive
4	Network	Disk is a network or remote drive
5	CD-ROM	Disk is a CD-ROM
6	RAM	Disk is a RAM drive

Mnemonic	Key Root Branch

HKCR	HKEY_CLASSES_ROOT
HKCC	HKEY_CURRENT_CONFIG
HKCU	HKEY_CURRENT_USER
HKLM	HKEY_LOCAL_MACHINE
HKU	HKEY_USERS

Data Type	Meaning	Notes

B	Binary	specified as hexadecimal pairs which may be optionally separated by spaces
D	Double word	specified as a single hexadecimal number between 0 and FFFFFFFF
S	String	specified as plain text
E	Expanded String	specified when the data contains a system variable enclosed with percent (%) characters
M	Multivalued String	specified by separating the individual strings with a vertical tab (\|) character

Value	Description

wav	the wave device
mp3	the mpeg device
seq	the midi sequencer device
cd	the cd audio device

Flag	Description	Possible values

c(urrent)	current track	number
n(umber)	number of tracks	number
s(tatus)	status of device	stopped, playing
m(edia)	media available	true, false
p(osition)	current position	in time units as for SEEK command
p\|n	position in track n	in time units as for SEEK
l(ength)	total length	in time units as for SEEK
l\|n	length of track n	in time units as for SEEK
t(ime)	time format	tsmf, milliseconds, song pointer

Info	Description

a(rg)	command line arguments for the shortcut target
d(esc)	shortcut description
h(ot)	hotkey to activate the shortcut
i(con)	location and index of the shortcut icon
p(ath)	path to the shortcut target
s(how)	show command when displayed
w(ork)	working directory for the target to the shortcut

Icon	Description

A	Application window icon
E	Exclamation mark icon
I	Information icon
F	Icon file
L	Windows logo icon
Q	Question mark icon
S	Script icon
X	Red X icon

Click	Description

LC	Left mouse click
LD	Left mouse double click
RC	Right mouse click
RD	Right mouse double click

Flag	Description

B(ITMAP)	Windows bitmap file
H(TML)	HTML Formatted file
M(SHTML)	Microsoft HTML Formatted
R(TF)	Rich Text Formatted text
TE(XT)	Plain text
TI(FF)	Picture file in TIFF format
W(AVE)	Wave audio file in standard format

Command	Description	Value

MSGBOX	OK Cancel Abort Retry Ignore Yes No Try Again Continue	1 2 3 4 5 6 7 10 11

MENUBOX	Cancel Selected item in menu	0 1..7

LISTBOX	Cancel Selected item in list	0 1..n

EDITBOX	OK Cancel	1 2

FILEBOX	OK Cancel	1 2

Text	Number

OK	1
Cancel	2
Abort	3
Retry	4
Ignore	5
Yes	6
No	7
Try Again	10
Continue	11