|
WIL support's user-defined procedures (UDP's).
There are three types of User Defined Procedures (UDP's):
#DefineFunction UDP's, variables are local to the UDF #DefineSubroutine UDP's, variables are global, to the caller. #DefineCommand UDP's, variables are global, to the caller (WinBatch Console only).
A #DefineFunction UDF is defined as follows:
#DefineFunction functname(param1, param2, param3, param4,…param16) <code> Return retval #EndFunction
"#DefineFunction" and "#EndFunction" are the keywords indicating the beginning and end of the UDF. "functname" is a placeholder for the name of the function. The function name must begin with a letter, can contain letters, numbers, and underscores, and can be up to 30 characters long. You may not use a function name that is the same as the name of a WIL DLL function, but you may override a function name that's in an extender DLL. You may specify up to 16 optional parameters. "param1" - "param16" are placeholders for your actual variable names. These are the names of the variables that your UDF will receive when it is called. Between the "#DefineFunction" and "#EndFunction" keywords is the code that will get executed when the UDF is called. It may contain a Return command followed by a value (or an expression that evaluates to a value), in which case the UDF will end and return this value. If you specify a Return command without a value, the UDF will return 0. If a UDF does not contain a Return command, it will execute to the end of the UDF and return 0. An Exit command in a UDF will cause the entire script to end, not just the UDF. A UDF may be defined anywhere in a script, as long as it is defined prior to being used for the first time. A UDF may be defined or used in a separate script that is called with the Call command, as long as it is defined before it is used. You may not have nested UDF definitions (i.e., each "#DefineFunction" must be followed by an "#EndFunction" as a pair). A #DefineFunction UDF will not have access to any variables in the main WIL script, other than the variables passed as param1 - param16. Any variables set in a UDF will be destroyed when the UDF returns, other than the return value of the UDF. Any percent signs in the UDF code will be expanded at runtime (when the code is called), not at define time. You may return a file handle or binary buffer or COM/OLE object from a UDF using the Return command. However, if you open one of these types of handles in your UDF and do not return it using the Return command, you are responsible for freeing it before the UDF returns (i.e., FileClose or BinaryFree or {object} = ""); otherwise, the object represented by the handle will become an "orphan" and will no longer be accessible and may not be automatically freed when the script exits. Example 1:
; Define three UDF's
#DefineFunction Done()
Message("All done", "Script processing is complete")
#EndFunction
#DefineFunction Square(number)
Return (number * number)
#EndFunction
#DefineFunction AddListItem(list, newitem, delimiter)
list = ItemInsert(newitem, -1, list, delimiter)
list = ItemSort(list, delimiter)
Return list
#EndFunction
; Now use them
list = "apples,bananas,peaches"
list = AddListItem(list, "cherries", ",")
Message("New list", list)
Message("The square of 5 is", Square(5))
Done()
Exit
See Also:
A #DefineSubroutine UDP is defined as follows:
#DefineSubRoutine functname(param1, param2, param3, param4,…param16) <code> Return retval #EndSubRoutine
The #DefineSubroutine UDP is similar, in most respects, to the #DefineFunction UDP, except that the variables are global to the calling routine. This means that it will be able to access and change variables in the calling routine, and any variables it sets will not be destroyed when it returns. Example 2:
#DefineSubRoutine LogErrors(loc_ErrNum)
lastlogtime = TimeYmdHms()
loc_fh = FileOpen("Errorlog.txt","APPEND")
loc_text = StrCat("Error",@TAB,loc_ErrNum,": ", Err%loc_ErrNum%,@TAB,"occured at",lastlogtime)
FileWrite(loc_fh, loc_text)
FileClose(loc_fh)
DropWild("loc_*")
Return lastlogtime
#EndSubRoutine
;Error String Constants
Err1008 = "FileCopy: Failed"
Err1009 = "FileCopy: FROM file open failed"
Err1010 = "FileCopy: TO file open failed"
Err1011 = "FileCopy: I/O error"
starttime = TimeYmdHms()
ErrorMode(@OFF)
ret = FileCopy("C:\zippideedodah.txt","C:\temp\zippideedodah.txt",@FALSE)
ErrorMode(@CANCEL)
errtime = LogErrors(LastError())
Message("Last error logged at",errtime)
Exit
(WinBatch Console only) A #DefineCommand UDP is defined as follows:
#DefineCommand functname param1 param2 param3 param4 …param16 <code> Return retval #EndCommand
The #DefineCommand UDP is similar to the #DefineSubroutine UDP because it has the same 'caller' scope as #DefineSubroutine . However, UDC's can only be called from WinBatch Console. Calls are ignored in scripts executed with regular WinBatch. The #DefineCommand syntax also differs because it does not need opening and closing parentheses and it uses spaces instead of comas as parameter separators. Also note that parameters can be any legal WIL expression but not WIL statements like a structured if, immediate if, any loop structures, an exit, or a goto.
Example 3:
See Also:WinBatch Console
WARNING: Use at your own risk. The variables used within the #DefineSubroutine or #DefineCommand have 'caller' scope, which means the Variables are shared with the calling routine. We suggest using a special naming convention on the variables inside the #DefineSubroutine or #DefineCommand. The Drop and DropWild functions, can be used to dispose of any unwanted variables at the end of the routine.
UDF/ UDS/ UDC Special Notes:
|
§ Step by step guide to learning WIL § Notes
|
