=================================================
Feature Tip
=================================================
Title: LotusScript 101 - Custom Functions: The most powerful feature
most developers never use
This tip was submitted by Kevin Ford, our searchDomino.com expert and
a Lotus Notes architect and developer at IBM in Poughkeepsie, N.Y. If
you have a specific application topic that you'd like Kevin to cover
or comments about a tip, email us at editor@searchdomino.com, or pose
an application question to Kevin in Ask the Experts section:
http://searchdomino.techtarget.com/ateQuestion/0,289624,sid4_tax282449,00.html
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:
-----------------------------------------
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"
previous page
|