IntControl 72

Syntax:

IntControl(72, p1, p2, p3, 0)

Sets Cancel handler.

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

p1 Meaning

-1 Don't change (just return current setting)
0 Exit on cancel processing (i.e., the script exits)
1 Goto the label :CANCEL
2 Gosub the label :CANCEL
3 Call the UDF specified by p3

@TRUE or @ FALSE. Specifies whether any existing "wberroradditionalinfo" data should be cleared first. This is a one-time flag, which gets reset to 0 after the next error occurs.

Name of the cancel handling UDF enclosed in quotes. The cancel 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.

The return value of the cancel handling UDF has special meaning. The following values may be specified:

Value	Meaning
0	(default) UDF handling is canceled.
1	Continue handling cancel events with this UDF.
2	Treat this cancel event as unhandled, and do normal cancel processing
3	Treat this cancel event as unhandled, but continue handling cancel events with this UDF.

If the cancel 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 a cancel occurs is 0.

By default, if you don't use this IntControl at all, then every time a Cancel event occurs, WIL does a "Goto Cancel".

The first time you use this IntControl, the behavior changes to being a one-time flag, which gets reset to 0 after the next Cancel event occurs.

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

Variable	Type	Meaning
wberrorhandlerline	(s)	Cancel line (i.e., line in script that caused Cancel)
wberrorhandleroffset	(i)	offset into script of Cancel line, in bytes
wberrorhandlerassignment	(s)	variable being assigned on Cancel line, or "" if none
wberrorhandlerfile	(s)	name of the currently-executing script
wberrortextstring	(s)	description of the WIL error
wberroradditionalinfo	(s)	delimited string of additional error information, if any. ASCII 160 is delimiter character between each error incident.
wberrorinsegment	(s)	name of the currently-executing UDF, or a blank string ("") if not in a UDF.
wberrorhandlerlinenumber	(i)	line number in the currently executing script or 0 if the cancel cannot be matched to a particular line.
wberrorarray	(a)	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 cancel 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 cancel in the UDF. wberrorarray[11] = Used only with cancel handler UDF method to set return value of the function the cancel occurred on.

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

If you want to have cancel handling in a User Defined Function/UserDefined Subroutine, then IntControl 72 must either:

Be defined within the User Defined Function/User Defined Subroutine. The :CANCEL label must also be contained within the User Defined Function/User Defined Subroutine.
Or p1 must be the value of 3 and p3 must specify the name of the cancel handler UDF.

Returns previous setting, or -1 if the setting had not previously been changed from the default behavior.