KiXtart Command Reference
Note: Square brackets ([ ]) indicate optional arguments, and angle brackets (< >) indicate required arguments.
Action
Defines a label within the script file to which you can transfer control.
Syntax
:label
Remarks
Labels must be unique within the script. You can define a label in an IF statement, but you cannot jump to one from outside that IF statement
Action
Indicates a comment. Subsequent characters on the script line are ignored.
Syntax
;
Action
Indicates a new line. This moves the cursor position to the beginning of the next line.
Syntax
?
Action
Causes the system to beep.
Syntax
BEEP
Action
Changes the character mode to large characters.
Syntax
BIG
Remarks
When BIG is used, subsequent screen output is 8 characters wide and 8 characters high. Use SMALL to reset the character mode to normal.
BIG is ignored when screen output is redirected to a file.
Action
Enables (BREAK ON) or disables (BREAK OFF) the ctrl+c/break keys and the Close command. This effectively allows control over whether a script run by KiXtart can be interrupted or not.
Syntax
BREAK <ON | OFF>
Remarks
By default, to prevent users from inadvertently interrupting a script, KiXtart automatically disables the ctrl+c/break keys, disables the Close command in the System menu of the current command-prompt window, and hides the Please wait while your logon script executes message box on Windows 9x.
In a multi-tasking environment such as Windows NT, you cannot fully prevent users from interrupting a program. (They can end programs by using the Task List, for example.) As an additional protection, on computers running Windows NT Workstation only, when BREAK is OFF (the default) KiXtart also installs a special event handler for the current console. The effect of this handler is that whenever a user forcibly terminates KiXtart, the user is automatically logged off. This means that you must be careful when testing scripts.
Tip : the Please wait while your logon script executes message box contains a Cancel button, which you can hide by opening a copy of Msnet32.dll in Visual C 4.00 WorkBench, selecting the LMWINSCRIPTDLG resource, and making the Cancel button invisible.
Action
Runs a separate KiXtart script.
Syntax
CALL "script name"
Remarks
When the called script ends or when a RETURN statement is encountered, script execution continues at the statement following the CALL statement in the calling script.
Theoretically, there is no limit to the number of scripts that can be nested. Obviously, the practical limit on the number of scripts you can call is determined by the amount of available memory at the time KiXtart runs, the size of the scripts, the number of variables defined, and so on.
Action
Changes the current working directory to the directory specified.
Syntax
CD "directory"
Remarks
Check the value of @ERROR to see if CD was successful.
Action
Clears the screen and moves the cursor to position 0,0.
Syntax
CLS
Remarks
The CLS command is ignored if all output has been redirected to a file using the REDIRECTOUTPUT function.
Action
Sets the color attribute to be used in subsequent display statements.
Syntax
COLOR Xx/Yy
Parameters
|
X |
Foreground color |
|
x |
Optional intensity indication |
|
Y |
Background color |
|
y |
Optional blink indication |
Possible values for the foreground and background colors are:
|
n |
Normal (black) |
|
b |
Blue |
|
g |
Green |
|
c |
Cyan |
|
r |
Red |
|
m |
Magenta |
|
y |
Yellow/brown |
|
w |
White |
Remarks
If the foreground color is followed by a plus sign (+), the color is displayed with high intensity.
Specifying a plus sign (+) with the background color causes the color to be displayed blinking.
Examples
|
COLOR w+/b |
Bright white text on a blue background |
|
COLOR g/r+ |
Green text on a blinking red background |
Action
Creates a cookie, or semaphore-file, that the Windows 9x Logon API uses to determine whether the script has finished running. This command is only useful when KiXtart is being used to emulate Lmscript.exe. For more information, see “Lmscript Emulation,” earlier in this document.
Syntax
COOKIE1
Action
Copies one or more files.
Syntax
COPY "source" "destination" [/h]
Remarks
Wildcards are supported.
If a file already exists at the destination, it is overwritten without warning.
The /h option can be used to include files with the hidden or system attribute set in the copy.
Action
Deletes a file.
Syntax
DEL "file name"
Remarks
DEL does not prompt the user to confirm the deletion.
Wildcards are supported.
Action
Declare one or more local variables.
Syntax
DIM "variable1" [<,>"variablex"]
Remarks
Local variables are visible only in the current script or script segment.
Examples
DIM $Variable
DIM $Array[9] ; Note : declaration of an array of 10 elements.
IF $X = 1
DIM $Var1, $Var2, $Var3
ENDIF
Action
Displays the contents of a file on the screen, starting at the current cursor position.
Syntax
DISPLAY "file name"
Action
Loops until an expression becomes true.
Syntax
DO ... UNTIL "expression"
Remarks
DO UNTIL loops can be nested as many times as memory allows.
Action
Exits the current KiXtart script, or, if used at the topmost level, exits KiXtart.
Syntax
EXIT [error level / exit code]
Remarks
If EXIT is followed by a numeric expression, then @ERROR is set to the value of that expression and you can check it in the calling script or batchfile.
Action
Flushes all pending characters from the keyboard buffer.
Syntax
FLUSHKB
Action
Accepts a single character from the keyboard and stores the character in a variable.
Syntax
GET $x
Remarks
The character is stored in the specified script variable. If a function key, such as F1, is pressed, GET returns 0, and @ERROR returns the key code of the function key.
Action
Reads a line of characters from the keyboard until the <enter> key is pressed, and stores the result in a variable.
Syntax
GETS $x
Action
Declare one or more global variables.
Syntax
GLOBAL "variable1" [<,>"variablex"]
Remarks
Global variables are visible everywhere in every script during the current KiXtart session.
Examples
GLOBAL $X
GLOBAL $X, $Y, $Z
Action
Changes the current drive.
Syntax
[GO] drive
Remarks
Use GO if you want to specify a variable as the drive to change to.
Examples
GO A:
A:
GO $2
Action
Causes script execution to continue at the first statement after a label.
Syntax
GOSUB <label>
Remarks
Label can be an expression.
When a RETURN statement is encountered, script execution continues at the statement following the GOSUB statement.
Examples
? "This demonstrates calling a subroutine"
GOSUB "Demo"
? "End of demonstration…"
EXIT 1
:Demo
? "We are in the subroutine now…"
RETURN
Action
Causes script execution to continue at the first statement after a label.
Syntax
GOTO <label>
Remarks
Label can be an expression.
Examples
GOTO "end"
$string = "end"
GOTO $string
Action
Conditionally runs statements.
Syntax
IF expression
statement1
....
[ELSE
statement2
.... ]
ENDIF
Remarks
The body of an IF statement is executed selectively depending on the value of the expression. If expression is true, then statement1 is executed. If expression is false and the ELSE clause is specified, then statement2 is executed.
IF statements can be nested as many times as memory allows.
If the expression does not contain any relational operators, the condition is considered to be true if it is numeric and it evaluates to a value other than zero, or if it is alphanumeric and it evaluates to a string containing at least one character.
Comparisons are not case-sensitive.
Examples
IF $X ; similar to IF $X <> 0
IF @HOMESHR ; similar to IF @HOMESHR <> ""
IF INGROUP("Domain Admins") ; similar to IF INGROUP("Domain Admins") > 0
IF INGROUP("Domain Admins") = 0 ; true if user NOT a Domain Admin
IF $X*2 < 10
IF (($X*2) < 10) OR ($Y + 100) /3 >120
IF INSTR(%PATH%,"NETLOGON") AND @DOS = "3.51"
IF (SUBSTR(@WKSTA,11,1)="1" AND @USERID = "PETERV") OR @DOMAIN = "VleerBeer"
IF @USERID = "RUUDV" OR @USERID = "WIMW"
IF (INGROUP("Domain Users") OR INGROUP("Users"))
Action
Creates a new directory.
Syntax
MD "directory"
Remarks
Check the value of @ERROR to see if MD was successful (@ERROR = 0).
Action
No function; supported only for compatibility with KiXtart 2.3x.
Syntax
PASSWORD "password"
Action
Plays ‘music’ on the computer's speaker, by using the SPK file format described below, or on a sound card by playing a WAV file.
Syntax
PLAY [FILE "path\i filename.spk"] | "string" | "path\i filename.wav"
There are four possible syntax forms:
· PLAY FILE "Jbond.spk"
· PLAY "0g256t 0g8d247f 4d165f 247f 8d262f 4d165f 262f 8d277f 4d165f"
· PLAY FILE "Ding.wav"
· PLAY "Chimes.wav"
The string or file consists of a sequence of commands indicating the frequency and duration of the tones to play. The following commands are available:
· F or f - frequency
This command causes a tone to be produced at the current frequency. The initial current frequency is 1000Hz. To change the value, indicate the desired frequency immediately followed by the f character. For example, to produce a tone at 1500Hz, specify 1500F.
· G or g - gap
This command sets the number of timer ticks (1 second = 18 ticks) of silence between individual tones. The number of timer ticks between tones is specified as a number immediately followed by G. The initial value is 0.
· D or d - duration
This command sets the length (in timer ticks) of each tone. For example, to make each tone last about a third of a second, use the command 6d.
· T or t - tempo
This command scales the duration of each tone. This allows you to change the duration of a series of tones globally, without having to change each of the individual duration commands.
A tempo value of 256 indicates normal tempo. A value of 4df lasts:
· 2 timer ticks, when the tempo is set to 128
· 4 timer ticks, when the tempo is set to 256
· 8 timer ticks, when the tempo is set to 512
Remarks
KiXtart automatically selects the appropriate action based on the file name extension you provide.
Example
PLAY "0g256t 0g8d247f 4d165f 247f 8d262f 4d165f 262f 8d277f 4d165f
277f 8d262f 4d165f 262f 8d247f 4d165f 247f 8d262f 4d165f
262f 8d277f 4d165f 277f 8d262f"
This plays the part of the James Bond theme.
Action
Exits KiXtart.
Syntax
QUIT [error level / exit code]
Remarks
If QUIT is followed by a numeric expression, then the value of that expression is used as the exit code of KiXtart, and you can check it using a batch file.
Action
Removes the directory specified.
Syntax
RD "directory"
Remarks
Check the value of @ERROR to see if RD was successful.
Action
Causes script execution to continue at the statement following the last CALL or GOSUB statement.
Syntax
RETURN
Remarks
If RETURN is specified in the main script, KiXtart terminates.
Action
Runs a command.
Syntax
RUN "command"
Remarks
Command can be any 16-bit or 32-bit application. To run command interpreter commands, specify the correct command interpreter as part of the command.
RUN does not wait for the program to complete. Script execution continues immediately. This behavior is different from the MS-DOS - based version of KiXtart, where the RUN command also terminates the script. If you want to emulate the MS-DOS - based version, you must add an EXIT command after the RUN command.
Examples
RUN @LDRIVE + ".EXE"
RUN "%COMSPEC% /e:1024 /c DIR C:"
Action
A SELECT statement is an efficient way to write a series of IF ELSE statements.
Syntax
SELECT
CASE expression
statement1
....
CASE expression
statement2
....
ENDSELECT
Remarks
A SELECT statement consists of one or more conditions (CASE) each of which is followed by one or more statements that are executed only if the condition evaluates to TRUE. The SELECT statement is processed from top to bottom. If an expression evaluates to TRUE, the statements immediately following it are executed, up to the next CASE statement.
Only one CASE statement is executed, regardless of how many statements evaluate to TRUE.
If expression does not contain any relational operators, the condition is considered to be true if it is numeric and if it evaluates to a value other than zero, or if it is alphanumeric and it evaluates to a string containing at least one character.
SELECT statements can be nested as many times as memory allows.
Examples
SELECT
CASE InGroup("Domain Admins") AND @DAY = 1
? "Whatever…"
CASE InGroup("Office Users")
? "Etc…"
? "Etc…"
CASE 1 ; this is a nice way to provide a default CASE; if all other
; CASEs fail, this one will always be run
? "Hmm, you're not in one of our groups?"
ENDSELECT
Action
Sets environment variables in the environment of the current user (HKEY_CURRENT_USER).
Syntax
SET "variable=string"
Remarks
After any change to the environment, KiXtart informs running programs that the change was made, prompting them to regenerate their environments. Programs that support this feature (such as Program Manager, Task Manager, and Windows Explorer) update their environments when they receive the WM_SETTINGCHANGE message.
The environment of the current process (KiXtart 95) is not affected.
This command does not work on Windows 9x. As an alternative, use the SHELL command to run Winset.exe. (Winset.exe is included on the Windows 9x CD.)
Action
Sets environment variables in the local environment that you see when you start a program from within a KiXtart script.
Syntax
SETL "variable=string"
Remarks
This command does not affect the current environment. If you start KiXtart from
a batch file, any commands in the batch file that are run after KiXtart exits do not see changes made by the SET or SETL commands. If you want to run batch files or programs that depend on settings set by KiXtart, start them from KiXtart using SHELL or RUN.
SETL sets the value of @ERROR.
Action
Sets environment variables in the environment of the local computer (HKEY_LOCAL_MACHINEManager).
Syntax
SETM "variable=string"
Remarks
After any change to the environment, KiXtart informs running programs that the change was made, prompting them to regenerate their environments. Programs that support this feature (such as Program Manager, Task Manager, and Windows Explorer) update their environments when they receive the WM_SETTINGCHANGE message.
The environment of the current process (KiXtart 95) is not affected.
This command does not work on Windows 9x. As an alternative, use the SHELL command to run Winset.exe. (Winset.exe is included on the Windows 9x CD.)
Action
Synchronizes the system clock of the local computer with the time on a specified source.
Syntax
SETTIME "source"
Remarks
Source can be one of the following:
|
A server name expressed in UNC format |
KiXtart connects to the server specified to retrieve the time. |
|
A domain name |
KiXtart browses the domain for a server running the Time Source service. |
|
"*" |
KiXtart browses the local domain for any server running the Time Source service. |
On Windows NT, SETTIME requires the current user to have the ‘Change the system time’ privilege.
For more information on running the Windows NT Time Source Service, see Knowledge Base article Q131715 (also available on TechNet).
Examples
SETTIME "*"
SETTIME "\MYTIME"
SETTIME "TIMEDOMAIN"
Action
Loads and runs a program.
Syntax
SHELL "command"
Remarks
Command can be any 16-bit or 32-bit application. To run command interpreter commands, specify the correct command interpreter as part of the command.
Script execution is stopped until the program exits.
If the program you want to run needs to set environment variables (as is the case with Smsls.bat, for example), you may need to specify additional environment space by using the /E parameter.
SHELL sets the value of @ERROR to the exit code of the program that is run.
Examples
SHELL @LDRIVE + ".EXE"
SHELL "%COMSPEC% /e:1024 /c DIR C:"
SHELL "SETW USERNAME=@USERID"
SHELL "CMD.EXE /C COPY " + @LDRIVE + ".TXT C:"
SHELL "%COMSPEC% /C COPY Z:.TXT C:"
SHELL "C:/E:1024 /C " + @LDRIVE + ".BAT"
Action
Halts script execution for the number of seconds specified.
Syntax
SLEEP <seconds>
Action
Changes the character mode to small (normal) characters.
Syntax
SMALL
Remarks
After using SMALL, subsequent screen output is normal. For more information, see BIG earlier in this section.
Action
Lists the current connections. Can also be used to connect a device, such as a drive or a printer, to a network resource; or to disconnect a device from a network resource.
Syntax
USE LIST
USE <* | "device" | "resource"> /DELETE [/PERSISTENT]
USE ["device"] <"resource"> [/USER:user] [/PASSWORD:password] [/PERSISTENT]
Remarks
Use USE “*” /DELETE to delete all current connections except those to a NETLOGON share and those to the drive or share from which KiXtart was started.
If a resource name contains non-alphanumeric characters (such as - or +), enclose the name in quotation marks.
On Windows NT only, the /USER and /PASSWORD parameters enable overriding the security context of the current user.
Check the value of @ERROR to see if USE was successful (a value of 0 indicates success).
Examples
USE E: "\SERVER" /PERSISTENT
USE * /DELETE
USE E: "\SERVER" /user:Yogi /password:Bear
USE E: "\SERVER"
USE LPT1: "\SERVER" /user:testlan
USE L: /DEL
USE LIST
USE H: @HOMESHR ; connect to user's home share
IF @ERROR = 0
H: ;
CD @HOMEDIR ; change directory to user's home directory
ENDIF
Action
Runs a set of statements as long as an expression is true.
Syntax
WHILE "expression" ... LOOP
Remarks
WHILE loops can be nested as many times as memory allows.
KiXtart Function Reference
Action
Adds the specified subkey to the registry.
Syntax
ADDKEY ("subkey")
Parameter
Subkey
A string that specifies the name of the subkey you want to add to the registry.
Returns
|
0 |
Subkey added |
|
Error code |
Function failed |
Example
$ReturnCode = AddKey("HKEY_CURRENT_USER")
If $ReturnCode = 0
? "Key added...."
Endif
Action
Adds a connection to the specified printer for the current user.
Syntax
ADDPRINTERCONNECTION ("printer name")
Parameters
Printer name
The name of the printer to which to connect.
Remarks
This function is available only on Windows NT, and can be used only to connect to printers on a server running under Windows NT.
When Windows NT connects to the printer, it may copy printer driver files to the local computer. If the user does not have permission to copy files to the appropriate location, ADDPRINTERCONNECTION fails, and @ERROR returns ERROR_ACCESS_DENIED.
Returns
|
0 |
Printer connection established |
|
Error code |
Function failed |
Example
If ADDPRINTERCONNECTION ("\vleerbeerlaserjet 4") = 0
? "Added printer connection...."
Endif
Action
Instructs Program Manager to create a new program group.
Syntax
ADDPROGRAMGROUP ("group name", common group flag)
Parameters
Group name
Identifies the group window to be added.
Common group flag
Optional numeric parameter. This parameter is available only on Windows NT. Common group flag can have the following values:
|
0 |
Creates a personal group. |
|
1 |
Creates a common group. The current user must have administrative privileges, or the function fails. |
Returns
|
0 |
Program group added |
|
Error code |
Function failed |
Example
If AddProgramGroup("NewGroup", 0) = 0
? "NewGroup has created...."
Endif
Action
Instructs Program Manager to add an icon to the active program group.
Syntax
ADDPROGRAMITEM ("command line", "name", "icon path", icon index, "default directory", minimize, replace, run in own space)
Parameters
Command line
Specifies the command line required to run the application. This parameter is a string containing the name of the executable file for the application. It can also include the path of the application and any required parameters.
Name
Specifies the title that is displayed below the icon in the group window.
Icon path
Identifies the file name for the icon to display in the group window. This string identifies a Windows-based executable file or an icon file. If no icon path is specified, Program Manager uses the first icon in the file specified by command line if that file is an executable file.
If command line specifies a file that has been associated with a program, Program Manager uses the first icon provided in the executable file of that program. Association information is obtained from the registry. If command line specifies neither an executable file nor an associated program, Program Manager uses a default icon.
Icon index
This parameter is an integer that specifies the index of the icon in the file identified by the icon path parameter. Program Manager includes five default icons that can be used for programs not written for Windows.
Default directory
Specifies the name of the default (or working) directory. This parameter is a string.
Minimize
Optional numeric parameter. Specifies whether an application window is minimized when first displayed. Possible values for this parameter are:
|
0 |
Default system setting |
|
1 |
Minimize |
Replace
Optional numeric parameter. Specifies whether ADDPROGRAMITEM replaces an existing program item with the same name. Possible values for this parameter are:
|
0 |
Adds a new program item without replacing the existing one. This is the default. |
|
1 |
Replaces any existing program item. |
Run in own space
Optional numeric parameter. Specifies whether the program runs in its own address space. This parameter applies only to 16-bit Windows applications running on Windows NT. This parameter can have the following values:
|
0 |
Does not run in separate address space. This is the default. |
|
1 |
Runs in separate address space. |
Remarks
There is a limit of 50 items that can be added to each program group.
Returns
|
0 |
Program item added |
|
Error code |
Function failed |
Example
If AddProgramItem("c:.exe","RegEdit","",0,"c:",0,0)
= 0
? "Added program item 'RegEdit' to current group..."
Endif
Action
Returns the ASCII code of the character specified.
Syntax
ASC (character)
Parameter
Character
Character you want to know the ASCII code of.
Returns
Numeric value representing the ASCII code of the character.
Example
$ASCII = Asc( "H" )
Action
Places the cursor in the position indicated.
Syntax
AT (row, column)
Parameters
Row
Specifies the row at which to position the cursor.
Column
Specifies the column at which to position the cursor.
Remarks
The cursor position is expressed in screen coordinates. A value of 0,0 represents the top left corner of the screen.
The AT command is ignored if all output has been redirected to a file using the REDIRECTOUTPUT function.
Returns
Nothing.
Action
Backs up a Windows NT eventlog.
Syntax
BACKUPEVENTLOG (“eventlog”, “backupfile”)
Parameter
Eventlog
String indicating the eventlog to clear. By default, Windows NT supports three eventlogs: “Application”, “Security” and “System”. Optionally, the string can include the name of a remote system on which to clear the log.
Backupfile
String indicating the name of the backupfile. Note: the file must not exist.
Returns
|
0 |
Eventlog backed up. |
|
>0 |
Errorcode. |
Examples
BackupEventlog( “Application” , “C:.evt” )
ClearEventlog( “\PDC” , “C:.evt”)
ClearEventlog( “System” , “C:.evt”)
Action
Draws a box.
Syntax
BOX (top_left_row, top_left_column, bottom_right_row, bottom_right_column, "line style")
Parameters
Top_left_row, top_left_column, bottom_right_row, bottom_right_column
The four corners of the box to be drawn, expressed in screen coordinates. A value of 0,0 represents the top left corner of the screen.
Line style
Possible values for line style are:
|
single |
Single line outline, space as filler |
|
double |
Double line, space as filler |
|
full |
Full line, space as filler |
|
grid |
Single line, cross as filler |
You can also create a custom box by using a string value for line style. The string can contain as many as 9 characters, which are defined as follows.
|
This character in the string |
Represents this portion of the box |
|
1st |
Top-left corner |
|
2nd |
Top horizontal |
|
3rd |
Top -right corner |
|
4th |
Right vertical |
|
5th |
Bottom -right corner |
|
6th |
Bottom horizontal |
|
7th |
Bottom -left corner |
|
8th |
Left vertical |
|
9th |
Filler |
Remarks
The BOX command is ignored if all output is redirected to a file using the REDIRECTOUTPUT function.
Returns
Nothing.
Example
BOX (10, 10, 12, 15, "+-+|+-+| ") ;
produces the following box:
+---+
| |
+---+
Action
Insert special characters, such as carriage returns, in a string.
Syntax
CHR (character code)
Parameter
Character code
A numeric expression representing the character code to insert.
Returns
The string representation of the character code.
Example
$Message = "Hello " + @USERID + chr(13) + chr(10) + "Welcome to our network."
Action
Clears a Windows NT eventlog.
Syntax
CLEAREVENTLOG (“eventlog”)
Parameter
Eventlog
String indicating the eventlog to clear. By default, Windows NT supports three eventlogs: “Application”, “Security” and “System”. Optionally, the string can include the name of a remote system on which to clear the log.
Returns
|
0 |
Eventlog cleared. |
|
>0 |
Errorcode. |
Examples
ClearEventlog( “Application” )
ClearEventlog( “\PDC” )
ClearEventlog( “System” )
Action
Closes a file previously opened by the OPEN function.
Syntax
CLOSE (file number)
Parameter
File number
A numeric expression indicating the file number of the file to close. Possible values range from 1 to 10.
Returns
|
-2 |
Invalid file number specified |
|
0 |
File closed |
Example
IF Close(3)
Beep
? "Error closing file!"
ENDIF
Action
Compares the date and time of two files.
Syntax
COMPAREFILETIMES ("file1", "file2")
Parameter
File1
Identifies the first file you want to compare.
File2
Identifies the second file you want to compare.
Returns
|
-3 |
File2 could not be opened (see @ERROR for more information). |
|
-2 |
File1 could not be opened (see @ERROR for more information). |
|
-1 |
File1 is older than file2. |
|
0 |
File1 and file2 have the same date and time. |
|
1 |
File1 is more recent than file2. |
Example
$Result = CompareFileTimes(@LDRIVE + ".INI", "C:.INI")
IF $Result = 1 OR $Result = -3
COPY @LDRIVE + ".INI" "C:.INI"
ENDIF
Action
Returns the hexadecimal representation of a decimal value.
Syntax
DECTOHEX (Decimal value)
Parameter
Decimal value
The value you want to have the hexadecimal representation of.
Returns
A string representing the hexadecimal value of the input value.
Example
$Result = DexToHex(123)
Action
Deletes the specified subkey from the registry.
Syntax
DELKEY ("subkey")
Parameter
Subkey
A string that specifies the name of the subkey you want to delete.
Remarks
This call fails if any subkeys exist within the specified subkey. Use DELTREE if you want to delete a subkey that contains subkeys.
Returns
|
0 |
Subkey deleted |
|
Error code |
Function failed |
Example
$ReturnCode = DelKey("HKEY_CURRENT_USER")
If $ReturnCode = 0
? "Key deleted...."
Endif
Action
Deletes a connection to a printer that was established by using ADDPRINTERCONNECTION.
Syntax
DELPRINTERCONNECTION ("printer name")
Parameters
Printer name
A string that specifies the name of the printer connection to delete.
Remarks
This function is only available on Windows NT.
The DELPRINTERCONNECTION function does not delete any printer driver files that were copied from the server on which the printer resides when the printer connection was established.
Returns
|
0 |
Printer connection deleted |
|
Error code |
Function failed |
Example
If DelPrinterConnection ("hplaser4") = 0
? "Deleted printer connection...."
Endif
Action
Instructs Program Manager to delete an existing program group.
Syntax
DELPROGRAMGROUP ("group name", common group flag)
Parameters
Group name
Identifies the group to be deleted.
Common group flag
Optional numeric parameter. This parameter is available only on Windows NT. Common group flag can have the following values:
|
0 |
Deletes a personal group. |
|
1 |
Deletes a common group. The current user must have administrative privileges, otherwise the function fails. |
Remarks
When this function runs, no confirmation is asked nor warning given.
Returns
|
0 |
Program group deleted |
|
Error code |
Function failed |
Example
If DelProgramGroup("NewGroup", 0) = 0
? "NewGroup deleted...."
Endif
Action
Instructs Program Manager to delete an item from the active program group.
Syntax
DELPROGRAMITEM ("item name")
Parameter
Item name
Specifies the item to be deleted from the active program group.
Returns
|
0 |
Program item deleted |
|
Error code |
Function failed |
Example
If DelProgramItem("Whatever") = 0
? "ProgramItem 'Whatever' deleted from the current group...."
Endif
Action
Deletes a subkey from the registry, including all the subkeys contained in the specified subkey.
Syntax
DELTREE ("subkey")
Parameter
Subkey
Specifies the subkey to be deleted from the registry.
Remarks
When this function runs, no confirmation is asked nor warning given.
Returns
|
0 |
Subkey deleted |
|
Error code |
Function failed |
Example
$ReturnCode = DelTree("HKEY_CURRENT_USER")
If $ReturnCode = 0
? "Key deleted...."
Endif
Action
Deletes a value entry from the registry.
Syntax
DELVALUE ("subkey", "entry")
Parameter
Subkey
A string that specifies the name of the subkey from which you want to delete an entry.
Entry
A string that specifies the name of the entry you want to delete.
Returns
|
0 |
Value entry deleted |
|
Error code |
Function failed |
Example
$ReturnCode =DelValue("HKEY_CURRENT_USER", "Test")
If $ReturnCode = 0
? "Value deleted...."
Endif
Action
Dir can be used to enumerate the files in a directory. Dir returns a string representing the name of a file, directory, or folder that matches a specified pattern. To retrieve subsequent entries in a directory, specify an empty string (“”) as the path.
Syntax
DIR ("path", index)
Parameter
Path
Optional string that specifies a file name - may include directory or folder, and drive. If path is empty (“”), Dir will return the next file of the previously opened enumeration handle. Wildcards (‘*’ and ‘?’) are supported.
Index
Optional number indicating which enumeration handle to use. The Dir function can enumerate two directories at the same time. To open the second enumeration handle, specify 1 for the index.
Returns
Returns a string representing the name of a file, directory, or folder that matches a specified pattern. An empty string ("") is returned if path is not found or to indicate that the end of the current enumration was reached. Dir also sets the value of @ERROR :
|
0 |
Dir successful. |
|
Error code |
Function failed. |
Example
$FileName = Dir("C:")
While $FileName <> “” and @ERROR = 0
? $FileName
Dir() ; retrieve next file
Loop
Action
Enumerates the global groups of which the current user is a member.
Syntax
ENUMGROUP (Index)
Parameter
Index
A numeric value representing the group whose name you want to discover (where 0 is the first subkey).
Returns
|
String |
Global group name |
|
Error code |
Function failed |
Example
$Index = 0
DO
$Group = ENUMGROUP($Index)
UNTIL Len($Group) = 0
Action
Lists the names of the subkeys contained in a registry key or subkey.
Syntax
ENUMKEY ("subkey", index)
Parameters
Subkey
Specifies the key or subkey for which you want to enumerate the subkeys.
Index
A numeric value representing the position of the subkey whose name you want to discover. Zero (0) represents the first subkey in the key.
Returns
|
0 |
Function returns a string representing the subkey in the specified key |
|
Error code |
Function failed |
|
259 |
Subkey does not exist |
Example
$Index = 0
:Loop1
$KeyName = ENUMKEY("HKEY_CURRENT_USER ", $Index)
If @ERROR = 0
? "Name found: $KeyName"
$Index = $Index + 1
goto Loop1
Endif
Action
Enumerates the local groups of which the current user is a member.
Syntax
ENUMLOCALGROUP (index, "source")
Parameter
Index
A numeric value representing the group whose name you want to discover (where 0 is the first subkey).
Source
Optional string value representing the server or domain whose local groups you want to query.
Returns
|
String |
Local group name |
|
Error code |
Function failed |
Example
$Index = 0
DO
$Group = ENUMLOCALGROUP($Index)
UNTIL Len($Group) = 0
- Or -
$Index = 0
DO
$Group = ENUMLOCALGROUP($Index, "\MyServer")
UNTIL Len($Group) = 0
Action
Lists the names of the registry entries contained in a specific key or subkey.
Syntax
ENUMVALUE ("subkey", index)
Parameters
Subkey
Specifies the key or subkey for which you want to enumerate the value entries.
Index
A numeric value representing the position of the entry whose name you want to discover. Zero (0) represents the first entry in the subkey.
Returns
|
0 |
Function returns a string representing the entry in the specified key or subkey |
|
Error code |
Function failed |
|
259 |
Entry does not exist |
Example
$Index = 0
:Loop1
$ValueName = ENUMVALUE("HKEY_CURRENT_USER", $Index)
If @ERROR = 0
? "Name found: $ValueName"
$Index = $Index + 1
goto Loop1
Endif
Action
Executes a piece of KiXtart script code.
Syntax
EXECUTE (script code)
Parameter
Script code
A string expression representing the code to execute.
Returns
The exitcode of the executed script.
Examples
Execute( ‘? “This is a demo of the Execute() function”’ )
Execute( ‘$$X = 10’ ) ; note the extra ‘$’
Execute( ‘$$X = ’ + @USERID )
Action
Checks for the existence of one or more files.
Syntax
EXIST ("file name")
Parameters
File name
Identifies the file(s) you want to locate.
Remarks
Supports wildcards.
Returns
|
0 |
File not found |
|
1 |
File found |
Examples
IF EXIST (@LDRIVE + “.txt")
DISPLAY @LDRIVE + “.txt"
ENDIF
IF EXIST (@LDRIVE + “ƒÄ£C
; Etc, etc.
ENDIF
Action
Checks for the existence of a registry subkey.
Syntax
EXISTKEY ("subkey")
Parameter
Subkey
Identifies the subkey you want to locate.
Remarks
The values returned by EXISTKEY have the opposite meaning of the values returned by EXIST.
Returns
|
0 |
Subkey found |
|
Error code |
Subkey not found |
Example
$ReturnCode = ExistKey("HKEY_CURRENT_USER")
If $ReturnCode = 0
? "Key exists...."
Endif
Action
Expands any environment variables inside a string to the corresponding value.
Syntax
EXPANDENVIRONMENTVARS ("string")
Parameter
String
The string you want to expand.
Returns
The expanded string.
Example
$Value = ReadValue("HKEY_LOCAL_MACHINE", “SystemDirectory” )
? ExpandEnvironmentVars( $Value )
Action
Returns the number of kilobytes (KB) available to the current user on a specific drive.
Syntax
GETDISKSPACE ("drive")
Parameter
Drive
String that specifies a directory on the disk of interest. On Windows NT and on Windows 95 OSR2 and later versions, this string can be a UNC name. If this parameter is a UNC name, you must follow it with an additional backslash. For example, you would specify \MyServeras \MyServer.
If Drive is an empty string, GetDiskSpace obtains information about the disk that contains the current directory.
On Windows NT and on Windows 95 OSR2 and later versions, Drive does not have to specify the root directory on a disk. On these platforms, the function accepts any directory on a disk.
Returns
A number representing the number of kilobytes (KB) available to the current user on the drive specified.
Remarks
On Windows 95 OSR1 and earlier versions, the function can only return correct values for volumes that are smaller than 2 gigabytes in size. On Windows NT and Windows 95 OSR2 and later versions, the function always returns correct values, regardless of the size of the volume.
Examples
$Result = GetDiskSpace( “C:\u8221" )
$Result = GetDiskSpace( “X:” )
Action
Returns the attributes of a file.
Syntax
GETFILEATTR ("file name")
Parameter
File name
Identifies the file for which you want to retrieve the attributes.
Returns
Zero to indicate the function failed. If the function failed, check @ERROR for details on the error. Otherwise, the return value represents the attributes of the file. The attributes can be one or more of the following values:
|
1 |
Read only |
The file or directory is read-only. Applications can read the file but cannot write to it or delete it. In the case of a directory, applications cannot delete it. |
|
2 |
Hidden |
The file or directory is hidden. It is not included in an ordinary directory listing. |
|
4 |
System |
The file or directory is part of, or is used exclusively by, the operating system. |
|
16 |
Directory |
The filename identifies a directory. |
|
32 |
Archive |
The file or directory is an archive file or directory. Applications use this attribute to mark files for backup or removal. |
|
64 |
Encrypted |
The file or directory is encrypted. For a file, this means that all data streams are encrypted. For a directory, this means that encryption is the default for newly created files and subdirectories. |
|
128 |
Normal |
The file or directory has no other attributes set. This attribute is valid only if used alone. |
|
256 |
Temporary |
The file is being used for temporary storage. File systems attempt to keep all of the data in memory for quicker access rather than flushing the data back to mass storage. A temporary file should be deleted by the application as soon as it is no longer needed. |
|
512 |
Sparse file |
The file is a sparse file. |
|
1024 |
Reparse point |
The file has an associated reparse point. |
|
2048 |
Compressed |
The file or directory is compressed. For a file, this means that all of the data in the file is compressed. For a directory, this means that compression is the default for newly created files and subdirectories. |
|
4096 |
Offline |
The data of the file is not immediately available. Indicates that the file data has been physically moved to offline storage. |
Example
$Result = GetFileAttr(@LDRIVE + ".exe")
IF GetFileAttr( “C:” ) & 16
? “C:is a directory !”
ENDIF
Action
Returns the size of a file in bytes.
Syntax
GETFILESIZE ("file name")
Parameter
File name
Identifies the file for which you want to retrieve the size.
Returns
Size of the file in bytes.
Remarks
The maximum size of files that GetFileSize can correctly report the size of is 2,147,483,647 bytes.
Example
$Result = GetFileSize(@LDRIVE + ".exe")
Action
Returns the date and time information of a file.
Syntax
GETFILETIME ("file name")
Parameter
File name
Identifies the file for which you want to retrieve the date and time information.
Returns
A string representing the date and time of the file in the format “YYYY/MM/DD HH:MM:SS”.
Remarks
The information returned represents the time the file was last written to.
Example
$Result = GetFileTime(@LDRIVE + ".exe")
Action
Returns a version information string of a file.
Syntax
GETFILEVERSION ("file name",”versionfield”)
Parameter
File name
Identifies the file for which you want to get the version string.
Versionfield
Optional parameter identifying the specific version information field that should be retrieved. By default, the FileVersion field is returned. Possible values for this field are :
Comments This field contains any additional information that should be displayed for diagnostic purposes.
CompanyName This field identifies the company that produced the file. For example, "Microsoft Corporation" or "Standard Microsystems Corporation, Inc."
FileDescription This field escribes the file in such a way that it can be presented to users. This string may be presented in a list box when the user is choosing files to install. For example, "Keyboard driver for AT-style keyboards" or "Microsoft Word for Windows".
FileVersion This field member identifies the version of this file. For example, "3.00A" or "5.00.RC2".
InternalName This field identifies the file's internal name, if one exists. For example, this string could contain the module name for a dynamic-link library (DLL), a virtual device name for a Windows virtual device, or a device name for an MS-DOS device driver.
Language Full English name of the language of the file specified in the format defined by ISO Standard 639. (example : “0413Dutch (Standard)”).
LegalCopyright This field describes all copyright notices, trademarks, and registered trademarks that apply to the file. This should include the full text of all notices, legal symbols, copyright dates, trademark numbers, and so on. In English, this string should be in the format "Copyright Microsoft Corp. 1990-1994".
LegalTrademarks This field describes all trademarks and registered trademarks that apply to the file. This should include the full text of all notices, legal symbols, trademark numbers, and so on. In English, this string should be in the format "Windows is a trademark of Microsoft Corporation".
OriginalFilename This field identifies the original name of the file, not including a path. This enables an application to determine whether a file has been renamed by a user. This name may not be MS-DOS 8.3-format if the file is specific to a non-FAT file system.
PrivateBuild This field describes by whom, where, and why this private version of the file was built. For example, "Built by OSCAR on ".
ProductName This field identifies the name of the product with which this file is distributed. For example, this string could be "Microsoft Windows".
ProductVersion This field identifies the version of the product with which this file is distributed. For example, "3.00A" or "5.00.RC2".
SpecialBuild This field describes how this version of the file differs from the normal version. For example, "Private build for Olivetti solving mouse problems on M250 and M250E computers".
Returns
A string representing the file version field.
Remarks
The information returned by this function is the same as the version information displayed in Windows Explorer.
This function applies only to 32-bit Windows - based executable files.
Example
$Result = GetFileVersion(@LDRIVE + ".exe")
$Result = GetFileVersion(@LDRIVE + ".exe", “ProductVersion” )
Action
Checks whether the current user is a member of a group.
Syntax
INGROUP ("group name")
Parameter
Group name
Identifies the group in which to check the user's membership.
Remarks
INGROUP can be used to check for groupmembership of groups that exist on the domain or server where the user is logged on, or to check for groupmembership of groups on a specific domain or server.
When checking for a local group, INGROUP identifies that the user is indirectly a member of the group by virtue of being a member of a global group which, in turn, is a member of the local group.
If you want to check for membership in a group on a specific domain or server, use the following format:
"OtherDomain"
- Or -
"\SomeServer"
For Windows 9x clients, INGROUP works on local groups only if the KiXtart RPC service is running.
Returns
|
0 |
The user is not a member of a group with this name. |
|
1 |
The user is a member of a global group with this name. |
|
2 |
The user is a member of a local group with this name. |
Example
IF INGROUP("Domain Users")
DISPLAY "z:.txt"
ENDIF
IF INGROUP("Developers") = 2
? "Member of local group Developers"
ENDIF
IF INGROUP("\" + @WKSTA + "") = 2
? "Member of local group Developers on local system"
ENDIF
Action
Scans a string for the presence of a second string.
Syntax
INSTR ("string1", "string2")
Parameters
String1
The string to search in.
String2
The string to search for.
Returns
|
? |
Offset of the first character of string2 found in string1 |
|
0 |
String2 not present in string1 |
Example
$x = INSTR(@DOMAIN, "TEST") ; check if domain contains the string "TEST"
Action
Returns a string in lowercase.
Syntax
LCASE ("string")
Parameters
String
The string you want to change to lowercase.
Returns
The input string in lowercase.
Example
$x = LCASE(@USERID)
Action
Returns the length of a string.
Syntax
LEN ("string")
Parameter
String
The string whose length you want to discover.
Returns
The number of characters contained in the specified string.
Example
$x = LEN(@USERID)
Action
Creates a subkey under HKEY_USERS or HKEY_LOCAL_MACHINE and stores registration information from a specified file into that subkey. This registration information is in the form of a hive. A hive is a discrete body of keys, subkeys, and values that is rooted at the top of the registry hierarchy. A hive is backed by a single file and .LOG file.
Syntax
LOADHIVE ("key", "file name")
Parameters
Key
The key you want to load the information in. This key must reside under HKEY_LOCAL_MACHINE or HKEY_USERS.
File name
Identifies the file you want to load the information from. This file specified needs to be a legal registry hive (created by SAVEKEY, or from REGEDT32.EXE).
Remarks
On Windows NT, using LOADHIVE requires Backup and Restore privileges.
Returns
|
0 |
Hive loaded |
|
Error code |
Function failed |
Example
$ReturnCode = LoadHive("HKEY_USERS", "c:.reg")
If $ReturnCode = 0
? "Hive loaded...."
Endif
Action
Loads a registry key (including its subkeys and values) from a file.
Syntax
LOADKEY ("subkey", "file name")
Parameters
Subkey
The subkey in which you want to load the information. This subkey must exist for the call to be successful.
File name
Identifies the file from which to import the information. This file must be a valid registry hive file created by using the SAVEKEY function, or by using a registry editor.
Remarks
On Windows NT, using LOADKEY requires Backup and Restore privileges.
Caution
LOADKEY imports information into the registry and overwrites any existing subkey. This replaces all the subkeys and values that may already exist in the subkey you are loading. Any existing values and subkeys are lost.
Returns
|
0 |
Subkey loaded |
|
Error code |
Function failed |
Example
$ReturnCode = LoadKey("HKEY_CURRENT_USER", "c:.reg")
If $ReturnCode = 0
? "Key loaded...."
Endif
Action
Logs an event in the Windows NT event log.
Syntax
LOGEVENT (type, ID, message, target, source)
Parameter
Type
Number representing the type of the event. Possible values :
|
0 |
SUCCESS |
|
1 |
ERROR |
|
2 |
WARNING |
|
4 |
INFORMATION |
|
8 |
AUDIT_SUCCESS |
|
16 |
AUDIT_FAILURE |
ID
Number representing the event that occurred.
Message
Message text of the event.
Target
Optional parameter representing the UNC name of the system where the event should be logged. By default, all events are logged on the local system.
Source
Optional parameter representing the source of the event. If this parameter is not specified, Kixtart will assume the KIX32.EXE as the source of the event.
Returns
|
0 |
Event logged |
|
Error code |
Function failed |
Remarks
This function is only available on Windows NT clients.
Example
$RC = LogEvent( 0 , 1 , “Logon script completed successfully” , “”, “MyEvent” )
$RC = LogEvent( 0 , 1 , “Logon script completed successfully”)
$RC = LogEvent( 1 , 1 , “Logon script failed!” , @LSERVER )
Action
Logs the current user off and ends the Windows session.
Syntax
LOGOFF (force)
Parameter
Force
During a logoff operation, applications that are shut down are allowed a specific amount of time to respond to the logoff request. If the time expires, Windows displays a dialog box that allows the user to forcibly shut down the application, to retry the logoff, or to cancel the logoff request. If the Force value is true (ie : non-zero), Windows always forces applications to close and does not display the dialog box.
|
0 |
Windows does not force applications to close. |
|
1 |
Windows always forces applications to close and does not display the dialog box. |
Returns
|
0 |
User logged off |
|
Error code |
Function failed |
Example
$RC = LogOff(0)
Action
Strips leading spaces from an input string and returns the result.
Syntax
LTRIM ("string")
Parameter
String
The string from which to strip leading spaces.
Returns
The input string without leading spaces.
Example
$x = LTRIM(SUBSTR(@IPADDRESS0, 1, 3)); 192
Action
Displays a standard dialog box in Windows.
Syntax
MESSAGEBOX ("message", "title", style, time-out)
Parameters
Message
The message to display in the dialog box.
Title
The title of the dialog box.
Style
Optional numeric expression that is the sum of values specifying the number and type of buttons to display, the icon style to use, the identity of the default button, and the modality. The following table illustrates the values used and the meaning of each group of values.
Buttons to display
|
Value |
Meaning |
|
0 |
Display OK button only. |
|
1 |
Display OK and Cancel buttons. |
|
2 |
Display Abort, Retry, and Ignore buttons. |
|
3 |
Display Yes, No, and Cancel buttons. |
|
4 |
Display Yes and No buttons. |
|
5 |
Display Retry and Cancel buttons. |
Icon to display
|
Value |
Meaning |
|
16 |
Stop symbol |
|
32 |
Question mark |
|
48 |
Exclamation mark |
|
64 |
Information symbol |
Default button
|
Value |
Meaning |
|
0 |
First button is default. |
|
256 |
Second button is default. |
|
512 |
Third button is default. |
Modality
|
Value |
Meaning |
|
0 |
Application-modal. The user must respond to the message box before continuing work in the application. |
|
4096 |
System-modal. All applications are suspended until the user responds to the message box. |
When adding numbers to create a final value for the argument type, use only one number from each group. If style is omitted, a default value of 0 is assumed.
Time-out
Optional numeric expression representing the number of seconds after which to close the dialog box.
Note
The time-out feature only works if the MESSAGEBOX dialog box is the active window for the duration of the time-out. If the user switches away from KiXtart and activates another application, the MESSAGEBOX dialog box is not closed.
Remarks
MESSAGEBOX displays a maximum of 1024 characters in application-modal dialog boxes. Longer messages are truncated after the 1024th character. Message strings longer than 255 characters with no intervening spaces are truncated after the 255th character. For system-modal dialog boxes, the number of characters you can display depends on screen resolution and number of lines in the message.
MESSAGEBOX breaks lines automatically at the right edge of the dialog box. If you want to set line breaks yourself, place a linefeed (ANSI character 10) before the first character of the text that is to begin each new line.
Returns
The value returned by MESSAGEBOX indicates which button was selected, as shown in the following table.
|
Value |
Meaning |
|
-1 |
User did not respond to the dialog box within the specified time-out period. |
|
1 |
OK button selected. |
|
2 |
Cancel button selected. |
|
3 |
Abort button selected. |
|
4 |
Retry button selected. |
|
5 |
Ignore button selected. |
|
6 |
Yes button selected. |
|
7 |
No button selected. |
If the dialog box contains a Cancel button, pressing esc has the same effect as choosing Cancel.
Example
$Selection = MessageBox("Do you want to continue ?", "KiXtart", 36)
If $Selection = 6
? "Yes selected, continuing...."
Endif
OptionalArgument1
Optional string value representing an argument for the method. Note : all optional arguments must be specified as a string. The actual type of the argument is determined automatically based on the corresponding TypeCharacter in TypeList.
Returns
A string representing the return value of the function. If the call fails, @ERROR will be set to the relevant error code.
Action
Accesses a method of an OLE Automation object that returns a value.
Syntax
OLECALLFUNC (objecthandle, "methodname", “typelist”, “optionalargument1”, “optionalargument2” , …)
Parameters
ObjectHandle
The handle of the object you want to access. This handle must have been obtained by a call to OLECreateObject, OLEGetObject, OLEGetSubObject, OLEGetProperty or OLECallFunc.
Methodname
The name of the method you want to access.
TypeList
TypeList is a casesensitive series of characters that define the type of each optional argument. Based on the type specified, KiXtart will convert the argument(s) to the correct type before calling the OLE function. This parameter can have the following values:
|
b |
Boolean |
|
c |
Currency |
|
D |
Date |
|
i |
Short integer |
|
I |
Long integer |
|
o |
Object handle |
|
r |
4 byte real |
|
R |
8 byte real |
Optionalargument
Optional string value representing an argument for the method. Note : all optional arguments must be specified as a string. The actual type of the argument is determined automatically by the corresponding TypeCharacter in TypeList.
Returns
A string representing the return value of the function. If the call fails, @ERROR will be set to the relevant error code.
Action
Accesses a method of an OLE Automation object that does not return a value.
Syntax
OLECALLPROC (objecthandle, "methodname", “typelist”, “optionalargument1”, “optionalargument2” , …)
Parameters
ObjectHandle
The handle of the object you want to access. This handle must have been obtained by a call to OLECreateObject, OLEGetObject, OLEGetSubObject, OLEGetProperty or OLECallFunc.
Methodname
The name of the method you want to access.
TypeList
TypeList is a casesensitive series of characters that define the type of each optional argument. Based on the type specified, KiXtart will convert the argument(s) to the correct type before calling the OLE function. This parameter can have the following values:
|
b |
Boolean |
|
c |
Currency |
|
D |
Date |
|
i |
Short integer |
|
I |
Long integer |
|
o |
Object handle |
|
r |
4 byte real |
|
R |
8 byte real |
Optionalargument
Optional string value representing an argument for the method. Note : all optional arguments must be specified as a string. The actual type of the argument is determined automatically by the corresponding TypeCharacter in TypeList.
Returns
If the function succeeds, the return value is 0. If the function fails, the return value represents an error code.
Action
OLECreateObject launches (if necessary) the OLE Automation server and returns a handle through which the OLE Automation object can be manipulated.
Syntax
OLECREATEOBJECT (“serverclassname")
Parameters
ServerClassName
The handle of the object you want to create.
Returns
If the function succeeds it returns the handle to the object. If the function fails, it returns 0.
Action
Retrieves the enumerationhandle of a collection, or retrieves an entry from a collection. Certain OLE objects offer socalled collections: objects that allow a controller to work with a set of similar things as a single group instead of as independent entities. OLEENUMOBJECT enables you to retrieve a handle to a collection, and, using that handle, to enumerate the objects in the collection.
Syntax
OLEENUMOBJECT (objecthandle, enumerationhandle )
Parameters
ObjectHandle
The handle of the object you want to access. This handle must have been obtained by a call to OLECreateObject, OLEGetObject, OLEGetSubObject, OLEGetProperty or OLECallFunc.
Enumerationhandle
This is an optional value. If specified (and non-zero), OLEENUMOBJECT will retrieve the next entry in the collection indicated by EnumerationHandle. If omitted, OLEENUMOBJECT will attemp to retrieve an enumerationhandle for the collection indicated by ObjectHandle.
Returns
The enumerationhandle of a collection, or the next entry of the specified collection. If the call fails, @ERROR will be set to the relevant error code.
Example
; sample code to enumerate all entries in the SAM of an NT 4 system.
;
$dse = OLEGetObject(0,"WinNT://MYSYSTEM")
$eh = OLEEnumObject( $dse ) ; 1st, retrieve the enumeration handle
WHILE @ERROR = 0
$entry = OLEEnumObject( $dse , $eh )
IF @ERROR = 0
? "Object: " + OLEGetProperty( $entry , "Name") + " ( " + OLEGetProperty( $entry , "Class") + " )"
ENDIF
LOOP
? OLEReleaseObject( $dse )
Action
OLEGetObject gets an object either from a file stored on disk, or from a class name, and returns a handle to the object.
Syntax
OLEGETOBJECT (mode, “objectname" , “classname”)
Parameters
Mode
|
0 |
ObjectName specifies a file on disk |
|
1 |
ObjectName specifies a classname |
|
2 |
ObjectName specifies a file on disk, and ClassName specifies the class of the object |
ObjectName
The filename or the classname of the object you want to create.
ClassName
Optional parameter (only required if Mode = 2) indicating the class of the object to get.
Returns
If the function succeeds it returns the handle to the object. If the function fails, it returns 0.
Action
Returns the value of a specific property of an OLE Automation object.
Syntax
OLEGETPROPERTY (objecthandle , “propertyname”)
Parameters
ObjectHandle
The handle of the object you want to access. This handle must have been obtained by a call to OLECreateObject, OLEGetObject, OLEGetSubObject, OLEGetProperty or OLECallFunc.
PropertyName
The name of the property you want to retrieve the value of.
Returns
If the function succeeds, the return value is the value of the property. If the function fails, the return value will be empty, and @ERROR will be set to the relevant error code.
Action
Some methods return handles to sub-objects. OLEGetSubObject is a way to retrieve these handles.
Syntax
OLEGETSUBOBJECT (objecthandle, "methodname", “typelist”, “optionalargument1”, “optionalargument2” , …)
Parameters
ObjectHandle
The handle of the object you want to access. This handle must have been obtained by a call to OLECreateObject, OLEGetObject, OLEGetSubObject, OLEGetProperty or OLECallFunc.
Methodname
The name of the method you want to access.
TypeList
TypeList is a casesensitive series of characters that define the type of each optional argument. Based on the type specified, KiXtart will convert the argument(s) to the correct type before calling the OLE function. This parameter can have the following values:
|
b |
Boolean |
|
c |
Currency |
|
D |
Date |
|
i |
Short integer |
|
I |
Long integer |
|
o |
Object handle |
|
r |
4 byte real |
|
R |
8 byte real |
Optionalargument
Optional string value representing an argument for the method. Note : all optional arguments must be specified as a string. The actual type of the argument is determined automatically by the corresponding TypeCharacter in TypeList.
Returns
If the function succeeds, the return value is 0. If the function fails, the return value represents an error code.
Action
Sets the value of a specific property of an OLE Automation object.
Syntax
OLEPUTPROPERTY (objecthandle , “propertyname”, “value”)
Parameters
ObjectHandle
The handle of the object you want to access. This handle must have been obtained by a call to OLECreateObject, OLEGetObject, OLEGetSubObject, OLEGetProperty or OLECallFunc.
PropertyName
The name of the property you want to retrieve the value of.
Value
String representing the value that the property should be set to.
Returns
If the function succeeds, the return value is 0. If the function fails, the return value represents an error code.
Action
OLEReleaseObject frees up any resources obtained when the OLE object was created. If you do not explicitly release an object, all its resources will remain allocated until KiXtart exits.
Syntax
OLERELEASEOBJECT (objecthandle)
Parameters
ObjectHandle
The handle of the object you want to release. This handle must have been obtained by a call to OLECreateObject, OLEGetObject, OLEGetSubObject, OLEGetProperty or OLECallFunc.
Returns
If the function succeeds, the return value is 0. If the function fails, the return value represents an error code.
Action
Opens a text file.
Syntax
OPEN (file number, "file name", mode)
Parameters
File number
A numeric expression indicating the file number of the file to open. Possible values range from 1 to 10.
File name
A string expression indicating the path and name of the ASCII file to open.
Mode
Optional parameter that indicates what should happen if the file does not exist. This parameter can have the following values:
|
0 |
If the file does not exist, OPEN fails with return code 2 (default). |
|
1 |
If the file does not exist, OPEN will create a new file. |
|
2 |
Opens the file for read access (default). |
|
4 |
Opens the file for write access. |
Note
These values are cumulative. So if you want to open a file for write access, and create it if it does not yet exist, you should specify 5. Notice however that a file can not be opened for read and write access at the same time.
Remarks
OPEN opens the ASCII file specified by file name, for the internal buffer indicated by file number. KiXtart supports a maximum of ten open files, so file number must be within the range of 1 to 10.
The file-I/O functions in KiXtart (OPEN, READLINE, and CLOSE) process small configuration files. They are not intended for larger operations, such as scanning long files. For the sake of simplicity and speed, OPEN reads an entire ASCII file into memory, and subsequent READLINE commands read lines stored in memory.
Although this design is memory-intensive, it is also very fast and simple.
Returns
|
-3 |
File number already in use |
|
-2 |
Invalid file number specified |
|
-1 |
Invalid file name specified |
|
0 |
File opened successfully |
|
>0 |
System error |
Example
IF Open(3, @LDRIVE + ".INI") = 0
$x = ReadLine(3)
WHILE @ERROR = 0
? "Line read: [" + $x + "]"
$x = ReadLine(3)
LOOP
ENDIF
Action
Reads a line from a file.
Syntax
READLINE (file number)
Parameter
File number
A numeric expression indicating the file number of the file to open. Possible values range from 1 to 10.
Remarks
READLINE reads a string ending in a carriage return. If successful, the function returns the string without a carriage return. If it encounters an error, @ERROR returns an error code.
Returns
|
-4 |
File not open for reading |
|
-3 |
File number not open |
|
-2 |
Invalid file number specified |
|
-1 |
End of file |
|
0 |
Line read successfully |
Example
IF Open(3, @LDRIVE + ".INI") = 0
$x = ReadLine(3)
WHILE @ERROR = 0
? "Line read: [" + $x + "]"
$x = ReadLine(3)
LOOP
Close (3)
ELSE
BEEP
? "Config file not opened, error code: [" + @ERROR + "]"
ENDIF
Action
Retrieves a string from an initialization file.
Syntax
READPROFILESTRING ("file name", "section", "key")
Parameters
File name
A string that names the initialization file. If this parameter does not include a full path, Windows searches for the file in the Windows directory.
Section
A string that specifies the section containing the key name. If this parameter is empty, READPROFILESTRING returns all section names in the file.
Key
A string containing the key name whose associated string is to be retrieved. If this parameter is empty, all key names in the section specified by section are returned.
Remarks
This function is provided for compatibility with 16-bit Windows - based applications. Win32 - based applications store initialization information in the registry.
Returns
|
0 |
Function returns a string representing the value of the specified key |
|
Error code |
Function failed |
Example
$dev = ReadProfileString(“win.ini”, "Windows", "Device")
If @ERROR = 0
? "Windows device = " + $dev
Endif
Action
Returns the ASCII representation of a registry entry data type (for example, REG_SZ).
Syntax
READTYPE ("subkey", "entry")
Parameters
Subkey
Identifies the subkey containing the entry.
Entry
Identifies the entry whose data type you want to discover.
Returns
|
0 |
Function returns ASCII representation of data type for specified registry entry |
|
Error code |
Function failed |
The following data types can be returned:
· REG_NONE
· REG_SZ
· REG_EXPAND_SZ
· REG_BINARY
· REG_DWORD
· REG_DWORD_LITTLE_ENDIAN
· REG_DWORD_BIG_ENDIAN
· REG_LINK
· REG_MULTI_SZ
· REG_RESOURCE_LIST
· REG_FULL_RESOURCE_DESCRIPTOR
Example
$RowsType = ReadType("HKEY_CURRENT_USER", "WindowRows")
If @ERROR = 0
? "Type of WindowRows: $RowsType"
Endif
Action
Reads the value of a registry entry.
Syntax
READVALUE ("subkey", "entry")
Parameters
Subkey
Identifies the subkey containing the entry.
Entry
Identifies the entry whose value you want to discover. To read the default entry of a key, specify an empty string as the entry name (“”).
Returns
|
0 |
Function returns ASCII representation of the specified registry entry |
|
Error code |
Function failed |
REG_MULTI_SZ (multi-string) variables are returned with the pipe symbol ( | ) used as the separator between strings. If a string contains a pipe symbol character, it is represented by two pipe symbol characters ( || ).
REG_DWORD variables are returned in decimal format.
Example
$Rows = ReadValue("HKEY_CURRENT_USER", "WindowRows")
If @ERROR = 0
? "Number of window-rows: $Rows"
Endif
Action
Redirects all screen output to a file.
Syntax
REDIRECTOUTPUT ("file name", overwrite)
Parameters
File name
A string that names the file to which to redirect the output. If this parameter is an empty string (""), output is redirected to the screen.
Overwrite
Optional numeric value indicating whether to clear the output file before writing any data to it. This parameter can have the following values:
|
0 |
New output data appended to the existing contents of file. |
|
1 |
All data in file overwritten when the output is redirected to the file. |
Remarks
If all output is redirected to a file, the AT, BIG, BOX, and CLS commands are ignored.
Returns
|
0 |
Output redirected |
|
Error code |
Function failed |
Example
IF RedirectOutput("logon.log") = 0
? "Opened 'logon.log' at " + @TIME ?
ENDIF
Action
Returns a pseudo random number.
Syntax
RND (Range)
Parameter
Range
Optional parameter indicating the range for the return value (maximum and default value = 32767).
Returns
Pseudo random number.
Remarks
The RND function returns a pseudorandom integer ranging from 0 to the maximum specified. Use the SRND function to seed the pseudorandom-number generator before calling RND.
Example
$x = RND()
$x = RND(10)
Action
Strips trailing spaces from an input string and returns the result.
Syntax
RTRIM ("string")
Parameter
String
The string from which to strip trailing spaces.
Returns
The input string without trailing spaces.
Example
$x = RTRIM(SUBSTR(@IPADDRESS0, 1, 3)); 192
Action
Saves a registry key (including its subkeys and value entries) to a file.
Syntax
SAVEKEY ("subkey", "file name")
Parameters
Subkey
Identifies the subkey you want to save.
File name
Identifies the file in which to save the information.
Remarks
When this function runs, the destination file is overwritten without warning.
On Windows NT, running SAVEKEY requires Backup and Restore privileges.
Returns
|
0 |
Subkey saved |
|
Error code |
Function failed |
Example
$ReturnCode = SaveKey("HKEY_CURRENT_USER", "c:.reg")
If $ReturnCode = 0
? "Key saved...."
Endif
Action
Sends one or more keystrokes to the active window as if typed at the keyboard.
Syntax
SENDKEYS ("keys")
Parameters
Keys
String specifying the keystrokes to send.
Each key is represented by one or more characters. To specify a single keyboard character, use the character itself. For example, to represent the letter A, use "A" for string. To represent more than one character, append each additional character to the one preceding it. To represent the letters A, B, and C, use "ABC" for string. The plus sign (+), caret (^),tilde (~), and parentheses ( ) have special meanings to SendKeys. To specify one of these characters, enclose it within braces ({}). For example, to specify the plus sign, use {+}. To specify brace characters, use {{} and {}}.
To specify characters that aren't displayed when you press a key, such as ENTER or TAB, and keys that represent actions rather than characters, use the codes shown below:
|
BACKSPACE |
{BACKSPACE} |
|
BREAK |
{BREAK} |
|
CAPS LOCK |
{CAPSLOCK} |
|
DEL |
{DEL} |
|
DOWN ARROW |
{DOWN} |
|
END |
{END} |
|
ENTER |
{ENTER} |
|
ESC |
{ESC} |
|
HELP |
{HELP} |
|
HOME |
{HOME} |
|
INS |
{INS} |
|
LEFT ARROW |
{LEFT} |
|
NUM LOCK |
{NUMLOCK} |
|
PAGE DOWN |
{PGDN} |
|
PAGE UP |
{PGUP} |
|
PRINTSCREEN |
{PRTSC} |
|
RIGHT ARROW |
{RIGHT} |
|
TAB |
{TAB} |
|
UP ARROW |
{UP} |
|
F1 |
{F1} |
|
F2 |
{F2} |
|
F3 |
{F3} |
|
F4 |
{F4} |
|
F5 |
{F5} |
|
F6 |
{F6} |
|
F7 |
{F7} |
|
F8 |
{F8} |
|
F9 |
{F9} |
|
F10 |
{F10} |
|
F11 |
{F11} |
|
F12 |
{F12} |
|
F13 |
{F13} |
|
F14 |
{F14} |
|
F15 |
{F15} |
|
F16 |
{F16} |
To specify keys combined with any combination of the SHIFT, CTRL, and ALT keys, precede the key code with one or more of the following codes:
|
SHIFT |
+ |
|
CTRL |
^ |
|
ALT |
~ |
To specify that any combination of SHIFT, CTRL, and ALT should be held down while several other keys are pressed, enclose the code for those keys in parentheses. For example, to specify to hold down SHIFT while E and C are pressed, use "+(EC)". To specify to hold down SHIFT while E is pressed, followed by C without SHIFT, use "+EC".
To specify repeating keys, use the form {key number}. You must put a space between key and number. For example, {LEFT 42} means press the LEFT ARROW key 42 times; {h 10} means press H 10 times.
Remarks
SendKeys cannot be used to send keystrokes to an application that is not designed to run in Microsoft Windows. Sendkeys also can't send the PRINT SCREEN key {PRTSC} to any application.
Returns
|
0 |
Keystrokes sent |
|
Error code |
Function failed |
Example
Shell( “Notepad.exe” )
SetFocus( “Untitled - Notepad” )
$ReturnCode = SendKeys("Hello World”)
Sleep( 2 )
$ReturnCode = SendKeys("~{F4}Y”)
Action
Sends a message across the network to another user or workstation.
Syntax
SENDMESSAGE ("recipient", "message")
Parameters
Recipient
Identifies the user or workstation to which to send the message.
Message
The message to send.
Returns
|
0 |
Message sent |
|
Error code |
Function failed |
Example
$ReturnCode = SendMessage("ADMIN" , @USERID + " logged in at " + @TIME)
If $ReturnCode = 0
? "Message has been sent.."
Endif
Action
Enables enabling/disabling of ASCII output. In KiXtart, standard console output is in Unicode, and SetASCII enables you to change this to ASCII, so you can output extended characters, such as line characters.
Syntax
SETASCII("mode")
Parameters
Mode
String that specifies whether to turn ASCII output on or off. Specifying “ON” will turn ASCII output on, and specifying “OFF” will turn ASCII output off.
Returns
|
“ON” | “OFF” |
Previous output state. |
Example
$previousstate = SetASCII( “ON” )
? “═══════════” ; output ASCII line characters
SetASCII( $previousstate )
Action
Changes the display state of the command-prompt window in which KiXtart is running.
Syntax
SETCONSOLE("mode")
Parameters
Mode
String that specifies the new display state. The following table shows the display states that are supported by this function.
|
SHOW |
Show window |
|
HIDE |
Hide window |
|
FOREGROUND |
Move window to foreground |
|
ALWAYSONTOP |
Bring window to top |
|
MINIMIZE |
Minimize window |
|
MAXIMIZE |
Maximize window |
Remarks
If a window is hidden, it does not disappear from the system, but remains active.
Returns
|
0 |
Display state changed |
|
Error code |
Function failed |
Example
If SetConsole ("FOREGROUND") = 0
? "Console moved to foreground......"
Endif
Action
Sets the default printer to which applications send print jobs.
Syntax
SETDEFAULTPRINTER ("printer name")
Parameters
Printer name
String that specifies the name of the printer to set as the default printer.
Returns
|
0 |
Default printer set |
|
Error code |
Function failed |
Example
If SetDefaultPrinter ("hplaser4") = 0
? "Set default printer to HP LaserJet 4...."
Endif
Action
Sets the attributes of a file.
Syntax
SETFILEATTR ("file name", attributes)
Parameter
File name
Identifies the file of which you want to set the attributes.
Attributes
Attributes to set for the file. The attributes can be one or more of the following values:
|
1 |
Read only |
The file or directory is read-only. Applications can read the file but cannot write to it or delete it. In the case of a directory, applications cannot delete it. |
|
2 |
Hidden |
The file or directory is hidden. It is not included in an ordinary directory listing. |
|
4 |
System |
The file or directory is part of, or is used exclusively by, the operating system. |
|
32 |
Archive |
The file or directory is an archive file or directory. Applications use this attribute to mark files for backup or removal. |
|
128 |
Normal |
The file or directory has no other attributes set. This attribute is valid only if used alone. |
|
256 |
Temporary |
The file is being used for temporary storage. File systems attempt to keep all of the data in memory for quicker access rather than flushing the data back to mass storage. A temporary file should be deleted by the application as soon as it is no longer needed. |
|
4096 |
Offline |
The data of the file is not immediately available. Indicates that the file data has been physically moved to offline storage. |
Returns
|
0 |
Attributes set |
|
Error code |
Function failed |
Example
$Result = SetFileAttr(@LDRIVE + ".exe", 32)
Action
Sets the input focus to the application specified. This function is very useful in combination with the SendKeys function.
Syntax
SETFOCUS ("Title")
Parameters
Title
String specifying the title in the title bar of the application window you want to activate. In determining which application to activate, title is compared to the title string of each running application. If there is no exact match, any application whose title string begins with title is activated. If there is more than one instance of the application named by title, one instance is arbitrarily activated.
Returns
|
0 |
Focus set to specified application. |
|
Error code |
Function failed |
Example
If SetFocus ("Untitled - Notepad") = 0
? "Focus set to Notepad...."
Endif
Action
Changes the (power)state of the computer.
Syntax
SETSYSTEMSTATE (mode, force)
Parameters
Mode
Optional parameter specifying one of the following modes:
|
Value |
Action |
|
0 |
Lock system (supported on Windows NT and Windows 2000 only). |
|
1 |
Standby. |
|
2 |
Hibernate. |
|
3 |
Poweroff. |
Force
Specifies whether applications with unsaved changes are forcibly closed. If force is not zero, applications are closed. If force is zero, a dialog box is displayed prompting the user to close the applications.
Returns
|
0 |
Action succeeded |
|
System error code |
Action failed |
Example
$RC = SetSystemState( 1 , 1 ) ; Force system to StandBy mode
Action
Sets the current wallpaper.
Syntax
SETWALLPAPER("wallpaper name")
Parameters
Wallpaper name
String that specifies the name of the bitmap to set as the default wallpaper.
Remarks
The file specified must be a valid BMP file.
Returns
|
0 |
Wallpaper set |
|
Error code |
Function failed |
Example
If SetWallpaper ("kixtart.bmp") = 0
? "Set current wallpaper to KiXtart.bmp...."
Endif
Action
Instructs Program Manager to minimize, maximize, or restore the window of an existing program group.
Syntax
SHOWPROGRAMGROUP ("group name", show command, common group flag)
Parameters
Group name
Identifies the group window to minimize, maximize, or restore.
Show command
Specifies the action Program Manager is to perform on the group window. This parameter is an integer and it must have one of the following values.
|
Value |
Action |
|
1 |
Activates and displays the group window. If the window is minimized or maximized, Windows restores it to its original size and position. |
|
2 |
Activates the group window and displays it as an icon. |
|
3 |
Activates the group window and displays it as a maximized window. |
|
4 |
Displays the group window in its most recent size and position. The active window remains active. |
|
5 |
Activates the group window and displays it in its current size and position. |
|
6 |
Minimizes the group window. |
|
7 |
Displays the group window as an icon. The active window remains active. |
|
8 |
Displays the group window in its current state. The active window remains active. |
Common group flag
Optional numeric parameter. This parameter is available only on Windows NT. Common group flag can have the following values:
|
0 |
Acts upon a personal group. |
|
1 |
Acts upon a common group. To manipulate a common group, the user must have administrative privileges, or the function fails. |
Returns
|
0 |
Program group maximized, minimized, or restored |
|
Error code |
Function failed |
Example
If ShowProgramGroup("NewGroup", 6, 0) = 0
? "NewGroup has been minimized...."
Endif
Action
Shuts down or reboots a computer.
Syntax
SHUTDOWN ("computer", "message", wait, force, options)
Parameters
Computer
The name of the computer that is to be shut down or rebooted. An empty string("") indicates the local computer.
Message
String that specifies a message to display in the Shutdown dialog box.
Wait
Optional parameter specifying the time in seconds that the dialog box is displayed. While the dialog box is displayed, system shutdown can be stopped by using the Win32 AbortSystemShutdown function.
If wait is not zero, SHUTDOWN displays a dialog box on the specified computer. The dialog box, which displays the name of the user who called the function and the message specified by message, prompts the user to log off. The system beeps when the dialog box is created.
The dialog box remains on top of other windows and can be moved but not closed. A timer counts down the time remaining before a forced shutdown. If the user logs off, the system shuts down immediately. Otherwise, the computer is shut down when the timer expires.
If wait is zero, the computer shuts down without displaying the dialog box, and the shutdown cannot be stopped by AbortSystemShutdown.
Force
Specifies whether applications with unsaved changes are forcibly closed. If force is not zero, applications are closed. If force is zero, a dialog box is displayed prompting the user to close the applications.
Options
Optional parameter specifying one of the following options.
|
Value |
Action |
|
1 |
Reboot computer after shutdown. |
|
2 |
Poweroff the system after shutdown (NB: this option only works for the local system). |
Returns
|
0 |
Computer shut down |
|
System error code |
Function failed |
Remarks
SHUTDOWN does not work reliably on Windows 9x due to an issue in the underlying Windows API. As a workaround, the following command can be used:
SHELL “%windir%.EXE user.exe,ExitWindows”
Example
$RC = Shutdown("", "System is being rebooted to enable new settings.", 60, 0, 1)
Action
The SRND function sets the starting point for generating a series of pseudorandom integers. To reinitialize the generator, use 1 as the seed argument. Any other value for seed sets the generator to a random starting point. RND retrieves the pseudorandom numbers that are generated. Calling RND before any call to SRND generates the same sequence as calling SRND with seed passed as 1.
Syntax
SRND ( seed )
Parameter
Seed
Numeric value to seed the generator with.
Returns
Nothing.
Example
SRND( 10 )
Action
Returns part of a string.
Syntax
SUBSTR ("string", start, length)
Parameters
String
The string from which to extract a substring.
Start
Numeric value representing the offset in the string where the substring begins.
Length
Numeric value representing the length of the substring.
Returns
The substring indicated by start and length.
Example
$x = SUBSTR(@USERID, LEN(@USERID) - 2, 2) ; get the last 2 chars of the userid
Action
Returns a string in uppercase.
Syntax
UCASE ("string")
Parameter
String
The string you want to change to uppercase.
Returns
The input string in uppercase.
Example
$x = UCASE(@USERID)
Action
Unloads the specified key and subkeys from the registry.
Syntax
UNLOADHIVE ("key")
Parameters
Key
The key you want to unload. This key must have been created using LoadHive.
Remarks
On Windows NT, using UNLOADHIVE requires Backup and Restore privileges.
Returns
|
0 |
Key loaded |
|
Error code |
Function failed |
Example
$ReturnCode = UnLoadHive( "HKEY_USERS" )
If $ReturnCode = 0
? "Hive unloaded...."
Endif
Action
Returns the numeric value of a string.
Syntax
VAL ("string")
Parameter
String
The string whose numeric value you want to discover. By default, Val expects the string to be in decimal format. To determine the numeric value of a hexadecimal string, start the string with an ampersand ‘&’.
Returns
The numeric value of the input string.
Examples
$x = VAL(SUBSTR(@IPADDRESS0, 1, 3))
$x = VAL(“&A34”)
Action
Appends a line to the end of the file indicated by FileNumber. If WriteLine encounters an error, @ERROR is set to the relevant errorcode.
Syntax
WRITELINE (file number, “linetowrite”)
Parameter
File number
A numeric expression indicating the file number of the file to open. Possible values range from 1 to 10.
LineToWrite
The string you want to write to the file.
Remarks
WriteLine does not automatically append a <Carriage Return>, so if you want to write a <Carriage Return>, you should add it to the string (as in : $LineToWrite + Chr(13) + Chr(10)).
Returns
|
-4 |
File not open for writing |
|
-3 |
File number not open |
|
-2 |
Invalid file number specified |
|
-1 |
End of file |
|
0 |
Line written successfully |
Example
IF Open( 3 , “C:.TXT” , 5 ) = 0
$x = WriteLine( 3 , “KiXtart started at ” + @TIME + Chr(13) + Chr(10) )
ELSE
BEEP
? "failed to open file, error code : [" + @ERROR + "]"
ENDIF
Action
Copies a string to an initialization file.
Syntax
WRITEPROFILESTRING ("file name", "section", "key", "string")
Parameters
File name
String identifying the initialization file.
Section
String containing the name of the section of the initialization file where string is copied. If the section does not exist, it is created. The section name is not case-sensitive, and can contain any combination of uppercase and lowercase letters.
Key
String containing the name of the key to associate with string. If the key does not exist in the specified section, it is created. If this parameter is empty, the entire section, including all entries within the section, is deleted.
String
String to write to the file. If this parameter is empty, the key identified by key is deleted.
Note
On Windows 9x, use of the tab character () is not supported as part of this parameter.
Remarks
This function is provided for compatibility with 16-bit Windows-based applications. Win32-based applications store initialization information in the registry.
Returns
|
0 |
Profile string written |
|
Error code |
Function failed |
Action
Assigns a value to a registry entry.
Syntax
WRITEVALUE ("subkey", "entry", "expression", "data type")
Parameters
Subkey
Identifies the subkey where you want to write a value entry.
Entry
The name of the entry. To write to the default entry of a key, specify an empty string as the entry name (“”).
Expression
The data to store as the value of the entry.
REG_MULTI_SZ (multi-string) variables are returned with the pipe symbol ( | ) used as the separator between strings. If a string contains a pipe symbol character, it is represented by two pipe symbol characters ( || ).
Data type
Identifies the data type of the entry.
The following data types are supported:
· REG_NONE
· REG_SZ
· REG_EXPAND_SZ
· REG_BINARY
· REG_DWORD
· REG_DWORD_LITTLE_ENDIAN
· REG_DWORD_BIG_ENDIAN
· REG_LINK
· REG_MULTI_SZ
· REG_RESOURCE_LIST
· REG_FULL_RESOURCE_DESCRIPTOR
Returns
|
0 |
Value entry written |
|
Error code |
Function failed |
Example
WriteValue("EZReg", "A MultiString variable", "Line 1|Line 2|Line 3 with a || in it|" "REG_MULTI_SZ")
If @ERROR = 0
? "Value written to the registry"
Endif
KiXtart Macro Reference
Macros can be used anywhere an expression is expected. Supported macros are defined in the following table.
|
Macro |
Definition |
|
Address of the network adapter |
|
|
User comment |
|
|
Current directory |
|
|
Date (in the format YYYY/MM/DD) |
|
|
Day of the week (Monday, Tuesday, and so on) |
|
|
Domain or workgroup the computer belongs to |
|
|
Version of Windows NT |
|
|
Return code of the most recent command or function. A return code of 0 means the command or function was successful. Any other value indicates an error. |
|
|
Full name of current user |
|
|
Short name of the directory part of home directory |
|
|
Drive letter of drive containing home directory |
|
|
Server and share name part of home directory |
|
|
Fully qualified TCP/IP host name (including TCP/IP domain name) |
|
|
Operating system: 1 = Windows NT; 2 = Windows 9x |
|
|
TCP/IP address (possible values for x are 0 - 3). Note Addresses are padded so that the resulting string always consists of four sets of three characters separated by periods. For example, if your IP address is 123.45.6.7, @IPADDRESS0 is 123. 45. 6. 7. |
|
|
Version of KiXtart |
|
|
Directory where network software resides (usually Systemroot) |
|
|
Logon domain |
|
|
Drive that is redirected to \logonserver |
|
|
Version of network software |
|
|
Long name of the directory part of home directory |
|
|
Logon server |
|
|
Maximum password age |
|
|
Day of the month (1-31) |
|
|
Months since January (1-12) |
|
|
Name of the month |
|
|
Current user's primary group |
|
|
User's privilege level (GUEST, USER, ADMIN) |
|
|
Password age |
|
|
Number of active Remote Access Service (RAS) connections |
|
|
KXRPC server used for the current session |
|
|
Directory of current script |
|
|
Error text corresponding with @ERROR |
|
|
SID* |
Current user's Windows NT Security Identifier (SID) |
|
SITE** |
Name of the site in which the system resides |
|
Directory from which KiXtart was started |
|
|
Full English name of the language of the operating system specified in the format defined by ISO Standard 639. (example : “0413Dutch (Standard)”). |
|
|
Current time (in the format HH:MM:SS) |
|
|
Current user's Windows NT user ID |
|
|
Full English name of the language selected by the current user specified in the format defined by ISO Standard 639. (example : “0413Dutch (Standard)”). |
|
|
Days since Sunday (1 - 7) |
|
|
Computer name |
|
|
Current user's Windows user ID |
|
|
Days since January 1 (1 - 365) |
|
|
Current year |
*Available on computers running Windows 9x only if the KiXtart RPC service is running.
** Only available on clients with full Active Directory support.
Note
During the logon sequence, WUSERID is empty on computers running Windows 9x if Windows NT Networking has been configured as the system's primary network provider.
The following examples show the correct use of KiXtart macros:
@LM "2.10"
@DATE "1997/10/03"
DISPLAY @USERID + ".TXT" displays the file "RUUDV.TXT"
CD "" + @DOMAIN changes the current directory to "domain"