LotusScript 101 - Custom Functions

I see a lot of Notes/Domino developers that use LotusScript but don't understand or use customized Functions. This is a real shame, because it is one of the most powerful tools that we have when writing modular code. It is, in fact, required to define modular code. Instead of declaring global variables and calling SubRoutines to modify these variables, create a function that you can pass a value to and will return a value when it is done doing what it is supposed to.

Here's the format for the custom function... (I am only going to talk about the simplest implementation.)

Function FunctionName( Parameters ) as ReturnType
Statements
Statements
End Function

At any time during a function, you can make the function return a value by simply treating the FunctionName like a variable. For example, the statement in parenthesis (FunctionName = "Red") will make the function return the value "Red" to the Call statement that called the function in the first place.

For the purpose of this example, My hypothetical function will prorate a salary over two time periods with two pay rates. It will accept three variables; CurrentPayRate, NewPayRate, IncreaseMonth. It will return the prorated salary. Obviously, you could do a lot more sophisticated calculations, but this should get the point across.

BELOW IS THE CODE FOR THE FUNCTION ITSELF

Code

Function Prorate( CurrentPayRate As Double, NewPayRate As Double, IncreaseMonth As Integer ) As Double
	'---- BEGIN simple error checking (Return 0 by using "Prorate = 0"
	If Not Isnumeric(CurrentPayRate) Or Not Isnumeric(NewPayRate) Or Not Isnumeric(IncreaseMonth) Then
		Msgbox "You must supply a number for each field", 0, "Invalid Values"
		Prorate = 0
		Exit Function
	Elseif CurrentPayRate = 0 Or NewPayRate = 0 Or IncreaseMonth = 0 Then
		Msgbox "You must supply a number for each field", 0, "Invalid Values"
		Prorate = 0
		Exit Function
	End If
	'---- END simple error checking
	'---- BEGIN Calculations on variables that were passed to function ----
	CurrentMonthlyRate = (CurrentPayRate / 12)
	NewMonthlyRate = (NewPayRate / 12)
	CurrentDollars = (CurrentMonthlyRate * (IncreaseMonth-1) )
	NewDollars = ( NewMonthlyRate * (12 - (IncreaseMonth-1) ) )
	'---- END Calculations on variables that were passed to function ----
	Prorate = (CurrentDollars + NewDollars)
End Function


BELOW IS THE CODE FOR THE STATEMENTS THAT CALL THE FUNCTION
-----------------------------------------------------------
Sub Click(Source As Button)
	Set workspace = New NotesUIWorkspace	
	Set uidoc = workspace.CurrentDocument
	
	currentPayRate = Cdbl(uidoc.FieldGetText("currentPayRate"))
	newPayRate = Cdbl(uidoc.FieldGetText("newPayRate"))
	increaseMonth = Cint(uidoc.FieldGetText("increaseMonth"))
	
	NewSalary = ProRate( currentPayRate, newPayRate, increaseMonth )
	If NewSalary > 0 Then
		Msgbox Cstr( NewSalary )
	End If
End Sub

For the above example, I created a form with three fields (named in Click event above). I then created a button marked ProRate. From any LotusScript editing pane for the button, simply typing the word "function functionName" (without quotes) and pressing enter will create a new event in that object and you can begin working immediately. After creating the function as above, I simply modified the click event of the button to call the ProRate function with the proper parameters (Data Types are of course critical). I declared all of my variables in the Global Declarations not as a matter of good practice but just to keep the code smaller for this example.

Using a function for a single use as in the button example is not very effective, but if you can do it, you can start creating your own functions that you can call iteratively and save yourself a lot of time in future programming. It would also allow you to create much more compact code.

An example might be to pass a back-end NotesDocument object to a function that validates and returns a boolean value of whether or not the document passed the test. Roughly, it would look like this... Function ValidateDoc( doc_in_question as NotesDocument ) As Integer

	ValidateDoc = 0
	if doc_in_question is nothing then
		Exit Function
	End If
	If not doc_in_question.HasItem("ImportantFieldName") then
		Exit Function
	End If
	'---- My two criteria passed, so I assume success and set to 1 then return
	ValidateDoc = 1
End Function

It would be called from any line of LotusScript like this.

if ValidateDoc( MyDoc ) = False then
	MsgBox "It Failed"
Else
	MsgBox "It Worked"
End If