WinBatch Tech Support Home

Database Search

If you can't find the information using the categories below, post a question over in our WinBatch Tech Support Forum.

TechHome

UDF - UDS Library
plus
plus
plus
plus
plus
plus
plus
plus
plus
plus
plus
plus
plus
plus
plus
plus
plus
plus
plus
plus
plus
plus
plus

Can't find the information you are looking for here? Then leave a message over on our WinBatch Tech Support Forum.

!! UDFs Explained !!

 Keywords: UDF UDS User Defined Functions and Subroutines  

User Defined Functions and Subroutines

WIL support's user-defined functions (UDF's). There are two types of User Defined Functions (UDF's):

	#DefineFunction UDF's, variables are local to the UDF	

	#DefineSubroutine UDF's, variables are global, to the caller.
	

User Defined Function

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 (ie, 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 (ie, 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:

	; 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: Call, Return


User Defined Subroutine

A #DefineSubroutine UDF is defined as follows:
	#DefineSubRoutine functname(param1, param2, param3, param4,…param16)  
	<code>  
	Return retval
	#EndSubRoutine
	
The #DefineSubroutine UDF is similar, in most respects, to the #DefineFunction UDF, 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.

WARNING: Use at your own risk. The variables used within the #DefineSubroutine 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. The Drop and DropWild functions, can be used to dispose of any unwanted variables at the end of the routine.

Example:

	#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
	


UDF/ UDS Special Notes