Starting Guide
Error Management
How can we prevent error messages from being displayed to clients?
An Error is not something bad. It is a hint that shows where the right direction is.
What occurs when an error arises?
There's a high probability that you're using this program for software distribution or in other production environments.
In such scenarios, you wouldn't want error messages to be displayed.
The first tool you need for error handling is the command:
USM.[number]
In our subsequent tests, we'll utilize the following script and simply alter the parameters of the USM. command to observe the outcomes.
Here's the test script for reference:
'***********************************
' USM.-Demo
'***********************************
'
USM.32
STW.tw|Nix|0
MBX.Ready
ENR.
'-----------------------------------------------------------
:on_Error
: $$ERF=?path\MR_Error.log
IEF.$$ERF
COP.$$ERF|?cdesktop\MR_Error.log
EIF.
MBX. AN error happened!
ENR.
'-----------------------------------------------------------
Manual Error handling starts with
USM.32
This is the default setting if you don't include the USM. command in your script.
When you use USM.32, you'll get a response similar to the one shown in the image below in the event of an error.
Depending on whether you select "Retry" or "Cancel", the script will perform different actions each time.
If you select "RETRY", the script will internally treat the line where the error occurred as a comment, and it will continue executing from the next line as if no error had occurred.
As a result, you'll see the Messagebox from the normal script termination, as shown in the image below.
If you pressed "CANCEL", which is the recommended selection, the script will go into "Error-Mode" and do one of two things.
1. If there is no Label :on_Error present in your actual script, the script will end immediately.
2. If there is a Label :on_Error present in your actual script, the script will just continue running at that label.
If the error happens in the section of the Label :on_Error then the script will not jump to this Label again, of course.
Lets take a look on this special Label. You can see how it really looks in the picture below.
One important thing is that you have a regular script end before the Label :on_Error.
You can use the END. or the ENR. statement for this. If you fail ending your script before that Label, then the script will anyway run into that code that comes after the :On_Error Label. Even if there was no error. And this is in most cases not useful.
:on_Error is a special Label. Its not a Label like any other!
If :on_Error is there, the script will jump there after an error and continue script execution there. :on_Error does NOT prevent error messages, For this you have to use the USM.-command.
InstaRec makes your scripts in a way that you can find the source of Errors.
Assume an error happened. The script runs into the :on_Error subprogram.
Now the next thing that happens is the SRV. - command. SRV -> Set Return Value.
SRV. will set the Exit code for your compiled script. The Exit- or Return-code is likely the code that is shown in the Management console of your software distribution program.
Now the Full line is:
SRV.$$PRO
Hint: While the actual Robot program is the "MR01.exe", the executable that you have compiled is another program. If you just call the "MR01.exe" manually, use SEC. to set the "Return Error-Level". In all other cases SRV. will work fine.
$PRO is a variable. This means that it is replaced with a value at runtime. For more info on variables see here:
2.3 Variables, global and local
Then, what value has $$PRO at this time?
To understand this, let's take a look on a real recoding and see what $$PRO is.
This is an shortened example code, that InstaRec provides.
VAR.$$PRO=10002
STW.HBJwct|45|MsiDialogCloseClass|7-Zip 4.57 (x64 edition) Setup
SCW.wctid|45|SysTreeView32|Tree of selections|169|1
WII.30
SFW.
SMH.Will be installed on local hard drive
TVI.*will be unavailable|i
WII.30
In the First Line of each block is the secret:
VAR.$$PRO=10002
This Line will set the Variable $$PRO to the value of 10002. We call this value the "blocknumber". Because each block of recorded code will have such a number.
If an error happens in this block, then $$PRO will give you a return code of 10002.
Why do we use 10002 and not just 2 ?
The reason is that the normal DOS Error Messages are in that range. Using Block number plus 10000, we are in a range that is free. Therefore if your software distribution tool shows you a return code of 10000+, then you know there has been a problem with a robot-script.
What do we get if there was no error?
In that case, the script will just run into the SRV.0 at the end of the script.
And we get a return code of zero. Which says that no error happend and all was Ok.
The combination of
SRV.0
END.
can be shortened to
END.0
from this version. End will internally just do the same, if it gets an Parameter.
Now how can we get rid of the messagebox with the error?
In case you distribute automated installations to clients, you may not want that error-messages appear on the clients desktop. Instead you want to have them in a log-file.
You can do this using the USM.10 command.
The USM.10 is an simpe addition of an USM.8 and a USM.2.
It will do two things:
1. USM.8 will redirect all Output from Messageboxes into the console-window.
2. USM. 2 will redirect all console-window output to a file
And how do we get the real error-message?
This way we will get all Error-Messages into a log-file. This log file is by default at two possible places.
1. If you run the script from the editor, the log-file is in your "Project folder".
That is, where the script itself is located.
2. If the robot runs without an Editor, the log-file is on the ?cdesktop\ .
You can however specify any other place for this error-log file and override the default settings, if you add a second parameter to the USM.-command. Like this:
USM.10|?pfad\My_Error.txt
There are more less often used options for your error-handling
While having the script run without visible errors, and getting the error into an log-file at the place of your choice is all you will need in most cases. There are more choices.
Most of them just for special cases. The USM.-command with the "0" as parameter, will prevent the robot from showing any error-messages. The script will just immediately end.
However this will not help us in most cases. We will therefore look at better combinations.
USM.4
1. will ignore any error,
2. comment that line
3. and continue running the script as if nothing had happened.
Be careful with this option. If you add more options, the "4" will anyway prevent the :on_Error Label from being called, and also prevent the script from being ended.
USM.16
is another Option. USM.16 will show up a Messagebox that will stay for less than a minute an then automatically be closed. After this, the script will continue running at the :on_Error Label, or just end if no such Label was found in the actual script.
USM.8
will redirect all Messages to the console-output.
USM.2
will redirect all Concole-Output to the a file. Note that this will redirect all console Output to the Error-Log-File.
USM.1
will just make a Message-Beep if an error occurs. It will not do anything else.It makes only sense, if you add the 1 to other options. For example, you can use USM.11 which is 10+1.
USM.64
If an error happens, after the script already jumped to the :on_Error Label, this Error will not jump to the :on_Error Label again. Therefore after a Jump to the :on_Error Label, a internal flag is set, that prevents the robot from jumping there again. This is to prevent a endless-loop.
The USM.64 will clear that internal flag. After it was called, the script will jump to the :on_Error Label, even if the error appeared after :on_Error Label was already been used.