This compact programming guide should introduce the newbie and advanced programmer
to the RapidBATCH scripting language and its syntax, basic instructions and functions.
To get more help and useful examples on RapidBATCH scripting, look up some script
examples in the sub-directory \SAMPLES of your RapidBATCH setup directory.
To edit RapidBATCH scripts, you can use any text editor of your choice (e.g. Windows Notepad).
Indeed, RapidBATCH provides its own, powerful script editor, the RapidBATCH Builder,
that lets you edit, run and compile scripts directly out of the code.
Fig. 0: The RapidBATCH Builder script editor
Contrary to many other development systems of this genre, RapidBATCH is a "pure" programming
language that is designed with an easily learnable, logical and flexible syntax. To run
RapidBATCH programs, the so-called scripts, RapidBATCH uses an interpreter that executes
the scripts directly from the code. That means that each script you run is directly
executed without translating it into for the computer understandable machine code. The advantage
of this concept is that the scripts can be tested and applied more easily.
In addition to this method of script execution, RapidBATCH provides you in the commercial
Professional Edition a compiler that allows you to compile your scripts into
stand-alone programs with the .EXE file extension. This allows you to provide and run RapidBATCH
scripts as standard Windows applications on any Win32 system without a RapidBATCH interpreter
or RapidBATCH development environment. Additionally, compiled scripts are protected from
unauthorized changes and manipulations.
A simple programming example
Let's begin with a simple example. The first script we want to program does nothing
more than display a typical Windows messagebox with the message-text "Hello World" on the screen.
To begin a new script, run the script editor RapidBATCH Builder from the start-menu
(Start -> Programs -> RapidBATCH Professional/SE -> RapidBATCH 4.2) or the
Windows Explorer (by running the program RBB.EXE in your RapidBATCH setup directory).
After that, enter the following source code:
echo 'Hello World'
end
Thats it. The above, two line script, is already a complete RapidBATCH program. Save
the script under a favored filename (e.g. HELLO.RB) and run it, by pressing the F5-key
or the "Run script" button in the RapidBATCH Builder toolbar. If you have the Professional Edition of RapidBATCH, you can also compile the script into a stand-alone EXE application
by pressing F9 or by choosing the menu-entry "Compile" from the script-menu. Congratulations
to you, your first, runable script in RapidBATCH!
Fig. 1: A "Hello World" in RapidBATCH!
Now, after you have run your first script, we will go over the explanation of these
two code lines: The instruction ECHO outputs, as you have seen already, a messagebox window.
As a parameter, this instruction expects the message text which should be shown in the messagebox.
This doesn't have to be written explicitly between aphostrophes, you only need to write values
in aphostrophes if you use an instruction with more that one parameter (as you will see later). But we use aphostrophes because this is the modern style of RapidBATCH scripting.
The END instruction marks the end of the script, so the compiler or interpreter knows
that the program's end is reached. RapidBATCH does not differentiate between upper and
lower cases in programming instructions, so the instructions ECHO, eChO and Echo are
always the same. I prefer the lower case as you can see above. The end of the line is
also the end of the instruction, so you always need to begin a new line for each instruction.
You can see that RapidBATCH is a flexible programming language with a very flexible syntax.
Working with variables
Now that you have written and ran your first script, we will begin a slightly different
part of programming, the variables. Variables are the key to complex and flexible
computer programs which act and run on the basis of variable data (because the workflow
of a program depends on this variable data).
The next script should now demonstrate how variables are used and what an (important) role
they can play. Create a new script in the Builder and enter the following source code:
inputbox [user] = 'Hello!', 'What is your name?', ''
echo [user]
end
Fig.2: Script using variables.
This script prompts the user for his name by using the INPUTBOX instruction. The name
the user enters will be saved in the variable with the variable-name [user] in front
of the equal-character (=). Variables are always written between brackets, and can be
used anywhere you can use constant values. This is done by directly specifiying the
variable instead of the constant value. That's the case in the ECHO instruction following
the INPUTBOX dialog. We specify the variable name instead of a constant data to the
instruction, that means we output the dynamic content of the variable [user] (which can
be any name the user entered) in this ECHO-messagebox.
Variables in RapidBATCH can store both texts (also called "strings", even character strings)
and numbers (numerical values). The conversion between the different data types occurs
internally so that you, the programmer, don't have to deal with this subject.
In RapidBATCH 4-series' predecessors, you always had to declare variables before their first usage by the DEC instruction. You can still use DEC if you like, but in RapidBATCH 4, variables are declared automatically now right when any value is assigned to them.
Probably you have already noticed how variables are handled: You can store data into
them and use this variable data instead of constant values in all instructions.
To assign a constant value or the value of another variable to a variable, you need to do a so called assignment. In the past (until RapidBATCH v4.4), you always had to use the instruction LET to assign a value to a variable. This is not neccessary anymore with RapidBATCH 4.4 and higher, so the you can write
[a] = 'Hello World'
[b] = [a]
or also with the old-styled RapidBATCH syntax:
[a] = 'Hello World'
[b] = [a]
to assign values to varaibales.
When you run these two lines, the variables [a] and [b] will contain the same value,
in this case "Hello World". So if you would output it in this way
echo [a] # [b]
the output in the messagebox will be "Hello WorldHello World". Here we use the new
hash operator (#), that was introduced with RapidBATCH 4.1, to concatenate the values
together into one output string. You can use the # operator everywhere you want.
But that isn't all you can do with variables. You can not only store values into them,
you can also manipulate or calculate their contents! For this purpose, RapidBATCH provides
you some useful built-in functions. These functions have return values and one or
more parameters. In the following example, we convert the value of a variable to upper case
using the UPVAR function. This script is based on the first variable sample from above, but
we extend it with this simple function-call now:
inputbox [user] = 'Hello!', 'What is your name?', ''
upvar [output] = [user]
echo 'Welcome ' # [output] # '!'
end
This program is now working with two variables. The variable [output] gets the result
value of the function UPVAR, the text converted to upper case. You also could assign the
result value directly to the parameter variable like this:
upvar [user] = [user]
In this case, the source value of [user] will be converted and replaced in [user] again
by the new, converted value.
Also, we use the hash-operator as described above to output a welcome message to the user.
Fig.3: The script converts the name and outputs a welcome message!
Please note, that function names in RapidBATCH mostly end with "-VAR" or begin with "GET-",
e.g. the GETCHR function. This format is used often with functions in RapidBATCH.
At the end of this, rather difficult chapter, we will write a script that calculates variables!
Calculations are processed with the CALCVAR function. This function expects a formula of
numeric constants and variable values, seperated by the arithmetic operators "+" for addition,
"-" for substraction, "*" for multiplication, "/" for division and last but not least "~" for modulo.
If an assigned value is not numeric (e.g. a variable containing the string "abc"),
the value is automatically converted to 0.
The script we want to create now should multiply a value entered at the prompt by a user with itself,
so that we get the squared result. The base formula is very simple:
RESULT = VALUE * VALUE
Our square calculator is programmed as the following:
inputbox [value] = 'Input', 'Please enter a value: ', '0'
calcvar [result] = [value] * [value]
echo 'The result is: ' # [result]
end
You can calculate any amount of values using CALCVAR, so that e.g. the following formula
is also possible:
calcvar [a] = '12' + [a] * [b] / [c] - '55' / '0.1' + [x]
Please consider, that you need to use a dot (.) for the comma (,) in all floating values!
CALCVAR represents an exception from all other RapidBATCH functions, because it expects
arithmetical characters instead of commas for the variable and value seperation. Also, CALCVAR is the only function in RapidBATCH allowing an optional amount of parameters. In all other RB functions, this is not the case.
Conditions
Now that you have gotten to know the great features of flexible programming using variables, this chapter will discuss how to handle conditions, that means how
you can operate on this variable data in your scripts using conditions and loops.
Let's begin with a simple script that asks for a password until the right password is entered.
In this case, we use the instructions REPEAT and UNTIL to construct a loop, that repeats
the INPUTBOX function until the given password verfication condition results are true.
The code:
repeat
inputbox [password] = 'Login', 'Please enter your password:', ''
until [password] = 'hello'
echo 'Welcome, the password was correct.'
end
When you run the script, you can see that the INPUTBOX always appears again until
you enter the right password ("hello"). For this condition, we use the equal operator
to verify the two values (which are the content of the variable [password] and the
constant value 'hello') if they are equal. Otherwise, possible operators are the not-equal
operator (!) and for numerical values the greater-than (>) and the lower-than (<) operators.
I advise insetting all code between REPEAT and UNTIL with spaces or tabs. This contributes
to a better code readability and makes it easier to find program errors (so called "bugs")
in bigger scripts.
But loops are not the only possibilty in the conditional programming of RapidBATCH.
The other, and more frequently used possibilty is the IF instruction. This can be used
with the instructions ELSEIF, ELSE and ENDIF in various, very complex constructions
and algorithms.
The following examples demonstrate how these instructions can be used.
A simple IF instruction would be
if [input] = 'hello' echo 'The prompted word was sucessfully verified to "hello"'
In this case, the instruction (or function), that should be executed when the condition succeeds,
is directly written behind the condition. To execute more than one instructions to one IF
condition, you need to construct a simple IF block. It begins with an IF and
the condition, then the code that should be executed when the condition succeeds and
finally an ENDIF instruction at the bottom that marks the end of this IF block.
if [input] = 'hello'
echo 'The prompted word was sucessfully verified to "hello"'
calcvar [hello] = [hello] + '2'
if [hello] > '32' halt
endif
The line break behind the condition instructs the interpreter resp. compiler, that
the following lines belong to this instruction as an IF block, until the next
ELSEIF, ELSE or ENDIF instruction.
To do more than one verification in one IF block, use the ELSEIF instruction to verify
another condition if the first condition fails:
if [input] = 'hello'
echo 'The prompted word was sucessfully verified to "hello"'
calcvar [hello] = [hello] + '2'
if [hello] > '32' halt
elseif [input] = 'bye'
echo 'Goodbye!'
halt
endif
If none of the conditions succeed, if all IF/ELSEIF conditions fail, you can add an ELSE
block that is executed in this case.
if [input] = 'hello'
echo 'The prompted word was sucessfully verified to "hello"'
calcvar [hello] = [hello] + '2'
if [hello] > '32' halt
elseif [input] = 'bye'
echo 'Goodbye!'
halt
else
echo 'ERROR: Submission undefined.'
goto restart
endif
At the end of this (again slighlty complex) chapter, a simple script that verifies
two prompted values to equal or not-equal:
repeat
repeat
inputbox [a] = 'Prompt A', 'Please enter a value:', ''
until [a] ! ''
repeat
inputbox [b] = 'Prompt B', 'Please enter a value:', ''
until [b] ! ''
if [a] = [b]
echo 'A equals with B'
else
echo 'A equals not with B'
endif
confirm [stop_now] = 'Again?'
until [stop_now] = '-1'
end
Labels and subs
An approved instrument to construct structured program flows in RapidBATCH is to jump to code
labels and sub-programs, the so-called subs. The possibilities are only discussed briefly,
because many problems can be solved more effectively with the new REPEAT and UNTIL instructions.
To work with code labels and sub-programs, RapidBATCH provides the instructions GOTO,
GOSUB and RESUME. GOTO allows you to "jump" ahead and back trough the program code to
a defined label, where the program execution is continued. Many programmers hate this
possibilty in various programming languages because it makes the code too complex and
difficult to read. Anyway, in some cases, labels and GOTOs are really essential.
The easiest example is the following script. We have three ECHO instructions, but only
the first and the last one will appear. The second will never be reached, because
the script jumps behind the first ECHO instruction to the label %end in front of the
last ECHO instruction. Labels are marked with a beginnig percent-character (%) and can
have any name. The percent is only assigned to the label to mark it in the code, if you
specify a label at a GOTO or GOSUB instruction, you do not include the percent character.
echo MessageBox 1
goto end
echo MessageBox 2
%end
echo MessageBox 3
end
RapidBATCH also provides the ability to create simple sub-programs, so-called subs.
These are not real procedures like the ones from bigger programming languages, e.g.
J.M.K S.F. Turbo/PL². Subs are code-blocks that you can jump to
from anywhere in the script and which automatically continue using the RESUME instruction
after the last code line of the sub.
The following example squares all numbers from 1 to 10 by calling the sub %square with each
loop. You will see, when the sub is executed, the RESUME instruction lets the script
continue from where the sub was called, so that the counter can be incremented and the
next call can be done.
[i] = 1
repeat
gosub square
calcvar [i] = [i] + '1'
until [i] > '10'
halt
%square
calcvar [x] = [i] * [i]
echo [i] # ' * ' # [i] # ' = ' # [x]
resume
end
Please note, that such sub calls can be nested together into complex scripts. If you
run the following script, the messageboxes appear in the sequence 1, 3, 4, 5, 6, 2!
echo 1
gosub test1
echo 2
halt
%test1
echo 3
gosub test2
resume
%test2
echo 4
gosub test3
resume
%test3
echo 5
gosub test4
resume
%test4
echo 6
resume
end
Note, that one label can be reached by various GOTO or GOSUB instructions.
User interaction
In the above chapters, you have already learned some possibilities of interaction with
the user. This chapter will descibe all the powerful user interaction possibilites that
RapidBATCH provides you in a more detailed way.
You already learned to know the ECHO instruction in our first script. ECHO shows a messagebox
window with a programmed text. However, this offers very few options and little individualization.
You can change the messagebox's standard title by changing the content of the pre-declared
variable [EchoBox_Title] to the desired value. To get full individualization in this, under
Windows very often used interaction dialog, you should use the MSGBOX instruction. This
instruction expects a title, a message-text and a window-style for a fully individual
messagebox window.
A very simple messagebox using the MSGBOX instruction would be:
msgbox 'Information', 'Hello World', '0'
end
Which of the displayed buttons was pressed is saved to the pre-declared variable [errorcode]
(in the above sample always 0, because we only let the user press one button, the "Ok"-button).
[errorcode] is a variable that is used by many RapidBATCH instructions to get the status
or errorcode an instruction generates. In this case, [errorcode] tells which button was
pressed (more about the [errocode] variable will be discussed later).
A messagebox-style is composed of a button-style and an icon-style. Additionally, the
position of the input focus (means: which button is automatically pressed when the
user hits the Enter-key) can be defined over this, by a numeric value representing style.
Possible button styles are:
| Style-ID: |
Button-Style: |
| 0 |
OK (1) |
| 1 |
OK (1) + CANCEL (2) |
| 2 |
CANCEL (3) + RETRY (4) + IGNORE (5) |
| 3 |
YES (6) + NO (7) + CANCEL (2) |
| 4 |
YES (6) + NO (7) |
| 5 |
RETRY (4) + CANCEL (2) |
Which value that is assigned to the [errorcode] variable can be seen in the clamped
values, e.g. if the user hits "Cancel", [errorcode] gets the value 3.
If you add one of the following values to the desired button-style, the messagebox
also displays one of the four messagebox standard-icons:
| Icon-ID: |
Icon: |
| 16 |
 ERROR |
| 32 |
 QUESTION |
| 48 |
 WARNING |
| 64 |
 INFORMATION |
Here is an example:
rem This is a fake, it does not really delete a file ;)...
msgbox 'Question:', 'Do you really want to delete the file?', '51'
if [errorcode] = '6'
echo 'File was deleted.'
elseif [errorcode] = '7'
echo 'File was not deleted.'
else
halt
endif
Fig. 4: Customized messagebox using the MSGBOX-instruction
Here, we add button-style 3 and icon-style 48 together, assigning 51 as messagebox-style.
If you add 256 (for the 2nd) or 512 (for the 3rd) to this value, you can also set the
focus to that button.
Since RapidBATCH 4.2, there's also another possibility to display data or status-informations to the user. The INFOBOX-dialog is a caption-less window, that is displayed in the foreground of all other applications on the screen. This dialog can be used, for example, to display a "Please wait..."-message when the script does other operations in the background. The INFOBOX can be displayed and hidden only by the script; It does not provide any possibilites to close or move this window.
A simple example is the following script:
infobox 'Please wait for 5 seconds', 'show'
wait '5000'
infobox 'Thank you!', 'show'
wait '1000'
infobox '', 'hide'
end
To change width or height of the INFOBOX-dialog, set the variables [InfoBox_Height] and [InfoBox_Width] to the desired values. [InfoBox_Enabled] lets you show or hide the dialog without an extra call of the INFOBOX-instruction.
To get data from the user, RapidBATCH provides the INPUTBOX-function, that you have already learned in the above chapters.
This dialog
allows the user to enter a value in an one-line edit field. If the "Ok"-button is clicked,
the entered value is returned, otherwise the function returns an empty string to the return
variable. You already know that the INPUTBOX-dialog can also be changed individually. It
lets you specify a dialog-title, a prompting text, and a pre-defined text in the text-field.
If you assign another value to the pre-declared variables [IBox_Ok] and [IBox_Cancel], you
can also change the labeling of the two buttons individually, e.g. to another language or meaning.
Another method that RapidBATCH provides for text input is the introduction in RapidBATCH 4.1
of the EDITBOX function. EDITBOX provides the script user a dialog with a multi-line editfield
and (same as INPUTBOX) two buttons. As parameters, EDITBOX expects a dialog-title,
a pre-defined text in the text-field (that can also include line breaks) and an EDITBOX-style,
that can be 0 for "WRITEABLE" and 1 for "READONLY" (you can also assign "writeable" and
"readonly" directly as style values).
This style allows the programmer to allow the user to only view the text in "READONLY" mode,
but not change it. EDITBOX can be used to view and edit files (e.g. ReadMe's, Log-Files) or
something else. Return-value of the EDITBOX is the whole text in the edit-field, including
line-breaks and other special characters.
The following script shows how EDITBOX is used to view the contents of the system file
AUTOEXEC.BAT in the edit field. Here, we use the READFILE function to read the contents
of AUTOEXEC.BAT. We will discuss this function in a later chapter in more detail.
readfile [text] = 'c:\autoexec.bat': '0'
editbox [text] = 'File: AUTOEXEC.BAT', [text], 'readable'
echo 'Return value of EDITBOX: ' # [new_line] # [text]
end
Fig. 5: Edit texts with the EDITBOX dialog.
The EDITBOX dialog can be resized by the user. You can individually resize the dialog
by setting corresponding pixel values to the pre-declared variables [EditBox_Height] and
[EditBox_Width].
[EditBox_Height] = '400'
[EditBox_Width] = '600'
editbox [text] = 'Testscript', 'Hello World...', '0'
end
Additionally, the captions of the buttons "Ok" and "Cancel" can be changed, like in the
INPUTBOX dialog, by overwriting the pre-declared variables [EditBox_Ok] and [EditBox_Cancel].
Besides these possibilites, offers you the LISTBOX function since v4.1, which displays to
the user a dialog containing a listbox where he can choose an entry that is returned by
the function. A perfect usage of the LISTBOX dialog can be a menu or other choice. LISTBOX
expects dialog-title and a list of entries, where one entry can be chosen. The list is
assigned as a string, in which each listbox entry is seperated by a pipe-character (|)
from the others.
The following script demonstrates how LISTBOX is used:
listbox [food] = 'Yummy!', 'Pizza|Hamburger|Fries|Hot Dog'
if [food] ! ''
echo 'Ahh I see, you like ' # [food] # '!'
endif
end
Fig. 6: A choice with the LISTBOX function
If the user clicks "OK" with no item highlighted or clicks the dialog's close-button, LISTBOX
returns an empty string. Otherwise the entry chosen from the list will be returned.
As with EDITBOX, the LISTBOX can be individualized by setting the variables [ListBox_Height]
and [ListBox_Width] for height and width and [ListBox_Ok] for an individual button caption.
To let the user choose a file, RapidBATCH provides the OPENBOX and SAVEBOX dialogs.
These functions show a standard Windows dialog for choosing a file from the file system.
The next example lets the user choose a file and displays the chosen file in a messagebox.
openbox [file] = 'Please choose a file:', 'All files|*.*'
echo 'Chosen file: ' # [file]
end
Fig. 7: Choosing a file with the OPENBOX dialog.
As parameters, both functions (OPENBOX, SAVEBOX) expect in addition to the result-variable,
a dialog-title and a file filter. This filter selects different file types and displays
only the files matching the specified filter in the dialog. In the above script, we
display all files by using the file filter "*.*". You can specifiy more than one filter.
Which filter is used can only be determined by the script user. A filter is specified
by a filter-descriptor, a pipe (|) and the filter. To add more filters, add another pipe
and do the same order again (filter descriptor, pipe, filter).
Last, but not least method is the FOLDERBOX-function. Since RapidBATCH 4.2, this dialog lets the user choose a folder from an explorer-like dialog window, where he can browse and choose a desired directory. The function expects two parameters (title and pre-selected folder), and returns the chosen path, or an empty string if nothing was selected.
An example:
folderbox [f] = 'Please select a folder:', 'C:\JMKSF\RB4'
echo 'The chosen folder was: ' # [f]
findfiles [content] = '*', '0'
replacevar [content] = [content], '|', [new_line]
echo [content]
end
Fig. 8: Choosing a folder with the FOLDERBOX-dialog.
System scripting and file operations
The major task of RapidBATCH is the development of automation tools and small applications
for system specific operations (even batch jobs ;)). For these purposes, RapidBATCH 4 provides
many system specific instructions, which allow you to copy, create, delete, edit, write files
and directories or to run external programs.
To run an external program, RapidBATCH provides you with three instructions. The first
is the classic SHELL instruction that allows you to run Windows programs with a specified
showmode. An example:
shell 'c:\winnt\system32\calc.exe','show'
This would start the Windows calculator CALC.EXE as an example. SHOW specifies that the
program is shown in normal mode. Also possible are the modes HIDE, MAXIMIZED and MINIMIZED.
In the mode HIDE, the program is executed in the background. This mode is only adviseable
if the program you want to run does not need any user input. When a program is started
with SHELL, the script itself runs further (because Windows is a multi-tasking system).
The second possibility is the SYSTEM instruction. SYSTEM lets you execute rhine operating
system commands, under Windows, these are DOS commands. An example:
system dir >output.txt
Unlike the SHELL instruction, SYSTEM waits with the script execution until the called
program is finished.
The third possibilty is the CALL instruction. CALL runs a program and waits with the
script execution until the called process terminates. This is often required if one
program needs to be aborted first before the next operation can be done. An example:
echo Running editor...
call [windir] # '\NOTEPAD.EXE'
echo Ready! Now we can continue...
end
To create, change and remove directories, RapidBATCH provides you the instructions
MKDIR, CHDIR and RMDIR. They always expect only one parameter, the directory that
should be created, changed or removed. The following sample creates, changes and removes
the directory C:\TEST:
mkdir 'c:\test'
chdir 'c:\test'
chdir '..'
rmdir 'c:\test'
end
If you want to open a file with an associated program, use the OPEN instruction. With
OPEN, you can also execute external programs or internet URLs. Examples:
open 'www.jmksf.com'
open 'hello.doc'
open 'test.exe'
To handle files, RapidBATCH 4 provides you many instructions and functions. These are the instructions NEWFILE, DELFILE, COPYFILE, RENAMEFILE, READFILE, WRITEFILE. NEWFILE creates, DELFILE removes a specified file. COPYFILE copies a source file into a target file, RENAMEFILE moves it. The function FILEEXISTS checks if the specified file exists or not, and the FINDFILES-function allows to read the content of a directory so you can handle on them. GETFILEATT and LETFILEATT allow to set file-attributes, such as hidden, archived or read-only.
Please take a look at the reference manual to get more informations and examples on these and several other instructions and functions for file operations.
To read and write files, RapidBATCH provides the READFILE-function and WRITEFILE-instruction.
The following example program is already a simple text editor that saves the user entered
text into the file TEST.TXT.
editbox [text] = 'Text Editor', '', '0'
if [text] ! ''
delfile 'test.txt'
writefile 'test.txt', [text]
echo 'File has been saved.'
endif
end
We delete the file before writing it by using the DELFILE instruction. The reason is that
WRITEFILE only extends a file's content by adding new data to the file's end, it does
not overwrite it. So if we delete the file before writing it, it is created again.
As you can see, WRITEFILE expects two parameters, the file name and the text that
should be written.
When we extend the script to only one single line, it allows the editing of already
written text and writes the new, changed text to the file again. This is really a tiny text editor, isn't it?
readfile [text] = 'test.txt', '0'
editbox [text] = 'Text Editor', [text], '0'
if [text] ! ''
delfile 'test.txt'
writefile 'test.txt', [text]
echo 'File has been saved.'
endif
end
Here, we read the whole file by assigning the line number 0 at the READFILE function.
0 means that READFILE should read the whole file. If you assign 1, the first line is read; if
you assign 2, the second line only is read. So this instructions allows you to read a
whole file or to read it line by line. The following script would only read the first
10 lines of the file TEST.TXT:
[count] = '1'
repeat
readfile [line] = 'test.txt': [count]
[text] = [text] # [new_line] # [line]
calcvar [count] = [count] + '1'
until [count] > '10'
echo [text]
end
Please note, that the return-variable specified at READFILE gets "EOF" (means: End Of File)
when the file end was reached or overstepped. That means, that you cannot read line 14
of a file that only consists of 5 lines. In such a case, [errorcode] gets the value -1
and can be verified.
Controlling programs by remote
Since RapidBATCH 4.1, you can also control any external programs remotely, sending keystrokes
to them by using the SENDKEYS instruction. This instruction lets you control other
applications by using a slightly complex looking but easily learnable command language
for sending keystrokes and key commands as they are fed from the computer's keyboard.
The following script demonstrates how to control the Windows editor "Notepad". It runs
Notepad and prints the text "Hello World" into the edit window. Then it saves the file
as TEST.TXT and aborts Notepad. The code:
shell [windir] # '\notepad.exe', 'show'
sendkeys 'Untitled - Notepad': 'Hello World#272fs#018test.txt~r#272~4#018'
end
SENDKEYS expects the title of the window as first parameter. This identifies the window
where they keystrokes should be sent to. Then the keystrokes themself are specified,
using a simple macro language.
The whole thing looks very complex on first view, but it isn't that difficult when you
find out the sense and logic that is used. You must "teach" your script how it needs to
"press" the keys in the application to get the desired result.
Let's go trough the above example keystrokes step-by-step:
| Section: |
A |
B |
C |
D |
| Commands: |
Hello World |
#272fs#018 |
test.txt~r |
#272~4#018 |
- Section A:
Here, we just write the text "Hello World" in the text window. You must check on
the input focus, making sure it is in the right position. In Notepad this is not
big problem, because the edit field has the focus automatically at the programs start.
- Section B:
Now, we want to open the dialog to save the file. For this case, we need to press ALT and F
at the same time. Here, we use the so called "keycodes". They begin with a hash (#) followed
by a triple-digit number, which represents the code. The ALT key has the keycode 018, but
because we need a held ALT key we add 254 to the keycode and this results in 272 as
the final keycode for a held ALT key. Following this, we send an "f" to open the file menu
from the menu bar and an "s" to open the "Save" dialog. Now, after we opened the "Save as..."
dialog, we release the ALT key again by sending the keycode 018 and pressing it shortly
(then it's left). Which key needs to be pressed in a menu for the shortcut can be seen
on the underlined letter, e.g. in the File menu of Notepad the "f".
You only need to specify keycodes for special characters; Standard letters can be directly
specified, like the "Hello World" above (you can also use keycodes to print "Hello World"
if you want to ;)).
- Section C:
Here, we "type" the desired filename "test.txt" in the appearing "Save as..." dialog
of the Notepad editor. The ~r means "Return", so we confirm the dialog. This, with a
tilde beginning key, are often used special keys and are called "Hotkeys", e.g. return,
tab, F1...F12 or the arrow keys.
- Section D:
Finally we "type" ALT (held) followed by F4 to terminate the application. ~4 means F4
(all F-keys are numbered in hexadecimal order F1 until FC (F1...F12)).
This combination terminates Notepad, and we release ALT again.
Surely you cannot memorize all these many keycodes, and additionally you sometimes
need to calculate them until you get the right result. A list of all possible keycodes
can be viewed in the file KEYCODES.TXT in the \DOC-directory of your RapidBATCH setup-directory.
The variable [errorcode]
RapidBATCH provides some pre-declared variables, e.g. [current] that includes the current
directory or [command] that includes the command-line parameters which had been assigned
to the script. One of the most important of these pre-declared variables for RapidBATCH scirpting is the [errorcode]-variable. Many instructions, e.g. MSGBOX, SHELL,
SYSTEM, CHDIR and several other ones return values to this variable, so you can find out e.g. at MSGBOX which button has been pressed or at CHDIR, SHELL or FILEEXISTS if the operation succeeded or not. The programming language reference contains information about each instruction and the values [errorcode] can receive from them. Here's a simple example:
call 'C:\WINDOWS\CALC.EXE', 'show'
echo 'Return value of CALC.EXE is ' # [errorcode]
end
Debugging scripts
When developing software, you'll often have the problem that your program does not work as it should. For this case, the Professional Edition (not included in the free Standard Edition) of RapidBATCH provides you a build-in debugging tool, a so called "debugger", that allows script execution in step-by-step or trace mode and lets you view and change the contents of variables.
The debugger can be used by two ways: Once by activating it in RapidBATCH Builder, or by using the special debugger control commands that where introduced with RapidBATCH v4.3.
Fig. 8: Activating the debugger in RapidBATCH Builder
In RapidBATCH Builder's debug-properties dialog (access this over the "Script"-menu), you can set up a debug session very easily.
To switch the general debug features on, check the checkbox "Debug script" on the top. In the "Debug mode" section, you can choose one of the two debug modes. "Step" is the step-by-step mode, that means you can step through each instruction of your script that should be executed, "Trace" is the trace-mode. If you debug your script in trace-mode, you can watch variable contents and change them, but the script is executed as when it's run without debugger (only the debug dialog containing the watch-variables will appear). Please note, that you can also switch between both debug modes at run-time.
The second section, "Variable watch & trace" lets you set the variables you want to monitor when debugging. "None" means, that no variables will be added to the watch, "Automatic" will automatically add all new declared variables to the variable watch. The third option, "Manual", adds only the variables you specified in the text field below to the variable watch.
If you set up the desired features, you can run the script and use the debugger.
Fig. 9: Debugging a script
When debugging a script, the debug-dialog will always appear in the upper-left corner of your screen. The listbox in the dialog contains the variables you are monitoring. To change a value of a monitored variable, select the variable you want to change from the list and edit or modify the desired value into the edit-field on the bottom (in from of the "Set"-button). When finished, hit the "Set"-button and the variable gets its new value.
Below the variable list, the next code-line that should be executed is displayed. To step to the next instruction and execute this line, hit the "Step"-button. You will see, the current line is executed and the next line of code will be displayed. Please note, when executing the code for a dialog (e.g. ECHO) in step-mode, you first need to confirm this dialog before you can continue with the next step.
To switch from step to trace-mode, hit the "Trace"-button next to the "Step"-button in the dialog.
Now, you surely know how to step and trace through your scripts. When clicking the "Halt"-button, the script is immediatelly aborted.
As mentioned above, there is still another possibility to debug you scripts: The debugger control instructions. The new interpreter version provided with RapidBATCH v4.3 and higher provides you in the Professional Edition two of these special instructions, that are called DEBUGMODE and DEBUGVARS. These debugger control instructions are only provided in the interpreter; The compiler ignores them. DEBUGMODE lets you set a debug mode at run-time, which can be step, trace or none. As parameter, this instruction expects one of these modes (step, trace, none).
An example:
debugmode step
[a] = 'Hello World'
[a] = [a] # ' by RapidBATCH'
debugmode none
echo [a]
end
In this example, you can step through the first two assignments until you step over the line "debugmode none". Behind this line, the script will be executed further without debugger.
To add new variables at run-time, use the DEBUGVARS-instruction. This insturction expects a list of variables to monitor or, instead of a list, the value "auto" or "none" (the option "auto" means monitor new variables automatically, "none" switches it off).
debugvars [a], [b]
rem In this case, the above line is same as "debugvars auto"
rem because we use only two variables, [a] and [b] in this script.
debugmode step
[a] = 'Hello World'
[b] = [a] # ' by RapidBATCH'
debugmode none
echo [a] # [new_line] # [b]
end
That's it! Have much fun & success on RapidBATCH scripting :)...
Many thanks to Roy Scott for reviewing the programming guide :) ...
<<< Back
Next >>>
|
