Script Syntax


Contents




Overview


Script files use a very simple to understand language to run their commands and actions.

In general terms these files use the extension .script and can be edited with any text editor or using the internal editor from WinBuilder.

Settings are written in the form of Key=Value (e.g. Color=Blue) and these values are kept inside sections (e.g. [MySection]).

You can also add aditional files inside your scripts and these files are stored as attachements in a process very similar to popular email messages. This way you can share your scripts in discussion forums with all the needed tools inside.

With this .script language you can copy files, create folders, write values on the registry and do a whole lot more.


We'll start off with very simple descriptions of each command and then some quick examples so that you can easily start understanding and creating your own scripts.





Compatibility


This page is updated directly from the internet and some of the commands that you find mentioned here might have been added only on recent WinBuilder versions.

It is recommended to use the latest versions to ensure the best results.





Usage



Overview


Script files can perform both specific and generic functions.

Some scripts will be responsable for creating the base structure of the project while others will be used to add extra functionality and programs.

These scripts can also use a very specific model that only works on a single project and cannot be sucessfully used on another project unless it also shares the same model as the original project from where it came. The model consists of functions and variables stored in scripts.

An effort is being made to create a generic sort of script to add programs across different projects, please read the script applications page for more details.



Sections

We use sections to group commands and settings inside script files. The easiest way to see how they are applied is to edit a few scripts and look at the source code to learn more about them.


A typical script is composed by 3 important sections


Here is a small example of how it should look:

[Main]
Title=Add my Program
Description=This script will add my program
Level=5

[Variables]
%myTitle%="This is a title for the program"

[Process]
echo,%myTitle%
....
....
We can aditionally use more sections to add variables from the script interface or even specify more sections with commands to be processed. We'll detail this further in these pages.

The [Interface] section is also important to scripts but we'll soon be referring to it in another chapter.



[Main] section

Inside this main section you can store the definitions that identify your script and allow it to be properly categorized inside the project. This section works like a normal INI section where you write all your data in the form of Key=Value (e.g. Color=Blue)

List of available keys


All of these keys can be edited easily using the wb's internal editor

These keys are optional, but it is recommended to place at least a few keys to better describe your script to others.

Some keys are assumed with default values if they are not found inside the script


[Variables] section

This section is described in more detail here



[Process] section

All commands you write in this section will be executed by the program.

From this section you can also call other sections using the run command from the same script or other scripts if necessary.

The result of each operation is written on the log window - which you can later view or save to an html page.






Levels


Levels is a feature from scripts that allow you to choose when your script should run while the project is being built.

You can select values between 1 and 10, when the project starts it will begin with the scripts that have the lower level number and will increase a level after all scripts with the previous levels are processed.

This is a very usefull way to ensure that your script always runs at the correct time. First levels are usually used to be build the structure of your project, while the last levels are the ones where your project is finished and an image is created.

By default, we use level 5 as the middle value where most scripts that are only meant to add programs should be processed.

To further categorize and group your scripts you can also create subfolders and in this way ensure that these scripts are separated from others with the same level. Look for examples on the available projects to understand more about these filters.







Syntax



.script commands can be grouped under the following categories


.script language commands are very dependent on the use of variables to make them more flexible, please read the respective variables page for aditional information.

All available commands are described on a single page so that you can later print this page to use as reference.




File Operations

Commands under this category were designed to handle files and are particulary useful to create the base structure of your project or add aditional features that you need.

List of available functions









FileCopy
FileCopy,"FromFile","ToDir"

This command will copy all files and respective sub folders from a given source to a specified destination. It uses Win32 API as a silent operation overwriting any previously existent files. You can view the result of this operation on the respective log entry.

FileCopy supports wildcards ( *.* )

Syntax example:
FileCopy,"c:\MyPath\*.txt","c:\AnotherPath"

On this example FileCopy will copy all text files (*.txt) from MyPath to AnotherPath




FileDelete
FileDelete,"FileToDelete"

This command will delete files. It uses Win32 API as a silent operation deleting all files that match the search criteria. You can view the result of this operation on the respective log entry. Beware that all deleted files are immediately removed instead of moved to the recycle bin.

FileDelete supports wildcards ( *.* )

Syntax example:
FileDelete,"c:\MyPath\*.txt"

In this example FileDelete will delete all text files (*.txt) from MyPath




FileRename
FileRename,"OldFilename","NewFilename"

This command will rename a single file

Syntax example:
FileRename,"c:\MyPath\myTextFile.txt","c:\MyPath\myOldTextFile.txt"

In this example FileRename will rename c:\MyPath\myTextFile.txt to another filename as myOldTextFile.txt




FileCreateBlank
FileCreateBlank,"NewFile"

This command simply creates a new empty file with the filename you specify. If a file with the same filename already exists it will be overwritten.

Syntax example:
FileCreateBlank,"c:\MyPath\MyNewFile.txt"

In this example FileCreateBlank will create an empty file called MyNewFile.txt




FileByteExtract
FileByteExtract,"FilesToSearch","OutputFile","ByteSignature","BytesLength"

This is a command with a very specific function. It will look inside all files that match the search criteria for a specific byte signature.

Byte signatures are specified in groups of two digits that are expressed in hexadecimal format. Possible value range from combinations starting at 00 and ending at FF

If this byte sequence is found, then it will copy a specific number of bytes and save them as a new file.

The bytes that compose the signature are also the header bytes on the new file.

This command was originally designed to find a byte sequence inside some system files that contained resources. Please look in the forums for pratical examples of usage.

Syntax example:
FileByteExtract,"c:\MyPath\*.*","c:\MyPath\NewFile.bin","001122334455",1440000

In this example, if a match is found then a new file will be created with the size specified in BytesLength





DirCopy
DirCopy,"FromDir","ToDir"

This command will copy a folder and respective sub folders from a given source to a specified destination. It uses Win32 API as a silent operation overwriting any previously existent folder.

Syntax example:
DirCopy,"c:\MyPath","c:\AnotherPath"

In this example DirCopy will copy all files inside MyPath to AnotherPath





DirDelete
DirDelete,"DirToDelete"

This command will delete a folder and respective files and folders inside. It uses Win32 API as a silent operation to delete the specified folder. Beware that deleted folders are not recoverable from the recycle bin.

Syntax example:
FileDelete,"c:\MyPath"

In this example FileDelete will remove MyPath





DirMove
DirMove,"MoveDir","ToDir"

This command will move a folder and respective sub folders from a given source to a specified destination. It uses Win32 API as a silent operation overwriting any previously existent folder.

The previous location ceases to exist with this folder being found under the new location

Syntax example:
DirMove,"c:\MyPath","c:\AnotherPath"

In this example DirMove will move MyPath to AnotherPath




DirMake
DirMake,"NewDir"

This command will create a new folder as you specify.

Syntax example:
FileCreate,"c:\MyPath"

In this example FileCreate will add a new directory called MyPath





CopyOrExpand
CopyOrExpand,"FileToCopyOrExpand","DestinationFolderOrFilename"

This is a very flexible command that is designed for cases where we can either need to Copy or Expand a file.

It was implemented to ease the task of copying files from Install CD's where often a specified can be present either in normal format or compressed.

These compressed files use the cabinet archiving method and usually have an identifiable _ as the last character on their extensions. (e.g. myFile.Tx_ ). When this file is expanded a new file with a full extension is retrieved.

DestinationFolderOrFilename means that you can either specify a folder where this file will be placed with the original (expanded) filename or new filename that you prefer.

Syntax example:
CopyOrExpand,"c:\MyPath\myTextFile.txt","c:\MyPath\myNewerTextFile.txt"

In this example CopyOrExpand will try first try to find a c:\MyPath\myTextFile.txt c:\MyPath\myTextFile.txt file and if it is not found then it will look for c:\MyPath\myTextFile.tx_ and expand this file if sucessfuly found.





Expand
Expand,"CABfile","DirToDecompress"

This command will decompress all files inside CABfile to the folder you specify.

Cabinet files usually use extension .CAB

Syntax example:
Expand,"c:\MyPath\MyFile.cab","c:\MyNewPath"

In this example Expand will try to expand all files found inside c:\MyPath\MyFile.cab to the folder c:\MyNewPath







Registry Handling


These commands are written to write and read values from the local registry on your windows machine. You can also load the hives from the projects being built at any given time.

These registry operations are valid for any Windows Platform, you should however note that Vista restricts the specific operation to load/unload hives - it is necessary to disable the UAC (User Account Control) before running projects that need this support.

List of available functions





RegWrite
RegWrite,"HKEY",KeyType,"Section","Keyname","Value"

This command will create a new registry entry as specified.

HKEY is the "Hive Key" where the key is to be placed. These hives are files that are loaded by your machine when booting and compose the registry structure. By default, most scripts use HKLM as the work hive.

Valid HKEY values

Details on the functions of each hive can be found at the Microsoft Site.


Keytype will specify how the data in the registry key should be interpreted.

Valid key type values


Section is the complete path to the section where the key is supposed to be written

Keyname and value are similar to the method for INI files, please ensure that the value you use is compatible with the key type.


Creating an empty section: Write a key using keytype as 0x1 and omit the entries for key and value - this will create a new section at the location you specify.


Syntax example:
RegWrite,HKLM,0x4,"Build\ControlSet001\Services\VgaSave\Device0","DefaultSettings.XResolution","1024"

The above example writes a numeric key with the value 1024





RegRead
RegRead,"HKLM","Section","Key","%Variable%"

This command will read a value from the key you specify.

It uses the same components as described above with the difference that it will copy the value of a key into a variable.

This command will only retrieve values from the following keytypes:

Syntax example:
RegRead,HKLM,"Build\ControlSet001\Services\VgaSave\Device0","DefaultSettings.XResolution","%myXresolution%"

In this example the variable %myXresolution% will store the value of the mentioned key





RegDelete
RegDelete,"HKLM","Section","Key"

This command will delete the key you specify.

It uses the same components as described above with the difference that it will the delete a key from the registry.

Syntax example:
RegDelete,HKLM,"Build\ControlSet001\Services\VgaSave\Device0","DefaultSettings.XResolution"

In this example the specified key will be deleted





RegHiveLoad
RegHiveLoad,"SectionName","HiveFilename"

This command will load an external registry hive onto your local registry system.

It is particulary useful to allow editing the hives of project when they are being built. Most scripts usually load the needed hives for editing and after writing all necessary data are properly unloaded (command described below).

This command is based on Windows 32bit API and works under any Windows platform - under Vista it is necessary to disable the UAC (User Account Control).


Syntax example:
RegHiveLoad,"Build","%targetdir%\I386\system32\setupreg.hiv"


In this example we will load the setupreg.hiv hive file from our work folder and place it under a registry section called Build





RegHiveUnload
RegHiveUnload,"SectionName"

This command will unload an external registry hive from your local registry system that was previously loaded with the RegHiveLoad command or with another application capable of handling external hives.

This is an obligatory step whenever you use the RegHiveLoad command otherwise your project might fail to be properly completed.

It will use as parameter the section name where the previously loaded hive was placed.

This command is based on Windows 32bit API and works under any Windows platform - under Vista it is necessary to disable the UAC (User Account Control).


Syntax example:
RegHiveUnload,"Build"


In this example we will load the setupreg.hiv hive file from our work folder and place it under a registry section called Build





RegImport
RegImport,"RegFileToImport"

This command will import an external registry file (*.reg) to your local registry system.

It will use as parameter the  filename to read values from.


Syntax example:
RegImport,"c:\myFile.reg"

In this example we add the values from myFile.reg onto the registry system

Ini manipulation


This category contains commands that were created to work with INI based text files.

INI consists in grouping information using a few rules, it is also very easy to understand and edit when needed.

We use INI files to exchange information between scripts or store data whenever needed. In most cases INI language files use extension .ini - but our commands are not limited to just this type of extension and can be used on any text file that uses a INI derivated language like .script language.


Quick explaining some INI concepts:



 Available INI functions





IniWrite
IniWrite,"Filename","Section","Key","Value"

This command will write the key and value on the section inside the file you specify.

Syntax example:
IniWrite,"C:\myFile.ini","mySection","myKey","myValue"

In this example the specified myKey and respective myValue will be written in the section mySection in C:\myFile.ini





IniRead
IniRead,"Filename","Section","Key","%variable%"

This command will read the key from a section inside a file that you specify.

Syntax example:
IniRead,"C:\myFile.ini","mySection","myKey","%myVariable%"

In this example the value of the specified key will be stored inside %myVariable%





IniDelete
IniDelete,"Filename","Section","Key"

This command will delete the key from a section inside a file that you specify.

Syntax example:
IniDelete,"C:\myFile.ini","mySection","myKey"

In this example the specified key and respective value will both be deleted





IniAddSection
IniAddSection,"Filename","Section"

This command will add a new section inside the file you select.

If this section already exists - no action will take place otherwise it will create a new empty section in the respective text file.


Syntax example:
IniAddSection,"C:\myFile.ini","mySection"

In this example we're adding a new section.





IniDeleteSection
IniDeleteSection,"Filename","Section"

This command will delete a given section inside the file you select.

All keys and values inside this section are completely removed as well.

Syntax example:
IniDeleteSection,"C:\myFile.ini","mySection"

In this example we're adding a new section.





IniWriteTextLine
IniWriteTextLine,"Filename","Section","StringLine"

This command will add a text line to given section inside the file you select.

This line is placed on the top of the section.

Syntax example:
IniWriteTextLine,"C:\myFile.ini","mySection","ThisIsMyLine"

In this example we a new line is added on the top of the section and all remaining lines are moved below.





IniMerge
IniMerge,"UpdatedINIfile","INIfileToUpdate"

This command will update all values from a INI file based on the contents from another INI file.

All Sections are compared inside both files and newer keys or items with different values are added to INIfileToUpdate

Syntax example:
IniMerge,"C:\myNewValues.ini","mySection","ThisIsMyBaseFile.ini"

In this example, the command will read all keys found inside myNewValues.ini and if they aren't present, ThisIsMyBaseFile.ini will be added, overwritting older values if necessary.


 


Attachments


Attachments are files that can be included inside your script.

Since script files are meant to be edited by any text editor, these files are encoded in a process similar to email attachments.

This method allows to add small files along with your scripts in order to keep everything together.

While a script is running you can use some of the following commands to best take advantage of this feature.

List of related commands




ExtractFile
ExtractFile,"%ScriptFile%","Folder","Filename","DirToExtract"

This command will extract a single file from a folder inside a given script.



Syntax example:
ExtractFile,"C:\myFile.script","Folder","myFile.txt","c:\"

Using this example we will extract a given myFile.txt from a script file to c:\





ExtractAndRun
ExtractAndRun,"%ScriptFile%","Folder","Filename"

This command will run a file that is attached inside a script file.

It is usefull when you only wish to run a file for a very specific purpose and this way avoid having to add extra commands to extract run and then delete the file from a temporary location when it is no longer needed.

Syntax example:
ExtractAndRun,"C:\myFile.script","Folder","myApp.exe"

Using this syntax we will extract myApp.exe to a temporary location and then delete this file when it is finished running.





ExtractAllFiles
ExtractAllFiles,"%ScriptFile%","Folder","DirToExtract"

This command will extract all files from a given folder inside a script.

Uses the same syntax as the ExtractFile command that extracts a single file, but with the advantage that you can extract all files from a folder without needing to specify any filenames.

Syntax example:
ExtractAllFiles,"C:\myFile.script","Folder","c:\"

Using this example we will extract all files found inside a folder in a given script file to c:\





ExtractAllFilesIfNotExist
ExtractAllFilesIfNotExist,"%ScriptFile%","Folder","DirToExtract"

This command uses the same syntax with the difference that it will  only extract files from a section in a given script if they aren't already found in DirToExtract

It was added to support cases where it is required to download only newer files and keep the older ones unchanged




Encode
Encode,%ScriptFile%,Folder,"Filenames"

This command will encode and add files inside a given folder on a script.

You can either specify a single filename or use wildcards that match a file criteria.

If the folder doesn't exist, it is created otherwise files are added to the already available folder.


Syntax example:
Encode,"C:\myFile.script","Folder","c:\myApp.exe"

With this syntax we add c:\myApp.exe inside Folder to C:\myFile.script






Text Files


With this set of commands we can handle text files and modify them as needed. All these commands can be applied to either a single or multiple file using wildcards.

Description of commands





TxtAddLine
TXTAddLine,"Filename","StringLine","Action"

With this command we can add a text line at a given location inside a text file, you can specify this location using an action option.

Action options

Syntax example:
TXTaddLine,"C:\myFile.txt","Hello World!",place,5

With this syntax we add a line saying Hello World! on the 5th line counting from the top. If the text file doesn't has 5 lines, then it will be placed as the last line. There is no limit to this count value.






TxtReplace
TXTReplace,"Filename","OldString","NewString"

This command will look inside a given filename and replace all text that match the value of OldString and replace them with NewString

Syntax example:
TXTreplace,"C:\myFile.txt","Hello World!","Have a good day"

All matches to Hello World! inside a text file will be replaced with Have a good day






TxtDelLine
TXTDelLine,"Filename","StringToDelete"

This command will look for lines that match the StringToDelete value and will remove these lines from the text file.

StringToDelete doesn't need to be the value of the entire line, it will only need to match the begining of the line.

Syntax example:
TXTDelLin,"C:\myFile.txt","Hello"

All lines that start with Hello inside C:\myFile.txt will be removed.





TxtDelSpaces
TXTDelSpaces,"Filename"

This is a very simple command that will delete all spaces inside a text file. It was created to make some specific INI files smaller in overall size.

Syntax example:
TXTdelSpaces,"C:\myFile.txt"





TxtDelEmptyLines
TXTDelEmptyLines,"Filename"

With a similar function to the above detailed command, this function will remove all empty lines from a give text file.

Syntax example:
TXTdelEmptyLines,"C:\myFile.txt"





If Clauses


In .script language you can use If clauses to ease your life when running a script and be able to evaluate certain conditions. 

If a condition is true when you test it with the IF command then a command will be executed.

List of available IF conditions





IF Exist.. or IF NotExist..
If,Exist..,"FilenameOrDirectory",Command

You can use this test to determine if a file or directory exists in a given location. If this test is true, then a Command is executed.

When testing sections, you need to add the filename and then the section name.

Available tests


Syntax example:
If,NotExistFile,"c:\myFile.txt",FileCreateBlank,"c:\myFile.txt"

In this given example we are testing if c:\myFile.txt does not exist. If this is true, then FileCreateBlank,"c:\myFile.txt" will be executed





IF Equal, Smaller, Bigger, NotEqual
If,%var%,test,value,Command

This set of IF clauses will test number values

Available tests

Syntax example:
If,%myVariable%,Equal,10,FileCreateBlank,"c:\myFile.txt"

In this given example we are testing if %myVariable% is equal to 10. If this is true then FileCreateBlank,"c:\myFile.txt" will be executed





IF Ping
If,ping,xxx.xxx.xxx.xxx,Command

Ping will test if a given IP is valid and run a command if this test is true.

Syntax example:
If,ping,10.111.8.1,FileCreateBlank,"c:\myFile.txt"

In this given example we are pinging a machine on the network. If this is true then FileCreateBlank,"c:\myFile.txt" will be executed.





IF Online
If,online,Command

Ping will test if the computer is online and run a command if this test is true.

Syntax example:
If,online,FileCreateBlank,"c:\myFile.txt"

In this given example we are checking if a machine is connected on a network. If this is true then FileCreateBlank,"c:\myFile.txt" will be executed.





IF License/NotLicense
If,License,textfilename,Command

This command was added to be used as tool to accept a license agreement whenever needed. It will open a special tab where the user has the option to read the terms of the license and then press a button corresponding to his decision to agree or not with the displayed terms.

TextFilename is the text file that will be displayed on the license window.

The option License runs a command when the user agrees with the license conditions and NotLicense will run a command if the user doesn't agree.

Syntax example:
If,NotLicense,c:\myEULA.txt,halt,"User doesn't agree with license."

This example will present the contents of myEula.txt - in case the user doesn't agree with this license the project build will be aborted.







Retrieve Functions


This set of functions will enable you to get some specific values when running your script.

They can be grouped as






Retrieve FolderSize/FileSize
Retrieve,FolderSizeOrFileSize,DirectoryOrFilename,%var%

This function is used to calculated sizes and store them inside variables.
Syntax example:
Retrieve,FolderSize,c:\myFolder,%var%

This example will write the size of myFolder as a new value for %var%





Retrieve File/Dir
Retrieve,File/Dir,DirectoryOrFilename,%var%

This function will bring a box asking the user to select a folder or a filename. Once a value is selected and the user clicks "Ok" to close the box, this value will be stored inside %var%
Syntax example:
Retrieve,File,c:\*.txt,%var%

You can use this example to open a box asking the user to select a file. This box will start in c:\ and will only display files that match the filter criteria which is *.txt on this case. Once a file is selected, the %var% will contain the full filename of this selected file.






Retrieve MD5
Retrieve,MD5,Filename,%var%

MD5 is a way to calculate a number known as a 'hash' or 'checksum' that is based on the filesize of a file.

It is used as a safety check to ensure that files are complete when they are download from a server. You can also call this function to ensure that your files were not modified.

Syntax example:
Retrieve,MD5,c:\MyText.txt,%var%

This function will write the value of the MD5 result on %var%, you can compare against a security value written elsewhere to prove that your file is intact.





String Format


This category details a command that is used to perform numeric calculations or extract specific details from a given text line (string).

List of available options







StrFormat INC/DEC/MULT/DIV
StrFormat,Action,%var%,1

This option is used to modify the value of a given number based on the arithmetic operation you select. It's also important to specify the value to use to perform this operation (only positive values).

The result is outputed to the used variable (%var%), negative numbers are supported by this variable value.
 
List of possible Action values
n is the last parameter on this command and should always be a numeric value.
Syntax example:
StrFormat,Inc,%LoopAgain%,5

In this example we have a variable called %LoopAgain% with a value of 10. Once we increase the value of this value with the last parameter of this command we will get the same variable %LoopAgain% with a value of 15. This same example applies for all other available actions.





StrFormat FILENAME/PATH/EXT
StrFormat,Action,Filename,%VarResult%

This option is used to extract specific information from the given text related to filenames.
 
List of possible Action values
Syntax example:
StrFormat,filename,c:\myPath\myFile.txt,%myVar%

This example will output to %myVar% a value of myFile.txt






StrFormat BYTES
StrFormat,bytes,%VarResult%

This option is used to convert a specific number of bytes from the given text. to a human readable format. Any ammount of bytes specified will be converted to Kb, Mb, Gb and Tb.

Syntax example:
StrFormat,bytes,1440000,%myVar%

In this example %myVar% will output a value of 1,44Mb




StrFormat DATE
StrFormat,Date,%var%,yyyy-mmm-dd hh:nn am/pm

This option is used to retrieve the current hour and date and output it to a variable using the format you prefer.
The last parameter will define the way how these values will be written to your variable. You can omit values that aren't needed and even add custom text inside.

Syntax example:
StrFormat,date,%myVar%,yyyy-mmm-dd

In this example %myVar% will output the current year, month and day - for example: 2007-jun-07






Network Tools


Functions on this category allow you to work with the network environment whenever available.



WebGet / WebGetIfnotExist
WebGet,"FileToDownload","FileOnDisk","MD5 check (optional)

Use this function to download files from a network server to the local machine. It is assumed that both machines (local and remote) are prepared for this operation.

No checks are done to ensure that the local machine is online or that is has enough disk space to download the file. The remote server must also be acessible and the file must be available for download.

Only direct download links are accepted, dynamic internet pages are not valid.

MD5 check is an aditional parameter that is added to ensure that your file matches a security check based on the MD5 hash calculation. This is an optional parameter, only needed for cases when it is important to only accept a file that passes on this download integrity test. If  a file fails this test it won't be copied over to the final destination as FileOnDisk.

If the target filename folder doesn't exist, it will be created. If a file already exists it will be overwritten (read WebGetIfnotExist for alternative behavior)

The WebGetIfNotExist command will only download a file if it is not already found as FileOnDisk - particulary useful to download a zipped file once from an internet server and ignore on the following times the script is executed.

Syntax example:
WegGet,"http://boot-land.net/winbuilder/WinBuilder.exe",c:\WinBuilder\WinBuilder.exe

Using this example we will download a WinBuilder.exe file from the server at boot-land.net to directory c:\WinBuilder.







Miscleaneous Commands


Under this category you find the commands which aren't grouped under any specific category but are still quite used on most scripting tasks.









Run / Exec
Run,%ScriptFile%,Section,parameters
Exec,%ScriptFile%,Section,parameters

This command is used to run the commands found in a section inside a script file. You can run sections from any script including the script from where run is originally called. Use %scriptFile% as a parameter to call another section found inside the same script.

By default this command will use the same variables available in the original script from where it was called. If you wish to load the variables from the external script then you should use Exec.


Syntax example:
run,%scriptfile%,mySection

In this example we run a section called mySection inside the same script file




Parameters support

This command also allows you to use parameters - this is a very useful feature to create a section that works based on these variables and this way avoid the need to add very long lines similar lines of code.

Inside each section that is called by run you can use the respective parameters which are numbered from #1 to #9

This means that you can use a run,%scriptfile%,mysection,"Hello World!"

And inside the [mysection] of the same script you can use a command like echo,#1 to display "Hello World!" on your log.



Exec
 
This command has a very similar behavior to the one described by the run command. It will aditionally add all the variables found inside the [variables] section. Identical variables found on the new script will overwrite the older ones.








ShellExecute / ShellExecuteEx


ShellExecute,Action,"Filename","Parameters","StartDir"
ShellExecuteEx,Action,"Filename","Parameters","StartDir"

This function will launch a file using the settings you specify. Action is the specific method you wish wish to use to start the external file. By default "Open" is the most used.

Possible action values
Filename is the complete filename to where the file can be found, you can omit the dir part if this file can be found on the system paths.

Parameters (optional) are the set of switches that you can pass along as command line parameters when executing the file.

StartDir (optional) is the location that you wish to specify as your default work directory.


The script will wait (pause) for the launched file or application to be closed before continuing processing the remaining commands.


ShellExecuteEx - has a similar behavior but won't wait for the application to be finished and will continue with the script processing right after launching the target filename.

Syntax example:
ShellExecute,open,cmd.exe

In this example we can open a new console window (cmd.exe)






Beep
Beep,Action

This is a very simple command that will use the default sound profile used on your machine to beep messages that requires the attention of the user.

Action can be one of the following values

Syntax example:
beep,ok





Message
Message,"message",Action

This command will pop a small text window displaying the contents of your message. The aditional action parameter will allow you to customize the icon displayed along with the message box.

Action can have of the following values
Syntax example:
message,"Script has been completed!",Information






System
System,Action

This command is used to perform some program internal actions and refresh values that were modified during the script execution. It will set a flag that reminds the program to perform the specified action once the project is completed.


Action can have of the following values





Echo
echo,message

This is a very simple command that will output your message to the processing window while the script is running. This message will only disapear until another message is displayed or the script finishes. These messages are also stored in the log and are used to inform the user about operations being performed by the script.

Syntax example:
echo,"Hello World!"






Wait
wait,seconds

Using this command will pause the script processing the the value of seconds that you specify. After this period is concluded, the process will continue.

Syntax example:
wait,5

This example will make the application wait 5 seconds before continuing





Exit
Exit,"exit message"

This command will force the script to be finished and will make the process continue to the next script on the list.

Exit message is a small text message that is displayed on the log where you can specify the reason why Exit was called.

Syntax example:
Exit,"File was not found"





Halt
Halt,"reason"

This command will force the overall project to terminate.

Reason is a small text message that is displayed in the log where you can specify the reason why Halt was called.

Syntax example:
Halt,"Incompatible Source"




SET
Set,"%Variable%","NewValue"

With this command we can change the value of a variable

If more variables are linked to this variable, then you might need to call System,RefreshVars to ensure that all variables get refreshed values and work properly.


Syntax example:
Set,"%workdir%","c:\myPath"





AddVariables
AddVariables,"%ScriptFile%","Section"

Use this command to add more variables to the script based on the entries found inside another section from any script file.

When a script is started it will read the [variables] section, during the script processing you can repeat this procedure and read the variables found inside any section you wish to use.

Use %scriptfile% to read a section from the same file from where this command is called.

Older variables with the same designation are overwritten with newer values.


Syntax example:
AdVariables,%scriptFile%,AlternativeVariables









Bugs


When a command doesn't work as expected you should follow these steps to ensure that it is a true bug and not a human error:



If none of the above solves your issue then here's the recommended way to proceed:




Log of changes

Changes in script language can be followed in each newer WinBuilder beta discussion where changes to the script code are suggested and debugged by other members.

Projects also follow their own script rules and these methods can change ocasionaly, whenever in doubt you should post your questions in each project forum discussion.



Please let us know if this page is not complete or if you still haven't found needed information.