Trap Errors

 Keywords:  Trap Errors Error Trapping Capture WBERRORHANDLER Error Handling ErrorMode @OFF Intcontrol 73 Try Catch throw

How to Trap Errors

There are two major methods to trap errors. The more powerful method is to use IntControl 73 to set an error handler to capture all types of errors. Where as, the older ErrorMode can only be used to capture minor errors.

If you simply want to supress all displayed errors then you might want to use IntControl 38. IntControl 38 can tell the script to exit quietly upon error.

Using IntControl 73

This IntControl lets you specify what should happen when the next error occurs in the script.

P1   Meaning
-1   Don't change (just return current setting)
 0   Normal error processing (default)
 1   Goto the label :WBERRORHANDLER
 2   Gosub the label :WBERRORHANDLER
 3   Call the UDF specified by p3

This is a one-time flag, which gets reset to 0 (default) when an error occurs.

When processing goes to :WBERRORHANDLER, the following WIL variables are automatically set:

Variable                  Type     Meaning
wberrorhandlerline        string   Error line (ie, line in script that caused Error)
wberrorhandleroffset      integer  Offset into script of error line, in bytes
wberrorhandlerassignment  string   Variable being assigned on error line, or "" if none
wberrorhandlerfile        string   Name of the currently-executing script
wberrortextstring         string   Description of the WIL error
wberroradditionalinfo     string   Additional error information, if any
wberrorinsegment          string   name of the currently-executing UDF, or a blank string ("") if not in a UDF.
wberrorarray              array    WIL array with the following elements:
                                   wberrorarray[0] = LastError()
                                   wberrorarray[1] = wberrorhandlerline
                                   wberrorarray[2] = wberrorhandleroffset
                                   wberrorarray[3] = wberrorhandlerassignment
                                   wberrorarray[4] = wberrorhandlerfile
                                   wberrorarray[5] = wberrortextstring
                                   wberrorarray[6] = wberroradditionalinfo
                                   wberrorarray[7] = wberrorinsegment
                                   wberrorarray[8] = wberrorhandlerlinenumber
                                   wberrorarray[9] = line number in the UDF where the error occurred or 0.
                                   wberrorarray[10] = a positive number if reported line numbers are accurate, zero (0) 
                                                      if possibly inaccurate or -1 if run from WinBatch Studio, in which 
                                                      case both wberrorarray[8] and wberrorarray[9] will contain the line 
                                                      number of the error in the UDF.
                                   wberrorarray[11] = used to set return value of the function the error occurred on.

Note: The :WBERRORHANDLER label must be in the same script where the error occurred.  If an 
error occurs in a called script, it will go to the label in the called script, not the calling 
script.

The syntax for Incontrol 73 is IntControl(73, p1, p2, p3, 0). The value specified by P1 determines how exactly the errors will be handled.

If P1 = 1 then when the next error occurs the script will GOTO to the label :WBERRORHANDLER. This is generally used to capture an error, do something, then exit the script.

IntControl(73,1,0,0,0)
badline=Message(aaaa,bbb)
Exit

:WBERRORHANDLER
lasterr = wberrorarray[0]
handlerline = wberrorarray[1]
textstring = wberrorarray[5]
linenumber = wberrorarray[8]
errstr = StrCat("Number: ",lasterr,@LF,"String: ",textstring,@LF,"Line (",linenumber,"): '",handlerline,"'")
Message("Error Information",errstr)
Exit

If P1 = 2 then when the next error occurs the script will GOSUB to the label :WBERRORHANDLER. This is generally used to capture an error, do something, then continue processing the script.

IntControl(73,2,0,0,0)
badline=Message(aaaa,bbb)
Exit

:WBERRORHANDLER
lasterr = wberrorarray[0]
handlerline = wberrorarray[1]
textstring = wberrorarray[5]
linenumber = wberrorarray[8]
errstr = StrCat("Number: ",lasterr,@LF,"String: ",textstring,@LF,"Line (",linenumber,"): '",handlerline,"'")
Message("Error Information",errstr)
IntControl(73,2,0,0,0)
Return

If P1 = 3 then when the next error occurs the script will call a User Defined Function. This is also generally used to capture an error, do something, then continue processing the script.

P3 should be the name of the error handling UDF. The error handler UDF must be defined to accept exactly one parameter. The parameter it receives will be the "wberrorarray" array. None of the other WIL variables will be automatically set.

By default, the error handler mode is reset to 0 when the UDF returns. If the UDF returns 1, the handler mode will not be reset. If the error handler UDF is invoked during a variable assignment statement (eg, "variable = function()"), and you set wberrorarray[11] to a specific value inside the handler UDF, that value will be assigned to the variable (x). Note that this does not work for a property assignment. By default, the value assigned when an error occurs is 0.

#DefineSubRoutine OnNextError(Err_Array)
   lasterr = wberrorarray[0]
   handlerline = wberrorarray[1]
   textstring = wberrorarray[5]
   linenumber = wberrorarray[8]
   errstr = StrCat("Number: ",lasterr,@LF,"String: ",textstring,@LF,"Line (",linenumber,"): '",handlerline,"'")
   Message("Error Information",errstr)
   Return(1);Re-arm error handler
#EndSubRoutine

IntControl(73,3,0,"OnNextError",0)
badline=Message(aaaa,bbb)
Exit

Using ErrorMode

Another option is to use the ErrorMode function to capture all 1000 level errors returned by Winbatch. Note: 2000 (moderate) and 3000 (fatal) level errors will require user intervention.

You should only use ErrorMode to capture a specific error of a specific function. If you want to trap an error, then just before you execute the command, turn error mode off. Execute the function then turn error mode back on, then immediately after use the Lasterror function to trap the error, as in the following example:

Example:

ErrorMode(@OFF)
DirChange("C:\temp")
FileDelete("*.*")

*IMPORTANT*
Don't even consider using ErrorMode without a full understanding of it use. Improper use of Errormode can make a 5 minute debugging project last 6 weeks. WinBatch Two Minute Lecture on ErrorMode Use

WinBatch was initially designed to run fully debugged scripts, under the theory that the programmer would be in front of the computer during the debugging process. If the undebugged scripts are submitted to a remote computer for execution on the remote computer, the error messages will come up on the remote computer.

The 1000 level errors (the trappable ones) deal with situations the programs can encounter on the machines they are running on (network connection down, file does not exist, etc) Whileas the 2000-3000 level errors tend to be ones that are real errors in the script itself - unrecognised functions, bad syntax, etc.

The most famous case of bad use of error mode was this script, placed in the windows directory for easy access.

ErrorMode(@OFF)
   DirChange("C:\temp")
   FileDelete("*.*")

The idea being that the user would occasionally run the script to clear all files out of his temp directory. A year later, because of space considerations he moved the temp directory to D:\TEMP. Then later ran the script without modification. The DirChange error was suppressed, the directory was not changed, and the FileDelete proceeded to delete a number of files from the Windows directory.

In summary, if you really want to handle errors for the entire script, we recommend using the Intcontrol 73 function. If you only want to minor capture errors for a single function use ErrorMode only, to wrap that function call. For a list of the various error numbers, see the Window Interface Language help file or manual.

Getting Extended Error Information:

Most WIL errors are accompanied by 'extended error information'. Extended error information is written to the wwwbatch.ini file:

"C:\Documents and Settings\{username}\Application Data\WinBatch\Settings\wwwbatch.ini"

There is a section that contains additional diagnostic information that may give some clue as to what it is that failed. �

IntControl 73 returns this same information in the 'wberroradditionalinfo' variable.

Extended error information is most commonly in the form of a Windows system error. For a list of Windows system errors see Microsoft's website: Windows System Error Codes

Using IntControl 38

IntControl 38 allows you to tell the script to run in quiet mode.

In "quiet mode":

No error messages are displayed. If an error log filename is specified, then error messages will be written to that file.
You MUST set the "warning" parameter in any FileCopy or FileMove commands to @FALSE, or else a fatal error will occur.
Sounds that would normally be controlled by the Sounds function are suppressed.

Handling Errors in a Called Script:

The Call() function calls a WIL batch file as a subroutine. This function is used to pass control temporarily to a secondary WIL batch file. All variables are common (global) between the calling program and the called WIL batch file, so that the secondary WIL batch file may modify or create variables. The secondary WIL batch file should end with a Return statement, to pass control back to the main WIL program.

If you want to have error handling occur with in a Called script, then IntControl 73 must be defined with in the Called script. For Example:

Main Script

#DefineSubRoutine OnNextError(Err_Array)
   lasterr = wberrorarray[0]
   handlerline = wberrorarray[1]
   textstring = wberrorarray[5]
   linenumber = wberrorarray[8]
   errstr = StrCat("Number: ",lasterr,@LF,"String: ",textstring,@LF,"Line (",linenumber,"): '",handlerline,"'")
   Message("Error Information",errstr)
   Return(1);Re-arm error handler
#EndSubRoutine

IntControl(73,3,0,"OnNextError",0)

Call('b.wbt','')
Pause(0,0)
Exit

Called Script

; Call() - Calls a WIL batch file as a subroutine.
; If you want to have error handling occur with in a Called script, then IntControl 73 must be defined with in the Called script.
IntControl(73,3,0,"OnNextError",0)
badline=Message(aaaa,bbb)
Return

Article ID:   W17358

File Created: 2014:07:18:09:07:48

Last Updated: 2014:07:18:09:07:48

Database Search

TechHome