Copyright: Copyright ©1995, 1996 J M Technical Services, UK.
Citation: Copyright ©1995, 1996 J M Technical Services, UK.


@ALT

Syntax:

@ALT(<string>)

Description:

This function is only useful when used within the string argument of a WINDOW SEND command to send keystrokes to another window.  It generates keystrokes that are the equivalent of holding down the Alt key while the keys in <string> are being sent.

Example:

rem close down an application

window send,Test - WordPad,@alt(F)X

See also:

@CR	@CTRL	@KEY	@SHIFT	@TAB	Sendng Keystrokes


@ASC

Syntax:

@ASC(<string>)

Description:

This function returns the ASCII code of the first (or only) character of <string>..

Example:

%A = @asc(A)

See also:

@CHR


@ASK

Syntax:

@ASK(<string>)

Description:

This function displays a dialog box containing a question mark icon, the message <string>, and buttons for Yes and No.  The value 1 (true) is returned (and OK is set to true) if the user responds Yes; otherwise the function returns null (false) and OK is set to false.

OK:

Set to true if Yes is pressed; otherwise set to false.

Example:

IF @ASK(Do you want to continue?)

  REM Do something useful

END

See also:

@INPUT	@QUERY


@CHR

Syntax:

@CHR(<value>)

Description:

This function returns the character whose ASCII code is <value>.  It can be used to generate characters that cannot easily be entered from the keyboard.

Example:

%A = WinScript @CHR(169)Skyline Software, UK.

See also:

@ASC


@CLICK

Syntax:

@CLICK(BUTTON)

@CLICK(NAME)

@CLICK(X)

@CLICK(Y)

@CLICK(REGION, <top>, <left>, <bottom>, <right>)

Description:

This function returns information about the last mouse click event to have occurred.

If the parameter is BUTTON, the function returns LEFT, RIGHT or CENTER depending on which button was pressed.

If the parameter is NAME the function returns the name of the bitmap control over which the mouse was clicked.

If the parameter is X or Y the function returns the X or Y co-ordinate of the pointer when the mouse was clicked.

If the parameter is REGION then the function returns the value 1 (true) if the mouse was clicked within the region bounded by the co-ordinates <top>, <left>, <bottom> and <right>, otherwise it returns null (false).

OK:

Set to false if one of the REGION parameters is invalid.

Example:

:evloop

wait event

if @equal(@event(),click)

  info You clicked the @click(button) Button@CR()Co-ords X: @click(X) Y: @click(Y)

  goto evloop

end

See also:

Dialog Programming	Events


@CLIPBRD

Syntax:

@CLIPBRD()

Description:

This function returns the text contents of the Windows clipboard.  Note that because the maximum length of a WinScript variable is 255 characters, if longer than this the contents will be truncated.

Example:

info Clipboard contents:@CR()@CLIPBRD()

See also:

CLIPBOARD


@COUNT

Syntax:

@COUNT( <list> )

Description:

This function returns the number of items in the string list <list>.  The parameter <list> must be either a list number (between 1 and 4) or the name of the dialog list box to which the function will apply.

Example:

LIST 1,CREATE,SORTED

LIST 1,LOADFILE,NAMES.TXT

INFO There are @COUNT(1) names in the list

LIST 1,CLOSE

See also:

@INDEX	@ITEM 	@MATCH	@NEXT 	LIST


@CR

Syntax:

@CR()

Description:

This function returns a carriage return character.  You use it to create output on multiple lines, or to send an Enter keystroke in a WINDOW SEND command.

Example:

%A = This is the first line of output

%B = This is the second line

INFO %A@CR()%B

See also:

@TAB  	WINDOW


@CTRL

Syntax:

@CTRL(<string>)

Description:

This function is only useful when used within the string argument of a WINDOW SEND command to send keystrokes to another window.  It generates keystrokes that are the equivalent of holding down the Ctrl key while the keys in <string> are being sent.

Example:

rem make text bold

window send,Microsoft Word,@ctrl(B)

See also:

@ALT	@CR	@KEY	@SHIFT	@TAB	Sendng Keystrokes


@CURDIR

Syntax:

@CURDIR(<drive letter>)

Description:

This function returns the current directory of the specified drive.  If no drive letter is specified, the function returns the current directory of the current default drive.

Example:

%C = @CURDIR()

REM %C now holds the current directory

%D = @CURDIR(D)

REM %D now holds the current directory of drive D:

See also:

@WINDIR


@DATE

Syntax:

@DATE()

Description:

If no parameter is specified the function returns the current date as a string 1st, 2nd, 3rd, 4th ... 31st.

A DOS file time value, as returned by the @FILE function, may be given as a parameter, in which case the value returned relates to the file time.

Example:

%D = @DAY() @DATE() @MONTH() @YEAR()

See also:

@DD  	@HH  	@MM  	@MN 	@SS	@YY

@DAY  	@MONTH  	 @YEAR


@DAY

Syntax:

@DAY()

Description:

This function returns the day of the week as a string Sunday ... Saturday.

A DOS file time value, as returned by the @FILE function, may be given as a parameter, in which case the value returned relates to the file time.

Example:

%D = @DAY() @DATE() @MONTH() @YEAR()

See also:

@DD  	@HH  	@MM  	@MN  	@YY

@DATE  	@MONTH  	@YEAR


@DD

Syntax:

@DD()

Description:

If no parameter is specified the function returns the current date as a number between 1 and 31.

A DOS file time value, as returned by the @FILE function, may be given as a parameter, in which case the value returned relates to the file time.

Example:

%D = @DD()/@MM()/@YY()

See also:

@HH  	@MM  	@MN   	@SS	@YY

@DATE	@DAY  	@MONTH  	@YEAR


@DDEITEM

Syntax:

@DDEITEM(<item>)

Description:

This function requests the data from a DDE server which is identified by <item>.  For information on what items are supported see the DDE server documentation.

OK:

Unchanged.

Example:

DDE LINK,QPW,SYSTEM

%I = @DDEITEM(SYSITEMS)

DDE TERMINATE

INFO DDE Topics supported by QPW:@CR()%I

See also:

DDE


@DIFF

Syntax:

@DIFF(<value1>,<value2>)

Description:

This function returns the difference of its two arguments: <value1> - <value2>.

OK:

Set to false if either of the arguments is null or non-numeric, or if overflow occurs.

Example:

%C = @DIFF(%A,%B)

See also:

@DIV	@FADD	@FDIV	@FMUL

@FORMAT	@FSUB	@PRED	@PROD	@SUCC

@SUM  	@ZERO


@DIV

Syntax:

@DIV(<value1>,<value2>)

Description:

This function returns the quotient of its two arguments: <value1> / <value2>.

OK:

Set to false if either of the arguments is null or non-numeric, or if overflow occurs.

Example:

%C = @DIV(%A,%B)

See also:

@DIFF	@FADD	@FDIV	@FMUL

@FORMAT	@FSUB	@PRED	@PROD	@SUCC

@SUM  	@ZERO


@DLGTEXT

Syntax:

@DLGTEXT(<control name>)

Description:

This function is used to read the text that appears in dialog window controls.  The string <control name> identifies the control that is the target of the function.

In the case of a list box control the contents of the selected item is returned, or null if no item is selected.

OK:

Unchanged.

Example:

%A = @dlgtext(Name)

%B = @dlgtext(Addr1)

See also:

DIALOG	Dialog Programming


@ENV

Syntax:

@ENV(<string>)

Description:

This function returns the value of the DOS environment variable named <string>.

Example:

%P = @ENV(PATH)

See also:


@EQUAL

Syntax:

@EQUAL(<string1>,<string2>)

Description:

This function compares two strings.  The value 1 (true) is returned if they are identical; otherwise the function returns null (false).

NOTE: the comparison is not case sensitive, so "WinScript" and "WINSCRIPT" are considered equal.

Example:

IF @EQUAL(%F,WIN.INI)

   WARN You must not delete this file!

END

See also:

@NOT 	@NULL 	@ZERO


@EVENT

Syntax:

@EVENT()

Description:

This function returns the name of the last event to have occurred.  It returns a null string if no event has occurred.  After the function has been called the event is cleared, so it should be stored in a variable if you need to test it more than once.

OK:

Unchanged.

Example:

:LOOP

  WAIT EVENT

  GOTO @EVENT()

:OKBUTTON

  INFO You pressed OK

  GOTO LOOP

:CANCELBUTTON

  INFO You pressed Cancel

See also:

Dialog Programming	Events


@EXT

Syntax:

@EXT(<string>)

Description:

This function returns the extension portion of a file path specified in <string>.

Example:

%X = @EXT(C:\WINDOWS\WIN.INI)

REM %X now contains INI

See also:

@NAME


@FADD

Syntax:

@FADD(<value1>,<value2>)

Description:

This function returns the sum of its two arguments: <value1> + <value2>, which may be floating-point numbers.

OK:

Set to false if either of the arguments is null or non-numeric, or if overflow occurs.

Example:

%F = @FADD(%A,3.14159)

See also:

@DIFF	@DIV	@FDIV	@FMUL

@FORMAT	@FSUB	@PRED	@PROD	@SUCC

@SUM  	@ZERO


@FDIV

Syntax:

@FDIV(<value1>,<value2>)

Description:

This function returns the result of: <value1> / <value2>, where the two values may be floating-point numbers.

OK:

Set to false if either of the arguments is null or non-numeric, or if overflow occurs.

Example:

%F = @FDIV(%A,%B)

See also:

@DIFF	@DIV	@FADD	@FMUL

@FORMAT	@FSUB	@PRED	@PROD	@SUCC

@SUM  	@ZERO


@FILE

Syntax:

@FILE(<file description>, <attributes>)

Description:

This function returns the full path name of the file <file description> if it exists.  It returns a null string if it does not exist.

The attribute string can be used to filter the filenames that will be checked.  The attributes can be:

A - archive

D - directory

H - hidden

R - read only

S - system

V - volume label

The 'pseudo-attributes' F, T or Z may also be present.  If T is present, and not F, the creation date/time of the file is returned as an integer, instead of the name.  If required this value can be converted to normal date/time representation using the functions @DD, @MN, @YY, @HH, @MM and so on.  If Z is present, and not F, the file size in bytes is returned, instead of the name.  If F is present as well as T and/or Z the string returned contains the filename followed by 'size=<size>' and/or 'time=<time>'.

Note: To test for the presence of a file on a removable (e.g. diskette) drive without causing a Windows error dialog to be displayed use the @SPACE function, which sets OK to false if the drive does not exist.

Example:

if @file(%F,D)

  INFO Directory %F does not exist

end

See also:

@SPACE


@FILEDLG

Syntax:

@FILEDLG(<file description> {, <title>})

Description:

This function displays a file dialog, and returns the name of the file that was selected (or a null string if no file was selected.)  The string <file description> contains a filter for the file type to be displayed, for example: *.txt.  The string <title> contains an optional title which will be used for the dialog.

Multiple choice filters and descriptions of the file types can be specified if <file description> follows the format:

"<file description 1>|<*.ext1> {|<file description2>|<*.ext2>} ..."

This format must be followed exactly or the description will be ignored.  Quotes must surround the entire file description string.

Example:

%F = @filedlg(*.txt)

%F = @filedlg("Text file (*.txt)|*.txt|Document file (*.doc)|*.doc",Open file)

See also:


@FMUL

Syntax:

@FMUL(<value1>,<value2>)

Description:

This function returns the product of its two arguments: <value1> x <value2>, which may be floating-point numbers.

OK:

Set to false if either of the arguments is null or non-numeric, or if overflow occurs.

Example:

%F = @FMUL(%A,%B)

See also:

@DIFF	@DIV	@FADD	@FDIV

@FORMAT	@FSUB	@PRED	@PROD	@SUCC

@SUM  	@ZERO


@FORMAT

Syntax:

@FORMAT(<value>,<format>)

Description:

This function returns <value> formatted in accordance with <format>, which must be in the form n.d where n is the total number of digits and d is the number of decimal places.  If only n is specified then two decimal places are assumed by default.

OK:

Set to false if either of the arguments is null or non-numeric.

Example:

DIALOG SET,AM1,£@FORMAT(%T,5.2)

See also:

@DIFF	@DIV	@FADD	@FDIV	@FMUL

@FSUB	@PRED	@PROD	@SUCC

@SUM  	@ZERO


@FSUB

Syntax:

@FSUB(<value1>,<value2>)

Description:

This function returns the difference of its two arguments: <value1> - <value2>, which may be floating-point numbers.

OK:

Set to false if either of the arguments is null or non-numeric, or if overflow occurs.

Example:

%F = @FSUB(%A,%B)

See also:

@DIFF	@DIV	@FADD	@FDIV	@FMUL

@FORMAT	@PRED	@PROD	@SUCC

@SUM  	@ZERO


@GREATER

Syntax:

@GREATER(<value1>, <value2>)

Description:

This function tests two string values, which are assumed to be numeric.  The value 1 (true) is returned if <value1> is greater than <value2>; otherwise the function returns null (false).

Example:

IF @GREATER(%1,%2)

   INFO Larger value is %1

END

See also:

@EQUAL 	@NOT 	@ZERO 	 @NULL


@HH

Syntax:

@HH()

Description:

If no parameter is specified the function returns the hours part of the current time as a number between 0 and 23.

A DOS file time value, as returned by the @FILE function, may be given as a parameter, in which case the value returned relates to the file time.

Example:

%T = @HH():@MM()

See also:

@DD  	@MM 	@MN  	@SS	@YY

@DATE	@DAY  	@MONTH  	@YEAR


@INDEX

Syntax:

@INDEX( <list> )

Description:

This function returns the current index (pointer) value for the string list <list>.  The parameter <list> must be either a list number (between 1 and 4) or the name of the dialog list box to which the function will apply.

Example:

LIST 1,CREATE,SORTED

LIST 1,LOADFILE,NAMES.TXT

IF @MATCH(1,John)

  INFO John is at position @INDEX(1) in the list

END

LIST 1,CLOSE

See also:

@COUNT	@ITEM 	@MATCH	@NEXT 	LIST


@INIREAD

Syntax:

@INIREAD(<section name>,<key name>)

Description:

This function returns a string containing the value of <key name> in the <section name> section of the INI file that was specified in the preceding INIFILE command (or WINSCR.INI if no INIFILE command has been executed.)  If <section name> is null the section [Scripts] is used.  The returned string is empty if the section or key do not exist.

OK:

Leaves unchanged.

Example:

%A = @INIREAD(Extensions,.txt)

See also:

INIFILE


@INPUT

Syntax:

@INPUT(<prompt text>,<default result>)

Description:

This function prompts the user to enter some text.  The optional default result is returned if the user presses Cancel.

Example:

%F = CONFIG.SYS

%F = @INPUT(Enter filename:,%F)

See also:

@ASK	@QUERY


@ITEM

Syntax:

@ITEM( <list> )

Description:

This function returns the contents of the string at the current index position in the string list <list>.  The index can be set using the LIST SEEK command.

The parameter <list> must be either a list number (between 1 and 4) or the name of the dialog list box to which the command will apply.  An error will occur if the list does not already exist.

OK:

Set to false if <item number> is out of range..

Example:

LIST 1,CREATE

LIST 1,LOADFILE,NAMES.TXT

LIST 1,SEEK,9

%I = @ITEM(1)

INFO The tenth name is %I

LIST 1,CLOSE

See also:

@COUNT 	@INDEX 	@MATCH	@NEXT 	LIST


@KEY

Syntax:

@KEY(<key name>)

Description:

This function is only useful when used within the string argument of a WINDOW SEND command to send keystrokes to another window.  It is used to generate keystrokes that are equivalent to the key named in <key name>.

Valid key names are: HOME, END, UP, DOWN, LEFT, RIGHT, PGUP, PGDN, INS, DEL, plus F1 to F12..

Example:

rem move cursor

window send,Test - WordPad,@key(HOME)@key(PGDN)@key(PGDN)

See also:

@ALT	@CR	@CTRL	@SHIFT	@TAB	Sendng Keystrokes


@LEN

Syntax:

@LEN(<string>)

Description:

This function returns the length of <string> in characters.  The value 0 is returned if the string is empty.

Example:

%L = @LEN(%A)

See also:

@POS  	@SUBSTR


@MATCH

Syntax:

@MATCH( <list>, <string> )

Description:

This function returns 1 (true) if a string in the string list <list>, starting from the current pointer position, contains text matching <string>.  The match is not case-sensitive.  The pointer is advanced to the matching item number, so you can obtain the contents of the string using @ITEM or @NEXT, rewrite it using LIST PUT and obtain the index value using @INDEX.  If no match is found, null (false) is returned and the index value is unchanged.

The parameters <list> must be either a list number (between 1 and 4) or the name of the dialog list box to which the command will apply.

OK:

Set to false if no match is found.

Example:

LIST 1,CREATE

LIST 1,LOADFILE,NAMES.TXT

%M = @MATCH(1,Jim)

INFO %M

LIST 1,CLOSE

See also:

@COUNT	@INDEX	@ITEM  	@NEXT 	LIST


@MCI

Syntax:

@MCI( < MCI command string > )

Description:

This function is used to control multimedia devices using the Multimedia Control Interface (MCI).  An MCI command is supplied as the parameter to the function.  The function returns the result of the command.  It returns the text of the MCI error message if the command fails..

Note: MCI is a feature of Windows.  For a full description of how to use it you will need documentation such as the Microsoft Multimedia Development Kit Programmer's Workbook or the Microsoft Windows Software Development Kit Multimedia Programmer's Reference.

OK:

Set to false if the command fails.

Example:

%R = @MCI(open C:\WINDOWS\MEDIA\THEMIC~1.WAV alias sound)

if @ok()

  %R = @MCI(play sound)

else

  warn MCI error: %R

end

See also:

PLAY	Example	Using MCI


@MM

Syntax:

@MM()

Description:

If no parameter is specified the function returns the minutes part of the current time as a number between 0 and 60.

A DOS file time value, as returned by the @FILE function, may be given as a parameter, in which case the value returned relates to the file time.

Example:

%T = @HH():@MM()

See also:

@DD  	@HH 	@MN 	@SS 	@YY

@DATE	@DAY  	@MONTH  	@YEAR


@MN

Syntax:

@MN()

Description:

If no parameter is specified the function returns the current month as a number between 1 and 12.

A DOS file time value, as returned by the @FILE function, may be given as a parameter, in which case the value returned relates to the file time.

Example:

%D = @DD()/@MN()/@YY()

See also:

@DD   	@HH  	@MM	@SS	@YY

@DATE	@DAY  	@MONTH  	@YEAR


@MONTH

Syntax:

@MONTH()

Description:

If no parameter is specified the function returns the current month as a string January ... December.

A DOS file time value, as returned by the @FILE function, may be given as a parameter, in which case the value returned relates to the file time.

Example:

%D = @DAY() @DATE() @MONTH() @YEAR()

See also:

@DD  	@HH  	@MM  	@MN	@SS 	@YY

@DATE  	@DAY  	@YEAR


@NAME

Syntax:

@NAME(<string>)

Description:

This function returns the filename portion (not including the extension) of a file path specified in <string>.

Example:

%N = @NAME(C:\WINDOWS\WIN.INI)

REM %N now contains WIN

See also:

@EXT


@NEXT

Syntax:

@NEXT( <list> )

Description:

This function returns the contents of the next item in the string list <list>.  The first item returned will be the first item (item 0) unless the item pointer has been repositioned using the LIST SEEK command.  After the function has been executed the list index is advanced by 1.

The parameter <list> must be either a list number (between 1 and 4) or the name of the dialog list box to which the command will apply.

You use the @NEXT function if you want to read sequentially through the items in a list.

OK:

Set to false when the end of the list is reached.

Example:

LIST 1,CREATE

LIST 1,LOADFILE,NAMES.TXT

REPEAT

  INFO @NEXT(1)

UNTIL @NOT(@OK())

LIST 1,CLOSE

See also:

@COUNT	@INDEX	@ITEM 	@MATCH 	LIST


@NOT

Syntax:

@NOT(<string>)

Description:

This function returns the value 1 (true) if the string is empty (null); otherwise the function returns null (false).

This function is equivalent to @NULL.

Example:

IF @NOT(@ZERO(%2))

   GOTO loop

END

See also:

@EQUAL 	@NULL  	@ZERO


@NULL

Syntax:

@NULL(<string>)

Description:

This function tests whether the enclosed string is empty.  The value 1 (true) is returned if it is empty (null), otherwise the function returns null (false).

This function is equivalent to @NOT.

Example:

IF @NULL(%2)

   WARN No command line parameter supplied!

END

See also:

@EQUAL 	@NOT 	@ZERO


@OK

Syntax:

@OK()

Description:

This function is used to test the status of various I/O commands which set the WinScript OK flag.  It returns 1 (true) if OK is true, otherwise the function returns null (false).

Example:

IF @OK()

  rem Do something useful

ELSE

  WARN Operation failed!

END

See also:


@POS

Syntax:

@POS(<string1>,<string2>)

Description:

This function returns the starting character position of the first occurrence of <string1> in <string2>.  The characters in the string are counted from 1.  The value 0 is returned if either string is empty or <string1> does not occur in <string2>.

Example:

%P = @pos(a,%A)

info Position of a in %A is: %P

See also:

@LEN  	@SUBSTR


@PRED

Syntax:

@PRED(<value>)

Description:

This function returns the predecessor of <value>, i.e. <value> - 1.  It is more efficient than using @diff(<value>,1)..

OK:

Set to false if <value> is null or non-numeric, or if overflow occurs.

Example:

%P = @PRED(%P)

See also:

@DIFF	@DIV	@FADD	@FDIV	@FMUL

@FORMAT	@FSUB	@PROD	@SUCC

@SUM  	@ZERO


@PROD

Syntax:

@PROD(<value1>,<value2>)

Description:

This function returns the product of its two arguments: <value1> x <value2>.

OK:

Set to false if either of the arguments is null or non-numeric, or if overflow occurs.

Example:

%C = @PROD(%A,%B)

See also:

@DIFF	@DIV	@FADD	@FDIV	@FMUL

@FORMAT	@FSUB	@PRED	@SUCC

@SUM  	@ZERO


@QUERY

Syntax:

@QUERY(<string>)

Description:

This function displays a dialog box containing a question mark icon, the message <string>, and buttons for OK and Cancel.  The value 1 (true) is returned (and OK is set to true) if the user responds OK; otherwise the function returns null (false) and OK is set to false.

OK:

Set to true if OK is pressed; otherwise set to false.

Example:

IF @QUERY(Insert disk in drive A: and press OK)

  REM Do something with disk in drive A:

END

See also:

@ASK 	@INPUT


@REGKEYS

Syntax:

@REGKEYS(<root key>, <subkey>)

Description:

This function returns a list of all the keys under the specified key in the Windows registry.  Key names are separated by semicolons.

<root key> specifies the root key to search from.  The permissible values are:

ROOT	specifies HKEY_CLASSES_ROOT

CURUSER	specifies HKEY_CURRENT_USER

LOCAL	specifies HKEY_LOCAL_MACHINE

USERS	specifies HKEY_USERS

<subkey> specifies the key value to retrieve.  Use backslashes to specify keys several levels deep.

OK:

Set to false if the key does not exist.

Example:

rem get list of keys for .doc

%A = @REGKEYS(ROOT,.doc)

See also:

REGISTRY	@REGREAD	Example


@REGREAD

Syntax:

@REGREAD(<root key>, <subkey>, <name>)

Description:

This function returns the value of the specified key from the Windows registry.

<root key> specifies the root key to search from.  The permissible values are:

ROOT	specifies HKEY_CLASSES_ROOT

CURUSER	specifies HKEY_CURRENT_USER

LOCAL	specifies HKEY_LOCAL_MACHINE

USERS	specifies HKEY_USERS

<subkey> specifies the key value to retrieve.  Use backslashes to specify keys several levels deep.

<name> specifies the named value to retrieve.  If omitted, the value of the first NULL name of the key is retrieved.

NOTE: The <name> parameter is not currently supported.

OK:

Set to false if the key does not exist.

Example:

%A = @REGREAD(ROOT,.wsc)

%B = @REGREAD(CURUSER,Control Panel\desktop\ReserveLocale)

See also:

REGISTRY	@REGKEYS	Example


@SHIFT

Syntax:

@SHIFT(<string>)

Description:

This function is only useful when used within the string argument of a WINDOW SEND command to send keystrokes to another window.  It generates keystrokes that are the equivalent of holding down the Shift key while the keys in <string> are being sent.

Example:

rem highlight some text

window send,Test - WordPad,@shift(@key(HOME)@key(DOWN)@key(DOWN))

See also:

@ALT	@CR	@CTRL	@KEY	@TAB	Sendng Keystrokes


@SPACE

Syntax:

@SPACE(<drive letter>)

Description:

This function returns the amount free space on the specified drive, in kilobytes.  The first character is used as the drive letter, so a full path may be specified without causing an error.  If <drive letter> is null, the space on the current drive is returned.

OK:

Set to false if the drive <drive letter> does not exist

Example:

%S = @SPACE(C)

%S = @SPACE(D:\TEMP)

See also:

Example


@SS

Syntax:

@SS()

Description:

If no parameter is specified the function returns the seconds part of the current time as a number between 0 and 59.

A DOS file time value, as returned by the @FILE function, may be given as a parameter, in which case the value returned relates to the file time.

Example:

%T = @HH():@MM():@SS()

See also:

@DD  	@HH 	@MM	@MN  	@YY

@DATE	@DAY  	@MONTH  	@YEAR


@SUBSTR

Syntax:

@SUBSTR(<string>,<pos1>,<pos2>)

Description:

This function returns the substring of <string> starting at character position <pos1> and ending at character position <pos2>.  The characters in the string are counted from 1.  An empty string is returned if <pos1> is greater than the length of the string.  An error will occur if <pos2> is less than <pos1> or either are greater than 254.

Example:

%S = @substr(%A,4,8)

info Substring of %A from 4 to 8 is: %S

See also:

@LEN   	@POS


@SUCC

Syntax:

@SUCC(<value>)

Description:

This function returns the successor of <value>, i.e. <value> + 1.  It is more efficient than using @sum(<value>,1)..

OK:

Set to false if <value> is null or non-numeric, or if overflow occurs.

Example:

%S = @SUCC(%S)

See also:

@DIFF	@DIV	@FADD	@FDIV	@FMUL

@FORMAT	@FSUB	@PRED	@PROD

@SUM  	@ZERO


@SUM

Syntax:

@SUM(<value1>,<value2>)

Description:

This function returns the sum of its two arguments, which are treated as integers.

OK:

Set to false if either of the arguments is null or non-numeric, or if overflow occurs.

Example:

%S = @SUM(%S,10)

See also:

@DIFF	@DIV	@FADD	@FDIV	@FMUL

@FORMAT	@FSUB	@PRED	@PROD	@SUCC

@ZERO


@SYSINFO

Syntax:

@SYSINFO(<string>)

Description:

This function returns various system information dependent on the value of <string>.

The possible values are:

DOSVER	Returns the DOS version number, e.g. 6.20

FREEMEM	Returns the number of Kb of free Windows memory

FSR	Returns the percentage of free system resources

GDIRES	Returns the percentage of GDI resources free

PIXPERIN	Returns the number of pixels pr inch of screen resolution

SCREENHEIGHT	Returns the height of the screen in pixels

SCREENWIDTH	Returns the width of the screen in pixels

USERRES	Returns the percentage of User resources free

WINVER	Returns the Windows version number, e.g. 3.10

WIN32	Returns then value 1 (true) if running in a 32 bit version of Windows.

Example:

title System Information

%D = DOS version     = @SYSINFO(DOSVER)

%W = Windows version = @SYSINFO(WINVER)

%F = Free resources  = @SYSINFO(FSR)%

%G = GDI resources   = @SYSINFO(GDIRES)%

%H = User resources  = @SYSINFO(USERRES)%

%M = Free memory     = @SYSINFO(FREEMEM)Kb

info %D@CR()%W@CR()%F@CR()%G@CR()%H@CR()%M

See also:

Screen metrics	Example


@TAB

Syntax:

@TAB()

Description:

This function returns a tab character.  You use it to insert a tab in text which is being output, or to send a tab keystroke in a WINDOW SEND command.

Example:

WINDOW SEND,Report - WordPad,Column 1@TAB()Column 2

See also:

@CR  	WINDOW


@UPPER

Syntax:

@UPPER(<string>)

Description:

This function returns the string <string> converted entirely to upper case characters.

Example:

%S = @UPPER(The quick brown fox)

REM %S now contains THE QUICK BROWN FOX

See also:


@WINDIR

Syntax:

@WINDIR()

Description:

This function returns the full path of the Windows directory.

Example:

%W = @WINDIR()

REM On most systems %W will now contain C:\WINDOWS

See also:

@CURDIR


@WINEXISTS

Syntax:

@WINEXISTS(<window title>)

Description:

This function is used to determine whether an application is running or not.  It returns the value 1 (true) if a window with a title bar of <string> exists (iconized windows included) and null (false) if not.  The full title bar text need not be given, but if any window matches the partial string then a true value will be returned..

Example:

if @not(@WinExists(Program Manager))

  run PROGMAN.EXE

end

See also:

WINDOW	@WINPOS


@WINPOS

Syntax:

@WINPOS(<window title>, {TOP|LEFT|WIDTH|HEIGHT})

Description:

This function returns the value of the top or left position of the named window or its width or height, according to the parameter specified.  The full window title text need not be given, but the first window that matches the string will be the one whose position is returned..

Example:

%A = @winpos(Explorer,top)

See also:

WINDOW	@WINEXISTS


@YEAR

Syntax:

@YEAR()

Description:

If no parameter is specified the function returns the current year as a four-digit number, e.g.: 1995.

A DOS file time value, as returned by the @FILE function, may be given as a parameter, in which case the value returned relates to the file time.

Example:

%D = @DAY() @DATE() @MONTH() @YEAR()

See also:

@DD  	@HH  	@MM  	@MN	@SS 	@YY

@DATE  	@DAY  	@MONTH


@YY

Syntax:

@YY()

Description:

If no parameter is specified the function returns the current year as a two-digit number.

A DOS file time value, as returned by the @FILE function, may be given as a parameter, in which case the value returned relates to the file time.

Example:

%D = @DD()/@MM()/@YY()

See also:

@DD  	@HH  	@MM 	@MN 	@SS

@DATE	@DAY  	@MONTH 	@YEAR


@ZERO

Syntax:

@ZERO(<string>)

Description:

This function returns the value 1 (true) if the value of <string> is zero; otherwise the function returns null (false).

Example:

IF @ZERO(%V)

  INFO Result is zero.

END

See also:

@DIFF	@DIV	@FADD	@FDIV	@FMUL

@FORMAT	@FSUB	@PRED	@PROD	@SUCC

@SUM


Assignments

Like commands, assignments need not start in the first character position, so they may be indented using spaces for readability.

An assignment consists of a variable name, an equals symbol and a string, (which may contain variable or function references) each separated by spaces.

Here are some examples of assignments:

%S = @SPACE(D)

%T = Backing up drive %D


BEEP

Syntax:

BEEP

Description:

Sounds a beep.

OK:

Unchanged.

Example:

BEEP

See also:


BITMAP dialog element
BITMAP(<name>;<top>;<left>;<width>;<height>;<filename> {; STRETCH})

This dialog element creates a bitmap at the position and size specified, containing the image <filename>.  The image can be a bitmap (BMP) icon (ICO) or metafile (WMF) format.  If an executable (EXE) file is specified then its icon is displayed.  If the width or height are omitted then the bitmap control is automatically sized to the image.  If STRETCH is specified then the image is sized to fit the bitmap control (note that this has no effect on icons.)


BUTTON dialog element
BUTTON(<name>;<top>;<left>;<width>;<height>)

This dialog element creates a button at the position and size specified.  The name is used as the caption for the button.  When pressed, the button will cause an event of type <name>BUTTON.


Bank charge
Sorry, but we are charged this fee by our bank to process cheques drawn on non-UK banks.  If you have a CompuServe account then you can avoid the charge by registering using GO SWREG instead.


CANCEL dialog element
CANCEL

This dialog element provides an easy way to create a Cancel button which is automatically positioned at the bottom of the window.  When pressed it causes a CANCELBUTTON event.


CHECK dialog element
CHECK(<name>;<top>;<left>;<width>;<height>;<caption>;<initial state>)

This dialog element creates a check box at the size and position specified, with a text caption of <caption> and an initial state of unchecked (0) or checked (1).


CLICK dialog element
CLICK(<cursor type>)

This dialog element specifies that the window is to notify mouse click events.  When the mouse is clicked over a bitmap control, a CLICK event occurs.  More information about it, such as which button was clicked or the X and Y co-ordinates, can be obtained using the @CLICK function.

Click notification only occurs on bitmap controls defined after the CLICK dialog element was specified.

The <cursor type> parameter is optional. If present, it specifies the cursor that will be used when the mouse is positioned over the bitmap.  This will give feedback to the user that the bitmap can be clicked.  Valid cursor types are: ARROW (the standard cursor), CROSS (a cross-hair cursor), HAND (a hand with outstretched finger) and MAGNIFY (a magnifying glass).


CLIPBOARD

Syntax:

CLIPBOARD CLEAR

CLIPBOARD APPEND,  <string>

Description:

The CLIPBOARD command is used to put data into the Windows clipboard.

CLIPBOARD CLEAR empties the clipboard of any data that was in it.

CLIPBOARD APPEND adds the contents of <string> to whatever is already in the clipboard. Successive appends add the text on a new line.

OK:

Unchanged.

Example:

CLIPBOARD CLEAR

CLIPBOARD APPEND,Hello Clipboard!

See also:

@CLIPBRD


Command Reference

BEEP

CLIPBOARD

DDE

DIALOG

DIRECTORY

EXIT

FILE

GOSUB

GOTO

IF

INFO

INIFILE

LIST

PLAY

PRINT

REGISTRY

REM

REPEAT

RUN

RUNH

RUNM

RUNZ

SHIFT

TITLE

WAIT

WARN

WINDOW


Commands

Unlike labels, commands need not start in the first character position.  It is recommended that they are indented using spaces for readability.

A command consists of the command name (see Command Reference) followed optionally by a string.  The string is used as the argument (or parameters) to the command.  Most commands have only a single argument, but some have more than one, in which case commas are used to separate the parameters.  A space must separate the command from the string.  Commands are not case-sensitive.

Here are some examples of commands:

TITLE My first script

INIFILE WRITE,Reg_Info,UserName,Fred Bloggs

Strings may include variable and function references, which are evaluated before the command is carried out.  Here is an example of commands containing variable and function references:

IF @FILE(%F)

  INFO File %F exists

END


Contents

TUTORIAL

Overview

The Development Environment

The WinScript Language

String Lists

Dialog Programming

Events

Running Scripts

Making Executable Files

Examples

REFERENCE MANUAL

Command Reference

Function Reference

Error Messages

LICENSING & REGISTRATION

Licence Agreement

Warranty and Liability

Registering WinScript


Controlling WordPad

This script gives an example of how to control another application (the Windows 95 WordPad) using WinScript.

file delete,test.txt

run wordpad.exe

wait 1

%W = Document - Wordpad

window position,%W,100,400

rem enter some text

window send,%W,This is a test string@CR()

window send,%W,@shift(This is some shifted text)@CR()

window send,%W,@tab()This text is indented.@CR()

window send,%W,123+£456=£789!!  5 > 4 = true?

wait 1

rem open and close help

window send,%W,@key(F1)

wait 4

window send,Help Topics,@alt(@key(F4))

wait 2

rem select all the text

window send,%W,@alt(el)

rem make it bold

window send,%W,@alt()O@CR()

window send,%W,@tab()@key(DOWN)@key(DOWN)@CR()

rem un-select it

window send,%W,@key(PGUP)

wait 2

rem save the file as TEST.TXT

window send,%W,@alt(F)STEST.TXT@CR()

wait 4

rem window title now changes to Test - Wordpad

%W = Test

rem quit WordPad

window send,%W,@alt(FX)

exit


Creating Dialogs

WinScript allows you to create a dialog window for your script, containing buttons and other controls.  You can use the dialog to present information to (and obtain it from) the user.  You create a dialog window using the WINDOW CREATEDLG command, which has the format:

WINDOW CREATEDLG, <window name>, <top>, <left>, <width>, <height>, <description>

The text <window name> appears in the title bar of the window.  The parameters  <top>, <left>, <width> and <height> specify the initial position and dimensions of the dialog window.  If the value of <top> is negative then the window is positioned in the center of the screen.  The value of <height> refers to the client area of the window: it does not include the height of the title bar.

The <description> consists of one or more dialog elements, separated by commas.  Because the description can consist of many elements, WinScript allows you to continue the description on the following line, by ending the line with a comma followed by a dash.

Dialog elements begin with the element type, which is optionally followed by details such as the control name, size, position and initial value.  The details are contained within brackets and separated by semicolons.  See Dialog Elements for more information.  See also Example.

Example:

window createdlg,Example Window,50,50,200,240,-

  TEXT(T1;15;40;;;This is a text control),-

  EDIT(E1;40;40;120;;This is an edit control),-

  LIST(L1;65;40;120),OK,CANCEL

dialog set,L1,This is a list box

creates this:

A visual dialog editor is planned as a future enhancement to WinScript.  Registered users will receive information about this when it is available.


DDE

Syntax:

DDE  LINK, <servername>,  <topicname>

DDE  EXECUTE, <macro>

DDE  POKE,  <itemname>,  <data>

DDE  TERMINATE

Description:

The DDE commands are used to establish and terminate a link using DDE between a script program acting as a DDE client and another application acting as a DDE server.

The DDE LINK command is used to initiate the DDE link before any communication can take place.  The DDE TERMINATE command is used to terminate the link once communication has finished.

The DDE EXECUTE command is used to send to the server application a command (or DDE macro) to be executed.  The commands that are valid are dependent on the application.

The DDE POKE command is used to send data to a named item in the DDE server.  Many applications do not accept poked data.

OK:

Set to false if the DDE command fails.

Example:

DDE LINK,Progman,Progman

if @not(@OK())

  warn Unable to establish DDE link@CR()with Program Manager

  exit

end

DDE EXECUTE,[CreateGroup(WinScript)]

DDE EXECUTE,[ShowGroup(WinScript,1)]

DDE EXECUTE,[AddItem(WINSCR.EXE,WinScript)]

DDE TERMINATE

See also:

@DDEITEM


DIALOG

Syntax:

DIALOG  CLEAR,  <control name>

DIALOG  CLEARSEL,  <control name>

DIALOG CLOSE

DIALOG  CURSOR {, WAIT}

DIALOG  DISABLE,  <control name>

DIALOG  ENABLE,  <control name>

DIALOG  FOCUS,  <control name>

DIALOG  HIDE,  <control name>

DIALOG  SET,  <control name>, <text>

DIALOG  SHOW,  <control name>

DIALOG  TITLE,  <title>

Description:

The DIALOG command is used to alter the text that appears in dialog window controls.  The string <control name> identifies the control that is the target of the command.

DIALOG CLEAR clears the text in the control named <control name>.

DIALOG CLEARSEL clears the selected item in a list box control named <control name>.

DIALOG CLOSE closes the dialog window.  An error will occur if any attempt is made to access dialog controls after this command has been executed.

DIALOG CURSOR, WAIT sets the cursor for the dialog to an hourglass.  The command DIALOG CURSOR sets it back to the default cursor.  To provide feedback to the user your script program should show the hourglass cursor whenever it will take some time to respond to a user action.

DIALOG DISABLE and DIALOG ENABLE disable and enable the control named <control name>.

DIALOG FOCUS sets the input focus to the control named <control name>.

DIALOG HIDE and DIALOG SHOW hide and show the control named <control name>.

DIALOG SET sets the text in the control named <control name> to <text>.  In the case of a list box the text replaces the selected item; it is added if no item is selected.  In the case of a bitmap the bitmap file <text> is loaded into the control.

DIALOG TITLE sets the text in the title bar of the dialog window to <title>.

OK:

Unchanged.

Example:

dialog title,Address Book

dialog clear,Name

dialog set,NM,1

dialog focus,Name

See also:

@DLGTEXT	WINDOW	Dialog Programming


DIRECTORY

Syntax:

DIRECTORY CHANGE, <path>

DIRECTORY CREATE, <path>

DIRECTORY DELETE, <path>

Description:

The DIRECTORY command is used to change, create or delete directories.

DIRECTORY CHANGE changes the current directory to the one named in <path>.  If <path> is on a different drive to the current drive then this is changed as well.  This command is similar in operation to the MS-DOS CHDIR command.

DIRECTORY CREATE creates a new directory named <path>.  If necessary, it will recursively create all the subdirectories in the path.  This command is similar in operation to the MS-DOS MKDIR command.

DIRECTORY DELETE removes the directory named in <path>.  The directory must be empty or it will not be removed.  This command is similar in operation to the MS-DOS RMDIR command.

OK:

True if the operation is successful; false if not.

Example:

directory delete,f:\tmp1

directory create c:\test\subdir1\subdir2

See also:


DRAGDROP dialog element
DRAGDROP

This dialog element specifies that the window is to accept drag and drop filenames.  When a file or files are dropped, a DRAGDROP event occurs.  This can be processed using the LIST DRAGDROP command.  See the Drag and Drop and Viewer examples for more information.


Data Lists

Syntax:

LIST  <list>, DROPFILES

LIST  <list>, FILELIST, <file specification>, {<attributes>}

LIST  <list>, LOADFILE, <filename>

LIST  <list>, SAVEFILE, <filename>

Description:

These LIST commands are used to get data into string lists.  The parameter <list> must be either a list number (between 1 and 4) or the name of the dialog list box to which the command will apply.  An error will occur if the list does not already exist.

DROPFILES is used to add to the list <list> the names of files that have been dropped on to a dialog window that has the DRAGDROP property.  For more information see Dialog Programming and the example scripts Drag and Drop and Viewer.

FILELIST is used to add to the list <list> the names of files that match a particular specification, which may include wildcards.  The file specification may optionally be followed by a list of attributes which will be used to filter the list of files selected.  The attributes may be specified as: A - archive; D - directory; H - hidden; R - read only; S - system; V - volume label.

LOADFILE is used to create a list holding the contents of a named text file.

SAVEFILE is used to save the contents of a list to a named text file.

OK:

Set to false if the LIST command fails.

Example:

LIST 1,LOADFILE,C:\CONFIG.SYS

LIST LB1,FILELIST,*.tmp

See also:

@COUNT	@INDEX	@ITEM	@MATCH 	@NEXT 	LIST	Using Lists


Development Environment

WinScript has an interactive development environment (IDE) which makes it easy to develop and debug your Windows scripts.  The environment is run from the main window, shown below, which normally sits at the top of the screen

 For a description of each feature of the IDE interface, click on a button or menu on the picture below.

Scripts are edited in the script window, which is a standard Windows text editor.  Scripts can be run from the main window, using either the menu options or the toolbar buttons.

WinScript provides several aids to debugging.  You can set a breakpoint at any point in the script, and then check the value of each variable using the watch window.   You can also use single-step mode to step through the script a line at a time.


Dialog Elements

Dialog elements are parameters to the WINDOW CREATEDLG command which specify the characteristics of the dialog window you want to create and the controls that should appear on it.

Most dialog elements have parameters, which are enclosed in brackets after the element name.  The parameters are separated by semicolons.  The name parameter, where required, is mandatory and is used to address the control when you want to write text to it or read text from it.  Most of the remaining parameters are optional, and may be left as null or omitted; WinScript will use suitable defaults.  With controls you will usually want to specify at least the top and left position co-ordinates.  Position co-ordinates are relative to the client area of the dialog window.

The following dialog elements are available:

BITMAP(<name>;<top>;<left>;<width>;<height>;<filename> {; STRETCH}))

BUTTON(<name>;<top>;<left>;<width>;<height>)

CANCEL

CHECK(<name>;<top>;<left>;<width>;<height>;<caption>;<initial state>)

CLICK(<cursor type>)

DRAGDROP

EDIT(<name>;<top>;<left>;<width>;<height>;<caption>)

LIST(<name>;<top>;<left>;<width>;<height>{; SORTED})

ICON(<filename>)

OK

POPUP(<item>{; <item>...})

STATUS(<name>,<text>)

STYLE(<style>{; <style>...})

TEXT(<name>;<top>;<left>;<width>;<height>;<caption>)

The order of specifying the dialog elements can be important.  The first button to be specified will be the default button which is executed if the user presses Enter.  The tab order of controls that can accept input will be the order of specification, and the first such control to be specified will be the one that has the input focus when the dialog window is created.  Click events are only notified for bitmaps defined after the CLICK dialog element.


Dialog Programming

WinScript allows you to create simple dialog windows which function as the main window for your script application.  Dialog windows may contain a number of controls, such as text controls and a status panel for displaying captions and other information, edit controls, check boxes and list boxes which can not only display information but allow interaction with the user, and buttons which tell you when to process information by generating events.

You create a dialog using the WINDOW CREATEDLG command (see Creating Dialogs for more information.)  The dialog must include buttons which users can press when they want the script to do something with the information in the dialog.  It will also usually include a button to close the dialog, and possibly end the script.

When a button is pressed it generates an event.  The name of the event is the name of the button followed by BUTTON; for example, when the OK button is pressed an OKBUTTON event occurs.  Other possible events are the DRAGDROP event, which occurs if the dialog window is drag and drop enabled and files are dragged to the window, the CLICK event which can occur when the mouse is clicked over a bitmap, and the CLOSE event which occurs when the user closes the window using the title bar buttons or the system menu.

There are two ways to process events.  You can use WAIT EVENT.  This halts the script entirely until an event occurs.  When it does, you can test it using the @EVENT function, carry out whatever processing is required, and if appropriate loop back to the WAIT EVENT command to wait for the next event.

If you require your script to do other work while the dialog is displayed then you can simply test @EVENT repeatedly: it will return null if no event has occurred.  It is advisable to put some sort of delay in the processing loop, such as WAIT 1, to give other applications a chance to run, otherwise your script will absorb an excessive amount of processor time.

When you are finished with the dialog window you close it using WINDOW CLOSE.  This frees all its resources.  Any dialog controls will no longer be accessible, so any data should be copied into variables or string lists before closing the window.  If the user closes the dialog window using the title bar buttons or the system menu then it is automatically closed.  No commands processed after the CLOSE event should access the dialog window or its controls at all.


Dialog Styles

Various styles of dialog can be created using the STYLE dialog element.  The main styles are shown below.

Default dialog style:

Gray3D dialog style:

Black dialog style:

Resiz dialog style:

Notitle dialog style:


Dialog example
Dialog

This script displays a simple data input dialog and displays the data in a message box.

rem Dialog Example

window createdlg,Dialog Example,100,100,300,180,Button(OK;126;118),-

  Text(T1;10;10;80;;Name:),Edit(Name;10;100;180),-

  Text(T2;30;10;80;;Address:),Edit(Add1;30;100;180),-

  Edit(Add2;50;100;180),Edit(Add3;70;100;180),-

  Check(CB1;90;10;;;Male),Status(SP;Record 1)

wait event

%E = @event()

if @equal(%E,OKButton)

  %T = @dlgtext(T1)

  %N = @dlgtext(Name)

  %A = @dlgtext(Add1)@CR()@dlgtext(Add2)@CR()@dlgtext(Add3)

  %C = @dlgtext(CB1)

end

info Event was: %E@CR()@CR()Data:@CR()%N@CR()%A@CR()Sex: %C

exit


Drag and Drop example
Drag and Drop

This script displays the names of files that are dropped on the dialog window in a listbox.

Title Drag and Drop Test

window createdlg,Drag and Drop Test,100,100,300,220,OK,-

  DRAGDROP,LIST(LB;10;10;280;160)

:loop

wait event

%E = @event()

if @equal(%E,DRAGDROP)

  list LB,DROPFILES

end

if @equal(%E,OKBUTTON)

  exit

end

if @equal(%E,CLOSE)

  exit

end

goto loop


Drive test example
Drive Test

This example demonstrates how to test for which drives exist, and what space is available on them, using the @SPACE function and the value returned by @OK.  Note that diskette drives containing no disk are shown as unavailable because the result of @OK when they are tested is false.

%C = 65

repeat

  %S = @space(@chr(%C))

  if @ok()

    %D = %D@chr(%C): - %SKb@CR()

  else

    %D = %D@chr(%C): - Unavailable@CR()

  end

  %C = @succ(%C)

until @equal(%C,75)

info Available drives:@CR()%D


EDIT dialog element
EDIT(<name>;<top>;<left>;<width>;<height>;<text>)

This dialog element creates an edit (input) box at the position and size specified, containing the text <text>.


ELSE

See:	IF


END

See:	IF


EXIT

Syntax:

EXIT

Description:

When obeyed after a GOSUB command, causes execution to continue at the line following the GOSUB.  Otherwise, EXIT causes execution of the script to terminate.

OK:

Unchanged.

Example:

EXIT

See also:

GOSUB


Error Messages

1	Invalid Command

A command has been encountered which WinScript does not recognize.  Usually this means it has been misspelt.

2	Missing parameter(s)

The command executed expects more parameters than the number given.

3	Missing or invalid file number

The file number should be 1 or 2.

4	Invalid list operation

The string list or list box control referenced in this command does not exist..

5	Invalid variable in assignment

Valid variable names are %1 .. %9 and %A .. %Z.

6	"=" symbol expected

A command started with a variable name but no equals symbol was found.

7	Invalid @ function

A function has been encountered which WinScript does not recognize.  Usually this means it has been misspelt.

8	Syntax error in @ function

Something is wrong with a function call (often a bracket missing.)

9	Missing END or ELSE

An IF or ELSE command has been executed but the corresponding ELSE or END could not be found.

10	Command nested too deeply

REPEAT or GOSUB commands have been nested more than 9 deep.  This can be caused by incorrect use of the GOTO command.

11	Missing argument(s) to @ function

The function executed expects more parameters than the number given.

12	Label not found

The label named in a GOTO or GOSUB command could not be found.

13	Invalid argument to @function

One of the parameters to a function is not valid.

14	Invalid parameter to command

One of the parameters to a command is not valid.

15	UNTIL without REPEAT

An UNTIL command was encountered but no previous REPEAT has been executed.

16	Null subkey not allowed

A null subkey is not permitted in this REGISTRY command..

17	Dialog already exists

A WINDOW CREATEDLG command cannot be executed when a dialog window already exists..

18	Dialog control does not exist

The dialog control referenced in the DIALOG or LIST command or @DLGTEXT function does not exist.

19	List index out of range

The item number in a list index operation is less than 0 or greater than the number of items in the list.

20	File does not exist

The icon or bitmap file referenced in a dialog element cannot be found.

21	Cannot create control

WinScript cannot create a control specified in a WINDOW CREATEDLG command.  A dialog element may contain an invalid parameter, for example, the control name may be duplicated or invalid.  There is a limit of 40 controls on a dialog.

253	Breakpoint reached

The script was stopped at a breakpoint.

254	Stopped by user

The script was paused.


Events

Events occur when the user interacts with a dialog which you have created using the WINDOW CREATEDLG command.  You can halt your script and wait for an event to occur using the WAIT EVENT command.  You can find out the type of event using the @EVENT function.

BUTTON events occur when a button is pressed.  The type of event is <name>BUTTON, where <name> is the name of the button.  So when the user presses a button labelled OK an OKBUTTON event occurs.

CLOSE events occur when the user closes the dialog from the system menu or using the close button.  The dialog is destroyed before control is given back to your script, so any attempt to access the dialog controls after a CLOSE event has occurred will result in an error.

CLICK events are optional.  They occur when a mouse button is clicked over a bitmap when the CLICK dialog element has been specified.  You can find out which button was pressed, which bitmap control it was clicked over and the X and Y co-ordinates within the bitmap by using the @CLICK function.

DRAGDROP events are optional.  If the DRAGDROP dialog element is specified and a file or files are dragged to the dialog window then a DRAGDROP event occurs.  You can find out the filenames by using the LIST DROPFILES command to get them into a string list.

MENU events occur if you have defined a popup menu for the dialog window.  The type of event is <name>MENU where <name> is the name of the menu item that was selected.

A TIMER event occurs when you use a command of the form WAIT EVENT, <interval>.  It occurs <interval> seconds after the command was issued.


Examples

These example scripts illustrate various techniques and ideas for using WinScript.  To run the examples, simply copy them to the script window,.save them to a suitable file name, modify them as necessary and then run them.

Controlling WordPad

Dialog

Drag and Drop

Drive Test

List

MCI Test

Registry Information

ShellNew

Startup

System Information

Viewer


FILE

Syntax:

FILE COPY, <file path 1>, <file path 2>

FILE DELETE, <file path>

FILE RENAME, <file path 1>, <file path 2>

Description:

FILE COPY copies the file named in <file path 1> to <file path 2>.  The original date and time are preserved.    The command is similar in operation to the MS-DOS COPY command.  Files that have been compressed using the Microsoft COMPRESS.EXE utility are automatically expanded to the output file.  The result is the same as using the Microsoft EXPAND.EXE utility.

FILE DELETE erases the file named in <file path>.  This command is similar in operation to the MS-DOS DEL command.

FILE RENAME renames the file named in <file path 1> to <file path 2>.  A file can be renamed from one directory to another (in other words, moved) only if both directories reside on the same logical drive.    This command is similar in operation to the MS-DOS REN command.

OK:

True if the operation is successful; false if not.

Example:

file delete,TEST.TXT

file copy A:\COMPRESS.EX_,C:\UTILS\COMPRESS.EXE

See also:


Function Reference

@ALT	@ASC	@ASK

@CHR	@CLICK	@CLIPBRD

@COUNT	@CR	@CTRL

@CURDIR

@DATE	@DAY	@DD

@DDEITEM	@DIFF	@DIV

@DLGTEXT

@ENV	@EQUAL	@EVENT

@EXT

@FADD	@FDIV	@FILE

@FILEDLG	@FMUL	@FORMAT

@FSUB

@GREATER

@HH

@INDEX	@INIREAD	@INPUT

@ITEM

@KEY

@LEN

@MATCH	@MCI	@MM

@MN	@MONTH

@NAME	@NEXT	@NOT

@NULL

@OK

@POS	@PRED	@PROD

@QUERY

@REGKEYS	@REGREAD

@SHIFT	@SS	@SUBSTR

@SUCC	@SUM	@SPACE

@SYSINFO

@TAB

@UPPER

@WINDIR	@WINEXISTS	@WINPOS

@YEAR	@YY

@ZERO


Functions

WinScript supports a range of functions (see Function Reference) which are evaluated at run time and return a string containing information.

Functions start with an @ symbol followed by the function name.  The argument(s) to the function are in the form of a string enclosed in parentheses.  The parentheses must be present even if the function takes no arguments.  For functions that take more than one argument the arguments are separated by commas.

Here are some examples of functions:

@ASK(Do you want to continue?)

@EQUAL(%F,WIN.INI)

Note that because the @ symbol is used to identify functions you cannot use it for any other purpose unless it is enclosed within double quotes..


GO SWREG

If you are a member of CompuServe, you can register by choosing GO SWREG and choosing the option to register a shareware applicaion.  The registration ID to use for WinScript is 8324.

Registration by this method costs $39.00 US.  There are no additional charges for overseas registrations as everything is done electronically.  You should receive your personal serial number by email within 3 to 4 days.  Updated versions of the software can be downloaded from the Windows Utilities forum as and when they appear.  If you discover a bug which is preventing you from using the product in the way you want, we can send you the bug-fixed version by email.


GOSUB

Syntax:

GOSUB  <string>

Description:

Causes script execution to continue at the command following the label :<string>.  When an EXIT command is encountered, execution will jump back to the command following the GOSUB.

OK:

Leaves unchanged.

Example:

GOSUB sayhello

INFO Goodbye

EXIT

:sayhello

  INFO Hello

  EXIT

See also:

EXIT


GOTO

Syntax:

GOTO  <string>

Description:

Causes script execution to continue at the command following the label :<string>.

Note that using the GOTO command to branch to a label that is within an IF ... END or REPEAT ... UNTIL group of commands will result in a "Missing END or ELSE" or "UNTIL without REPEAT" error message, unless the GOTO command and the label are both within the same group of commands.

Using a GOTO command to branch out of a REPEAT ... UNTIL group of commands will eventually result in a "Command nested too deeply" error.  The reason is that WinScript does not know that the REPEAT command has finished until it has executed the UNTIL command with the terminating condition as true.

OK:

Leaves unchanged.

Example:

GOTO label

WARN This message box will not be displayed

:label

INFO This message box will be displayed.

See also:

GOSUB


ICON dialog element
ICON(<filename>)

This dialog element sets the icon which will be used in the title bar of the window, and in the task bar when it is minimized.  The <filename> must specify an icon file with a .ICO extension.


IF

Syntax:

IF  <string>

   ... commands executed if string not null (true)

ELSE

   ... commands executed if string is null (false)

END

Description:

The string is evaluated.  If the result is a null string (false), execution of the script continues from the command after the ELSE, if present.  If no ELSE is present then execution continues after the END.

If the string is non-null then script execution continues on the next line, but any commands between the ELSE (if present) and END will be skipped.

IF commands may be nested.  If this is done then it is important to ensure that the correct ELSE and END commands are not omitted.  For clarity it is a good idea to indent the nested IF commands as shown in the example.  Note also that unlike many other languages there is no need for a THEN at the end of the IF command line.

Warning: Because WinScript treats a non-null result for the condition string as true, if you do mistakenly put a THEN at the end of an IF command line this will be treated as text and the condition will always be true.  A similar problem will occur if you omit the @ from a function name, causing it to be treated simply as text.

OK:

Leaves unchanged.

Example:

IF @ask(Do you want to continue?)

  info You answered YES

ELSE

  IF @ask(Are you sure?)

    info You answered NO

  ELSE

    info Make your mind up

  END

END

See also:

@NOT	@NULL	REPEAT	Tip


INFO

Syntax:

INFO  <string>

Description:

Displays a dialog box containing an information symbol icon and the message <string>.  Execution of the script continues when the OK button is pressed.

OK:

Set to true.

Example:

INFO There is %SKb of free space on drive D:

See also:

WARN 	@ASK 	@QUERY


INIFILE

Syntax:

INIFILE  OPEN,  <inifile name>

INIFILE  WRITE,  <section name>, <key name>, <string>

Description:

The INIFILE OPEN command sets the name of the INI file which will be used by any succeeding INI file read and write commands to <inifile name>.  By default, WinScript's own INI file WINSCR.INI is used.

If you are using an INI file to store information specific to your scripts it is probably advisable to use WINSCR.INI rather than using individual INI files for each one.  However, care should be taken to avoid using the same section and key names as those used by WinScript itself.

The INIFILE WRITE command writes a line <key name>=<string> under the section header <section name> in the currently open INI file.  A section name of [Scripts] is used if the <section name> parameter is null.

Note that there is no INIFILE CLOSE command as Windows only keeps an INI file open for the duration of each read or write.

OK:

Leaves unchanged.

Example:

INIFILE OPEN,MYSCR.INI

INIFILE WRITE,Data,Name,Fred Bloggs

See also:

@INIREAD


LIST

Syntax:

LIST  <list>, <command>, <parameters>

Description:

The LIST command is used to create, manipulate and dispose of string lists.  WinScript allows you to have up to four string lists, numbered 1 to 4.  List boxes which appear in a dialog window can also be treated as string lists.  The parameter <list> must be either a list number (between 1 and 4) or the name of the dialog list box to which the command will apply

Lists can contain any number of strings holding up to 255 characters each.  A list can either be sorted, or will retain the order in which the information was entered.

For more information see Using Lists and Data Lists.

OK:

Set to false if the LIST command fails.

Example:

LIST 1, CREATE, SORTED

LIST 1, ADD, Fred Jones

LIST 1, ADD, John Smith

See also:

@COUNT	@INDEX	@ITEM	@MATCH 	@NEXT


LIST dialog element
LIST(<name>;<top>;<left>;<width>;<height>;{SORTED})

This dialog element creates a list box at the position and size specified.  The optional parameter SORTED specifies whether the list items are to be maintained in ASCII order or not.  To get data into the list box you must use the LIST command.


Labels

Labels are used as the target of GOTO and GOSUB commands.  They start in the first character position of a line with a colon, and are followed by the label name.

This is an example of a label:

:LABEL

Labels, GOTO and GOSUB commands are used to change the order of execution of script commands.


Licence Agreement

Licence

WinScript is not free software.  The software is, and remains, the property of J M Technical Services.

You are granted a licence to evaluate this software free of charge for a period of 28 days.  On the expiry of this period, you agree to either a) register the software, or b) delete the software from your system.

WinScript is copyright © 1995 J M Technical Services.  All rights are reserved.

Trademarks

Windows, Windows 95 and Visual Basic are trademarks of Microsoft Corporation.

Delphi is a trademark of Borland International, Inc.


List example
List

This example uses a list box to demonstrate some of the things you can do with lists.

WINDOW CREATE,List example,100,100,280,240,LIST(LB;10;4;192;172),-

  TEXT(T1;190;4),BUTTON(Quit;22;208),BUTTON(Add;54;208),BUTTON(Remove;86;208),-

  BUTTON(Match;118;208),BUTTON(Put;150;208)

%C = 0

repeat

  list LB,add,This is line %C

  %C = @succ(%C)

until @equal(%C,16)

:loop

dialog set,t1,Pointer = @index(LB)

wait event

goto @event()

:addbutton

%A = @input(Enter text to add:)

list LB,add,%A

goto loop

:putbutton

%A = @input(Enter text to put:)

list LB,put,%A

goto loop

:removebutton

dialog clearsel,LB

goto loop

:matchbutton

%A = @input(Enter text to match:,%A)

if @not(@match(LB,%A)

  warn No match found

end

goto loop

:quitbutton


MCI Test

This script lets you send Multimedia Control Interface (MCI) commands, and displays any error messages that may result.  It is a good tool for trying out MCI commands prior to incorporating them into your own scripts.

title Test MCI

%2 = open C:\WIN95\MEDIA\THEMIC~1.WAV alias sound

%3 = play sound

%4 = close sound

:loop

%C = @input(Enter MCI command (Cancel quits):,%2)

if @not(@ok())

  exit

end

if @null(%C)

  exit

end

%R = @MCI(%C)

if @ok()

  info MCI Response: %R

else

  warn MCI error: %R

end

shift

goto loop

See also

Using MCI


Making Executable Files

WinScript allows you to create an executable file for a script.  From the Run menu, select Make EXE file, and this dialog appears:

You can choose a different icon for the program using the Change Icon button.  When you press OK, WinScript generates an EXE file with the same name as the script.

WinScript executables are not standalone executable programs.  The EXE file created is simply a shell program that calls WinScript and passes it the name of the script and any other command line parameters.  The script file and the WinScript interpreter are still needed or the script will not run.

Since you can run scripts by automatic association there is not, in many cases, any point in creating an executable file for your scripts.  However, executables are useful for the following reasons:

Windows uses the path to search for an executable file command, so if the directory containing the EXE file is on the path string there is no need to type the full path to the script.

If you drag files to an executable file icon, they are passed to the program as parameters when the program is run.  The script file name is always the first parameter; you can access the dragged filenames as %2 onwards.


OK dialog element
OK

This dialog element provides an easy way to create an OK button which is automatically positioned at the bottom of the window.  When pressed it causes an OKBUTTON event.


Order Form

Please use this form when registering direct with J M Technical Services.

Product:	WinScript version 1.00

Program registration fee:	£	25.00

Bank charge for cheques drawn on

non-UK banks (delete if inapplicable):	£ 	  6.00

==========

TOTAL (payable to J M Technical Services)	£	   .00

==========

Your name:	_________________________________________________

Company name:	_________________________________________________

Your address:	_________________________________________________

_________________________________________________

_________________________________________________

Post/Zip code:	_________________________

Country:	_________________________

Email address:	_________________________

I would like to receive an email newsletter about WinScript:  YES  /  NO

Send to:	J M Technical Services

11a Cedar Lane

Cockermouth

Cumbria

CA13 9HN

United Kingdom

Email:	jmoss@jmtech.demon.co.uk

100015,1242@compuserve.com


Overview

WinScript is a simple programming language for Microsoft Windows.  It's aim is to allow you to quickly develop simple programs or automated procedures for Windows as easily as writing a batch file or Basic program for DOS.  The language has a simple syntax, which spreadsheet-like formula functions and typeless variables.  Programs can be tested instantly using the interactive development environment with integrated editor and debugger.

WinScript is not intended to be an alternative to programming languages like Visual Basic or Delphi for application development.  But it is a better choice when you need a simple utility or a quick solution to a problem.  Most WinScript scripts can be written and tested in a matter of minutes once you are familiar with the script language.  We are confident that you will find WinScript an indispensible addition to your collection of Windows utilities.

Examples of tasks for which you could use WinScript are:

create an 'intelligent' start-up script to load applications or perform housekeeping tasks at start-up, dependent on time, date etc.;

create a start-up menu with buttons to select which applications are loaded;

create an 'Agent' script that runs in the background and performs actions at certain times;

control other Windows applications by sending keystrokes, using DDE and setting the size and position of their windows;

create software installation programs;

create simple utilities such as databases or system resource monitors;

create front-ends for DOS programs, which can run invisibly in the background so that it looks as if a Windows application is running;

produce interactive multimedia applications that display bitmaps and play sounds.


PLAY

Syntax:

PLAY  <file name> {, WAIT}

Description:

Plays an audio wave (*.WAV) file.  If the parameter WAIT is specified the script does not proceed to the next command until the sound is finished.

OK:

Leaves unchanged.

Example:

PLAY intro.wav,WAIT

See also:

@MCI


POPUP dialog element
POPUP(<item>;{<item>;...}

This dialog element defines a popup menu for the dialog window.  When a menu item is selected, it causes an <item>MENU event.


PRINT

Syntax:

PRINT  <filename>, WAIT

Description:

Prints the file <filename> using the file association stored in the Windows registry.

If the WAIT parameter is included then script execution does not continue until printing has terminated.

Note: When 32-bit applications are run and the WAIT parameter is used, the command does not return until all instances of the program that was used to print the file have been closed.  See the RUN command for further details.

OK:

Set to false if the command fails.

Example:

PRINT c:\docs\myfile.doc

See also:

RUN


REGISTRY

Syntax:

REGISTRY  DELETE, <root key>,  <subkey>

REGISTRY  WRITE, <root key>,  <subkey>,  <name>,  <value>

Description:

The REGISTRY command modifies the value of keys in the Windows registry.

REGISTRY DELETE deletes the specified key and all of its subkeys.

REGISTRY WRITE sets the value of the specified key.  If the subkey does not exist it is created.

<root key> specifies the root key to search from.  The permissible values are:

ROOT	specifies HKEY_CLASSES_ROOT

CURUSER	specifies HKEY_CURRENT_USER

LOCAL	specifies HKEY_LOCAL_MACHINE

USERS	specifies HKEY_USERS

<subkey> specifies the key value to use.  Keys several levels deep can be specified using backslashes.

<name> specifies the named value to retrieve.  If null, the value of the first NULL name of the key is changed.  Note that this parameter is currently ignored, but is included for compatibility with the 32-bit version.

<value> is the string value to which the key is set.  Currently WinScript only supports string values.

WARNING: Modifying the system registry is potentially dangerous, and can render Windows unable to run.  Ensure you have a backup of the registry files before experimenting.

OK:

Set to false if the REGISTRY command fails.

Example:

REGISTRY WRITE,ROOT,.wsc,,wnscript

REGISTRY DELETE,ROOT,.tmp

See also:

@REGKEYS	@REGREAD	Example


REM

Syntax:

REM  <text>

Description:

Use the REM command to enter a comment in your script.

OK:

Leaves unchanged.

Example:

REM This script does something interesting

See also:


REPEAT

Syntax:

REPEAT

   ... commands ...

UNTIL <string>

Description:

Commands between the REPEAT and UNTIL lines are repeatedly executed while the result of <string> evaluates to null (false).  If the string is non-null then script execution continues on the line following UNTIL.

REPEAT commands may be nested.  For clarity it is a good idea to indent the commands nested within REPEAT ... UNTIL as shown in the example.

It is not recommended to use the GOTO command to branch out of a REPEAT ... UNTIL group of commands.

OK:

Leaves unchanged.

Example:

REPEAT

  %A = @SUM(%A,1)

UNTIL @EQUAL(%A,6)

See also:

@NOT	@NULL	IF 	Tip


RUN
RUN, RUNH, RUNM, RUNZ

Syntax:

RUN  <filename>  <parameters>,WAIT

Description:

Opens (or runs) the file or program <filename>, with the additional parameters specified.  If a filename is given then the file is opened using the file association stored in the Windows registry.

If the WAIT parameter is included then script execution does not continue until the program has terminated.

The variants of the command are:

RUN	- run as a normal window;

RUNH	- run in a hidden window;

RUNM	- run as a maximized window;

RUNZ	- run minimized as an icon.

Note: When 32-bit applications are run and the WAIT parameter is used, the command does not return until all instances of the program that was run have been closed.  In other words, if you run Notepad and another Notepad is already open, the command will not finish until both have been closed.  A solution would be to use the following code instead of using WAIT:

repeat

  wait 1

until @not(@winexists(<window title of your instance of the program>))

This may be fixed in the 32-bit version of WinScript.

OK:

Set to false if the command fails.

Example:

RUN readme.txt

RUNZ pkzip.exe c:\temp\test.zip *.txt,WAIT

See also:

PRINT


RUNH

see:	RUN


RUNM

see:	RUN


RUNZ

see:	RUN


Registering WinScript

Registration of WinScript will entitle you to continued use of the software after the initial evaluation period has expired.  You will be granted a non-exclusive, non-transferable licence to use the software on a single computer system, subject to the terms and conditions set out in the Licence Agreement.

Currently you have a choice of two methods for registering WinScript.  You can register directly with J M Technical Services, paying by cheque, or if you are a member of CompuServe you can GO SWREG, in which case the registration fee is billed to your CompuServe account.

On registering WinScript you will receive by post or email a serial number which is keyed to the personal details you supplied.  Use the registration script supplied with the product to customise your copy with your name, company name and serial number.  This will prevent the About box being displayed automatically at start-up.  Some future enhancements may only be available to registered users.

You can also opt to receive an email bulletin containing hints, tips and sample scripts for you to use.  Please let us know how you are using the product, and any enhancements or new features you would like to see incorporated in future versions.


Registry Information example
Registry Information

This script displays information about the file associations that are set up in the Windows registry.

title Registry Info

%X = @input(Enter file extension,.wsc)

if @ok()

  rem get file type

  %A = @regread(ROOT,%X)

  if @null(%A)

    info No registry association for %X

  else

    rem get file type description

    %B = @regread(ROOT,%A)

    rem get the first level subkeys

    %C = @regkeys(ROOT,%A)

    rem is there a shell key?

    if @not(@zero(@pos(shell,%C)))

      rem get the shell open command

      %D = @CR()ShellOpen: @regread(ROOT,%A\shell\open\command)

    end

    info Registry association for %X@CR()Type: %A@CR()Keys: %C@CR()Description: %B%D

  end

end


Running Scripts

Scripts may always be run from the development environment.  Once they are finished and fully debugged, however, you will probably want to run them on their own, as standalone programs.

Scripts can be run by association.  When you run the Setup script supplied, Windows creates an association between script files (extension .WSC) and the WinScript program.  WinScript treats the first parameter on its command line as the name of a script to run.  Using the association, you can run scripts simply by double-clicking on a script icon, or by including them in the Windows startup group.  You can also create an executable file for your script.

Running scripts in this way saves resources as the development environment is not loaded into memory.


SHIFT

Syntax:

SHIFT

Description:

Shifts the command line parameter variables so that %8 takes the value of %9, %7 takes the value of %8 and so on down to %1 takes the value of %2.  This is similar to the MS-DOS SHIFT batch file command.

OK:

Leaves unchanged.

Example:

SHIFT

See also:


STATUS dialog element
STATUS(<name>;<text>)

This dialog element creates a status panel at the bottom of the dialog window, containing the text <text>.  A dialog can only have one status panel.


STYLE dialog element
STYLE(<style> {; <style> ...})

The STYLE dialog element defines various characteristics of the appearance of the dialog (see Dialog Styles).

Valid styles are:

GRAY3D	Dialog has a gray 3D appearance.

BLACK	Dialog uses white text on a black background

RESIZ	Dialog has standard window color and a resizable border

NOTITLE	Dialog has no title bar

ONTOP	Dialog will remain on top of other windows

The STYLE dialog element must appear before any controls are defined.  Styles may be combined by listing more than one, but when combining styles that set the color of the dialog the colors associated with the last style listed will be used.


Screen metrics

Metrics is the term used by Microsoft to describe the characteristics of an output device, such as the display.  One factor that may affect your scripts is the number of pixels per inch used by the display driver.. Windows displays typically use either 96ppi or 120ppi, the latter when the Large Fonts display option is selected.

When large fonts are used, text takes up more space relative to the dialog controls it is displayed in.  There are two solutions you can adopt if your scripts may be run on systems using either small or large fonts.  Either allow plenty of space so that text displays correctly in any event, or hold the relevant co-ordinates in variables and scale them by a factor of 5 / 4 when large fonts are used.


Script Window

The script window is used for editing and debugging scripts.  The window supports all the editing options and shortcut keys of a standard Windows text editor such as Notepad.

If you right-click in the editor window, a menu appears from which you can choose a number of options.

You can call up the command or function reference sections from the help system using the menu.  You can also place the cursor in the middle of a command or function and call up the help page for that command or function from the menu.  Alternatively you can select some text with the mouse and then press Control + F1.

For debugging purposes, you can set a breakpoint by placing the cursor in the line at which you want execution to stop, right-clicking the mouse and selecting Breakpoint at Cursor from the menu.  The line at which the breakpoint is set is displayed in the status bar.  You can clear the breakpoint from the same menu.

During single-step debugging, the command which is about to be executed is shown highlighted.

If an error is found during execution of a script, the line containing the error is highlighted when WinScript displays the error message.


Sending Keystrokes

Text and keystrokes can be sent to another application just as if they were typed at the keyboard, using the WINDOW SEND command.

To identify the window to which keystrokes are to be sent, the window title must be specified.  Just as when using the keyboard, the window which will receive keyboard input is the active window, so WinScript makes the window active by executing a WINDOW ACTIVATE command.

The keystrokes to be sent are specified as a string parameter to the WINDOW SEND command.  Text can be entered as ordinary text.  Functions like @TAB() and @CR() can be used for the Tab and Enter keys.  WinScript also provides several special functions which can be used to generate keystrokes for certain other important keys.  @ALT can be used to simulate the Alt key being pressed, @CTRL simulates the Ctrl key being pressed, and @SHIFT simulates the Shift key being pressed.  In addition, the @KEY function can be used to generate the keystrokes for the Home, End, Up arrow, Down arrow, Left arrow, Right arrow, PgUp, PgDn, Ins and  Del. keys.  If the @CHR function is used to generate characters that do not correspond to a key on the keyboard then the results may be unpredictable.

Sending keystrokes to another application is not an entirely predictable affair.  Timing considerations may mean that an apparently correct sequence of keystrokes may not work, or may not always work reliably.  An application may ignore keystrokes that arrive faster than it can respond to them.  Note also that other activity on the system may result in a different window bringing itself to the foreground while keystrokes are being sent, resulting in it, rather than the intended recipient, from receiving the remaining keystrokes.  To minimise these problems, the amount of data sent by each WINDOW SEND command should be kept short, and WAIT commands used between them.

For an example of how to control another application using WinScript, see the Controlling WordPad example.

Note that the WINDOW SEND command is not supported under Windows NT.


ShellNew Example
ShellNew

This script displays a small dialog box which allows you to choose a new document from a selection of templates from the New... popup menu in Windows 95.  It is included as an example of what you can do with WinScript and Windows 95.  If you use the script you will want to modify it to suit your own requirements.

In this example the dialog offers a choice of three templates which are stored in the directory D:\WORK\Templates.  To invoke the script when the New... menu item is chosen you should use REGEDIT to create a ShellNew subkey in the entry for the file extension (.DOC in this case) in the Windows Registry, and then create a string value for this key called Command, which must contain the command: WINSCR SHELLNEW.WSC "%2".  The target filename is passed to the script as %2.  Quotes are needed round the parameter because there are spaces in it which would cause WinScript to treat each word as a separate parameter.  The target extension is put into %X which you can test and then create a different dialog depending on the type of new document to be created, so the same script can be called for different file types.

rem Create new document from template

rem %2 is target filename

%X = @ext(%2)

%D = @substr(%2,1,@diff(@len(%2),@len(@name(%2).%X)))

if @equal(%X,DOC)

  window createdlg,Document Templates,-1,0,230,140,ICON(worddoc.ico),CLICK,-

    BITMAP(Normal;10;24;32;32;worddoc.ico),BITMAP(Invoice;10;96;32;32;worddoc.ico),-

    BITMAP(Fax;10;168;32;32;worddoc.ico),-

    TEXT(T1;48;24;;;Normal),TEXT(T2;48;96;;;Invoice),TEXT(T3;48;172;;;Fax)

end

wait event

if @equal(@event(),CLICK)

  %N = @click(name)

  %O = @substr(New_%N,1,8)

  file copy,D:\WORK\TEMPLA~1\%N.%X,%D%O.%X

end

exit


Startup example

This example creates a startup menu with two buttons in the center of the screen, which you can use to select which programs are run automatically at startup.

title Startup Menu

window createdlg,Startup,-1,20,160,142,STYLE(ONTOP),-

  TEXT(T1;10;20;;;Choose a startup option:),-

  BUTTON(Standard;36;20;120),BUTTON(Quick;76;20;120),STATUS(SB)

%C = 10

repeat

  dialog set,SB,Time remaining: %C seconds

  %C = @pred(%C)

  %D = 400

  wait 1

  %E = @event()

  if @zero(%C)

    rem default

    %E = STANDARDBUTTON

  end

until %E

:startup

dialog close

wait 1

:

: run stuff that should always be run

:

if @equal(%E,STANDARDBUTTON)

:

: run stuff that won't be run if you

: press the Quick button

:

end

exit


String Lists

String lists can be used to hold the contents of text files as well as lists of ASCII data.  As the name implies, they are lists of strings.  Strings are limited in length to a maximum of 255 characters, but the number of strings in a list is limited only by available memory.

WinScript supports four independent string lists, which are numbered from 1 to 4.  In addition, the contents of listboxes - which can appear in a dialog window - are also string lists, and can be manipulated using the same list commands.

String lists can be unsorted, in which case strings remain in the order they were loaded and items may be added at the end using LIST ADD or replaced by using LIST PUT. Using the LIST SEEK and LIST PUT commands, and the @MATCH and @ITEM functions, lists can be used as random access files.

Alternatively lists may be sorted, in which case WinScript maintains the order of items and new items must only be added using LIST ADD.  To replace an item in a sorted list you must delete it and then add it.

For more information on how lists are used, see Using Lists.

For information on how to load data into lists see Data Lists.


Strings

In WinScript, all variables and parameters to commands and functions are strings.  Strings can contain embedded variables and functions, which are substituted or evaluated as the string is processed from left to right.

So if %D contains C: then the string:

Drive %D has @SPACE(%D)Kb free

would be evaluated to:

Drive C: has 32456Kb free

Note that the symbols % and @ (which are used to denote variables and functions), commas (which are used to split strings into two or more parameters for commands or functions that expect multiple parameters), and brackets (which enclose the parameters of an individual function), cannot normally appear in a string because of the special meaning attached to them.  To overcome this, strings can be enclosed in double quotes (").

Text within double quotes is interpreted simply as text: no variable substitution or function evaluation will be performed.  Quotes can appear anywhere in a string to prevent substitution or evaluation for a particular section, as in this example:

%A = Order @input(Enter quantity,1) "widgets @ "%R" each (incl. "%T"% sales tax)"


System Information example
System Information

This script displays information about the system.

rem Test @SYSINFO function

title System Information

%D = DOS version@tab()= @SYSINFO(DOSVER)

%W = Windows version@tab()= @SYSINFO(WINVER)

%X = Temp directory@tab()= @ENV(TEMP)

%Y = Windows directory@tab()= @WINDIR()

%F = Free resources@tab()= @SYSINFO(FSR)%

%G = GDI resources@tab()= @SYSINFO(GDIRES)%

%H = User resources@tab()= @SYSINFO(USERRES)%

%M = Free memory@tab()= @SYSINFO(FREEMEM)Kb

%S = Screen width@tab()= @SYSINFO(SCREENWIDTH)

%T = Screen height@tab()= @SYSINFO(SCREENHEIGHT)

info %D@CR()%W@CR()%X@CR()%Y@CR()%F@CR()%G@CR()%H@CR()%M@CR()%S@CR()%T


TEXT dialog element
TEXT(<name>;<top>;<left>;<width>;<height>;<text>)

This dialog element creates a text control at the position and size specified, containing the text <text>.


TITLE

Syntax:

TITLE  <string>

Description:

Sets the title of the script which will appear in message and input boxes.  If no title is set, the filename of the script file is used.

OK:

Leaves unchanged.

Example:

TITLE Daily Backup

See also:


Tip (IF command)
WinScript does not allow compound conditions.  However, you can have a group of statements executed if one or more of several conditions are true by concatenating the conditions, since WinScript considers a non-null result to be true.  For example:

if @ext(%F,COM)@ext(%F,EXE)@ext(%F,BAT)

  run %F

end


Using Lists

Syntax:

LIST  <list>, ADD,  <text>

LIST <list>, ASSIGN, <list2>

LIST <list>, CLEAR

LIST  <list>, CLOSE

LIST  <list>, CREATE, {SORTED}

LIST  <list>, DELETE

LIST  <list>, PUT,  <text>

LIST  <list>, SEEK,  <record number>

LIST  <list>, WRITE,  <text>

Description:

These LIST commands are used to modify, save and dispose of string lists.  The parameters <list> and <list2> must be either a list number (between 1 and 4) or the name of the dialog list box to which the command will apply.  An error will occur if the list does not already exist or the record number (for the SEEK command) is out of range.

ADD is used to add an item to the list.  You use this to add items to a sorted list (they are inserted in the correct position according to the sort order) or to append items to an unsorted list, much as you would write successive lines to a text file.

ASSIGN copies the contents of <list2> to <list>

CLEAR is used to remove all items from a list and reset the item pointer to zero.

CLOSE must be used to dispose of a list that you have CREATEd once you have finished with it.  This releases the memory it used, and makes the list number available again for a new list.

CREATE creates a new, empty string list.  The option SORTED specifies whether the list is to be maintained in ASCII code order.

DELETE deletes the item at the position in the list indicated by the index (pointer).  This is the first item (item 0) when the list is first opened, but can be modified by means of the SEEK command.

PUT is used to write the specified text to the position in the list indicated by the index (pointer).  PUT lets you treat a list as a random access file.  Note that you cannot use PUT with sorted lists.

SEEK is used to set the index pointer to a specific item number.

OK:

Set to false if the LIST command fails.

Example:

LIST 1, SEEK, 3

LIST 1, WRITE, This is item 4 in the list

LIST 1, SAVEFILE, LIST.TXT

LIST 1, CLOSE

See also:

@COUNT	@INDEX	@ITEM	@MATCH 	 @NEXT 	LIST 	Data Lists	Example


Using MCI

WinScript allows you to control multimedia devices using the Windows Multimedia Control Interface (MCI).  WinScript provides the @MCI function, which can be used to send MCI command strings and obtain the response, which may consist of information or an error message.

MCI is a command language in its own right.  For a complete description of it, refer to Microsoft's own multimedia documentation or third party books on Windows multimedia development.  If you can obtain the help file MCISTRWH.HLP, supplied with Microsoft Visual C++, this will also be a useful reference.

MCI command strings are English-like and readily understandable.  You open a device, play it, and then close it when you are finished with it.  For example, the command strings:

open cdaudio

play cdaudio from 1 to 2

close cdaudio

would play the first track of an audio CD.  Audio data files must be given a name, called an alias, which is used in the MCI commands.  For example:

open C:\WINDOWS\MEDIA\THEMIC~1.WAV alias sound

play sound

close sound

If the above MCI command strings were sent using a WinScript script then the result would be nothing, because the sound would be stopped by the close command before it had a chance to play.  By appending the word wait to an MCI command string, control is not returned to the script until the command has completed.  If the command

play cdaudio from 1 to 2 wait

was sent then execution of the script would be held up until the track had finished playing.


Variables

WinScript allows you to have up to 35 variables.  Variable names start with a percent symbol, followed by the character 1 to 9 or A to Z.

The variables %1 to %9 contain the command line parameters to WinScript.  %1 contains the name of the script file.  Parameters %2 to %9 can be used to pass information to WinScript when it is run from a batch file or an icon.  Unlike a DOS batch file you can also assign your own data to the variables %1 to %9, overwriting the original contents.

WinScript variables are untyped strings, each of which contain a maximum of 255 characters.  Because variables are untyped it is up to you to ensure that, for example, where a function requires a numeric value the variable passed to it contains a string which is a valid number.

Note that the use of the percent symbol to identify variables, and the @ symbol to identify functions, means that you cannot generally use these symbols in a string of text.  Double quotes can be used to enclose text containing these symbols and prevent them from being interpreted as variables or function names, like this:

INFO Email address:@tab()%N"@cix.compulink.co.uk"

WinScript also supports string lists.  You can think of these as arrays of strings, which can be maintained in sorted or unsorted order and accessed either sequentially or by item number.


Viewer example
Viewer

This example program displays image files which are dragged and dropped on to the window.

title Image Viewer

%W = 320

%H = 160

window createdlg,Image Viewer,100,100,%W,%H,DRAGDROP,-

  BITMAP(BM;0;0;%W;%H)

:evloop

wait event

if @equal(@event(),close)

  exit

end

list 1,create

list 1,dropfiles

%F = @next(1)

dialog set,BM,%F

dialog title,%F

list 1,close

goto evloop


WAIT

Syntax:

WAIT <interval>

WAIT EVENT {, <interval> }

Description:

Pauses execution of the script for a period of <interval> seconds.  If <interval> is not specified then the default period is 1 second.

An interval of between 1 and 60 seconds can be specified.  A long interval is useful for scheduling events but when debugging a script, note that if you choose Run / Stop from the menu or press the Stop toolbar button this will not be acted on until after the pause has completed.

The WAIT EVENT command is used in dialog programming.  It is only valid when a dialog is being displayed.  It causes the script to wait indefinitely until an event occurs such as a button being pressed.

If an interval is specified in a WAIT EVENT command, then a TIMER event will be generated when the interval has elapsed.  This is useful for dialogs that must be updated at intervals, because it allows you to respond immediately to button and other events as well.

OK:

Not affected.

Example:

%T = @INPUT(Enter alarm time [hh:mm]:)

repeat

  wait 30

  %N = @HH():@MM()

until @EQUAL(%T,%N)

beep

warn Wake up!

See also:


WARN

Syntax:

WARN  <string>

Description:

Displays a dialog box containing an exclamation mark icon and the message <string>.  Execution of the script continues when the OK button is pressed.

OK:

Set to true.

Example:

WARN There is less than 100Kb of free space on drive D:

See also:

INFO 	@ASK 	@QUERY


WINDOW

Syntax:

WINDOW  ACTIVATE,  <window name>

WINDOW  CLOSE,  <window name>

WINDOW  CREATEDLG,  <window name>,  <top>, <left>, <width>, <height>, <description>

WINDOW  HIDE,  <window name>

WINDOW  ICONIZE,  <window name>

WINDOW  MAXIMIZE,  <window name>

WINDOW  NORMAL,  <window name>

WINDOW  ONTOP,  <window name>

WINDOW  POSITION,  <window name>, <top>, <left>, <width>, <height>

WINDOW  SEND,  <window name>,  <string>

Description:

The WINDOW command is used to control other windows.  The string <window name> identifies the window that is the target of the command.  The string must contain enough of the title text to uniquely identify the window.

WINDOW ACTIVATE Activates (restores from an icon, or brings to the top) the named window.

WINDOW CLOSE closes the named window.

WINDOW CREATEDLG creates a dialog window to the design you specify.  This command has many different parameters.  It is described in more detail in the topics Creating Dialogs and Dialog Elements.  The types of dialog you can create are shown in Dialog Styles.

WINDOW HIDE hides the named window.

WINDOW ICONIZE minimizes the named window to the Task Bar.

WINDOW MAXIMIZE maximizes the named window.

WINDOW NORMAL restores to normal size the named window.

WINDOW ONTOP sets the Topmost attribute of the named window so that it remains in view even when not active.

WINDOW POSITION positions the named window so that it's top left corners are at the co-ordinates specified.  The width and height can also be specified: if they are omitted, the window retains its existing size.

WINDOW SEND sends the contents of <string> to the named window.  For more information, see Sending Keystrokes.  Note that this facility cannot be used under Windows NT.

OK:

Set to false if no matching window was found.

Example:

if @winexists(Connected to Internet)

  window position,Connected to Internet,100,100

  window ontop,Connected to Internet

end

See also:

@WINEXISTS	@WINPOS


Warranty and Liability

J M Technical Services shall not be liable for any loss or damage resulting from the use of this software.  It is entirely the user's responsibility to take adequate precautions to safeguard any equipment or data which may be affected by the use of this software.  By deciding to use the software you are agreeing to these terms.


Watch Window

The watch window is used to examine the contents of WinScript's variables, and the OK status variable.

This window is most useful when single-stepping through a script.


WinScript Language

The WinScript programming language has been designed to be simple, flexible and easy to use.  Programs consists of three main elements, labels, commands and assignments.


breakpoint
Set/unset breakpoint at cursor position


continue
Continue execution from current point


controls
Controls are objects such as buttons, text and list boxes which may appear in a window.


edit menu
The Edit menu contains options for cutting text, copying it to and pasting it from the clipboard, and for search and replace.


editcopy
Copies the selected text to the clipboard.


editcut
Cuts selected text to the clipboard


editfind
Search for text in the script


editfindnext
Search for the next occurrence of text in the script


editpaste
Pastes text from the clipboard.


editreplace
Search for and replace text


events
Events occur when a button is pressed or when the dialog window is closed.  Optionally, you can also have an event occur when you click on the dialog or a bitmap with the mouse, or when files are dragged and dropped over the dialog window.  You can halt a script and wait for an event to occur using the WAIT EVENT command, and determine the type of event using the @EVENT function..


exit
Exits WinScript.


file menu
The File menu contains options for opening and saving scripts, and for exiting WinScript.


filenew
Creates a new script.


fileopen
Opens an existing script.


filesave
Saves the script.


help menu
The Help menu allows you to access WinScript's online help.


helpcontents
Displays the contents page of the online help.


helpsearch
Allows you to perform a keyword search of the online help.


options menu
The Options menu lets you set your preferences, such as whether the environment should iconize while a script is running, and the font to be used in the editor window.  You can also set the default directory which WinScript will search in if it cannot find a script, icon or bitmap file in the current directory.


pause
Pauses execution of a running script.


run
Starts a script from the first line.


run menu
The Run menu is used to run the script.  Other options allow you to toggle single step mode, show or hide the variable watch window, set command line parameters for the script being tested, and create an executable file.


singlestep
Toggles on/off the single-step debugging mode.


step
Starts a script from the next line.  Used in single-step debugging mode.


watch
Shows or hides the variable watch window.