This language reference provides informations, examples and syntax-rules on every instruction and function RapidBATCH 4.1 provides.
1. Variables- and Control-Instructions
1.1
DEC var1,var2,var3 ... varn
|
Description:
Declares one ore more new variables in the script.
|
Example:
dec [a], [b]
|
Notes:
It is not recommended to declare variables explicity before their usage in RB4. Dec can be used optionally.
|
1.2
LET var = value
|
Description:
Lets a value to a variable. Its possible to set a constant value or another variable.
|
Example:
let [a] = 'Hello World'
let [path] = [current] # '\test.txt'
let [c] = Welcome to RapidBATCH 4!
|
Notes:
none.
|
1.3
HALT
|
Description:
Stops the script immediatelly.
|
Example:
halt
|
Notes:
none.
|
1.4
IF condition instruction
IF condition
{instruction block}
[ELSEIF condition
{instruction block}]
[ELSE
{instruction block}]
ENDIF
|
Description:
The IF-instruction allows for conditional processing. It lets you compare values and runs any RapidBATCH instruction if the result of the comparison is TRUE. Alternative to only one instruction, an instruction-block can be specified that is closed by the next ENDIF-instruction. Those IF-constructions can also have an ELSEIF-block, that can verify another condition (if the first IF or prior ELSEIF failed), or ELSE-block which is executed if the condition's result is false. There can be only one IF and only one ELSE in one IF-block. ELSEIF-blocks can be specified in any amount.
In RapidBATCH, a condition is a comparison of two values. The programmer is able to compare to equal (=), not-equal (!), greather-than (>) and lower-than (<), whereas latter can only be used with numerical values. You can compare two variables, a variable with a constant value or two constant values (which is not very sensefull).
|
Example:
if [a] = [b] echo A is equal B!
if [password] = 'swordfish'
echo Login accomplished.
let [admin] = false
elseif [password] = 'master'
echo You have administrational rights.
let [admin] = true
else
echo False password!
halt
endif
if [a] < '10'
echo Error!
halt
endif
|
Notes:
IF-blocks can be combined in any order.
|
1.5
REPEAT ... UNTIL condition
|
Description:
With REPEAT and UNTIL, you're able to construct loops, that repeat a block of instructions until the specified condition is verified to true.
In RapidBATCH, a condition is a comparison of two values. The programmer is able to compare to equal (=), not-equal (!), greather-than (>) and lower-than (<), whereas latter can only be used with numerical values. You can compare two variables, a variable with a constant value or two constant values (which is not very sensefull).
|
Example:
rem this script counts a value from 0 to 10
let [i] = 1
repeat
echo 'Value: ' # [i]
calcvar [i] = [i] + '1'
until [i] > '10'
|
Notes:
REPEAT...UNTIL-loops can be combined in any order.
|
1.6
GOTO label
|
Description:
GOTO jumps to a specified label in the script. This possibility allows you to write ultra-complex scripts. A label is specified in the script with a beginning %-character.
|
Example:
%test
.
.
.
goto test
|
Notes:
The label specified at GOTO may not begin with the %-character.
|
1.7
GOSUB label .. RESUME
|
Description:
Same as GOTO, GOSUB jumps to a specified label in the script. The difference to GOTO is, that GOSUB jumps to a label, in this case a sub-program, and executes all code until the next RESUME-instruction. Then, the RESUME-instruction returns to the line behind the last GOSUB-call. This possibility allows you to write ultra-complex scripts. A label is specified in the script with a beginning %-character. GOSUB...RESUME constructions can be combined into complex srtructures of sub-program calls.
|
Example:
let [i] = 1
%next
if [i] = '11' halt
gosub square
calcvar [i] = [i] + '1'
goto next
%square
calcvar [x] = [i] * [i]
linkvar [out] = [i] + '*' + [i] + '=' + [x]
echo [out]
resume
|
Notes:
If no RESUME is found, GOSUB is executed like a GOTO.
|
1.8
WAIT millisec
|
Description:
Waits the specified amount of milli-seconds with the script execution.
|
Example:
wait 5000
echo Hello World ... after 5 seconds ;)
|
Notes:
none.
|
1.9
REM comment
|
Description:
REM allows you to comment your script. By the way, REM has no function, it just tells the compiler/interpreter that it should ignore all characters behind this instruction until the next line-break.
|
Example:
rem Ask user if he want to continue
confirm Do you want to continue?
|
Notes:
none.
|
2. User dialogs
2.1
MSGBOX title, message, buttons
|
Description:
MSGBOX lets the programmer show a defineable messagebox window to the user of the script. MSGBOX expects a title, a message text and a so called button type. Its possible to let a numerical value for the button type or RapidBATCH's build-in constants, e.g. OK or YESNOCANCEL. The list below shows the possible button types you can use. Which button has been pressed is saved to the variable [errorcode] (see return values in the list).
| Buttonvalue: |
Buttons (with return values): |
| 0 (ok) |
OK (1) |
| 1 (okcancel) |
OK (1) + CANCEL (2) |
| 2 (cancelretryignore) |
CANCEL (3) + RETRY (4) + IGNORE (5) |
| 3 (yesnocancel) |
YES (6) + NO (7) + CANCEL (2) |
| 4 (yesno) |
YES (6) + NO (7) |
| 5 (retrycancel) |
RETRY (4) + CANCEL (2) |
|
Example:
msgbox 'Hello!', 'Hello, my script user!', 'ok'
msgbox 'Exit script?', 'Do you really want to exit the script?', 'yesno'
if [errorcode] = '7'
halt
else
goto start
endif
|
Notes:
You can also use a customized icon in a message box. Calculate the button type, e.g. 4 for YES-NO and add the value 16, 32, 48 or 64 to it (so you assign e.g. 36 as buttontype). The result is a messagebox with YES-NO-Buttons and a question-mark icon! Return values are the same.
In RapidBATCH 3.0, this instruction has been called ECHOBOX. The old instruction is also possible to be compatible with RB 3.x and 2.x.
|
2.2
ECHO message
|
Description:
ECHO is a shortcut for a simple messagebox-dialog with OK-Button and Info-Icon.
|
Example:
echo Hello World
echo [text]
|
Notes:
none.
|
2.3
CONFIRM message
|
Description:
CONFIRM is another shortcut for a messagebox-dialog with YES-NO-Buttons. If the user presses YES, the variable [errorcode] gets the value 0, else -1.
|
Example:
confirm Do you really want to quit?
|
Notes:
none.
|
2.4
INPUTBOX var = title, prompt, pre-text
|
Description:
INPUTBOX shows a simple input dialog where the user can enter data. INPUTBOX expects a variable that gets the value the user entered, a title, a prompting text and a previewed text shown in the edit field.
|
Example:
inputbox [name] = 'Login', 'Please enter your login name:', 'Anonymous'.
if [name] ! 'Anonymous'
inputbox [password] = 'Password', 'Please enter password:', ''.
if [password] ! 'swordfish'
halt
else
let [loginstatus] = 'user'
endif
else
let [loginstatus] = 'guest'
endif
|
Notes:
If the user hits the CANCEL-Button, the return value is an empty string.
|
2.5
EDITBOX var = title, text, mode
|
Description:
The EDITBOX-function provides a dialog with a multi-line edit-field and "Ok" and "Cancel" buttons. In this dialog, the user can view or edit greater amounts of text.
The function expects a return-variable (which is, as the case may be, the by the user edited text) a dialog-title, the text displayed in the edit field and a show mode, which can be 0 (or WRITEABLE) or 1 (or READONLY). If you assign WRITEABLE as showmode, the text can be edited, else it can only be viewed (READONLY-mode).
|
Example:
editbox [text] = 'Edit', 'Edit any text into this field', 'writeable'
editbox [text] = 'View', 'This text cannot be modified.', 'readonly'
|
Notes:
If the user hits the CANCEL-Button, the return value is an empty string. You can individualize the EDITBOX-dialog over the pre-declared variables [EditBox_Width], [EditBox_Height], [EditBox_Ok] and [EditBox_Cancel].
|
2.6
LISTBOX var = title, list
|
Description:
The LISTBOX-function allows the user to make a choice from a list of options, e.g. in a menu or a file list. Return-value of the function is the chosen entry or, if no entry was selected, an empty string. As parameters, the function expects beneath the return-variable a dialog-title and the list of the entries, which is specified as a string, where each entry is seperated by a pipe-character (|), e.g. "First Entry|Second Entry|Third Entry|...".
If the user hits the dialog's close-button or the "Ok"-button without choosing an entry, the return value is an empty string.
|
Example:
listbox [food] = 'Yummy!', 'Pizza|Hamburger|Fries|Pita'
if [food] ! ''
echo 'Ah, you're a ' # [food] # ' eater ;) ...'
endif
end
|
Notes:
You can individualize the LISTBOX-dialog over the pre-declared variables [ListBox_Width], [ListBox_Height] and [ListBox_Ok].
|
|
2.7 OPENBOX filename = title, filter
|
Description:
Shows the Windows Standard Dialog to choose a file. OPENBOX expects a variable which gets the choosen filename, a title and a so called file filter.
A filter is specifiled as a string that looks like
"Text files|*.txt"
Or for more than one file types:
"Text files|*.txt|HTML-Files|*.html|DOC-Files|*.doc" ...
First, the file label that is shown in the filetype dropdown-box must be specified, then the filter type, all sepereated by pipe-characters (|).
|
Example:
openbox [file] = 'Open a file','Text files|*.txt|All Files|*.*'
|
Notes:
Use the SAVEBOX-instruction to show the Windows-standard save dialog. When you set the pre-declared variable [OpenBox_MultiSel] to 0, you can choose more than one file from the directory. In such a case, a file list is returned that begins with the directory that contains the files and the list of files, each seperated by a pipe-character (|). An example: "c:\my files|test.txt|hello.txt|myfile.txt" if the user chose the files TEST.TXT, HELLO.TXT and MYFILE.TXT from the directory C:\MY FILES.
|
|
2.8 SAVEBOX filename = title, filter
|
Description:
Shows the Windows Standard Dialog to choose a file. SAVEBOX expects a variable which gets the choosen filename, a title and a so called file filter.
A filter is specifiled as a string that looks like
"Text files|*.txt"
Or for more than one file types:
"Text files|*.txt|HTML-Files|*.html|DOC-Files|*.doc" ...
First, the file label that is shown in the filetype dropdown-box must be specified, then the filter type, all sepereated by pipe-characters (|).
|
Example:
savebox [file] = 'Open a file','Text files|*.txt|All Files|*.*'
|
Notes:
Use the OPENBOX-instruction to show the Windows-standard open dialog. When you set the pre-declared variable [SaveBox_MultiSel] to 0, you can choose more than one file from the directory. In such a case, a file list is returned that begins with the directory that contains the files and the list of files, each seperated by a pipe-character (|). An example: "c:\my files|test.txt|hello.txt|myfile.txt" if the user chose the files TEST.TXT, HELLO.TXT and MYFILE.TXT from the directory C:\MY FILES.
|
3. Functions
3.1
CALCVAR result = value1 +|-|*|/ value2 ... valueN
|
Description:
The CALCVAR-function performs calculations on variables and constant values, if they contain numerical contents. You can use the four standard arithmetic operatiors + for addition, - for substraction, * for multiplication and / for division. Floating values using a comma, you need to write a dot instead of the comma, so if you want to calculate "1,5", you need to write "1.5".
|
Example:
calcvar [c] = [a] + [b]
calcvar [x] = '10' * [n] / '4' - '77' * '3.5'
|
Notes:
none.
|
3.2
UPVAR result = value
|
Description:
Converts the specified value to upper cases and returns the converted string.
|
Example:
upvar [uppername] = 'hello world'
|
Notes:
Use the LOWVAR-function to convert a string to lower cases.
|
3.3
LOWVAR result = value
|
Description:
Converts the specified value to lower cases and returns the converted string.
|
Example:
lowvar [uppername] = 'HELLO WORLD'
|
Notes:
Use the UPVAR-function to convert a string to upper cases.
|
3.4
TRIMVAR result = value
|
Description:
The function TRIMVAR deletes all spaces from in front of and behind a string.
|
Example:
trimvar [a] = ' hello world '
|
Notes:
none.
|
3.5
GETCHR result = ascii-code
|
Description:
Returns the ASCII-character to the specified ASCII-code.
|
Example:
getchr [quot] = 034
|
Notes:
none.
|
3.6
GETLEN result = value
|
Description:
Returns the length in characters of the sepcified value.
|
Example:
getlen [len] = 'Hello World'
|
Notes:
none.
|
3.7
COPYVAR result = value: from, to
|
Description:
Extracts a substring from the specified value, that begins at character from and ends at character to. The result is the copied sub-string.
|
Example:
copyvar [n] = [name]: '5', '10'
|
Notes:
none.
|
3.8
GETPOS position = value: substr
|
Description:
Returns the position of the value substr in the specified value. If the value does not include the sub-string, the result value is 0.
|
Example:
getpos [pos] = 'Hello World': 'llo'
|
Notes:
none.
|
4. System-specific operations and file handling
4.1
CHDIR path
|
Description:
Changes to the specified directory. If the operation has been successfull, the variable [errorcode] gets the value 0, else -1.
|
Example:
chdir c:\jmksf
|
Notes:
Use MKDIR and RMDIR to create or remove directories.
|
4.2
MKDIR path
|
Description:
Creates a new, specified directory. If the operation has been successfull, the variable [errorcode] gets the value 0, else -1.
|
Example:
mkdir c:\jmksf\test
|
Notes:
Use CHDIR and RMDIR to change or remove directories.
|
4.3
RMDIR path
|
Description:
Removes the specified, empty (!) directory. If the operation has been successfull, the variable [errorcode] gets the value 0, else -1. Its not possible to remove directories which contain files via RMDIR.
|
Example:
rmdir c:\jmksf\test
|
Notes:
Use MKDIR and CHDIR to create or change directories.
To delete a directory, call the FINDFILES-function using the '*' filter in a loop and delete every file with DELFILE.
|
4.4
SYSTEM command
|
Description:
Executes an operating system command (DOS-commands). The script cannot run further before the SYSTEM-instruction finished its command.
|
Example:
system dir >list.txt
|
Notes:
[errorcode] gets -1 if no command.com can be found.
|
4.5
SHELL program, showmode
|
Description:
Executes an extern program.
If you run a program with SHELL, the own script runs further (multitasking).
program specifies the file name of the program that should be startet, showmode a so called show mode. Possible are the values SHOW (0), HIDE (1), MAXIMIZED (2) and MINIMIZED (3).
|
Example:
shell 'c:\windows\calc.exe', 'show'
shell 'c:\windows\desktop\test.bat', 'hide'
|
Notes:
none.
|
4.6
DELFILE filename
|
Description:
Deletes the specified file. [errorcode] gets 0 if the operation has been sucessfull, else -1.
|
Example:
delfile c:\windows\system\kernel32.dll
echo ;)
|
Notes:
none.
|
4.7
NEWFILE filename
|
Description:
Creates a new file. If the file has been created successfully, [errorcode] gets 0, else -1.
|
Example:
newfile c:\windows\desktop\hello.txt
|
Notes:
none.
|
4.8
COPYFILE source:target
|
Description:
Copies the file source to the file target. [errorcode] gets 0 if the operation has been successfull, else -1.
|
Example:
copyfile 'c:\jmksf\rbatch32\samples\hello.rb': 'a:\hello.rb'
|
Notes:
none.
|
4.9
FILEEXISTS filename
|
Description:
Tests if the specified file exists or not. [errorcode] gets 0 if the file does exist, else -1.
|
Example:
fileexists c:\windows\calc.exe
if [errorcode] = '0' echo CALC.EXE exists!
|
Notes:
none.
|
4.10
RENAMEFILE source:target
|
Description:
Renames the file source into the file target. [errorcode] gets 0 if the operation succeeded, else -1.
|
Example:
renamefile 'c:\test.txt': 'c:\test.old'
|
Notes:
With RENAMEFILE, you can also move files to other directories.
|
4.11
WRITEFILE filename: value
|
Description:
Writes the specified value to the specified file. The value is appended to the file's end, so that the files content won't be overwritten.
|
Example:
writefile 'c:\test.txt', 'Hello World'
|
Notes:
If the specified file does not exists, it will be automatically created.
|
4.12
READFILE result = filename: line
|
Description:
Reads the specified line from the specified file, and returns this. If the file end is reached or if the file couldn't be found, [errorcode] gets -1 and the return value is "EOF".
If the assigned line-number is lower than 1, READFILE reads the whole file content with a limit of 32768 bytes and returns it.
|
Example:
rem Read first line of the file...
readfile [text] = 'c:\test.txt', '1'
rem Read whole file...
readfile [text] = 'c:\test.txt', '0'
|
Notes:
none.
|
4.13
OPEN data
|
Description:
Opens a specified file with the associated program or loads an internet-URL into the browser. OPEN can also execute extern programs like SHELL.
|
Example:
open hello.rb
open http://www.jmksf.com
open c:\windows\calc.exe
|
Notes:
none.
|
4.14
MCI mci-string
|
Description:
Sends a command string to the Windows Multimedia Control Interface that lets you play nearly any type of media data, e.g. WAV, MOV, MIDI, MP3, AVI ...
|
Example:
mci open music.mp3
mci play music.mp3
wait 5000
mci close music.mp3
|
Notes:
Please view the help file MCI.HLP in the \DOC-directory of your RB4 setup directory to get a list of possible MCI-commands and functions. [errorcode] tells you the return-value of the WinAPI mciSendString()-function.
|
4.15
GETENV var = env_var
|
Description:
Gets the value of a DOS environment variable.
|
Example:
getenv [pathvar] = PATH
|
Notes:
Set envionment variables with the LETENV-instruction.
|
4.16
LETENV env_assignment
|
Description:
Sets an existing environment variable, or creates a new one.
|
Example:
letenv HELLO=Hello World
|
Notes:
Environment-variables which are created by a script will be autmatically deleted by the operating system when the script halts. Get environment variables with the GETENV-instruction.
|
4.17
CALL command
|
Description:
Runs a program in modal-mode. That means, that the script waits until the program, which had been started by CALL, terminates
|
Example:
call c:\windows\calc.exe
|
Notes:
[errorcode] gets -1, if an error occured, else 0.
|
4.18
SENDKEYS programwindow: keystrokes
|
Description:
Sends keystrokes and hotkeys to a window with the text programwindow in the title bar. This instruction allows to control any other Windows-application by remote, using a simple macro language.
Standard keys (letters, numbers) can directly be specified. Special keys can be assigned as hotkeys or over their keycodes. To specifiy a hotkey, use the hotkey-identifier, beginning with a tilde (~) and the identifier, from the list below. For any other special-keys or for shortcuts (e.g. ALT+F4) use keycodes, beginning with a hash (#) and the according keycode. A list of all available keycodes can be seen in the file KEYCODES.TXT in the \DOC-directory of your RB4 setup-directory.
| Hotkey: |
Meaning/Key: |
| r |
Enter, Return |
| t |
Tabstop |
| a |
ALT |
| c |
Shift |
| b |
Backspace |
| U |
Up-Key |
| D |
Down-Key |
| L |
Left-Key |
| R |
Right-Key |
| 1 |
F1-Key |
| 2 |
F2-Key |
| 3 |
F3-Key |
| 4 |
F4-Key |
| 5 |
F5-Key |
| 6 |
F6-Key |
| 7 |
F7-Key |
| 8 |
F8-Key |
| 9 |
F9-Key |
| A |
F10-Key |
| B |
F11-Key |
| C |
F12-Key |
| ~ (means: ~~) |
~-character |
|
Example:
shell [windir] # '\notepad.exe', 'show'
sendkeys 'Untitled - Editor': 'Hello World#272fs#018test.txt~r#272~4#018'
end
|
Notes:
[errorcode] gets -1 if no window was found, else 0.
|
4.19
FINDFILES file = filter
|
Description:
FINDFILES lists the content of a directory. The function must be called with the same file filter until it returns an empty string. It returns at every call the next file name of the current filter. If the filter is changed (and not all files where read), FINDFILES returns the new files with the new filter. This possibility allows to get the content of a directory without external programs. You can use the * and ? standard-wildcards in the file filter.
|
Example:
repeat
findfiles [file] = '*.*'
let [filelist] = [filelist] # [file] # [new_line]
until [file] = ''
echo [filelist]
end
|
Notes:
none.
|
4.20
FILESIZE result = file
|
Description:
Returns the size, in bytes, of the specified file.
|
Example:
filesize [bytes] = 'c:\autoexec.bat'
|
Notes:
none.
|
5. Pre-declared Variables
5.1
[errorcode]
|
Description:
The [errorcode]-variable contains status values and is used by many instructions to brief if an error occured or, e.g. in a MSGBOX- or CONFIRM-dialog, which button has been pressed by the user.
|
5.2
[command]
|
Description:
The Variable [command] contains the command line parameters assigned to the script (at the interpreter directly behind the filename, in compiled scripts all behind the executable file name).
|
5.3
[ownname]
|
Description:
Own filename of the script. In scripts executed by the interpreter, this is the name of the .RB-file, in compiled scripts the name and path of the .EXE-file.
|
5.4
[Echo_Title]
|
Description:
Title of an ECHO-messagebox.
Standard-value: "RapidBATCH Echo"
|
5.5
[Confirm_Title]
|
Description:
Title of a CONFIRM-messagebox.
Standard-value: "RapidBATCH Confirmation"
|
5.6
[current]
|
Description:
[current] contains the path of the current directory. Change the directy by using the CHDIR-instruction.
|
5.7
[windir]
|
Description:
The Windows system directory path.
|
5.8
[time]
|
Description:
The system's time in the format hh:mm:ss
|
5.9
[day], [month], [year]
|
Description:
The system's date informations, splitted into three variables (for different date formatting)
|
5.10
[curuser]
|
Description:
In Windows NT, 2000 and XP the name of the current user who is logged in. In Windows 95, 98 and ME family logon, the value is "unknown".
|
5.11
[winvers]
|
Description:
The Windows-version. Possible values: 95, 95A, 95B, 95C, 98, 98SE, ME, NT4, 2000, XP and unknown, if there is a newer Windows-version than XP (e.g. Longhorn, Windows 2003 Server).
|
5.12
[IBox_Ok], [IBox_Cancel]
|
Description:
The caption of the OK- and Cancel-buttons in the INPUTBOX-dialog window.
|
5.13
[EditBox_Ok], [EditBox_Cancel],
[EditBox_Height], [EditBox_Width]
|
Description:
These variables allow to individualize the EDITBOX-dialog. With [EditBox_Ok] and [EditBox_Cancel], you're able to change the caption of the "Ok" and "Cancel" buttons; [EditBox_Height] and [EditBox_Width] allow to set a customized size of the dialog, in pixels.
|
5.14
[ListBox_Ok], [ListBox_Height], [ListBox_Width]
|
Description:
These variables allow to individualize the LISTBOX-dialog. With [ListBox_Ok], you're able to change the caption of the "Ok" button; [ListBox_Height] and [ListBox_Width] allow to set a customized size of the dialog, in pixels.
|
5.15
[OpenBox_MultiSel], [SaveBox_MultiSel]
|
Description:
Sets the OPENBOX- resp. SAVEBOX-dialog to the possibilty, that more files can be chose. Set the variable to 0, and the user can choose more than one files in the according dialog, else, if the value is -1, he is able to choose only one file.
|
5.16
[new_line]
|
Description:
A line break. This variable was only introduced to save the creation of an own line break variable with a GETCHR-call like
getchr [linebreak] = '10'
Because such a possibilty was desired by many users, it was implemented in v4.1. For a line break in a string, you only need to catenate iot together, e.g.
let [hello] = 'Hello' # [new_line] # 'World'
will output
Hello
World
|
5.17
[clipboard]
|
Description:
Accesses the Windows® clipboard. You can send data to the clipboard by letting data to it, or you read it out by reading the variable.
|
<<< Back
|
|
