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
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
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