Error handling

·	Basic syntax check

·	[Machines] section pre-scan

·	When an error occurs in a script

·

BatchSettings.IgnoreErrors setting - ignore all command errors and continue with the script

·

$i pre-command switch - ignore errors on a single line

·

Use %LastErrorCode% to check if the previous command succeeded or not

·

[OnError] section - execute commands when an error occurs

·

$c pre-command switch - call a subsection before a command is executed (in order to avoid problem with dynamic variables containing undefined values when script resumed)

---

Basic syntax check

Before the actual script starts, SetupBatcher checks the command syntax of the whole script. If SetupBatcher finds an error during this process, you will be prompted to edit the script. If everything is OK, the phrase "Basic syntax check OK." will be written to the log window.

[Machines] section pre-scan

Linux and Novell notice: the [Machines] section is not used in Linux or Novell server scripts.

If the basic syntax check is OK, SetupBatcher will look for a [Machines] section in the script; if present the [Machines] section pre-scan will start. Now SetupBatcher will try to contact all listed machines. If there are unreachable machines, a prompt with number of bad machines etc. is displayed. Unreachable machines are marked with an error code and ignored by SetupBatcher during the script. It is possible to rerun the batch job on unreachable machines later when they are back up on the net.

It is possible to disable [Machines] pre-scan with the BatchSettings.CheckMachines setting.

When an error occurs in a script

1) The error message from the command is written to the log window



2) Then the script stops and an abort / retry / ignore / support dialog is displayed

·	Abort - stop the script - continue with step 3 below

·	Retry - retry the command

·	Ignore - ignore the error and continue with the next command

·	Support - automatically creates support email template that contains program version, script and error log

3) An error marker is written to the script, learn more about markers here




4) The script line where the error occurred is highlighted




5) The error variables %LastErrorCode%, %LastErrorMsg% and %LastErrorCommand% are set.

BatchSettings.IgnoreErrors setting - ignore all command errors and continue with the script

Set BatchSettings.IgnoreErrors to make the script continue even if there are errors. Notice that this setting prevents the [OnError] section from running.

$i pre-command switch - ignore errors on a single line

Insert "$i" before a command to automatically ignore errors on that one line - a warning will be written to the log window but the batch job will not stop. Example: "$i DOS md mydir" will not stop the batch even if the directory "mydir" already exists. Notice that this switch prevents the [OnError] section from running.

Use %LastErrorCode% to check if the previous command succeeded or not

Example

$i command xxx
if %LastErrorCode%<>0 THEN
 xxx
ENDIF

A successful command can not clear the %LastErrorCode% set by an error in a previous command, the %LastErrorCode% can only be cleared by a LastError.Clear command.

Example

$i command1
if %LastErrorCode%<>0 THEN
 LastError.Clear
 DOS net send administrator error1
ENDIF
$i command2
if %LastErrorCode%<>0 THEN
 DOS net send administrator error2
ENDIF

Without the LastError.Clear command the administrator would get both an "error1" and an "error2" message when an error occurs in command1.

[OnError] section - execute commands when an error occurs

If present, the [OnError] section of the script is executed when an error occurs. This section is useful when you want to handle errors yourself - for instance when scripts are executed automatically from the schedule services, or if you want to leave the computer while big batch jobs run and have SetupBatcher to notify you if there are errors.

The [OnError] section does not run when the BatchSettings.IgnoreErrors setting is present or for errors on commands preceded with the $i switch.

Tip: To prevent SetupBatcher from displaying errors in GUI mode, use the BatchSettings.ErrorDialogDisable setting.

Example - net send popup

[OnError_Batch_Begin]
DOS net send administrator SetupBatcher Error - %LastErrorCommand% - %LastErrorMsg%
[OnError_Batch_End]



Example - error log file

[OnError_Batch_Begin]
DOS echo %date% %time% %LastErrorCommand% - %LastErrorMsg% >>"%StartDir%\error.txt"
[OnError_Batch_End]



Example - email with blat

[OnError_Batch_Begin]
DOS echo %LastErrorCommand% - %LastErrorMsg% >"%StartDir%\error.txt"
DOS %BlatPath%\blat.exe "%StartDir%\error.txt" -t test@mymail43.com -server mail.mymail43.com -f test@mymail43.com -s "%LocalName% SetupBatcher Error"
[OnError_Batch_End]

Example - write to event log

[OnError_Batch_Begin]
EventLog.Write Error, 770, SetupBatcher Error - %LastErrorCommand% - %LastErrorMsg%
[OnError_Batch_End]



$c pre-command switch - call a subsection before a command is executed

If a script is stopped and then resumed at a position between initialization of a dynamic variable and a command referring to the variable, the dynamic variable will contain an undefined value when the command needs it.

The solution to this problem is to put dynamic variable validation and initialization code in user defined subsections that are called with the "$c" switch every time before commands that uses dynamic variables are executed.

For subsection syntax, see GoSub. Unlike GoSub, subsections called with the "$c" switch does not contain any markers - all commands in the called section are always executed. To avoid confusion, do not call the same subsection from both GoSub and "$c".

Example 1 - script that reproduces the problem with undefined value

[Settings_Begin]
BatchSettings.Delimiter=TAB
BatchSettings.MarkerCol=1
[Settings_End]

[Batch_Begin]
SET CurrentDate=%date%   
MessageBox %CurrentDate%   
RaiseError 1, Simulated error!   
MessageBox %CurrentDate%   
[Batch_End]

Run the above script. It will first show a message dialog with current date, then the error dialog "Simulated error!" with "Abort", "Retry" and "Ignore" buttons, click "Abort".

Then start the script again without removing the markers, it will continue where the last error occurred with the "RaiseError" command. Now, in the error dialog "Simulated error!", click "Ignore". The second "MessageBox %CurrentDate%" line is executed and the dialog will read "Empty variable". This is because the script was resumed after the initialization of "%CurrentDate%".

Example 2 - script with solution

[Settings_Begin]
BatchSettings.Delimiter=TAB
BatchSettings.MarkerCol=1
[Settings_End]

[Sub_GetDate_Begin]
If %CurrentDate%= Then   
 MessageBox GetDate   
 SET CurrentDate=%date%   
EndIf   
[Sub_GetDate_End]

[Batch_Begin]
$c GetDate MessageBox %CurrentDate%   
RaiseError 1, A simulated error!   
$c GetDate MessageBox %CurrentDate%   
[Batch_End]

Run the above script and do exactly as in example 1, now the second "MessageBox %CurrentDate%" line will display current date. Notice that "%CurrentDate%" only is initialized when needed.

But why not use the below code instead?

SET CurrentDate=%date%   
MessageBox %CurrentDate%   
RaiseError 1, Simulated error!
SET CurrentDate=%date%
MessageBox %CurrentDate%   

Well, firstly, "only initialized when needed" is a key phrase; in the example with the current date it would not make a difference, but consider initializing a variable with a value from a remote directory server, then each read would generate unnecessary network traffic and slow down the script considerably.

Secondly, suppose that the error occurs on the actual line referring to the variable, then the preceding "SET" line would not be executed when script was resumed anyway - "$c" is always executed right before the command.