Lotus Education On Demand: Creating Script Libraries in Notes

Back to Main Menu

Introduction: Creating Script Libraries

User Defined Functions and Subroutines
Overview: Functions and Subroutines
Entering Subs and Functions in the Design Pane
Functions
Calling a Function
Subs
Calling a Sub
Passing Arguments to a Function or Sub
Exiting a Function or Subroutine

Script Libraries
What are Script Libraries?
Setting up a Script Library
Incorporating Script Libraries into Notes Applications

Exercises
Directions
Exercise: Create Subs and Functions in a Script Library
Exercise Solutions

Introduction: Creating Script Libraries

The Creating Script Libraries is self-directed learning targeted for existing Notes/Domino application developers who have been working with LotusScript. Script libraries are a design element available with Notes 4.5 and above that allow global storage and retrieval of subroutines. Understanding functions and subs is a necessary component to learning about script libraries. This tutorial covers the tasks in creating and implementing script libraries, including:

• Creating user-defined functions or subroutines
• Setting up a script library
• Incorporating script libraries into Notes/Domino applications

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

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.

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:

• numeric calculations
• branching or looping operations
• supplying values in expressions and assignments
• supplying arguments to other functions

Syntax
Function functionName[(argumentList)] As dataType

[statements]

End Function

Elements

Table that describes the elements used in the Function statement. Element Name Description functionName The name of the function. argumentList A comma separated list of declarations indicating the values to be passed to the function in function calls. This element is optional. The syntax for each of the arguments listed is: arg1 As dataType arg1 is the variable name for the argument passed into the function. As dataType specifies the variable's data type. You can omit this clause and append a data type suffix character to arg1 to declare the variable as one of the scalar data types. dataType The data type of the value returned by the function. This element is optional. dataType can be any of the scalar data types, or Variant, or a class name. You can omit this clause and append a data type suffix character to functionName to declare the variable as one of the scalar data types. statements One or more lines of code that specifiy the work the function is to perform. These statements can contain: assignment statements variable declarations calls to other subprograms control flow statements

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

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

• Use the function name in a statement that captures the return value
• Use the Call statement

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

Subs
A sub is a subprogram that performs one or more operations without returning a value to its caller.

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

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

• Call the sub by name
• Use the Call Statement

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.


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

• By Reference
• By Value

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


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

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:

• Options
• Declarations
• Initialize
• Terminate
• User defined functions and subs

• LotusScript code is now reusable which saves development time
• Code is easier to debug and maintain
• Errors are minimized

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.

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.

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.

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 -- attached below).

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

3. Open the database.

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

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