There are self paced exercises to test the skills learned. To complete the exercises, there is a database attached with the default form to use as well as a completed form with working LotusScript code.

Back to Table of Contents

User Defined Functions and Subroutines

Overview: Functions and Subroutines
Breaking up program code into discrete blocks of reusable code, or subprograms, is a basic principle of structured programming. A subprogram can be used many times in the same program. Thereby saving development time.

LotusScript allows you to define two types of subprograms:

Functions and subs are defined for use with scriptable Notes objects such as a forms, fields, or buttons.

Back to Table of Contents


Entering Subs and Functions in the Design Pane
User defined subs and functions appear as events within the design pane. To enter a sub or function, do the following:

1. Access the design pane.

2. Select an object in the Define menu for which you can write a script, for example a button.

3. Click the Script radio button and select an event from the event menu, such as Click.

4. Enter the function or sub statement in the programmer's pane.

5. When the statement is complete, the function or sub name appears in the Event menu.

Back to Table of Contents

Functions
A function is a subprogram that accepts input and returns a value to the program that calls it. Once a function is created, it can be invoked anytime within the program.

Functions can be used to perform tasks such as:

The Function Statement
The Function statement in LotusScript defines a function.

Syntax
Function functionName[(argumentList)] As dataType

[statements]

End Function

Elements
Click to review a table that describes the elements used in the Function statement.

Usage
To return a value from a function, assign a value to functionName within the body of the function definition. Refer to the example below.

To use the value returned by a function, put the function call anywhere in an expression where a value of the data type returned by the function is legal. Refer to Calling a Function.

Example
In the following example, a function named netPay is defined. The function takes two arguments taxRate and grossPay. It calculates net pay and returns that value as the currency data type.

Function netPay(taxRate As Single, gross As Single) As Currency

netPay=gross-(gross*taxRate)

End Function

Alternatively, you could ask for the values within the function itself:

Function netPay(taxRate As Single, gross As Single) As Currency

taxRate=Inputbox("Enter the Tax Rate")

gross=Inputbox("Enter Gross Pay Amount")

netPay=gross-(gross*taxRate)

End Function

Back to Table of Contents

Calling a Function
There are two ways to access a function:

Call Syntax
Call functionName[(argument list)]

Example 1: Use the Function Name
The following example uses the function netPay in a Messagebox statement:

Dim taxRate As Single
Dim grossInc As Single

REM - - -User input provides the values of taxRate and grossInc
taxRate=Inputbox("Enter the Tax Rate")
grossInc=Inputbox("Enter the Gross Pay")

REM - - -The netPay is a user-defined function which has been declared previously
REM - - -netPay's return value is displayed in a messagebox
Messagebox netPay(taxRate,grossInc)

Example 2: Use the Call Statement
The following example invokes the function netPay using the call statement:

Dim taxRate As Single
Dim grossInc As Single

REM - - -User input provides the values for taxRate and grossInc
taxRate=Inputbox("Enter the Tax Rate")
grossInc=Inputbox("Enter the Gross Pay")

REM - - -netPay is a user-defined function which has been declared previously
REM - - - netPay is invoked with the Call statement
Call netPay(taxRate,grossInc)

REM - - -The return value for netPay is displayed in a messagebox.
Messagebox netPay

The Sub Statement
The Sub statement defines a sub.

Syntax:

Sub subName[(argument list)]
[statements]
End Sub

Elements

Click to review a table that describes the elements used in the function statement.

Usage
A sub does not return a value.

Execute a sub by calling the sub from another subprogram. Refer to Calling a Sub.

Example
In the following example, the sub namePhone is defined. The sub takes two string arguments, x and y. The sub displays these variables in a messagebox.

Sub namePhone(x As String, y As String)
Messagebox "Name: " & x & " " & "Phone: " & y
End Sub

Back to Table of Contents

Calling a Sub
There are two ways to access a sub:

Call Syntax

Call subName[(argument list)]

Example 1: Call a Sub by Name
The following script calls the sub namePhone, and passes it the string variables theName and phone:

Dim theName As String
Dim phone As String

theName=Inputbox("Enter Your Name")
phone=Inputbox("Enter Your Phone Number")

namePhone theName,phone

Example 2: Use the Call Statement
The following script uses the Call statement to invoke the sub namePhone:

Dim theName As String
Dim phone As String

theName=Inputbox("Enter Your Name")
phone=Inputbox("Enter Your Phone Number")

Call namePhone(theName , phone)

Note: Parentheses are required around arguments when using the Call statement.

Back to Table of Contents


Passing Arguments to a Function or Sub
There are two ways to pass arguments to a function or sub.

Passing Arguments by Reference
Passing by reference means the function or sub operates on the actual variable. When you pass a variable by reference to a function or sub that modifies it, the variable will have a different value when the function or sub finishes. Passing by reference is the default for passing arguments.

Example:
The following LotusScript code shows a function that has two variables passed to it by reference:

REM - - -Declare x and y as integer in the declarations event for an object, such as a form.
Dim x As Integer
Dim y As Integer

REM - - - Function addem is declared, x and y are passed by reference.
Function addem(x As Integer,y As Integer)
y=x+y
Messagebox "The function returns value of y, y is " & y
End Function

REM - - - Call Function addem from an event, such as the initialize event for the form.
Sub Initialize
y=0
x=1
Messagebox "y before function call is: " & y 'Display y, y=0
Call addem (x,y) 'y and x are added together, y=1
Messagebox "y after function is: " & y 'Display y, y=1
End Sub

REM - - -Y's value is changed from 0 to 1.


Passing Arguments by Value
Passing an argument by value means the function or sub operates on a copy of the variable, not the actual variable. The variable retains its original value when the subprogram ends.

Use the Byval keyword in the definition of the arguments to specify passing values by value.

Syntax:

Function funcName(Byval argname As datatype)
[statements]
End Function

Example:
The following code shows the addem function; the variable y is passed by value:

REM - - - Function addem is declared, y is passed by value.
Function addem(x As Integer, Byval y As Integer)
y=x+y
Messagebox "The function returns value of y, y is " & y
End Function

REM - - - Call Function addem from an event, such as the initialize event for the form
Sub Initialize
y=0
x=1
Messagebox "y before function call is: " & y 'Display y, y=0
Call addem (x,y) 'y and x are added together, y=1
Messagebox "y after function is: " & y 'Display y, y=0
End Sub


Back to Table of Contents

Exiting a Function or Subroutine
Sometimes it is appropriate to exit a function or sub prior to completing the block statement. A block statement consists of code which is executed as one unit (such as a function or sub). Use the Exit statement to end a sub or function prior to its completion.

The Exit Statement
The Exit statement in LotusScript terminates execution of the current block statement.

Syntax

Exit blockType

Elements

blockType

blockType refers to a keyword designating the type of block statement. In this case, the block statement is a function or sub.

Usage

When LotusScript encounters an Exit statement, it returns control to the scope containing the block statement for which execution is to be terminated.

Transfer of Control
The following shows the rules for transfer of control after the Exit statement:

Exit BlockType Execution Continues
Exit Function In the calling script, as it would from a normal return from the procedure.
Exit Sub In the calling script, as it would from a normal return from the procedure.

Note: If you exit a function without assigning a value to the function, that function returns the initialized value of the variable. Depending on the data type of the function or property's return value, this value can be either 0, EMPTY, or the empty string ("").

Example: Exit Statement
The following LotusScript code shows a function named assignCode which incorporates the exit statement.

REM - - -Function assignCode is declared.
Function assignCode As String
Dim code As String

REM - - -Prompt the user for input, assign the value to code.
code = InputBox("Enter a 9-digit Social Security Number")

REM - - -Test for the length of code. Exit function if code <>9; the value of assignCode is "".
If Len(code) <> 9 Then Exit Function

REM - - -The length of code is 9; assign the value of code to the function asssignCode.
assignCode = code
End Function

The code below calls the function assignCode:

REM - - -assignCode is called within the If statement and the value of assignCode is verified.
REM - - -If the value of assignCode does not equal "", a valid code was entered.
REM- - -If the value of assignCode is "", the code is invalid.
If assignCode() <> "" Then
Messagebox "You entered a valid code."
Else
Messagebox "The code you entered is not valid."
End If

Back to Table of Contents

Script Libraries


What are Script Libraries?
A script library is a design element available in Notes 4.5 and above that stores user scripts, particularly functions and subs. Script libraries are designed in the same manner as a form or a view. Rather than containing fields or columns, they contain LotusScript code.

The scope of a script library is the current database. Scope refers to the area of a application in which a variable, function or sub is declared and can be used. All scripts within a database can access the code stored in the script libraries for that database. In this way subprograms are created once and used as needed.

A script library contains code for the following events in the design pane:

Advantages
There are several advantages to using script libraries:

Accessing a script library
To access a script library, perform the following steps:

1. Choose View -> Design from the menu.
2. Click script libraries under design.
3. Double-click the name of the library. The graphic below shows a list of script library names in the script library list window.

Back to Table of Contents

Setting up a Script Library
Perform the following steps to create a script library:

1. Access the programmer's pane for script libraries. Select Create -> Design -> Script Library from the menu. The graphic below shows the programmer's pane for script libraries.

2. Create a new function or sub or write code for existing events such as Initialize.

3. Name the Library. From the menu, select Edit -> Properties. Each library must have a unique name containing no spaces.

Back to Table of Contents

Incorporating Script Libraries into Notes Applications
A sub or function defined in a script library, can be accessed by any scriptable object within the database where the library resides. To use a script library, enter a Use statement in the (Options) event for the current object or for the (Globals) object.

The Use Statement
The Use statement loads a module needed by the program being compiled. A module consists of a grouping of code.

Syntax
Use useScript

Elements
useScript

useScript is a string literal or a constant containing a string value which specifies a module to load

Usage
The Use statement appears at the module level. A Use statement can appear for all the scriptable objects, e.g. Forms, buttons, and fields.

Example
In the following example a script library, Library1, is made available to the current object's script. The Use statement appears in the (Options) script for the object or for the (Globals) object.

Use "Library1"

Implementing a Script Library
Perform the following steps to use a script library:

1. Make the script library available to the current module. Enter a Use statement in the (Options) script for the object or for the (Globals) object.

2. Call a sub or function that resides in script library, from the current object.

Back to Table of Contents

Exercises


Directions
The following exercises will test the knowledge learned in the previous lessons. The database Script Libraries - Exercises is attached and should be used to complete the exercises.

Procedure

1. Detach the database file Script Libraries - Exercises (SLEX.NSF).

2. Place the file in the \notes\data subdirectory and add the database to your workspace.

3. Open the database.

Back to Table of Contents

Exercise: Create Subs and Functions in a Script Library
In the following exercise, you will create a function and sub in the script library titled Exercise and call the subprograms from an event on the Payroll (Exercise) form.

Steps

1. Open the Exercise script library in the Script Libraries: Exercises database (SLEX.NSF).

2. Create a function named GrossPay that will do the following:

• Ask for the number of hours worked
• Ask for the hourly pay rate
• Calculate the gross pay rate (hours*rate)
• Return the gross pay to the calling program
• Set the fieldname "Hours", "Rate" in the current document with the information obtained above.
• Set the fieldname GrossPay in the current document with the information returned from the function
  

• Ask for the employee's first name
• Ask for the employee's last name
• Set the fieldname "EmpName" in the current document to the employee's first and last names.

5. Make the Exercise script library available to the Payroll (Exercise) form.

6. From the postopen event of the Payroll (Exercise) form, call the FullName sub and GrossPay function.

Hint: The FieldSetText method of the NotesUIDocument Class sets the value of a field on a document.

Syntax notesUIDocument.FieldSetText( fieldName$, textValue$ )

Back to Table of Contents

Exercise Solutions
The following represents one possible solution to the exercise:

REM - - -Place the following code in the script library for the (declarations) event.
Dim ws As NotesUiWorkspace
Dim uidoc As NotesUiDocument

REM - - -The following code is placed in the script library for the initialize event
Set ws =New NotesUiWorkspace
Set uidoc=ws.CurrentDocument

REM- - -FullName Sub is defined
Sub FullName()
First=Inputbox("Enter Employee First Name")
Last=Inputbox("Enter Employee Last Name")
FirstLast=First & " " & Last
uidoc.fieldsettext "EmpName",FirstLast
End Sub

REM- - -GrossPay function is defined
Function GrossPay()
Hours=Inputbox("Enter the number of hours worked")
Rate=Inputbox("Enter the hourly rate")
GrossPay=Hours*Rate

uidoc.fieldsettext "Hours",Cstr(Hours)
uidoc.fieldsettext "Rate", Cstr(Rate)
End Function

REM - - -The Exercise script library is made available to the form by placing the following code
REM - - - in the (options) event for the form

Use "Exercise"

REM - - -The sub and function are invoked by placing the following code in the postopen
REM - - -event for the form

Call FullName
uidoc.FieldSetText "GrossPay", Cstr(GrossPay())


Back to Table of Contents