What is Domino?

Lotus Domino applications let people share, collect, track, and organize information, using Lotus Notes or the Web. The data itself may be contained in Notes databases or in legacy data systems.

Lotus Domino also contains several programming interfaces, such as LotusScript, Java, and CORBA. The COM interface is the newest member of this family, as seen in this diagram of programmatic access to Domino Objects:

A distinctive feature of the COM interface in Domino is that it enables the Domino Objects to be exposed to other programs without Domino itself running. Using COM, the developer accesses the Domino Objects from an external programming language or environment. The COM developer sees Domino as a library of services; Domino supplies COM classes and multiple interfaces to an application written in a familiar language such as Microsoft Visual Basic for Applications (VBA) or Microsoft Visual C++.

Thus, Microsoft Office components such as Microsoft Excel and Microsoft Word can access and manipulate the Domino Objects through COM. So, too, can new technologies such as Microsoft's ASP (Active Server Pages). The result is that Domino's strengths in areas such as collaboration, workflow, security enforcement, and e-mail can be integrated into broader applications. Such applications are highly scalable; they can be deployed across organizations of widely varying size and complexity.


What is COM?

COM is short for Component Object Model. It is a Microsoft specification of a standard for object interfaces. COM is the object-model basis for high-level technologies such as ActiveX Controls and OLE 2.

The COM specification enables an object to expose its functionality to host applications independent of the program where the object is defined. The COM standard specifies that exposed objects are reusable, and ensures the binary compatibility of these objects.

Microsoft's documentation of COM is on the Web, accessible from: www.microsoft.com/com.

Standard COM

The COM interface in Domino adheres to all of the important aspects of the COM standard. To ensure that a wide variety of third-party tools can access the Domino Objects, these features are implemented:

  • A type library

  • An IClassFactory interface

  • Standard reference counting of objects

  • In-process execution: A separate Notes or Domino process isn't required

COM and OLE Automation

COM accessing Domino Objects is likely to have performance advantages over OLE Automation running in Domino.

COM supports early binding of objects to their typed variables, whereas OLE Automation supports only late binding. Early binding means that objects can be assigned to typed variables, and type checking can be done at compile time. In late binding, there are only Object variables, whose contents must be checked at run time.

Also, accessing the Domino Objects through COM doesn't require the Notes client to be running, or even to be installed, on a Domino server. COM is available on the server itself, unlike OLE Automation.

The following table summarizes the differences between OLE Automation and COM.

COM for the Domino developer

COM also offers advantages to the experienced Domino programmer, leveraging his or her knowledge of Domino. For authenticating a user seeking to access Domino Objects, COM uses the security mechanisms built into Notes. Also, since the Domino Objects are in both Notes and Domino, an application can be deployed without deploying supporting DLLs or libraries.

The integration of native Domino technology with third-party technologies is facilitated by the dual interfaces and the type-library registration implemented in Domino's COM interface. Because Domino registers its type library of COM classes, any third-party development tool that can access the type library can use the Domino Objects. Such tools include, for example, Delphi, FrontPage, Outlook, and Visual InterDev, as well as Microsoft Visual C++, VBA, Visual Basic, and VBScript.


What is in the COM Toolkit

The Lotus Domino and Notes Toolkit for COM is provided to help an application programmer get started with developing a COM application that uses the Domino Objects. The Toolkit contains the following:

  • COM support files (source files).

  • Sample applications that demonstrate using the COM interfaces, written in Visual C++, Visual Basic, VBA, and VBScript.

    • Each sample application includes source files, build files, and Notes databases as needed, and documentation in a Readme.txt file.

  • This file, containing documentation in Microsoft HTML Help format or Notes .NSF format.

You can access the Domino Objects using COM without the Toolkit, but the Toolkit can ease your task significantly. The Readme files for the samples describe, for each application, what the requirements are; how to build the application and set up to run it; and what results to look for. Even if your development language is not one of those illustrated, the large number of samples should give you valuable information about how to proceed.

Once you have installed the Toolkit on your workstation, the best way to use it is to scan the listing of samples in the topic About the sample programs, choose one that interests you, and open its Readme.txt file for more information about building it and running it.

For more information about using the Toolkit, see the remaining topics in this section, "About Domino and the COM Toolkit."

For a self-contained reference about the implementation of COM in Domino, see the section "Accessing Domino Objects via COM: Reference."


Installing and registering the Domino Objects

The Domino Objects, with their COM interface, are available on a machine where you have installed any of the following products, in version R5.0.2b or later:

  • Domino Designer

  • Domino Server

  • Notes Client

If you receive an error accessing the Domino Objects via COM, you should register the objects, following this procedure:

  1. Open a command window.

  2. Make your current directory the Notes or Domino directory.

  3. Run this command:

    4. regsvr32 nlsxbe.dll
    If this command generates an error, you may need to add your Windows system directory to the path: the Windows\System directory in Windows 95/98, or the WinNT\System32 directory in Windows NT.


COM objects and LotusScript objects

The COM interface to the Domino Objects is the same as the LotusScript interface, with some exceptions:

  • Some class members (methods or properties) are LotusScript-only, and some are COM-only

  • Some members have a different signature (parameter set) for LotusScript than for COM

The great majority of class members are identical for LotusScript and COM.

For an overview of the COM/LotusScript differences, see the long topic Accessing the Domino Objects through COM in the second section of this Help file. It lists the methods and properties, and their signatures, that differ between COM and LotusScript.

Detailed documentation of the individual COM/LotusScript differences, for each LotusScript class and its methods and properties, is in the third section of this Help file, "The LotusScript/COM/OLE Classes." This documentation module applies to R5.0.2b and later releases of Domino Designer.


Programming the Domino Objects with COM

The Domino Objects architecture

The Domino Objects class architecture is based on a conceptual containment model that defines each object's scope.

Since one Domino object may be contained by several others, a full containment diagram is beyond the scope of this documentation. This diagram shows only the most important containment relationships:

For the full containment diagram of Domino Objects classes, please refer to the chart "Notes Classes for LotusScript" on the Lotus Developer Network Web site, available from www.lotus.com/techzone.

You will need to be familiar with the Domino Objects to use this Toolkit. For more in-depth information, please see the documentation of LotusScript classes later in this file: The entire section "The LotusScript/COM/OLE Classes," beginning with the topic Using the Domino classes.

Creating and deleting COM objects

The only class in the Domino Objects hierarchy that you can instantiate directly with a Create method is the NotesSession class. Once your application has created and initialized an object of that class, it creates further objects by working down through the hierarchy, invoking properties and methods that return objects.

Closing a container object automatically closes all contained objects. If a container object goes out of scope, it closes automatically, and any objects it contains also close. Consequently, you should be careful that your program saves changes to contained objects before closing the object that contains them, or letting it go out of scope.

Binding objects to variables in the application

Applications written in Visual Basic can declare a variable typed as either Variant or Object. In this case, a reference to a COM object using this variable is resolved at run time (late binding).

Or, a variable may be typed as being of a particular class. In this case, a reference to a COM object using this variable is resolved at compile time (early binding).

Domino Objects support for COM comprises both late-binding (so-called "dispatch") interfaces and early-binding ("custom") interfaces for every Domino Objects class.

VBScript allows only late binding. Visual C++ allows either type of binding, but the natural choice is early binding, for speed and simplicity.

These scripts in Visual Basic demonstrate the difference. Here is a COM sample of late binding:

Dim session As Object
Set session = CreateObject("Lotus.NotesSession")
' Initialize the NotesSession
session.Initialize
MsgBox session.UserName

To effect early binding, rewrite the first line, so the first two lines are:

Dim session As NotesSession
Set session = CreateObject("Lotus.NotesSession")

These two lines can also be re-written as the single line:

Dim session As New NotesSession

These samples also illustrate session initialization, discussed next.

Access and authentication: Initializing a NotesSession object

Initializing a NotesSession object is the only way to gain COM access to other Domino Objects. Initialization is done using either of two methods on the NotesSession object:

  • The Initialize method

  • The InitializeUsingNotesUserName method

These methods are both COM-specific; neither can be used to initialize a NotesSession object in LotusScript.

To authenticate the user issuing one of these methods, the Notes or Domino host uses built-in security procedures.

There are several different types of session. They also differ by whether the session host can be either a Notes client or a Domino server, and what the detailed authentication procedures are. The following table shows the possibilities.

Type of session | How to create the session | Type of installation: Notes client or Domino server | Explanation and comments
Session based on the current user id in NOTES.INI | session.Initialize | Client or server | Does not verify password in id file (if file exists). Prompts for password if it is required.
 | session.Initialize (password) | Client or server | Verifies that password is valid for id file. If not, session is not initialized and password prompt does not come up.
Internet session as Anonymous | session.InitializeUsingNotesUserName("") | Server only | Session initialized if Anonymous is allowed in the server record. Can not access other servers.
Internet session for a user in the Name and Address book | session.InitializeUsingNotesUserName (username) | Server only | Session initialized if user has access to the server. Internet password is not checked. Can not access other servers.
 | session.InitializeUsingNotesUserName (username, password) | Server only | Session initialized if user has access to the server and Internet password is valid. Can not access other servers.

When using the table, keep in mind that:

  • The two methods Initialize and InitializeUsingNotesUserName both assume that the user trusts the Notes or Domino installation.

  • The method parameters are all strings. The username parameter to InitializeUsingNotesUserName can be an empty string.

  • The password parameter is optional in both methods, with one exception: When the invoking application is in C++, the password parameter to the Initialize method is required (it can be Null).

  • A password prompt is issued only for the Initialize method, and only if several conditions are true: A password argument is not supplied, the user ID has a password, and the software supports prompting.

To use the InitializeUsingNotesUserName method successfully, you need to observe all details of the specification. Note that:

  • The method call must be made from a program running on the same physical machine as the Domino server.

  • The Domino NOTES.INI file must include the line:

    • KeyFilename=server.id
  • The username argument can be either a name entry or a short name entry in the server's Name and Address book.


Language-specific requirements

The Readme.txt file in the root directory of the Toolkit lists the development environments that are represented by samples in the Toolkit: Visual C++, Visual Basic, Visual Basic for Applications, and VBScript. These are also the environments needed for developing your own COM application with the Toolkit.

Creating session objects is the most important operation in a COM application. To see how session objects are created in Visual Basic and in VBScript, see the heading "Creating a session object" in the topic Accessing the Domino Objects through COM.

To find comparable code in C++ and VBA, look in the source code of the Toolkit's samples. For example, the Intro sample program in C++ is designed as a template for developing COM applications in C++.

Note Other COM-enabled development languages (not documented in the Toolkit) include Java, JScript, JavaScript, and Delphi. Some languages can only use the IDispatch version of the Domino-Objects-supplied interfaces (late-binding), while others can use both the IDispatch version and the COM version.


About the sample programs

Each sample program in the Toolkit is self-standing; there are no interdependencies among the programs.

For each sample, the necessary program files -- sources, headers, icon files, project files, etc., and a Readme file -- are the exact contents of the directory for that sample in the installed Toolkit. There are some Notes databases that may be shared between samples.

Please note that there are two programs called DbDir, one in Visual C++ and one in Visual Basic. From the user's point of view, they perform the identical function. You can look at the source code and compare how COM-specific programming is done differently in the two languages.

The Readme.txt files for every sample program are in a uniform format, that includes such items as short descriptions of the program and its files, setup procedures, how to run the program, and expected results from the program.

A guide to the sample programs

In the following sample descriptions, it's assumed that the directory named dtcom is the Toolkit root directory.

C++ samples

The following samples are in dtcom\samples\cpp.

  • DbDir: Displays a list of all databases in a Notes data directory.

  • Intro: Instantiates a Notes session, and displays and prints the current user's name.

  • CreateDoc: Reads a comma-separated value file and creates documents in a Notes database of customers.

  • CppAPI: Demonstrates interoperability between the Notes/Domino C++ API and the COM Toolkit.

Visual Basic samples

The following samples are in dtcom\samples\vb.

  • DbDir: Displays a list of all databases in a Notes data directory.

  • ReadHelp: Reads and searches the Domino Designer Help database. Demonstrates how to efficiently search and display a large view.

  • ReadMail: Runs a three-pane display on a mail file; enables access to the file for viewing individual messages, searching for messages, and creating and sending memos.

Visual Basic for Applications samples

The following samples are in dtcom\samples\vba\excel or dtcom\samples\vba\word.

  • MailCell: From a list of databases in a Notes data directory, this sample assembles information about a selected database and mails it to the user from Microsoft Excel.

  • NameLookup: This Microsoft Word macro enables the user to select a contact person from a Notes Name and Address Book, and builds a letterhead from the name and address information.

  • WorkFlow: Demonstrates workflow for creating and routing an expense report from Microsoft Excel.

VBScript sample

The following sample is in dtcom\samples\vbscript\asp.

IntroAsp: A minimal Active Server Pages program that returns the title of a database on a remote Domino server to a Web browser.


About this COM reference

The long topic Accessing the Domino Objects through COM comprises a minimal self-contained reference to accessing Domino Objects through COM. You should consult this topic before starting COM development.

The headings in this topic are:

  • Requirements

  • Session object creation

  • Session initialization

  • Exceptions to LotusScript specifications

  • COM-only properties and methods

  • Constants

Examples in Visual Basic, VBScript, and ASP code that further illustrate using these objects follow this topic.

Note This topic is written in a compact reference style. The topics in the first section of this Help file, "About Domino and the COM Toolkit," expand on some of this material.


Accessing the Domino Objects through COM

The back-end Domino Objects have a Component Object Model (COM) interface. The COM interface is the same as the LotusScript interface with some exceptions. These exceptions are noted below in "General exceptions to LotusScript specifications" and "Specific exceptions to LotusScript specifications," and in the LotusScript classes A-Z reference.

COM provides both early-binding (custom) and late-binding (dispatch) interfaces. Early binding makes the Domino classes available as typed variables with compile-time checking. Late binding can be used where the language (for example, VBScript) precludes early binding.

Notes

  • This feature is new with Release 5.0.2b.

  • This feature is not supported on the following operating systems: OS/2, UNIX, and Macintosh.

Requirements

The COM interface is available on a computer containing any of the following:

  • Domino Designer Release 5.0.2b or later

  • Domino Server Release 5.0.2b or later

  • Notes Client Release 5.0.2b or later

The Domino or Notes software must be installed but need not be running.

Installation of the Domino or Notes software makes a type library available and registers the following classes:

  • Lotus.NotesSession

  • Lotus.NotesSession.1

Do not confuse these with the OLE automation objects Notes.NotesSession and Notes.NotesUIWorkspace.

The Domino COM objects must be able to locate a valid NOTES.INI file, looking first in the Domino or Notes program directory and then at the PATH system variable. The KeyFileName setting in the NOTES.INI file specifies the user ID that COM uses.

Creating a session object

To access the Domino Objects, create an object based on the registered Lotus.NotesSession class.

Visual Basic

Include the Domino object library in the Visual Basic project:

  • Choose Project - References.

  • Check "Lotus Domino Objects."

The location will show the path to DOMOBJ.TLB in the Domino or Notes program directory.

Alternatively, you can select the Browse button and specify DOMOBJ.TLB in the Domino or Notes program directory.

The Domino Objects then become available to the project. You can see them in the Object Browser and they appear as prompts when you start typing an object name.

The classes appear in the left-hand pane of the browser; the properties and methods appear in the right-hand pane for the selected class. Constants appear in the left-hand pane as Enum data structures; the members appear in the right-hand pane. For example, the Enum structure named ACLLEVEL contains the members ACLLEVEL_AUTHOR, ACLLEVEL_DEPOSITOR, and so on. The error constants appear in the right-hand pane when NOTES_ERRORS is selected in the left-hand pane.

To access the Domino Objects, create a NotesSession object with either:

Dim session As New NotesSession

Or:

Dim session As NotesSession

Set session = CreateObject("Lotus.NotesSession")

Note If you declare the session variable as Variant or Object, COM uses late binding.

VBScript

In VBScript, create a NotesSession object with:

Dim session

Set session = CreateObject("Lotus.NotesSession")

VBScript treats all variables as Variant so COM uses late binding.

The Domino constants are not defined. You must specify the actual values (or define the constants yourself). See the discussion of constant values below in "Constants."

Initializing a session

You must explicitly initialize a COM session with one of the following NotesSession methods. These methods do not apply to LotusScript applications.

Call session.Initialize("passwordOptional")

Call session.InitializeUsingNotesUserName("name", "passwordOptional")

The parameters are all strings. The name parameter can be an empty string. The password parameter is optional.

Initialization occurs as follows:

  • Initialize: this method can be used on a computer with a Notes client or Domino server and bases the session on the current user ID. If a password is specified, it must match the user ID password. If a password is not specified, the user is prompted for a password as required and as the software permits. If the software does not support prompting (for example, VBScript under ASP/IIS), you must supply the password or the user ID must not have one.

  • InitializeUsingNotesUserName: this method can be used only on a computer with a Domino server. If a name is specified, the InitializeUsingNotesUserName method looks it up in the local Domino Directory and permits access to the local server depending on the "Server Access" and "COM Restrictions" settings. The password must match the Internet password associated with the name. If no name is specified, access is granted if the server permits Anonymous access.

These methods assume that you trust the local Domino or Notes installation.

Access to the Domino Objects is as a client if you use the Initialize method and the user ID is not specified as a server in the local Domino or Notes directory. Otherwise, access is as a server. As a client, you can access any server that accepts your user ID. As a server, you can access only the local server.

General exceptions to LotusScript specifications

The following are the general differences between accessing Domino Objects through LotusScript or COM:

  • In a COM application, you cannot create Domino objects with the New modifier except for NotesSession. You must initialize the NotesSession object and use properties and methods that return Domino Objects.

  • COM supports only back-end classes. COM does not support the following classes: Button, Field, Navigator, NotesTimer, NotesUIDatabase, NotesUIDocument, NotesUIView, NotesUIWorkspace.

  • COM does not support the concept of a current environment (for example, current database, current agent, or document context).

  • Boolean values are typed as Boolean in COM, and Variant or Integer in LotusScript. This is not a problem porting from LotusScript to COM, but is a problem porting from COM to LotusScript.

  • Parameters typed as Integer in LotusScript are typed as Long in COM. This should not be a problem porting between LotusScript and COM.

  • Values that take a constant are typed as Enum in COM, and Variant or Integer in LotusScript. This should not be a problem porting between LotusScript and COM.

  • In COM, you cannot use item names as NotesDocument properties. For example, in LotusScript you can refer to the Subject item as doc.Subject (where doc is a NotesDocument object). In COM, you cannot do this; you must use the properties and methods that get and set item values.

  • Where a Domino property or method returns an array of Domino objects in a late-binding application, you must assign the return value to a variable before you can index it as an array. For example, the following code results in a run-time error with late binding (but works with early binding):

    • Set col = view.Columns(2)
    You must first assign the Columns property to a variable:

    cols = view.Columns

    Set col = cols(2)
  • Error codes in COM are four bytes. The first two bytes contain the value &H8004. The last two bytes contain the Domino error code as specified in LSXBEERR.LSS in the Domino or Notes program directory. See the discussion of constant values below in "Constants."

  • Where the return type of a property or method is an unknown object, COM may issue the compile-time error "Method or data member not found," or one of the run-time errors "Object required" or "Type mismatch." An example is the Parent property of NotesViewEntry, which can be a NotesViewEntryCollection, NotesViewNavigator, or NotesView object. LotusScript resolves the object but COM does not. There is no work-around.

Language differences between LotusScript and Visual Basic

Also note the following language differences between LotusScript and Visual Basic:

  • LotusScript uses ForAll ... End ForAll. Visual Basic uses For Each ... Next.

  • LotusScript does not support the Boolean data type.

  • Visual Basic does not support the compiler directives %Rem, %End Rem, %If, %Elseif, %Else, %End If, and %Include.

  • Visual Basic does not support the vertical bar | and braces {} for delimiting strings.

  • Visual Basic does not support &B for binary literals. It does support &H and &O for hexadecimal and octal literals.

  • LotusScript uses Format to format dates. Visual Basic uses FormatDateTime.

  • LotusScript does not support CBool, CByte, and CDec.

  • Visual Basic does not support Today.

  • LotusScript does not support the Err intrinsic object. Visual Basic does not support On Error with an error number as a parameter.

Specific exceptions to LotusScript specifications

The following are specific differences between accessing Domino Objects through LotusScript or COM.

Class | Exceptions | Why
Button | Entire class | Not in COM
Field | Entire class | Not in COM
Navigator | Entire class | Not in COM
NotesACL | RemoveACLEntry | COM only
NotesACLEntry | NameObject | COM only
 | New | Not in COM
NotesAgent | HttpURL | COM only
 | NotesURL | COM only
NotesDatabase | HttpURL | COM only
 | NotesURL | COM only
 | UnprocessedDocuments | Not implemented in COM (Note 1)
 | Create | Not in COM (Note 2)
 | GetURLHeaderInfo | In COM, parameters 1 and 2 are optional
 | New | Not in COM
 | Open | In COM takes no parameters (Note 2)
 | OpenByReplicaID | Not in COM (Note 2)
 | OpenIfModified | Not in COM (Note 2)
 | OpenMail | Not in COM (Note 2)
 | OpenURLDb | Not in COM
 | OpenWithFailover | Not in COM
 | UnprocessedFTSearch | Not implemented in COM (Note 1)
 | UnprocessedSearch | Not implemented in COM (Note 1)
NotesDateRange | Parent | COM only
NotesDateTime | Parent | COM only
 | New | Not in COM
NotesDbDirectory | Parent | COM only
 | CreateDatabase | COM only (Note 2)
 | GetFirstDatabase | In COM, use NOTES_DATABASE instead of DATABASE due to a naming conflict
 | New | Not in COM
 | OpenDatabase | COM only (Note 2)
 | OpenDatabaseByReplicaID | COM only (Note 2)
 | OpenDatabaseIfModified | COM only (Note 2)
 | OpenMailDatabase | COM only (Note 2)
NotesDocument | HttpURL | COM only
 | NotesURL | COM only
 | New | Not in COM
NotesDocumentCollection | AddDocument | COM has optional second parameter, checkDups As Boolean = False, but it has no use currently
NotesEmbeddedObject | DoVerb | COM treats as Sub not Function
NotesForm | HttpURL | COM only
 | NotesURL | COM only
 | Parent | COM only
NotesInternational | Parent | COM only
NotesItem | New | Not in COM
NotesLog | Parent | COM only
 | New | Not in COM
NotesMIMEEntity | No exceptions |
NotesName | Parent | COM only
 | New | Not in COM
NotesNewsletter | Parent | COM only
 | New | Not in COM
NotesOutline | ParentDatabase | COM only
 | AddEntry | Not in COM; obsolete in LotusScript
 | CreateEntry | In COM, parameter 2 not optional; specify Nothing for default
 | GetChild | Not in COM; obsolete in LotusScript
NotesOutlineEntry | IsHidden | Not in COM; obsolete in LotusScript
 | Parent | COM only
 | SetAction | COM treats as Sub not Function
 | SetNamedElement | COM treats as Sub not Function
 | SetNoteLink | COM treats as Sub not Function; COM has only 1 parameter, Obj As UNKNOWN
 | SetURL | COM treats as Sub not Function
NotesRegistration | New | Not in COM
NotesReplication | No exceptions |
NotesRichTextItem | AddNewLine | In COM, parameter 1 optional and Iefaults to 1
 | AddTab | In COM, parameter optional and defaults to 1
 | New | Not in COM
NotesRichTextParagraphStyle | SetTab | In COM, parameter 2 optional
 | SetTabs | In COM, parameter 3 optional and defaults to 1
NotesRichTextStyle | Parent | COM only
NotesRichTextTab | No exceptions |
NotesSession | CurrentAgent | Not implemented in COM (Note 1)
 | CurrentDatabase | Not implemented in COM (Note 1)
 | DocumentContext | Not implemented in COM (Note 1)
 | HttpURL | COM only
 | NotesURL | COM only
 | ServerName | COM only
 | URLDatabase | COM only
 | UserNameList | Not implemented in COM (Note 1)
 | UserNameObject | COM only
 | CreateRegistration | COM only
 | CreateTimer | Not in COM
 | Evaluate | COM only
 | Initialize | COM only
 | InitializeUsingNotesUserName | COM only
 | Resolve | COM only
NotesTimer | Entire class | Not in COM
NotesUIDatabase | Entire class | Not in COM
NotesUIDocument | Entire class | Not in COM
NotesUIView | Entire class | Not in COM
NotesUIWorkspace | Entire class | Not in COM
NotesView | ColumnNames | COM only
 | HttpURL | COM only
 | NotesURL | COM only
 | CreateViewNav | COM has optional Long parameter for cache size
 | CreateViewNavFrom | COM has optional Long parameter for cache size
 | CreateViewNavFromCategory | COM has optional Long parameter for cache size
 | CreateViewNavFromChildren | COM has optional Long parameter for cache size
 | CreateViewNavFromDescendants | COM has optional Long parameter for cache size
 | CreateViewNavMaxLevel | COM only
 | GetColumn | COM only
NotesViewColumn | Parent | COM only
NotesViewEntry | No exceptions |
NotesViewEntryCollection | AddEntry | COM has optional second parameter, checkDups As Boolean = False, but it has no use currently
NotesViewNavigator | CacheSize | COM only (Note 3)
 | GetCurrent | COM only
 | GotoChild | COM only
 | GotoEntry | COM only
 | GotoFirst | COM only
 | GotoFirstDocument | COM only
 | GotoLast | COM only
 | GotoLastDocument | COM only
 | GotoNext | COM only
 | GotoNextCategory | COM only
 | GotoNextDocument | COM only
 | GotoNextSibling | COM only
 | GotoParent | COM only
 | GotoPos | COM only
 | GotoPrev | COM only
 | GotoPrevCategory | COM only
 | GotoPrevDocument | COM only
 | GotoPrevSibling | COM only

Note 1: "Not implemented in COM" means that the code compiles but returns a "not implemented" run-time error.

Note 2: The LotusScript NotesDatabase methods Create, Open with parameters, OpenByReplicaID, OpenIfModified, and OpenMail are implemented in COM in NotesDbDirectory as CreateDatabase, OpenDatabase, OpenDatabaseByReplicaID, OpenDatabaseIfModified, and OpenMailDatabase.

Note 3: You can query and set this property but it is not actually used.

COM-only properties and methods

Following are the specifications for the COM-only properties and methods.

NotesACL

Call notesACL.RemoveACLEntry( name$ )

NotesACLEntry

Set notesName = notesACLEntry.NameObject

NotesAgent

url$ = notesAgent.HttpURL

url$ = notesAgent.NotesURL

NotesDatabase

url$ = notesDatabase.HttpURL

url$ = notesDatabase.NotesURL

NotesDateRange

Set notesSession = notesDateRange.Parent

NotesDateTime

Set notesSession = notesDateTime.Parent

NotesDbDirectory

Set notesSession = notesDbDirectory.Parent

Set notesDatabase = notesDbDirectory.CreateDatabase( file$ , [ openBooleanTrue ] )

Set notesDatabase = notesDbDirectory.OpenDatabase( file$ , [ openBooleanFalse ] )

Set notesDatabase = notesDbDirectory.OpenDatabaseByReplicaID( rid$ )

Set notesDatabase = notesDbDirectory.OpenDatabaseIfModified( file$ , timeNotesDateTime )

Set notesDatabase = notesDbDirectory.OpenMailDatabase( )

NotesDocument

url$ = notesDocument.HttpURL

url$ = notesDocument.NotesURL

NotesForm

Set notesDatabase = notesForm.Parent

url$ = notesForm.HttpURL

url$ = notesForm.NotesURL

NotesInternational

Set notesSession = notesInternational.Parent

NotesLog

Set notesSession = notesLog.Parent

NotesName

Set notesSession = notesName.Parent

NotesNewsletter

Set notesSession = notesNewsletter.Parent

NotesOutline

Set notesDatabase = notesOutline.ParentDatabase

NotesOutlineEntry

Set notesOutline = notesOutlineEntry.Parent

NotesRichTextStyle

Set notesSession = notesRichTextStyle.Parent

NotesSession

url$ = notesSession.HttpURL

url$ = notesSession.NotesURL

name$ = notesSession.ServerName

Set notesDatabase = notesSession.URLDatabase

Set notesName = notesSession.UserNameObject

Set notesRegistration = notesSession.CreateRegistration( )

variant = notesSession.Evaluate( formula$ , docNotesDocument )

Call notesSession.InitializeUsingNotesUserName( [ password$ ] )

Call notesSession.InitializeUsingNotesUserName( [ name$ ] , [ password$ ] )

unknown = notesSession.Resolve( url$ )

NotesView

variant = notesView.ColumnNames

url$ = notesView.HttpURL

url$ = notesView.NotesURL

Set notesViewNavigator = notesView.CreateViewNavMaxLevel( level& , [ cacheSize& ] )

Set notesViewColumn = notesView.GetColumn( columnNumber& )

NotesViewColumn

Set notesView = notesViewColumn.Parent

NotesViewNavigator

size& = notesViewName.CacheSize

notesViewName.CacheSize = size&

Set notesViewEntry = notesViewNavigator.GetCurrent( )

Call notesViewNavigator.GotoChild( notesViewEntry )

Call notesViewNavigator.GotoEntry( objUnknown )

Call notesViewNavigator.GotoFirst( )

Call notesViewNavigator.GotoFirstDocument( )

Call notesViewNavigator.GotoLast( )

Call notesViewNavigator.GotoLastDocument( )

Call notesViewNavigator.GotoNext( notesViewEntry )

Call notesViewNavigator.GotoNextCategory( notesViewEntry )

Call notesViewNavigator.GotoNextDocument( notesViewEntry )

Call notesViewNavigator.GotoNextSibling( notesViewEntry )

Call notesViewNavigator.GotoParent( notesViewEntry )

Call notesViewNavigator.GotoPos( pos$ , separator$ )

Call notesViewNavigator.GotoPrev( notesViewEntry )

Call notesViewNavigator.GotoPrevCategory( notesViewEntry )

Call notesViewNavigator.GotoPrevDocument( notesViewEntry )

Call notesViewNavigator.GotoPrevSibling( notesViewEntry )

Constants

The table that follows specifies the values of the non-error constants used by the Domino classes. You can also see the constant values by examining DOMOBJ.TLB in the Notes or Domino program directory with a product such as Visual InterDev (VID).

The Domino error constants are specified in the file LSXBEERR.LSS in the Domino or Notes program directory and in the "File contents " topic in this chapter. In COM, the error value is four bytes: the first two bytes contain the value &H8004 and the last two bytes contain the Domino error code. To convert from Domino to COM, append the Domino 4-digit hexadecimal value to &H8004. To convert from COM to Domino, truncate the first four digits from the COM hexadecimal value.

Enum structure | Constant | Value
ACLLEVEL | ACLLEVEL_AUTHOR | 3
 | ACLLEVEL_DEPOSITOR | 1
 | ACLLEVEL_DESIGNER | 5
 | ACLLEVEL_EDITOR | 4
 | ACLLEVEL_MANAGER | 6
 | ACLLEVEL_NOACCESS | 0
 | ACLLEVEL_READER | 2
ACLTYPE | ACLTYPE_MIXEDGROUP | 3
 | ACLTYPE_PERSON | 1
 | ACLTYPE_PERSONGROUP | 4
 | ACLTYPE_SERVER | 2
 | ACLTYPE_SERVERGROUP | 5
 | ACLTYPE_UNSPECIFIED | 0
AG_TARGET | TARGET_ALL_DOCS | 1
 | TARGET_ALL_DOCS_IN_VIEW | 5
 | TARGET_NEW_DOCS | 2
 | TARGET_NEW_OR_MODIFIED_DOCS | 3
 | TARGET_NONE | 0
 | TARGET_SELECTED_DOCS | 4
 | TARGET_UNREAD_DOCS_IN_VIEW | 6
AG_TRIGGER | TRIGGER_AFTER_MAIL_DELIVERY | 2
 | TRIGGER_BEFORE_MAIL_DELIVERY | 6
 | TRIGGER_DOC_PASTED | 3
 | TRIGGER_MANUAL | 4
 | TRIGGER_NONE | 0
 | TRIGGER_SCHEDULED | 1
 | TRIGGER_UPDATE | 5
COLORS | COLOR_BLACK | 0
 | COLOR_BLUE | 4
 | COLOR_CYAN | 7
 | COLOR_DARK_BLUE | 10
 | COLOR_DARK_CYAN | 13
 | COLOR_DARK_GREEN | 9
 | COLOR_DARK_MAGENTA | 11
 | COLOR_DARK_RED | 8
 | COLOR_DARK_YELLOW | 12
 | COLOR_GRAY | 14
 | COLOR_GREEN | 3
 | COLOR_LIGHT_GRAY | 15
 | COLOR_MAGENTA | 5
 | COLOR_RED | 2
 | COLOR_WHITE | 1
 | COLOR_YELLOW | 6
DB_TYPES | DATABASE (avoid using this in COM) | 1247
 | NOTES_DATABASE | 1247
 | REPLICA_CANDIDATE | 1245
 | TEMPLATE | 1248
 | TEMPLATE_CANDIDATE | 1246
EMBED_TYPE | EMBED_ATTACHMENT | 1454
 | EMBED_OBJECT | 1453
 | EMBED_OBJECTLINK | 1452
FT_TYPES | FT_DATABASE | 8192
 | FT_DATE_ASC | 64
 | FT_DATE_DES | 32
 | FT_FILESYSTEM | 4096
 | FT_FUZZY | 16384
 | FT_SCORES | 8
 | FT_STEMS | 512
 | FT_THESAURUS | 1024
IT_TYPE | ACTIONCD | 16
 | ASSISTANTINFO | 17
 | ATTACHMENT | 1084
 | AUTHORS | 1076
 | COLLATION | 2
 | DATETIMES | 1024
 | EMBEDDEDOBJECT | 1090
 | ERRORITEM | 256
 | FORMULA | 1536
 | HTML | 21
 | ICON | 6
 | LSOBJECT | 20
 | MIME_PART | 25
 | NAMES | 1074
 | NOTELINKS | 7
 | NOTEREFS | 4
 | NUMBERS | 768
 | OTHEROBJECT | 1085
 | QUERYCD | 15
 | READERS | 1075
 | RICHTEXT | 1
 | SIGNATURE | 8
 | TEXT | 1280
 | UNAVAILABLE | 512
 | UNKNOWN | 0
 | USERDATA | 14
 | USERID | 1792
 | VIEWMAPDATA | 18
 | VIEWMAPLAYOUT | 19
LOG_EVENTS | EV_ALARM | 8
 | EV_COMM | 1
 | EV_MAIL | 3
 | EV_MISC | 6
 | EV_REPLICA | 4
 | EV_RESOURCE | 5
 | EV_SECURITY | 2
 | EV_SERVER | 7
 | EV_UNKNOWN | 0
 | EV_UPDATE | 9
LOG_SEVERITY | SEV_FAILURE | 2
 | SEV_FATAL | 1
 | SEV_NORMAL | 5
 | SEV_UNKNOWN | 0
 | SEV_WARNING1 | 3
 | SEV_WARNING2 | 4
NOTES_ERRORS | See the "File contents" topic in this chapter. |
OE_CLASS | OUTLINE_CLASS_DATABASE | 2194
 | OUTLINE_CLASS_DOCUMENT | 2190
 | OUTLINE_CLASS_FOLDER | 2197
 | OUTLINE_CLASS_FORM | 2192
 | OUTLINE_CLASS_FRAMESET | 2195
 | OUTLINE_CLASS_NAVIGATOR | 2193
 | OUTLINE_CLASS_PAGE | 2196
 | OUTLINE_CLASS_UNKNOWN | 2189
 | OUTLINE_CLASS_VIEW | 2191
OE_TYPE | OUTLINE_OTHER_FOLDERS_TYPE | 1589
 | OUTLINE_OTHER_UNKNOWN_TYPE | 1591
 | OUTLINE_OTHER_VIEWS_TYPE | 1588
 | OUTLINE_TYPE_ACTION | 2188
 | OUTLINE_TYPE_NAMEDELEMENT | 2187
 | OUTLINE_TYPE_NOTELINK | 2186
 | OUTLINE_TYPE_URL | 2185
REG_TYPE | ID_CERTIFIER | 173
 | ID_FLAT | 171
 | ID_HIERARCHICAL | 172
RP_PRIORITY | DB_REPLICATION_PRIORITY_HIGH | 1549
 | DB_REPLICATION_PRIORITY_LOW | 1547
 | DB_REPLICATION_PRIORITY_MED | 1548
 | DB_REPLICATION_PRIORITY_NOTSET | 1565
RT_ALIGN | ALIGN_CENTER | 3
 | ALIGN_FULL | 2
 | ALIGN_LEFT | 0
 | ALIGN_NOWRAP | 4
 | ALIGN_RIGHT | 1
RT_EFFECTS | EFFECTS_EMBOSS | 4
 | EFFECTS_EXTRUDE | 5
 | EFFECTS_NONE | 0
 | EFFECTS_SHADOW | 3
 | EFFECTS_SUBSCRIPT | 2
 | EFFECTS_SUPERSCRIPT | 1
RT_FONTS | FONT_COURIER | 4
 | FONT_HELV | 1
 | FONT_ROMAN | 0
RT_PAGINATE | PAGINATE_BEFORE | 1
 | PAGINATE_DEFAULT | 0
 | PAGINATE_KEEP_TOGETHER | 4
 | PAGINATE_KEEP_WITH_NEXT | 2
RT_TAB | TAB_CENTER | 3
 | TAB_DECIMAL | 2
 | TAB_LEFT | 0
 | TAB_RIGHT | 1
SPACING | SPACING_DOUBLE | 4
 | SPACING_ONE_POINT_25 | 1
 | SPACING_ONE_POINT_50 | 2
 | SPACING_ONE_POINT_75 | 3
 | SPACING_SINGLE | 0
USER_TYPE | NOTES_DESKTOP_CLIENT | 175
 | NOTES_FULL_CLIENT | 176
 | NOTES_LIMITED_CLIENT | 174
VC_ALIGN | VC_ALIGN_CENTER | 2
 | VC_ALIGN_LEFT | 0
 | VC_ALIGN_RIGHT | 1
VC_DATEFMT | VC_FMT_MD | 2
 | VC_FMT_Y4M | 6
 | VC_FMT_YM | 3
 | VC_FMT_YMD | 0
VC_FONTSTYLE | VC_FONT_BOLD | 1
 | VC_FONT_ITALIC | 2
 | VC_FONT_STRIKEOUT | 8
 | VC_FONT_UNDERLINE | 4
VC_NUMATTR | VC_ATTR_PARENS | 2
 | VC_ATTR_PERCENT | 4
 | VC_ATTR_PUNCTUATED | 1
VC_NUMFMT | VC_FMT_CURRENCY | 3
 | VC_FMT_FIXED | 1
 | VC_FMT_GENERAL | 0
 | VC_FMT_SCIENTIFIC | 2
VC_SEP | VC_SEP_COMMA | 2
 | VC_SEP_NEWLINE | 4
 | VC_SEP_SEMICOLON | 3
 | VC_SEP_SPACE | 1
VC_TDFMT | VC_FMT_DATE | 0
 | VC_FMT_DATETIME | 2
 | VC_FMT_TIME | 1
 | VC_FMT_TODAYTIME | 3
VC_TIMEFMT | VC_FMT_HM | 1
 | VC_FMT_HMS | 0
VC_TIMEZONEFMT | VC_FMT_ALWAYS | 2
 | VC_FMT_NEVER | 0
 | VC_FMT_SOMETIMES | 1

See examples
Examples: Accessing the Domino Objects through COM


Examples: Accessing the Domino Objects through COM

  1. This Visual Basic code initializes a Domino session and prints the common name of the user ID.

    2. Private Sub InitializeDimNew_Click()

    Dim s As New NotesSession

    Call s.Initialize

    MsgBox s.CommonUserName, , "Common user name"

    End Sub
  2. This Visual Basic code initializes a Domino session as above but uses CreateObject instead of New on NotesSession. Note that "s" must be declared as type NotesSession for early binding.

    3. Private Sub InitializeCreateObject_Click()

    Dim s As NotesSession

    Set s = CreateObject("Lotus.NotesSession")

    Call s.Initialize

    MsgBox s.CommonUserName, , "Common user name"

    End Sub
  3. This VBScript code initializes a Domino session as above.

    4. <HTML>

    <HEAD>

    <TITLE>Initialize Session</TITLE>

    <SCRIPT LANGUAGE="VBScript">

    Sub Button1_OnClick

        dim s

        Set s = CreateObject("Lotus.NotesSession")

        Call s.Initialize

        MsgBox s.CommonUserName,, "Common user name"

    End Sub

    </SCRIPT>

    </HEAD>

    <BODY>

    <H3>Initialize Session and Print User Name</H3><HR>

    <FORM><INPUT NAME="Button1" TYPE="BUTTON" VALUE="Click Here"></FORM>

    </BODY>

    </HTML>
  4. This Visual Basic code prints the titles of all the databases on a Domino server.

    5. Private Sub DbDirectory_Click()

    Dim s As New NotesSession

    Dim dir As NotesDbDirectory

    Dim db As NotesDatabase

    s.Initialize

    Set dir = s.GetDbDirectory("Doc/CAM/Notes")

    Set db = dir.GetFirstDatabase(NOTES_DATABASE)

    dbString = db.Title

    dbCount = 1

    While Not (db Is Nothing)

        If dbCount > 12 Then

            MsgBox dbString, , "Databases on " + dir.Name

            dbString = db.Title

            dbCount = 1

        Else

            dbString = dbString + Chr(10)

            dbString = dbString + db.Title

            dbCount = dbCount + 1

        End If

        Set db = dir.GetNextDatabase

    Wend

    MsgBox dbString, , "Databases on " + dir.Name

    End Sub
  5. This VBScript code prints the titles of all the databases on a Domino server as above.

    6. <HTML>

    <HEAD>

    <TITLE>Initialize Session</TITLE>

    <SCRIPT LANGUAGE="VBScript">

    Sub Button1_OnClick

        dim s, dir, db

        Set s = CreateObject("Lotus.NotesSession")

        Call s.Initialize

        Set dir = s.GetDbDirectory("Doc/CAM/Notes")

        Set db = dir.GetFirstDatabase(1247)

        dbString = db.Title

        dbCount = 1

        While Not (db Is Nothing)

            If dbCount > 12 Then

                MsgBox dbString,, "Databases on " + dir.Name

                dbString = db.Title

                dbCount = 1

            Else

                dbString = dbString + Chr(10)

                dbString = dbString + db.Title

                dbCount = dbCount + 1

            End If

            Set db = dir.GetNextDatabase

        Wend

        MsgBox dbString,, "Databases on " + dir.Name

    End Sub

    </SCRIPT>

    </HEAD>

    <BODY>

    <H3>Print Databases on Doc</H3><HR>

    <FORM><INPUT NAME="Button1" TYPE="BUTTON" VALUE="Click Here"></FORM>

    </BODY>

    </HTML>
  6. This ASP code is similar to the last two examples. It prints the titles of all the databases on the current server.

    7. <%@ Language=VBScript %>

    <HTML>

    <HEAD>

    <META NAME="; GENERATOR; " Content="; Microsoft; Visual; Studio; 6#; ">

    </HEAD>

    <BODY>

    <%

        dim s, dir, db

        Set s = CreateObject("Lotus.NotesSession")

        Call s.Initialize

        dim serverName

        serverName = ""

        Set dir = s.GetDbDirectory(serverName)

        Set db = dir.GetFirstDatabase(1247)

        if (dir.Name <> "") then

            Response.Write("<h2>" + "Databases on " + dir.Name + "</h2>")

        else

            Response.Write("<h2>Databases on local</h2>")

        end if

        Response.Write("<table border=1  bgcolor=#CCCCCC>")

        Response.Write("<tr>")

        Response.Write("<th>File Name")

        Response.Write("<th>DB Title")

        While Not (db Is Nothing)

            Response.Write("<tr><td>")

            Response.Write(db.FileName)

            Response.Write("</td>")

            Response.Write("<td>")

            Response.Write(db.Title)

            Response.Write("</td></tr>")

            Set db = dir.GetNextDatabase

        Wend

        Response.Write("</table>")

    %>

    </BODY>

    </HTML>
  7. This Visual Basic code gets all the documents in a view of a Domino database, and prints the values of a text item and multivalue text item.

    8. Private Sub DisplayItemValues_Click()

    Dim s As New NotesSession

    Dim db As NotesDatabase

    Dim v As NotesView

    Dim vn As NotesViewNavigator

    Dim e As NotesViewEntry

    Dim doc As NotesDocument

    Call s.Initialize

    Set db = s.GetDatabase("", "OverviewExamples.nsf")

    Set v = db.GetView("All Documents")

    Set vn = v.CreateViewNav()

    Set e = vn.GetFirstDocument()

    While Not (e Is Nothing)

        Set doc = e.Document

        subj = doc.GetFirstItem("Subject").Values

        MsgBox subj(0), , "Subject"

        cats = doc.GetFirstItem("Categories").Values

        For Each cat In cats

            MsgBox cat, , "Category"

        Next

        Set e = vn.GetNextDocument(e)

    Wend

    End Sub
  8. This ASP code is similar to the last example. It prints the values of a text item and multivalue date/time item.

    9. <%@ Language=VBScript %>

    <HTML>

    <HEAD>

    <META NAME="; GENERATOR; " Content="; Microsoft; Visual; Studio; 6#; ">

    </HEAD>

    <BODY>

    <%

        Dim s 'As New NotesSession

        Dim db 'As NotesDatabase

        Dim v 'As NotesView

        Dim vn 'As NotesViewNavigator

        Dim e 'As NotesViewEntry

        Dim doc 'As NotesDocument

        Set s = CreateObject("Lotus.NotesSession")

        Call s.Initialize

        Dim serverName

        serverName = ""

        Set db = s.GetDatabase(serverName, "AllTypes.nsf")

        Set v = db.GetView("All Documents")

        Set vn = v.CreateViewNav()

        Set e = vn.GetFirstDocument()

        While Not (e Is Nothing)

            Set doc = e.Document

            Dim values, item1

            Set item1 = doc.GetFirstItem("TextField")

            values = item1.Values

            Response.Write("<p>Subject: " + values(0) + "<br>")

            Set item1 = doc.GetFirstItem("DateTimeField")

            values = item1.Values

            For Each dateTime In values

                Response.Write("DateTime: " + CStr(dateTime))

            Next

            Set e = vn.GetNextDocument(e)

        Wend

    %>

    </BODY>

    </HTML>
  9. This Visual Basic code prints a specific message if an anticipated error occurs. If another error occurs, the code prints the Notes error code -- the last two bytes of the COM error code converted to an integer.

    10. Private Sub OpenDatabase_Click()

    Dim s As New NotesSession

    Dim dir As NotesDbDirectory

    Dim db As NotesDatabase

    Call s.Initialize

    Set dir = s.GetDbDirectory("")

    On Error GoTo errorHandler

    Set db = dir.OpenDatabase(Form1.DatabaseName.Text)

    MsgBox db.Title, , "Title"

    Exit Sub

    errorHandler:

    If Err() = ERR_SYS_FILE_NOT_FOUND Then

        MsgBox "Change the file name and try again", , _

        "File not found"

    Else

        MsgBox "Error " & _

        CInt("&H" & Right(Hex(Err()), 4)), , _

        "Domino error"

    End If

    End Sub
  10. This VBScript code prints a specific message if an anticipated error occurs. The error is defined by appending the hexadecimal value of the Domino error code to &H80040 (4003 is 3 digits in hexadecimal). If another error occurs, the code prints the Domino error code -- the last two bytes of the COM error code converted to an integer.

    11. Sub Button1_OnClick

        On Error Resume Next

        dim s, dir, db, ERR_SYS_FILE_NOT_FOUND

        If Len(Hex(4003)) = 3 Then

            ERR_SYS_FILE_NOT_FOUND = Clng("&H80040" & Hex(4003))

        Else

            ERR_SYS_FILE_NOT_FOUND = Clng("&H8004" & Hex(4003))

        End If

        Set s = CreateObject("Lotus.NotesSession")

        Call s.Initialize

        Set dir = s.GetDbDirectory("")

        Set db = dir.OpenDatabase(Document.Form1.Text1.Value)

        If Err.Number = 0 Then

            MsgBox db.Title,, "Title"

        Else

            If Err.Number = ERR_SYS_FILE_NOT_FOUND Then

                MsgBox "Change the file name and try again",, _

                "File not found"

            Else

                MsgBox CInt("&H" & Right(Hex(Err.Number),4)),, "Domino error"

            End If

        End If

    End Sub
  11. This ASP code prints the results of a full-text search.

    12. <%@ Language=VBScript %>

    <HTML>

    <HEAD>

    <META NAME="; GENERATOR; " Content="; Microsoft; Visual; Studio; 6#; ">

    </HEAD>

    <BODY>

    <%

    'URL http://yourserver/Demo9.asp?key=keyWord

        Dim s 'As New NotesSession

        Dim db 'As NotesDatabase

        Dim v 'As NotesView

        Dim vn 'As NotesViewNavigator

        Dim e 'As NotesViewEntry

        Dim doc 'As NotesDocument

        Set s = CreateObject("Lotus.NotesSession")

        Call s.Initialize

        Dim serverName

        serverName = ""

        Response.Write("<h2>Full Text Search Result</h2>")

        Dim dbName, keyWord

        keyWord = Request.QueryString("key")

        dbName = "employees.nsf"

        Set db = s.GetDatabase(serverName, dbName)

        If (db is Nothing) then

            Response.Write("<p>Cannot find the database: " + dbName)

        Else

            Response.Write("<p>Database: " + db.FileName + "<br>")

            Response.Write("Key Word: " + keyWord + "<br>")

        End if

        Call db.UpdateFTIndex(true)

        Set dc = db.FTSearch(keyWord, 100)

        Response.Write("Records found: " + CStr(dc.Count) + "<br><br><br>")

        Set doc = dc.GetFirstDocument()

        Dim thisItem

        If Not (doc is Nothing) then

            Response.Write("<table border=1 bgcolor=#CCCCCC>")

            Response.Write("<th>ID")

            Response.Write("<th>First Name")

            Response.Write("<th>Last Name")

            Response.Write("<th>Department")

            Response.Write("<th>Title")

        End if

        While Not (doc Is Nothing)

            Response.Write("<tr>")

            Set thisItem = doc.GetFirstItem("ID")

            Response.Write("<td>" + thisItem.Text + "</td>")

            Set thisItem = doc.GetFirstItem("FirstName")

            Response.Write("<td>" + thisItem.Text + "</td>")

            Set thisItem = doc.GetFirstItem("LastName")

            Response.Write("<td>" + thisItem.Text + "</td>")

            Set thisItem = doc.GetFirstItem("Department")

            Response.Write("<td>" + thisItem.Text + "</td>")

            Set thisItem = doc.GetFirstItem("Title")

            Response.Write("<td>" + thisItem.Text + "</td>")

            Set doc = dc.GetNextDocument(doc)

            Response.Write("</tr>")

        Wend

        Response.Write("</table>")

    %>

    </BODY>

    </HTML>
    Here is an HTML file to drive the ASP.

    <HTML>

    <HEAD>

    <META NAME="GENERATOR" Content="Microsoft Visual Studio 6.0">

    <TITLE></TITLE>

    </HEAD>

    <BODY>

    <form method=GET  action="http://mkoma4/COM_AspSep28/Demo/Demo9.asp">

    <h2>Full Text Search on Employees Database</h2>

    <br>

    <br>

    <P>Input A Keyword:

    <input name=key size=20>

    <br>

    <br>

    <br>

    <input type=reset value="Clear Form">

    <input type=submit value="Submit">

    </form>

    </BODY>

    </HTML>


Using the Domino classes

Domino Designer defines LotusScript classes that allow you to access Domino structures at two levels:

  • The database (back-end) classes allow you to access named databases, views, documents, and other Domino objects. Both workstation and server users can run scripts that access database objects.

  • The UI (front-end) classes allow you to access current objects that the user is working on. Only workstation users can run scripts that access UI objects.

The following table outlines the LotusScript classes defined by Domino Designer.

Level | Class | Description
Database | NotesACL | Represents a collection of all the access control list entries for a database.
 | NotesACLEntry | Represents a single entry in an access control list.
 | NotesAgent | Represents an agent.
 | NotesDatabase | Represents a Domino database.
 | NotesDateRange | Represents a range of dates and times.
 | NotesDateTime | Provides a means to translate between LotusScript and Domino date/time formatting.
 | NotesDbDirectory | Represents the database files on a server or the local machine.
 | NotesDocument | Represents a document in a database.
 | NotesDocumentCollection | Represents a collection of documents.
 | NotesEmbeddedObject | Represents embedded objects, links, and file attachments.
 | NotesForm | Represents a form in a database.
 | NotesInternational | Represents the international settings in the operating system.
 | NotesItem | Represents a piece of data in a document.
 | NotesLog | Represents actions and errors that occur during script execution.
 | NotesMIMEEntity | Represents a NotesItem of type MIME.
 | NotesName | Represents a user or server name.
 | NotesNewsLetter | A summary document that contains information from, or links to, several other documents.
 | NotesOutline | Represents an outline in a database.
 | NotesOutlineEntry | Represents an entry in an outline.
 | NotesRegistration | Represents the registration of an ID file.
 | NotesReplication | Represents the replication settings of a database.
 | NotesRichTextItem | Represents items that can contain rich text.
 | NotesRichTextParagraphStyle | Represents rich text paragraph attributes.
 | NotesRichTextStyle | Represents a rich text style.
 | NotesRichTextTab | Represents rich text tab attributes.
 | NotesSession | Root of Domino database objects--for global attributes, context, and persistent information.
 | NotesTimer | A mechanism for triggering an event every fixed number of seconds.
 | NotesView | Represents a named view of a database.
 | NotesViewColumn | Represents a column of a view.
 | NotesViewEntry | Represents a view entry. A view entry represents a row in a view.
 | NotesViewEntryCollection | Represents a collection of view entries, selected according to specific criteria.
 | NotesViewNavigator | Represents a view navigator. A view navigator provides access to all or a subset of the entries in a view.
UI | Button | Represents an action, button, or hotspot on a form or document.
 | Field | Represents a field on a form.
 | Navigator | Represents an object in a navigator.
 | NotesUIDatabase | Represents the database that's currently open in the Domino workspace.
 | NotesUIDocument | Models the behavior of a Domino document window.
 | NotesUIView | Represents the current database view.
 | NotesUIWorkspace | Provides access to the current workspace.


Accessing Domino databases

The NotesDatabase and NotesDbDirectory classes provide means for locating and opening Domino databases. A NotesDatabase object provides access to NotesView, DocumentCollection, and NotesDocument objects. NotesDocument objects can be accessed directly through a NotesDatabase object, or by first obtaining a NotesDocumentCollection or NotesView object. A NotesDatabase object also provides access to NotesACL and NotesForm objects.

  • Accessing database properties

  • Locating a database on a server and local disk

  • Opening and closing a database

  • Creating a database

  • Examining and adjusting an access control list

  • Accessing a form

  • Accessing an outline


Accessing database properties

The following table lists the NotesDatabase properties.

Property | Data type | Description
ACL | NotesACL | Access control list for the database
Agents | NotesAgent array | Agents in the database
AllDocuments | NotesDocumentCollection | All the documents in the database
Categories | String | (Read-Write) Categories in the database
Created | Date/Time | Date and time the database was created
CurrentAccessLevel | Integer | User's access level to the database
DelayUpdates | Boolean | (Read-Write) True will delay (batch) server input/output for better performance
DesignTemplateName | String | Database design template, if any
FileName | String | Database file name
FilePath | String | Database file path
FolderReferencesEnabled | Boolean | (Read-Write) Determines what folders, if any, a document is in
Forms | NotesForm array | Forms in the database
HttpURL | String | (Read-only) The HTTP URL of a database. For COM only.
IsDirectoryCatalog | Boolean | (Read-only) Indicates if a database is a Directory Catalog database
IsFTIndexed | Boolean | True if the database is full-text indexed
IsMultiDbSearch | Boolean | True if the search index is multi-database
IsOpen | Boolean | True if the database is open
IsPrivateAddressBook | Boolean | True if the database is a Personal Address Book; only valid through AddressBooks in NotesSession
IsPublicAddressBook | Boolean | True if the database is a Domino Directory; only valid through AddressBooks in NotesSession
LastFTIndexed | Date/Time | Date and time a full-text index, if any, was last updated
LastModified | Date/Time | Date and time the database was last modified
Managers | String array | Users that have Manager access to the database
MaxSize | Double | (Read-only) Shows the maximum size assigned to the database
NotesURL | String | (Read-only) The Notes URL of a database. For COM only.
Parent | NotesSession | Session that contains a database.
PercentUsed | Double | Percent of a database's total size that is occupied by real data
ReplicaID | String | Database replica ID in hexadecimal
ReplicationInfo | NotesReplication | (Read-only) Provides access to a NotesReplication object
Server | String | Name of the server containing the database
Size | Double | Database size, in bytes
SizeQuota | Long | (Read-Write) Database size quota, if any; you must be an administrator to write
TemplateName | String | Database template name, if database is a template
Title | String | (Read-Write) Database title
UnprocessedDocuments | NotesDocumentCollection | All documents not yet processed in agent or view
Views | NotesView array | Named views in the database

For further details on accessing the properties and methods of a database, please refer to the Usage section in the NotesDatabase class topic.

See examples
Examples: Accessing database properties


Locating a database on a server and local disk

The NotesDbDirectory class provides a means to locate databases on servers and the user's local disk. To access a particular server, specify its name as the argument to the New method for NotesDbDirectory. The GetFirstDatabase and GetNextDatabase methods return handles to NotesDatabase objects. The Name property contains the name of the server or workstation.

The Parent property, supported in COM only, returns the session that contains the DbDirectory object. In COM, you can access NotesDatabase objects through the following methods in the NotesDbDirectory class.

Methods | Description
CreateDatabase | Creates a new database. For COM only.
OpenDatabase | Opens a database. For COM only.
OpenDatabaseByReplicaID | Opens a database with a specified replica ID. For COM only.
OpenDatabaseIfModified | Opens a database if modified since a specified date. For COM only.
OpenMailDatabase | Opens current user's mail database. For COM only.

See examples
Example: Locating a database on a server and local disk


Opening a database

The New method for the NotesDatabase class opens an existing database if you specify the file name as the second argument. The New method does not create a database. The first argument specifies the server and defaults (empty string) to the local Domino directory.

The second argument specifies the file name of the database. If you specify an empty string here, you must later use one of the Open methods to open the database. If you are running on a server and opening a database on that server, specify the first argument as an empty string.

Use the CurrentDatabase property of NotesSession to access the current database. The current database does not have to be opened.

To open a database whose object you set, for example, using the GetFirstDatabase or GetNextDatabase method of NotesDbDirectory, use the Open method with two empty strings for the arguments.

Use the OpenByReplicaID method to open a database whose server and replica ID are known. You can obtain the replica ID from a database that is already open with the ReplicaID property.

The OpenIfModified method opens a database only if it was modified after a specified date.

The OpenMail method opens the user's mail database.

The OpenWithFailover method opens a database on a server. If the database is not on the server but the server is part of a cluster, this method attempts to open the database on the other servers in the cluster.

See examples
Examples: Opening a database


Creating a database

Use one of the following methods to create a database. The New method does not create a database.

  • Create Creates an uninitialized database. A script can access it, but a user cannot access it from the Notes workspace because it has no forms or views.

  • CreateFromTemplate Creates an initialized database based on an existing database (whether the database is a template or not). The new database has the design and documents of the template and can be accessed from the Notes workspace.

  • CreateReplica Creates an uninitialized replica of an existing database. The replica must be initialized either by you with the Replicate method or by the user accessing it from the Notes workspace upon first use.

  • CreateCopy Creates a copy of the design of an existing database.

See examples
Examples: Creating a database


Accessing an outline

You can access a NotesOutline object through the CreateOutline and GetOutline methods in NotesDatabase. The CreateEntry method in NotesOutline allows you to create a new NotesOutlineEntry object and place it in the outline.

NotesOutline contains the following properties:

Property | Data type | Description
Alias | String | (Read-only) Alias name of the outline, used for programmatic access.
Comment | String | (Read-only) A brief description of the outline.
Name | String | (Read-only) Name of the outline, used for programmatic access.
ParentDatabase | NotesDatabase | (Read-only) The parent database that contains an Outline object. For COM only.

NotesOutline contains the following methods:

Method | Description
AddEntry | Adds a new entry to the outline. This method is obsolete as of Release 5.0.2, but is supported for backward compatibility. Use CreateEntry to add a new entry to an outline.
CreateEntry | Creates a new entry and adds it to an outline.
CreateEntryFrom | Creates a copy of an existing entry. This method is new in Release 5.0.2.
GetChild | Gets the child of the specified entry in an outline. This method is new in Release 5.0.2.
GetFirst | Gets the first entry of an outline.
GetLast | Gets the last entry of an outline.
GetNext | Returns the entry immediately following the specified entry.
GetNextSibling | Given an entry in an outline, returns the entry immediately following it at the same level.
GetParent | Given a response entry in an outline, returns its parent entry.
GetPrev | Given an entry in an outline, returns the entry preceding it.
GetPrevSibling | Given an entry in an outline, returns the entry immediately preceding it at the same level.
MoveEntry | Moves the specified entry from one location to another in an outline.
RemoveEntry | Deletes the specified entry and its subentries from an outline.
Save | Saves any changes made to an outline.

NotesOutlineEntry contains the following properties:

Property | Data type | Description
Alias | String | (Read-only) Alias name of the outline entry, used for programmatic access.
Database | NotesDatabase | (Read-only) Database resource link for an outline entry.
Document | NotesDocument | (Read-only) Document resource link for an outline entry.
EntryClass | Integer | (Read-only) Class of an outline entry.
Formula | String | (Read-only) Formula for an action outline.
FrameText | String | (Read-only) The name of the target frame in which you want the entry to appear.
HasChildren | Boolean | (Read-Write) Indicates whether an entry contains child entries.
HideFormula | String | (Read-Write) The hide formula, if any.
ImagesText | String | (Read-Write) The name of the image file you would use to add an icon to your entry.
IsHidden | Boolean | (Read-Write) Indicates if an entry is hidden in the current context, or sets all contexts.
IsHiddenFromNotes | Boolean | (Read-Write) Indicates if an entry is hidden in the Notes client.
IsHiddenFromWeb | Boolean | (Read-Write) Indicates if an entry is hidden in a Web browser.
IsInThisDb | Boolean | (Read-only) Indicates if an entry refers to an element within the current database.
IsPrivate | Boolean | (Read-only) Indicates if an entry is spcific to an individual.
KeepSelectionFocus | Boolean | (Read-Write) Indicates if an entry keeps selection focus.
Label | String | (Read-Write) Label for an entry.
Level | Long | (Read-Write) Indicates the level of this entry.
NamedElement | String | (Read-only) Named element referenced by an outline entry.
Parent | NotesOutline | (Read-only) The outline that contains an OutlineEntry object. For COM only.
Type | Constant of type Long | (Read-Write) Type of outline entry.
URL | String | (Read-only) The URL of an outline entry.
UseHideFormula | Boolean | (Read-Write) Indicates if an entry uses the hide formula.
View | NotesView | (Read-only) View resource link for an outline entry.

NotesOutlineEntry contains the following methods:

Method | Description
SetAction | Specifies a formula for an action outline entry.
SetNamedElement | Specifies a named element for an outline entry.
SetNoteLink | Specifies a resource link for an outline entry.
SetURL | Specifies a URL as the resource link for an outline entry.

See examples
Examples: Accessing an outline


Examining and adjusting an access control list

You examine and adjust the access control list (ACL) of a database through objects of the following classes:

Class | Contains | To
NotesDatabase | ACL property | Access a NotesACL object
 | CurrentAccessLevel property | Determine the current user access level
 | GrantAccess, RevokeAccess, and QueryAccess methods | Directly create, remove, and check ACL entries
NotesACL | GetEntry, GetFirstEntry, and GetNextEntry methods | Access ACL entries
 | CreateACLEntry method | Create ACL entries
 | RemoveACLEntry | Remove ACL entries in COM only.
 | InternetLevel property | Determine and set the maximum Internet access level for the current database
 | Roles property and AddRole, DeleteRole, and RenameRole methods | Access roles
 | Parent property | Determine the database that owns the ACL
 | UniformAccess property | Enforce, or not enforce, a consistent ACL across all replicas of a database
NotesACLEntry | CanCreateDocuments, CanCreateLSOrJavaAgent , CanCreatePersonalAgent, CanCreatePersonalFolder, CanCreateSharedFolder , CanDeleteDocuments, IsAdminReaderAuthor , IsAdminServer, Level, Name, and Parent properties | Examine the ACL entry
 | NameObject property | Supported in COM only
 | New and Remove methods | Create and remove an entry
 | Roles property and IsRoleEnabled, EnableRole, and DisableRole methods | Associate ACL entries with roles
 | IsPublicReader and IsPublicWriter properties | Become public readers and writers
 | IsGroup , IsPerson , and IsServer properties | Determine and set the user type for an ACL entry

The Save method of NotesACL writes changes you make to the ACL and ACL entries to permanent storage. Otherwise, the changes are lost when your program exits.

See examples
Examples: Examining and adjusting an access control list


Examining and adjusting database replication settings

You examine and adjust the replication settings of a database through the NotesReplication class.

See examples
Examples: Examining and adjusting database replication settings


Resetting the replication properties of a database

The Reset method of the NotesReplication class enables you to reset the replication properties of a database to their last saved values.

See examples
Example: Resetting the replication properties of a database


Saving database replication properties

You can save the replication properties of a database by using the Save() method of the NotesReplication class. If you make changes to database replication properties using the NotesReplication class you must use the Save() method before closing the database, or all changes will be lost.

See examples
Example: Saving database replication properties


Accessing a document

You can access existing documents in a database using the GetDocumentByURL method of NotesDatabase class. This method instantiates a document in the Web Navigator database and returns a NotesDocument object for it.

See examples
Example: Accessing a document


Accessing a form

You can access existing forms in a database as follows:

  • The Forms property of NotesDatabase returns an array of NotesForm objects.

  • The GetForm method of NotesDatabase returns a named NotesForm object.

The NotesForm class provides access to the following form properties:

Property | Data type | Description
Aliases | Array of strings | (Read-only) Aliases of the form
Fields | Array of strings | (Read-only) Names of all the fields of the form
FormUsers | Array of strings | (Read-Write) Contents of the $FormUsers field
HttpURL | String | (Read-only) The HTTP URL of a form. For COM only.
IsSubform | Boolean | (Read-only) True if the form is a subform
Name | String | (Read-only) Name of the form
NotesURL | String | (Read-only) The Notes URL of a form. For COM only.
Parent | NotesDatabase | (Read-only) Database that contains a Form object. For COM only.
ProtectReaders | Boolean | (Read-Write) Protects $Readers items from being overwritten by replication
ProtectUsers | Boolean | (Read-Write) Protects $FormUsers items from being overwritten by replication
Readers | Array of strings | (Read-Write) Contents of the $Readers field

You can remove an existing form from the database with the Remove method of NotesForm.

See examples
Examples: Accessing a form


Accessing views and folders

The NotesView class lets you locate documents within views and folders, and perform operations on views and folders. The NotesView class does not have a New method. You access views and folders through the GetView method and the Views property of NotesDatabase.

  • Accessing view or folder properties

  • Locating a view or folder

  • Accessing view or folder columns

  • Refreshing a view or folder

  • Removing a view or folder

  • Retrieving multiple entries from a view

  • Retrieving an entry from a view

  • Creating view navigators

  • Accessing view entry properties

  • Getting the position of a view entry

  • Accessing a view entry collection

  • Adding an entry to a view entry collection

  • Deleting an entry from a view entry collection

  • Searching for entries in a view entry collection

  • Retrieving entries from a view entry collection

  • Removing documents from a view entry collection

  • Accessing NotesViewNavigator properties

  • Accessing entries in a view navigator

  • Accessing documents in a view navigator

  • Accessing an entry by position


Accessing view or folder properties

The following table lists the view and folder properties.

Property | Data type | Description
Aliases | Array of strings | (Read-only) View names subsequent to first listed name
AutoUpdate | Boolean | (Read-Write) True if the front-end view is updated each time a change occurs in the back-end
BackgroundColor | Integer | (Read-only) The background color of a view
ColumnCount | Integer | (Read-only) The number of columns in a view
ColumnNames | Variant | (Read-only) The names of the columns in a view. For COM only.
Columns | NotesViewColumn array | (Read-only) Columns that are in the view
Created | Date/Time | (Read-only) Creation date and time
AllEntries | NotesViewEntryCollection | (Read-only) All the entries in a view
HeaderLines | Integer | (Read-only) The number of lines in the header of a view
HttpURL | String | (Read-only) The HTTP URL of a view. For COM only.
IsCalendar | Boolean | (Read-only) True if the view is a calendar view
IsCategorized | Boolean | (Read-only) True if the view is categorized
IsConflict | Boolean | (Read-only) True if the view is enabled for conflict checking
IsDefaultView | Boolean | (Read-only) True if this is the default view
IsFolder | Boolean | (Read-only) True if this is a folder
IsHierarchical | Boolean | (Read-only) True if the view is hierarchical
IsModified | Boolean | (Read-only) True if the view is modified
LastModified | Date/Time | (Read-only) Date and time the view was last modified
Name | String | (Read-only) First name listed of the view including cascades
NotesURL | String | (Read-only) The Notes URL of a view. For COM only.
Parent | NotesDatabase | (Read-only) Database containing this view
ProtectReaders | Boolean | (Read-Write) True if the $Readers field is protected from being overwritten during replication
Readers | Array of strings | (Read-Write) Contents of the $Readers field
Rowlines | Integer | (Read-only) The number of lines in each row of the view
Spacing | Integer | (Read-only) The spacing between rows of a view
TopLevelEntryCount | Integer | (Read-only) The number of top-level entries in a view
UniversalID | String | (Read-only) Universal ID of the view

See examples
Examples: Accessing view or folder properties


Locating a view or folder

If you know the name of the view or folder, specify it in the GetView method of NotesDatabase. The view or folder name must be specified exactly, including cascades; for example, "Certificates and ID Information\Cross Certificates" must be specified exactly.

If the name has a synonym, you can specify the name or the synonym. For example, if a view name is By Author and the synonym is AuthorView, you can specify it as either of the following:

"By Author"

"AuthorView"

However, you cannot specify both the name and the alias with the "or" character. For example, "By Author | AuthorView" is illegal.

If you don't know the name of the view or folder, you can compare each view and folder in the Views property of NotesDatabase with one of the NotesView properties; for example, IsDefaultView or UniversalID.

See examples
Examples: Locating a view or folder


Accessing view or folder columns

You can access view or folder columns through the Columns property of NotesView, which returns a NotesViewColumn object. This object gives you access to the following properties.

Property | Data type | Description
Alignment | Constant | (Read-only) The alignment of data in a column
DateFmt | Constant | (Read-only) The specific format of date date in a column
FontColor | Constant | (Read-only) The font color of data in column
FontFace | String | (Read-only) The font face of data in a column
FontPointSize | Integer | (Read-only) The font point size of data in a column
FontStyle | Constant | (Read-only) The font style of data in a column
Formula | String | (Read-only) The column formula if one exists
HeaderAlignment | Constant | (Read-only) The alignment (justification) of the header in a column
IsAccentInsensitiveSort | Boolean | (Read-only) True if the column is sorted with out regard to accent
IsCaseInsensitiveSort | Boolean | (Read-only) True if the column is sorted without regard to case
IsCategory | Boolean | (Read-only) True if the column is categorized
IsField | Boolean | (Read-only) True if the column is based on field values
IsFormula | Boolean | (Read-only) True if the column is based on a formula
IsHidden | Boolean | (Read-only) True if the column is hidden
IsHideDetail | Boolean | (Read-only) True if the column details for totals are hidden
IsIcon | Boolean | (Read-only) True if the column values are displayed as icons
IsResize | Boolean | (Read-only) True if the column is resizable
IsResortAscending | Boolean | (Read-only) True if the resortable column can be resorted in ascending order
IsResortDescending | Boolean | (Read-only) True if the resortable column can be resorted in descending order
IsResortToView | Boolean | (Read-only) True if the column is resortable
IsResponse | Boolean | (Read-only) True if the column contains only response documents
IsSecondaryResort | Boolean | (Read-only) True is the column is a secondary resortable column
IsSecondaryResortDescending | Boolean | (Read-only) True if the secondary resortable column is descending
IsShowTwistie | Boolean | (Read-only) True if the expandable column displays a twistie
IsSortDescending | Boolean | (Read-only) True if the sorted column is descending
IsSorted | Boolean | (Read-only) True if the column is sorted
ItemName | String | (Read-only) Name of the item whose value, if any, is in the column
ListSep | Constant | (Read-only) List (muli-value) separator for values in a column
NumberAttrib | Constant | (Read-only) Attributes for numeric values in a column
NumberDigits | Integer | (Read-only) Number of decimal places for numeric values in a column
NumberFormat | Constant | (Read-only) Format for numeric values in a column
Parent | NotesView | (Read-only) The view that contains a column. For COM only.
Position | Integer | (Read-only) Position of the column in the view, starting at 1
TimeDateFmt | Constant | (Read-only) The format of time-date data in a column
TimeFmt | Constant | (Read-only) The format of time data in a column
TimeZoneFmt | Constant | (Read-only) The format of the zone in time-data in a column
Title | String | (Read-only) Title of the column
Width | Integer | (Read-only) The width of a column

See examples
Examples: Accessing view or folder columns


Refreshing a view or folder

If you update a database with additions, deletions, or changes, the updates are not reflected in a view or folder until it is refreshed. The interactive user can refresh a view or folder by clicking the Refresh button or choosing View - Refresh.

To refresh the stored view, call the Refresh method of NotesView after the updates are made. Document updates must first be posted to storage with the Save method of NotesDocument. For an example, see "Creating a document."

To refresh the view on the user screen, first call Refresh method, then call the ViewRefresh method of NotesView.

You could also refresh a view automatically by setting the AutoUpdate property in the NotesView class.

See also
Creating a document


Removing a view or folder

The Remove method of NotesView removes a view or folder from a database.

See examples
Example: Removing a view or folder


Retrieving multiple entries from a view

The GetAllEntriesByKey method of the NotesView class retrieves all view entries from a view by key.

See examples
Example: Retrieving multiple entries from a view


Retrieving an entry from a view

The GetEntryByKey method of the NotesView class retrieves a view entry from a view by key.

See examples
Example: Retrieving an entry from a view


Creating view navigators

The CreateViewNav method in the NotesView class creates a view navigator for all entries in a view.

See examples
Examples: Creating view navigators


Accessing view entry properties

The NotesViewEntry class lets you access rows in a view. This object gives you access to the following properties.

Property | Data type | Description
ChildCount | Integer | (Read-only) The number of immediate children belonging to the current view entry
ColumnValues | Array of variants | (Read-only) The value if each column in the view entry
DescendantCount | Integer | (Read-only) The number of descendants belonging to the current view entry
Document | NotesDocument | (Read-only) The document associated with the view entry
FTSearchScore | Integer | (Read-only) The full-text search score of a view entry which has been retrieved as part of a full-text search
IndentLevel | Integer | (Read-only) The indent level of a view entry
IsCategory | Boolean | (Read-only) True if the view entry is a category
IsConflict | Boolean | (Read-only) True if the view entry conflict document
IsDocument | Boolean | (Read-only) True if the view entry is a document
Istotal | Boolean | (Read-only) True if the view entry is a total
IsValid | Boolean | (Read-only) True if the view entry is valid
NoteID | String | (Read-only) The note ID of a view entry
Parent | NotesView | (Read-only) The parent ViewEntryCollection, ViewNavigator, or View object of a view entry
SiblingCount | Integer | (Read-only) The number of siblings belonging to the current view entry
UniveralID | String | (Read-only) The universal ID of a document associated with a view entry

See examples
Example: Accessing NotesViewEntry properties


Getting the position of a view entry

The GetPosition method of the NotesViewEntry class returns the position of an entry in the view hierarchy.

See examples
Example: Getting the position of a view entry


Accessing a view entry collection

The NotesViewEntryCollection class allows you to gather view entries according to a specific criterion. The NotesViewEntryCollection class gives you access to the following properties:

Property | Data type | Description
Count | Long | (Read-only) The number of entries in a collection
Parent | NotesView | (Read-only) The view that contains a view entry collection
Query | String | (Read-only) The text of the query that produced a view entry collection

See examples
Example: Accessing a view entry collection


Adding an entry to a view entry collection

You can add an entry to a view collection by using the AddEntry method of the NotesViewEntryCollection class.


Deleting an entry from a view entry collection

You can delete an entry from a view by using the DeleteEntry method in the NotesViewEntryCollection class.


Searching for entries in a view entry collection

The FTSearch method in the NotesViewEntryCollection class allows you to locate specific entries.

See examples
Example: Searching for entries in a view entry collection


Retrieving entries from a view entry collection

The GetEntry method in the NotesViewEntryCollection class retrieves a specified entry in a view entry collection.

See examples
Examples: Retrieving entries from a view entry collection


Removing documents from a view entry collection

The RemoveAll and RemoveAllFromFolder methods in the NotesViewEntryCollection class allow you to permanently remove all documents associated with entries in a view entry collection.

See examples
Examples: Removing documents from a view entry collection


Accessing NotesViewNavigator properties

The NotesViewNavigator class provides access to all entries or a subset of entries in a view. You can create a navigator by using the CreateViewNav, CreateViewNavFrom, CreateViewNavFromCategory, or CreateViewNavFromChildren methods in the NotesView class.

Property | Data type | Description
CacheSize | Long | (Read-Write) The size of the navigator cache in view entries. For COM only.
MaxLevel | Long | (Read-Write) The navigator's maximum level of navigation.
ParentView | NotesView | (Read-only) The parent view of a navigator

See examples
Example: Accessing NotesViewNavigator properties


Accessing entries in a view navigator

The following methods in the NotesViewNavigator class allow you to access entries in a view navigator.

Method | Description
GetChild | Returns the first child (response) of an entry in a view navigator
GetCurrent | Returns the current entry in a view navigator. For COM only.
GetEntry | Returns the current entry in a view navigator. For COM only.
GetFirst | Returns the first entry in a view navigator
GetFirstDocument | Returns the first document in a view navigator, skipping any category entries
GetLast | Returns the last entry ina view navigator
GetLastDocument | Returns the last document entry ina view navigator, skipping any category and totals entries.
GetNext | Returns the next entry in a view navigator
GetNextCategory | Returns the next category entry in a view navigator
GetNextDocument | Returns the next document entry in a view navigator
GetNextSibling | Returns the next sibling entry in a view navigator
GetNth | Returns the nth entry in a view navigator
GetParent | Returns the parent entry in a view navigator
GetPos | Returns the entry at a specified position in a view navigator
GetPrev | Returns the previous entry in a view navigator
GetPrevCategory | Returns the previous category entry in a view navigatory
GetPrevDocument | Returns the previous document entry in a view navigator
GetPrevSibling | Returns the previous sibling entry in a view navigator
GotoChild | Moves the current pointer to the first child of the current or specified entry in a view navigator. For COM only.
GotoEntry | Moves the current pointer to a specified document or view entry. For COM only.
GotoFirst | Moves the current pointer to the first entry in a view navigator. For COM only.
GotoFirstDocument | Moves the current pointer to the first document entry in a view navigator, skipping any category entries. For COM only.
GotoLast | Moves the current pointer to the last entry in a view navigator. For COM only.
GotoLastDocument | Moves the current pointer to the last document entry in a view navigator, skipping any totals and category entries. For COM only.
GotoNext | Moves the current pointer to the next entry of the current or specified entry in a view navigator. For COM only.
GotoNextCategory | Moves the current pointer to the next category entry of the current entry in a view navigator. For COM only.
GotoNextDocument | Moves the current pointer to the next document entry of the current entry in a view navigator. For COM only.
GotoNextSibling | Moves the current pointer to the next sibling entry of the current or specified entry in a view navigator. For COM only.
GotoParent | Moves the current pointer to the parent entry of the current or specified entry in a view navigator. For COM only.
GotoPos | Moves the current pointer to the entry at a specified position in a view navigator. For COM only.
GotoPrev | Moves the current pointer to the entry previous to the current or specified entry in a view navigator. For COM only.
GotoPrevCategory | Moves the current pointer to the previous category entry in a view navigator. For COM only.
GotoPrevDocument | Moves the current pointer to the previous document entry in a view navigator. For COM only.
GotoPrevSibling | Moves the current pointer to the previous sibling entry of the current or specified entry in a view navigator. For COM only.

See examples
Examples: Accessing entries from a view navigator


Accessing documents in a view navigator

You can access documents in a view navigator by using the GetFirstDocument, GetLastDocument, GetNextDocument, or GetPrevDocument methods in the NotesViewNavigator class.

See examples
Examples: Accessing documents in a view navigator


Accessing an entry by position

You can access an entry by its position in the hierarchy of the view navigator by using the GetPos method in the NotesViewNavigator class.

See examples
Examples: Accessing an entry by position


Accessing documents

The NotesDocument class lets you examine and manipulate document properties and contents. You gain access to a NotesDocument object through methods in the NotesDatabase, NotesView, and NotesDocumentCollection classes.

  • Accessing document properties

  • Accessing the current document

  • Collecting all documents and unprocessed documents

  • Collecting documents by searching

  • Adding a document

  • Locating a document by ID

  • Locating documents within a view or folder

  • Creating a document

  • Deleting a document

  • Removing a document

  • Copying a document

  • Mailing a document


Accessing document properties

The following table lists the document properties.

Property | Data type | Description
Authors | String array | (Read-only) Names of users who have saved the document
ColumnValues | Variant array | (Read-only) Column values in parent view, or null; not applicable if document not accessed through a view
Created | DATE variant | (Read-only) Date and time the document was created
EmbeddedObjects | Variant array | (Read-only) Embedded objects in the document
EncryptionKeys | String array | (Read-Write) Keys used to encrypt the document
EncryptOnSend | Boolean | (Read-Write) True if the document is encrypted when mailed
FolderReferences | String array | (Read-only) Shows what folders have references to a particular document
FTSearchScore | Integer | (Read-only) Relevance value if the document was retrieved from a full-text search
HasEmbedded | Boolean | (Read-only) True if the document has embedded objects
HttpURL | String | (Read-only) The HTTP URL of a document. For COM only.
IsDeleted | Boolean | (Read-only) True if the document is deleted
IsNewNote | Boolean | (Read-only) True if the document is created but does not yet exist on disk
IsProfile | Boolean | (Read-only) True if the document is a profile document
IsResponse | Boolean | (Read-only) True if the document is a response document
IsSigned | Boolean | (Read-only) True if the document is signed
IsUIDocOpen | Boolean | (Read-only) True if the document is accessed through a NotesUIDocument object
IsValid | Boolean | (Read only) True if the document exists
Items | NotesItem array | (Read-only) All the items in the document
Key | String | (Read-only) If a profile document, the user name (key) of the profile
LastAccessed | DATE variant | (Read-only) Date and time the document was last accessed
LastModified | DATE variant | (Read-only) Date and time the document was last modified
NameOfProfile | String | (Read-only) If aprofile document, the name of the profile.
NoteID | String | (Read-only)Note ID of the document
NotesURL | String | (Read-only) The Notes URL of a document. For COM only.
ParentDatabase | NotesDatabase | (Read-only) Database that contains the object
ParentDocumentUNID | String | (Read-only) Universal ID of the parent if the document is a response
ParentView | NotesView | (Read-only) View from which the document was retrieved, if any
Responses | NotesDocumentCollection | (Read-only) 1st-level responses to this document, if any
SaveMessageOnSend | Boolean | (Read-Write) True if message is saved when mailed
SentByAgent | Boolean | (Read-only) True if the document was mailed by an agent using the Send method
Signer | String | (Read-only)Name of signer if the document is signed
SignOnSend | Boolean | (Read-Write) True if the document is signed when mailed
Size | Long | (Read-only) Size of document in bytes, including any attachments
UniversalID | String | (Read-Write) Universal ID of the document
Verifier | String | (Read-only) User ID verifying the signature if the document is signed

See examples
Examples: Accessing document properties


Accessing the current document

You can access the back-end document that is currently open through the NotesUIWorkspace, NotesUIDocument, and the NotesUIView classes.

The NotesUIDocument class has the following properties:
Property | Data type | Description
AutoReload | Boolean | (Read-Write) True to automatically reload the current document any time there is a change.
CurrentField | String | (Read-only) The name of the current field if the document is in Edit mode.
DialogBoxCanceled | Boolean | (Read-only) Indicates if a user cancels a dialog.
Document | NotesDocument | (Read-only) A reference to the NotesDocument object associated with this document window, giving you access to the back-end properties and methods. If you modify and save an item using the NotesDocument object, the item is automatically updated in the workspace, except for rich-text items.
EditMode | Boolean | (Read-Write) True for Edit mode.
FieldHelp | Boolean | (Read-Write) True to display field help.
HorzScrollBar | Boolean | (Read-Write) True if the horizonal scroll bar is visible.
HiddenChars | Boolean | (Read-Write) True to display hidden characters.
InPreviewPane | Boolean | (Read-only) True if the document is being accessed from the preview pane.
IsNewDoc | Boolean | (Read-only) True if the document is not yet saved.
PreviewParentDoc | Boolean | (Read-Write) True if the lower pane containing the parent document is displayed.
PreviewDocLink | Boolean | (Read-Write) True if the lower pane containing the linked document is displayed.
Ruler | Boolean | (Read-Write) True if the ruler is visible.
WindowTitle | String | (Read-only) The name of the window title.

The NotesUIDocument class has the following methods.
Method | Description
Categorize | Categorizes the current document.
Clear | Clears the selected text.
Close | Closes the current document.
CollapseAllSections | Collapses all sections in the document.
Copy | Copies the selected text to the Clipboard.
CreateObject | Creates an object in a rich-text item.
Cut | Cuts the selected text and places it on the Clipboard.
DeleteDocument | Marks the current document for deletion and closes it. The NotesUIDocument object is no longer available once you call this method.
DeselectAll | Deselects the entire contents of the current field.
ExpandAllSections | Expands all sections in the document.
FieldAppendText | Appends the specified text to the specified or current field.
FieldClear | Clears the contents of the specified or current field.
FieldContains | Returns True if the specified or current field contains the specified case-sensitive text.
FieldGetText | Gets the text of the specified or current field.
FieldSetText | Sets the specified or current field to the specified text.
FindFreeTimeDialog | Brings up the Find Free Time box.
FindFreeTimeDialogEx | Brings up the Find FreeTime box to allow searches for available meeting times.
FindString | Finds the text in a given field.
Forward | Creates a new mail document and prompts for recipients.
GetObject | Gets a specified object.
GetSelectedText | Gets the selected text in a UI document.
GotoTop | Goes to the first field or scrolls to the top of the document.
GotoBottom | Goes to the last field or scrolls to the bottom of the document.
GotoField | Given a field name, puts the cursor in the specified field in a document.
GotoNextField | Goes to the next field or scrolls so that it is visible.
GotoPrevField | Goes to the previous field or scrolls so that it is visible.
GotoTop | Places the cursor in the first editable field or the first button in a document.
Import | Imports a file to the document.
InsertText | Inserts the specified text at the current cursor position.
NavBarSetText | Sets the URL navigation bar text.
NavBarSpinnerStart | Starts the URL navigation bar spinner.
NavBarSpinnerStop | Stops the URL navigation bar spinner.
Paste | Pastes the Clipboard text to the current cursor position.
Print | Prints the current document.
Refresh | Refreshes the document.
RefreshHideFormulas | Recalculates the hide-when formulas for the current document; this is an expensive operation.
Reload | Refreshes the current document with any changes made to the stored document.
Save | Saves the current document.
SaveNewVersion | Saves the current document as a new version.
SelectAll | Selects the entire contents of the current field.
Send | Mails the current document and closes it.
SpellCheck | Checks the spelling in a document.

The NotesUIView class has the following properties:
Property | Data type | Description
CalendarDateTime | Variant of type DATE | (Read-only) The date and time of the current region in a calendar view.
CaretCategory | Variant | (Read-only) Returns the current category in the view for the current document.
Documents | NotesDocumentCollection | (Read-only) All the documents that the current NotsUIView event is working on.
View | NotesView | (Read-only) The back-end view that corresponds to the currently open view.

The NotesUIView class has the following methods:
Method | Description
Print | Implements the @Command([FilePrint]). Prints the currently open or selected document(s), or the current view.
SelectDocument | Selects the specified document in a view.

For a list of events in NotesUIView, see NotesUIView class.

See examples
Examples: Accessing the current document


Collecting all documents and all unprocessed documents

The AllDocuments property of the NotesDatabase class is a NotesDocumentCollection object that contains all the data documents in a database. The UnprocessedDocuments property applies only to agents and view actions. For agents, this property contains all documents not yet processed by the agent or the result of the search specified to the agent builder, depending on how you create the agent. For view actions, this property contains all selected documents.

The NotesDocumentCollection class has the following properties and methods for accessing documents:

  • Count property and GetNthDocument method can be used to get 1 through Count documents in a For loop.

  • GetFirstDocument and GetNextDocument methods can be used to get the first and next documents in a While loop until the next document is Nothing.

  • GetLastDocument and GetPrevDocument methods can be used to get the last and previous documents in a While loop until the previous document is Nothing.

The documents in a document collection are not ordered.

See "Locating documents within a view or folder" in this chapter, for getting documents in view order.

When you use an agent to work on unprocessed documents, you must mark those documents as updated so that they are recognized as old documents in subsequent runs. Use either the UpdateAll method of NotesDocumentCollection or the UpdateProcessedDoc method of NotesSession.

The NotesDocumentCollection class contains the following properties.

Property | Data type | Description
Count | Long | (Read-only) Number of documents in the collection
IsSorted | Boolean | (Read-only) True if the documents are sorted
Parent | NotesDatabase | (Read-only) Database that contains the collection
Query | String | (Read-only) Text of the query that created the collection

See examples
Examples: Collecting all documents and unprocessed documents

See also
Locating documents within a view or folder


Collecting documents by searching

The FTSearch, UnprocessedFTSearch, Search, and UnprocessedSearch methods of NotesDatabase return a NotesDocumentCollection object containing documents that match a search query. The FTSearch of NotesDocumentCollection refines a NotesDocumentCollection so that only documents that match a search query are retained.

For FTSearch and UnprocessedFTSearch, the search query is a string that meets the Notes rules for full-text search queries, requiring that a search entity be a single word or multiple words enclosed in quotes (double quotes in a LotusScript string constant). Search entities can include ? and * wildcards, and can be combined by ! (not), & (and), and | (or) operators.

For Search and UnprocessedSearch, the search query is a formula.

A database does not have to be full-text indexed for an FTSearch and UnprocessedFTSearch to work, but the search is slower. The UpdateFTIndex method creates or updates a full-text index. The IsFTIndexed property tests for the existence of an index.

See examples
Examples: Collecting documents by searching


Adding a document

The AddDocument method of NotesDocumentCollection allows you to add a document to a document collection.

See examples
Example: Adding a document

See also
NotesDocumentCollection class
AddDocument method


Locating a document by ID

If you have saved or acquired the note ID or universal ID of a document, you can find a single document by specifying the ID in the GetDocumentByID or GetDocumentByUNID method of NotesDatabase. You can get these IDs from the NoteID and UniversalID properties of a NotesDocument object.

See examples
Example: Locating a document by ID


Accessing a NotesDocument object through a view

You can access NotesDocument objects through a NotesView object by using the User view in the Domino Directory.

See examples
Example: Accessing a NotesDocument object through a view


Locating documents within a view or folder

First find and set the view or folder to a NotesView object using the GetView method or the Views property of a NotesDatabase object.

Traversing a view

Use the GetFirstDocument (or GetLastDocument) method of NotesView followed by a loop of GetNextDocument (or GetPrevDocument) methods to traverse all the documents in a view or folder.

Getting a document at a known position in a view

Use the GetNthDocument of NotesView to get a document at a known position within the top-level (main) documents of a view or folder. This method does not access response documents.

Subsetting a view with a full-text search

The FTSearch method of NotesView creates a subset of the view or folder consisting of documents that match a search query. The search query, specified as the first argument of FTSearch, is a string that meets the rules for full-text search queries. The rules require that a search entity be a single word or multiple words enclosed in quotes (double quotes in a LotusScript string constant). Search entities can include ? and * wildcards, and can be combined by ! (not), & (and), and | (or) operators.

A database does not have to be full-text indexed for a search to work, but the search is slower. The UpdateFTIndex method of NotesDatabase creates or updates a full-text index. The IsFTIndexed property of NotesDatabase tests for the existence of an index.

After creating the subset view or folder, traverse it using GetFirstDocument (or GetLastDocument) of NotesView and GetNextDocument (or GetPrevDocument). The subsetted view is flat; that is, no response hierarchy exists.

Use the Clear method of NotesView to restore the full view or folder.

Subsetting a view with a sorted column key

Use the GetDocumentByKey method to find the first document in a view or folder that matches specified character strings in the sorted columns. For example, if columns 1 and 2 are sorted, you can specify one character string to find a match in the first column, or two strings to find a match in the second column after the first column is matched. You can specify a partial or exact match on the keys.

Use the GetAllDocumentsByKey method to find all documents in a view or folder that match specified character strings in the sorted columns. This technique does not set the ColumnValues property in the retrieved documents; if this is a concern, use GetDocumentByKey to find the first matching document, then use GetNextDocument to find subsequent documents that might also match -- you have to check that they do.

Working with response documents

Use the GetNextSibling and GetPrevSibling methods of NotesView to skip documents that are at a different level from the current document in the response hierarchy. For example, if you have accessed a main document that has response documents, GetNextSibling gets the next main document whereas GetNextDocument gets the first response document to the current main document.

Use the GetChild method to get the first document at the next lower level to the current document. Use the GetParentDocument method to move up a level; you can also pass the ParentDocumentUNID property of NotesDatabase to the GetDocumentByUNID method.

Use the Responses property of NotesDocument to collect all the first-level responses for a document in a NotesDocumentCollection object. The object contains zero responses if the document is not a parent. To obtain response documents at subsequent levels, you must access the Responses property for every response document at each level. Documents collected in the Responses property do not have a particular order.

Use the IsResponse property of NotesDocument to see if a document is a response document.

Use the MakeResponse method to make one document a response to another.

Putting a document in a folder

Use the PutAllInFolder method of NotesDocumentCollection or the PutInFolder method of NotesDocument to copy documents to a public or private folder. Use the RemoveAllFromFolder method of NotesDocumentCollection or the RemoveFromFolder method of NotesDocument to remove a document from a public or private folder.

See examples
Examples: Locating documents within a view or folder


Creating a document

Use the New method of a NotesDocument object to create a new document in a database.

See "Creating an item and assigning values" in this chapter, for instructions on adding item values.

Use the Save method of NotesDocument to post the new document to the database in storage. Otherwise, the new document is lost when the program exits.

See examples
Example: Creating a document

See also
Creating an item and assigning values


Deleting a document

The DeleteDocument method of NotesDocumentCollection deletes a document from a document collection, but does not delete it from the disk.

See examples
Example: Deleting a document

See also
NotesDocumentCollection class
DeleteDocument method


Removing a document

The Remove method of NotesDocument removes a document from a database. The RemoveAll method of NotesDocumentCollection removes all documents in a collection from a database. An argument permits you to force the removal (True) or make it conditional on the document not being modified by someone else since the program started (False).

See examples
Example: Removing a document


Copying a document

The CopyToDatabase method copies a document to a specified database (which can be the same database in which the document exists).

See examples
Examples: Copying a document


Mailing a document

Use the Send method of NotesDocument to mail a document. You can specify the recipient in the second argument or omit the argument and use the SendTo field of the document. Specify the first argument as True to include the form in the mailed document.

If you have only Reader access to a database, you can run a LotusScript agent that creates and sends a document, but the agent will not work if you attach a file to that document.

To save the document after it is mailed, you can set the SaveMessageOnSend property to True before mailing the document.

To sign the mail, use the Sign method of NotesDocument before sending the mail. Use the Save method afterwards if you want to save the signature.

To encrypt the mail, set the EncryptOnSend property of NotesDocument to True before sending the mail. Do not use the Encrypt method.

Use the CreateReplyMessage method of NotesDocument to create a new document that is a reply to the current document. The new document uses the default mail form for replies.

See examples
Example: Mailing a document


Accessing items

The NotesItem and NotesRichTextItem classes let you examine and manipulate item properties and contents. You gain access to a NotesItem or NotesRichTextItem object through various methods in the NotesDocument class. The NotesRichTextItem class inherits from NotesItem, meaning that NotesRichTextItem objects can use all the properties and methods of NotesItem. You can:

  • Access item properties

  • Get an item and its values

  • Create an item and assign values

  • Copy an item

  • Remove an item

  • Work with a rich text item

  • Work with a MIME entity

  • Work with an embedded object

  • Access rich text style properties

  • Access rich text paragraph style properties

  • Work with tabs


Accessing item properties

Property | Data type | Description
DateTimeValue | NotesDateTime | (Read-Write) Date/time value of an item of type Date/time.
IsAuthors | Boolean | (Read-Write) True if the item is of type Authors.
IsEncrypted | Boolean | (Read-Write) True if the item is encrypted
IsNames | Boolean | (Read-Write) True if the item is of type Names.
IsProtected | Boolean | (Read-Write) True if Editor access is required to modify
IsReaders | Boolean | (Read-Write) True if the item is of type Reader Names
IsSigned | Boolean | (Read-Write) True if the item is signed
IsSummary | Boolean | (Read-Write) True if the item can appear in a view; by default, False if you create a new NotesItem object, but True if you if you use the item name as document property
LastModified | Date/Time | (Read-only) Date and time the item was last modified.
Name | String | (Read-only) Name of the item.
Parent | NotesDocument | (Read-only) The document that contains the item.
SaveToDisk | Boolean | (Read-Write) True if the item is saved to disk when the document is saved.
Text | String | (Read-only) Plain text representation of the item's value.
Type | Integer constant | (Read-only) The data type of an item.
ValueLength | Integer | (Read-only) Size in bytes of an item's values in bytes.
Values | String or double array, or string | (Read-Write) Values that an item holds

The Values property is a string for rich text items, an array of doubles for number and time-date items, and an array of strings for all other data types including plain text. For a single value in a non-rich text item, access element 0. If the item contains multiple values, access each array element, for example, in a Forall loop. Access a rich text item as a simple value, not an array.

The Text property of NotesItem displays the complete Values array with the display separator, typically the semicolon, between elements. This property converts non-text data types to text.

See examples
Example: Accessing item properties


Getting an item and its values

The NotesDocument class provides several properties and methods to access the items in the document. If you do not know the name of an item or want to traverse the items in a document, you can use the Items property, an array of NotesItem objects. As you access each array element, use the NotesItem properties and methods to interrogate and manipulate the object.

To access an item whose name is known, use the GetFirstItem of NotesDocument.

You can get the value of an item through several techniques. The first two techniques do not require that you first access the item object.

  • After accessing the NotesDocument object containing the item, you can specify the item name as though it were a property of the document. For example, if doc is the name of a document object and Subject is an item in the document, doc.Subject is the value of the item.

  • You can use the GetItemValue method of NotesDocument.

  • You can access the item and examine its Values property.

Two items can have the same name. To access an item other than the first item, use the Items property of NotesDocument.

See examples
Examples: Getting an item and its values


Creating an item and assigning values

The New method of the NotesItem class creates a new item in a document and assigns a value to it. You can also use the AppendItemValue method of the NotesDocument class to create a new item. If another item exists with the same name, the new item does not replace that item but becomes an additional item.

To assign and reassign values to an item, you can:

  • Write to the item name as though it were a property of the document. For example, if doc is the name of a document object and Subject is an item in the document, you can write to doc.Subject. The assigned value can be any LotusScript data type, scalar or array, a reference to a NotesItem object, a reference to a NotesDateTime object, or a reference to a NotesDateRange object.

  • Use the ReplaceItemValue method of NotesDocument. This is equivalent to the first technique.

  • Access the item and write to its Values property.

Writing to the Values property affects only the current item object, while the other techniques replace all values of all items with the specified name.

After creating or replacing an item, you must call the Save method for the NotesDocument object containing the item or the update is lost when the program exits.

Computed fields are not recalculated when you save a document. If you change items that affect a computed field and want the new value to be available immediately (for example, if you want the user to see the new value in a view or you want to use the new value in a calculation), you must calculate the value in the script.

The user cannot see the new item as a field in the document unless you add the field to the form design. However, the item exists and can be accessed programmatically.

An item cannot appear in a view unless the IsSummary property is True. IsSummary is always False for rich text items, which cannot appear in views. IsSummary is initially False if the item is created with New or ReplaceItemValue.

You can replace the value of an item in every document of a document collection with the StampAll method of NotesDocumentCollection. This method writes immediately to the back-end document. Be sure to save all documents (Save method of NotesDocument) that you have modified in the script before using StampAll on them. You do not have to save after StampAll.

See examples
Examples: Creating an item and assigning values


Copying an item

Use the CopyItemToDocument method of the NotesItem class to copy the current item to another document. Use the CopyAllItems method of NotesDocument to copy all items in the current document to another document.

Use the CopyItem method of NotesDocument to copy an item to another item in the same document.

After copying an item, you must call the Save method for the NotesDocument object containing the new item or the update is lost when the program exits.

See examples
Examples: Copying an item


Removing an item

Use either the Remove method of the NotesItem class or the RemoveItem method of NotesDocument to remove an item from a document. The Remove method removes only the current object--other items with the same name remain in existence. The RemoveItem method removes all items with the specified name.

After removing an item, you must call the Save method for the NotesDocument object that contained the item or the update is lost when the program exits.

See examples
Examples: Removing an item


Working with a rich-text item

The NotesRichTextItem class inherits from NotesItem and so has the same properties and methods. NotesRichTextItem has an additional property for embedded objects and additional methods for creating items and working with embedded objects. If you do not need the additional property and methods, you can access a rich-text item as either a NotesItem or NotesRichTextItem object.

The NotesRichTextItem class has only one property:

Property | Data type | Description
EmbeddedObjects property | Array of NotesEmbeddedObjects | (Read-only) All the embedded objects, object links, and file attachments contained in a rich-text item.

The NotesRichTextItem class contains the following methods:

Method | Description
AddNewLine | Appends one or more new lines (carriage returns) to the end of a rich-text item.
AddPageBreak | Places a hard page break at the end of a NotesRichTextItem
AddTab | Appends one or more tabs to the end of a rich-text item.
AppendDocLink | Given a database, view, or document to link to, adds a link to the end of a rich-text item.
AppendParagraphStyle | Appends a paragraph style at the end of a NotesRichTextItem. Text in the current paragraph is rendered using that paragraph styles' attributes.
AppendRTItem | Appends the contents of one rich-text item to the end of another rich-text item.
AppendStyle | Appends a style to the end of a rich-text item. Text following the style is rendered using that styles's attributes until another style is appended.
AppendText | Appends text to the end of a rich-text item. The text is rendered with the current style of the item.
EmbedObject | Given the name of a file or an application, does one of the following: attaches the file you specify to a rich-text item, embeds an object in a rich-text item, or places an object link in a rich-text item.
GetEmbeddedObject | Given the name of an embedded object or an object link in a rich-text item, returns the corresponding NotesEmbeddedObject.
GetFormattedText | Returns the contents of a rich-text item as plain text.
New | Creates a new rich-text item.

Updates to rich text items accessed through NotesUIDocument are not immediately incorporated into the NotesUIDocument object. You must close and open the document to see the updates.

See examples
Examples: Working with a rich-text item


Working with a MIME entity

The NotesMIMEEntity class is used to read items of type MIME (Multipurpose Internet Mail Extensions). MIME defines methods for handling 8-bit data, character sets, and a variety of content types, including rich text. MIME also allows for structured messages, where a message can have multiple parts and relations between the parts.

A typical example is an Internet mail routed to a mailfile without conversion to rich text. Such NotesItems are of type MIME_PART, and typically named "Body." These NotesItems are accessible programmatically as rich-text items (default), or as MIME entities. .

The following table lists the properties of NotesMIMEEntity.

Property | Data type | Description
ContentAsText | String | (Read-only) The text content of a MIME entity.
ContentSubType | String | (Read-only) The sub-type of the content type of a MIME entity.
ContentType | String | (Read-only) The content type of a MIME entity.
Headers | String | (Read-only) The RFC822 header fields, as one string.

The NotesMIMEEntity class contains the following methods:

Method | Description
GetFirstChildEntity | Returns the first MIMEEntity that is contained within an outer/parent multipart MIMEEntity.
GetNextSibling | Returns the next MIMEEntity that is contained (at the same level as the current MIMEEntity) within an outer/parent multipart MIMEEntity.
GetParentEntity | Returns the outer/parent MIMEEntity that contains the current MIMEEntity.

See examples
Examples: NotesMIMEEntity class

See also
ConvertMime property


Accessing rich-text style properties

You can access rich-text style properties through the NotesRichTextStyle class. The NotesRichTextStyle class contains the following properties:

Property | Data Type | Description
Bold | Boolean or Constant | (Read-Write) Bold rich-text attribute.
Effects | Constant | (Read-Write) Effects (emboss, extrude, etc.).
FontSize | Integer | (Read-Write) Font size in points.
Italic | Boolean or Constant | (Read-Write) Italic rich-text attribute.
NotesColor | Constant | (Read-Write) Color rich-text attribute.
NotesFont | Constant | (Read-Write) Font rich-text attribute.
Parent | NotesSession | The session that contains a RichTextStyle object. For COM only.
PassThruHTML | Boolean | (Read-Write) HTML attribute.
StrikeThrough | Boolean or Constant | (Read-Write) Strikethrough rich-text attribute.
Underline | Boolean or Constant | (Read-Write) Underline rich-text attribute.

Use a NotesRichTextStyle object with the AppendStyle method of NotesRichTextItem. At creation, all the NotesRichTextStyle properties are STYLE_NO_CHANGE.

See examples
Examples: Accessing rich-text style properties

See also
NotesRichTextStyle class


Accessing rich-text paragraph style properties

The NotesRichTextParagraphStyle allows you to access the following attributes of a rich-text paragraph object:

Property | Data type | Description
Alignment | Constant | (Read-Write) Alignment attribute of a rich-text paragraph.
FirstLineLeftMargin | Long | (Read-Write) First line left margin attribute of a rich-text paragraph.
InterLineSpacing | Constant | (Read-Write) Interline spacing attribute of a rich-text paragraph.
LeftMargin | Long | (Read-Write) Left margin attribute of a rich-text paragraph.
RightMargin | Long | (Read-Write) Right margin attribute of a rich-text paragraph.
SpacingAbove | Constant | (Read-Write) Spacing above attribute of a rich-text paragraph.
SpacingBelow | Constant | (Read-Write) Spacing below attribute of a rich-text paragraph.
Tabs | Variant | (Read-only) Tabs in a rich-text paragraph style.

Use the CreateRichTextParagraphStyle method of NotesSession to create a new rich-text paragraph style object.

See examples
Examples: Accessing rich-text paragraph style properties

See also
NotesRichTextParagraphStyle class


Working with tabs

You can manipulate the tabs in a rich-text paragraph style object through the ClearAllTabs, SetTab, and SetTabs and Clear methods in the NotesRichTextParagraphStyle and RichTextTab classes.

The following table lists the properties in the RichTextTab class.

Property | Description
Position | (Read-only) Position of a tab in a rich-text paragraph style
Type | (Read-only) Type of tab

See examples
Examples: Working with tabs

See also
NotesRichTextTab class
NotesRichTextParagraphStyle class


Accessing sessions

The NotesSession class provides a means for accessing attributes of the user environment and persistent information about agents. It also provides methods for accessing environment variables.

The user environment is either:

  • The server or workstation containing the script's database in the following cases: An agent whose trigger is If New Mail Has Arrived, or an agent whose trigger is On Schedule.

  • The workstation of the current user in all other cases.

A script has only one Domino session, so successive calls to the New method return the same session handle. You do not need the session handle to access databases or perform other operations in Domino Designer, only to access the session properties and methods.

See the following topics:

  • Accessing session properties

  • Using environment variables

  • Accessing agents

  • Accessing international settings

See also
Accessing the Domino Objects through COM


Accessing session properties

The following table lists the NotesSession properties.

See "Accessing the current document" in this chapter, for a discussion of CurrentDatabase. See "Accessing Notes agents" for a discussion of CurrentAgent.

Property | Data type | Description
AddressBooks | NotesDatabase array | (Read-only) Accessible Public and Personal Address books, both local and remote
CommonUserName | String | (Read-only) Common name of the current server or user
ConvertMime | Boolean | (Read-Write) True if items of type MIME_PART are converted to rich text upon instantiation
CurrentAgent | NotesAgent | (Read-only) Agent in which the program is running
CurrentDatabase | NotesDatabase | (Read-only) Database in which the program is running
DocumentContext | DocumentContext | (Read-only) In-memory document created by an external program through the Notes API
EffectiveUserName | String | (Read-only) User ID of the creator of the current script
HttpURL | String | (Read-only) The Http URL of a session. For COM only.
International | NotesInternational | (Read-only) The international (regional) settings for your operating environment.
IsOnServer | Boolean | (Read-only) True if the program is running on a server
LastExitStatus | Integer | (Read-only) Status the last time the script ran, if an agent
LastRun | Date/Time | (Read-only) Date and time the script last ran, if an agent
NotesBuildVersion | String | (Read-only) Build version of Domino Designer.
NotesURL | String | (Read-only) The Notes URL of a session. For COM only.
NotesVersion | String | (Read-only) Version of Domino Designer.
Platform | String | (Read-only) Operating system platform
SavedData | NotesDocument | (Read-only) Document that stores data between agent invocations, if an agent
ServerName | String | (Read-only) The full name of the server. For COM only.
URLDatabase | NotesDatabase | (Read-only) Database object representing the default Web Navigator database. For COM only.
UserName | String | (Read-only) User ID (hierarchical name) of the current server or user
UserNameList | Array of NotesName | (Read-only) Returns all the usernames on a session, including primary and alternate names.
UserNameObject | NotesName | (Read-only) The name of the user or server that created the session. For COM only.

See examples
Example: NotesSession class
Examples: Accessing session properties

See also
Accessing agents
Accessing the current document


Using environment variables

The GetEnvironmentValue, GetEnvironmentString, and SetEnvironmentVar methods retrieve and set environment variables, which are stored in the local NOTES.INI or Preferences file. Use GetEnvironmentValue only for numeric environment variables. Use GetEnvironmentString for strings and numeric values.

SetEnvironmentVar prepends a dollar sign ($) to parameter 1, the name of the environment variable, if the third parameter is false or omitted. The dollar sign distinguishes user environment variables (name starts with a dollar sign) and system environment variables (name does not start with a dollar sign). GetEnvironmentValue and GetEnvironmentString prepend a dollar sign if the second parameter is false or omitted, and do not prepend a dollar sign if the second parameter is true.

Environment variables are useful for saving state and data between sessions on a single server or workstation where no conflicts are possible. They are also useful for obtaining the environment information set by Domino Designer, such as KitType, Directory, Preferences, Domain, Port, and so on.

See examples
Examples: Using environment variables


Accessing agents

The NotesAgent class represents an agent. You can access the current agent through the CurrentAgent property of NotesSession; this property is empty if the script is not running as an agent. You can access all agents in a database through the Agents property of NotesDatabase; this property is empty if the database contains no agents. You can access a named agent in a database through the GetAgent method of NotesDatabase.

The following table lists the NotesAgent properties.

Property | Data type | Description
Comment | String | (Read-only) Comment entered by agent designer
CommonOwner | String | (Read-only) Common name of the user who last modified the agent
HasRunSinceModified | Boolean | (Read-only) True if the agent has run since it was created or last modified
HttpURL | String | (Read-only) The HTTP URL of an agent. For COM only.
IsEnabled | Boolean | (Read-Write) True if the agent can run
IsNotesAgent | Boolean | (Read-only) True if the agent can run in the Domino client environment
IsPublic | Boolean | (Read-only) True if the agent is public
IsWebAgent | Boolean | (Read-only) True if the agent can run in a Web browser environment
LastRun | Date variant | (Read-only) Date that the agent last ran
Name | String | (Read-only) Name of the agent
NotesURL | String | (Read-only) The Notes URL of an agent. For COM only.
Owner | String | (Read-only) Name of the creator of the agent
ParameterDocID | String | (Read-only) The NoteID of a document
Parent | NotesDatabase | (Read-only) Database that contains the agent
Query | String | (Read-only) Query used by the agent to select documents
ServerName | String | (Read-Write) Name of the server on which the agent runs
Target | Boolean or Constant | (Read-only) Indicates which documents the agent acts on
Trigger | Boolean or Constant | (Read-only) Indicates when the agent runs

The NotesAgent class contains a Remove method to remove the agent from the database.

The SavedData property of NotesSession returns a NotesDocument object. The agent can use this document to store data that is persistent across invocations of the agent. However, if the agent is modified in any way, the saved data document is cleared. This document is not accessible from the parent NotesDatabase object or from a NotesView object.

The Run method runs the agent on the computer running the current program. The RunOnServer method runs the agent on the computer containing the agent's database.

See examples
Examples: Accessing agents


Accessing international settings

The NotesInternational class represents the international (regional) settings of the operating environment. You can access the international settings through the International property of NotesSession.

The following table lists the NotesInternational properties. They are read-only.

Property | Data type | Description
AMString | String | (Read-only) String that denotes AM time
CurrencyDigits | Integer | (Read-only) Number of decimal digits in number format
CurrencySymbol | String | (Read-only) Symbol that indicates a number is currency
DateSep | String | (Read-only) Character used to separate months, days, and years
DecimalSep | String | (Read-only) Decimal separator in number format
IsCurrencySpace | Boolean | (Read-only) True if the currency format has a space between the currency symbol and the number
IsCurrencySuffix | Boolean | (Read-only) True if the currency symbol follows the number in the currency format
IsCurrencyZero | Boolean | (Read-only) True if fractions have a zero before the decimal point in number format
IsDateDMY | Boolean | (Read-only) True if the order of the date format is day-month-year
IsDateMDY | Boolean | (Read-only) True if the order of the date format is month-day-year
IsDateYMD | Boolean | (Read-only) True if the order of the date format is year-month-day
IsDST | Boolean | (Read-only) True if the date format reflects daylight-savings time
IsTime24Hour | Boolean | (Read-only) True if the time format is 24-hour
Parent | NotesSession | (Read-only) The session that contains a NotesInternational object. For COM only.
PMString | String | (Read-only) String that denotes PM time
ThousandsSep | String | (Read-only) Thousands separator in number format
TimeSep | String | (Read-only) Character used to separate hours, minutes, and seconds
TimeZone | Integer | (Read-only) Time zone
Today | String | (Read-only) String that means today in a time-date specification
Tomorrow | String | (Read-only) String that means tomorrow in a time-date specification
Yesterday | String | (Read-only) String that means yesterday in a time-date specification

See examples
Example: NotesInternational class


Accessing supporting Domino objects

The NotesDateTime, NotesLog, NotesNewsLetter, NotesTimer, and NotesName classes allow you to:

  • Convert between Domino Designer and LotusScript time

  • Make a Domino log

  • Make a Domino newsletter

  • Set up a timer

  • Represent a name


Converting between Domino Designer and LotusScript time

The formats of a Domino Designer date-time item and a LotusScript date variant differ. For example, you cannot put a LotusScript date variant in a Domino Designer date-time item or manipulate a Domino Designer time-date item with LotusScript date functions.

The NotesDateTime class converts between formats by representing both formats as properties. For example, you can get the value of a Domino Designer date-time item by setting the LocalTime property, which is in Domino Designer format, and then manipulate the value with LotusScript functions by accessing the LSLocalTime property of the same object.

The following table lists the NotesDateTime properties.

Property | Data type | Description
DateOnly | String | (Read-only) Date part of Domino Designer date-time in local time
GMTTime | String | (Read-only) Domino Designer date-time in Greenwich Mean Time
IsDST | Boolean | (Read-only) True if the time is daylight-saving time
LocalTime | String | (Read-Write) Domino Designer date-time in local time
LSGMTTime | Date variant | (Read-only) LotusScript date-time in Greenwich Mean Time
LSLocalTime | Date variant | (Read-Write) LotusScript date-time in local time
Parent | NotesSession | (Read-only) The session that contains a DateTime object. For COM only
TimeOnly | String | (Read-only) Time part of Domino Designer date-time in local time
TimeZone | Integer | (Read-only) Hours that must be added to the time to get Greenwich Mean Time
ZoneTime | String | (Read-only) Domino Designer date-time adjusted for TimeZone and IsDST, which can be changed with ConvertToZone

The NotesDateRange class represents a range of dates. The following table lists the NotesDateRange properties. When you set a NotesDateRange object, either write to StartDate and EndDate, or Text, but not both. Values written to StartDate or EndDate are immediately transcribed to Text, and vice-versa.

Property | Data type | Description
EndDateTime | NotesDateTime | (Read-Write) Domino Designer date-time in local time
Parent | NotesSession | (Read-only) The session that contains a DateRange object For COM only
StartDateTime | NotesDateTime | (Read-Write) The starting date-time of the range
Text | string | (Read-Write) The range as two date-time strings separated by a hyphen

See examples
Example: Converting between Domino Designer and LotusScript time


Making a Domino log

The NotesLog class provides these methods for opening a log:

  • OpenFileLog opens a file for logging.

  • OpenMailLog opens a mail memo for logging. The memo is mailed when the log is closed.

  • OpenNotesLog opens a database for logging. Each log entry is a Domino document with the items A$PROGNAME, A$LOGTIME, A$USER, A$LOGTYPE, A$ACTION, A$ERRCODE, and A$ERRMSG. Use the system template ALOG.NTF to create databases suitable for logging.

  • OpenAgentLog opens an agent log for logging. This method is valid only in an agent. Each agent has an associated log that is accessible through Agent - Log when the agent is selected.

The Close method closes a log.

These methods make entries in the log:

  • LogAction logs an action.

  • LogError logs an error.

The LogEvent method can be used on servers to generate Domino events on the network, including events that can be seen by the NotesView product.

The following table lists the NotesLog properties.

Property | Data type | Description
LogActions | Boolean | (Read-write) True to enable action logging; true unless you set it to false
LogErrors | Boolean | (Read-write) True to enable error logging; true unless you set it false
NumActions | Integer | (Read-only) Number of actions logged so far
NumErrors | Integer | (Read-only) Number of errors logged so far
OverwriteFile | String | (Read-write) True to write over an existing file rather than to append; false unless you set it true
Parent | NotesSession | (Read-only) The session that contains a NotesLog object. For COM only.
ProgramName | String | (Read-write) Name of the script to which the entries apply; this string precedes each log entry

See examples
Example: Making a Domino log


Making a Domino newsletter

A newsletter is a summary document containing information from and/or links to other documents. The essential steps for creating a newsletter are:

  1. Use the New keyword in the Dim statement to create a NotesNewsletter object.

  2. Call one of the following NotesNewsletter methods to create a document: FormatDocument to create a NotesDocument object that contains a rendering of other documents; FormatMsgWithDoclinks to create a document that contains doclinks to other documents plus header information.

You can use the Send method of NotesDocument to mail the resulting newsletter.

The following table lists the NotesNewsletter properties.

Property | Data type | Description
DoScore | Boolean | (Read-Write) True if the newsletter includes each document's relevance score
DoSubject | Boolean | (Read-Write) True if the newsletter includes each document's subject
Parent | NotesSession | (Read-only) The session that contains a Newsletter object. For COM only.
SubjectItemName | String | (Read-Write) Name of the field in each source document containing the subject; this is how NotesNewsletter tags each link

See examples
Example: Making a Domino newsletter


Setting up a timer

A timer allows you to call an event handler every specified number of seconds. The essential steps for creating a timer are:

  1. In a (Declarations) or (Options) script that is global to all the other scripts in the application, use the Dim statement to assign a reference variable to a NotesTimer object.

  2. In executable code, use the Set statement to create the NotesTimer object. The first parameter is the interval, in seconds, at which the event handler is called. The second, optional parameter is any comment. You can also use the CreateTimer method of NotesSession.

  3. Use the On Event statement to establish an event handler for the Alarm event of the NotesTimer object.

  4. Write a user sub to handle the event.

The interval is not guaranteed; other activities on the computer involving script may delay the event.

The following table lists the NotesTimer properties.

Property | Data type | Description
Comment | String | (Read-Write) Any comment; second parameter when object is created
Enabled | Boolean | (Read-Write) True (the default) if the NotesTimer object is active
Interval | Integer | (Read-Write) Interval, in seconds, at which the event handler is called; first parameter when object is created

See examples
Examples: NotesTimer class


Representing a name

A NotesName object allows you to represent a Notes user or server name so that you can access the parts of the name as properties. Use the New method of NotesName or the CreateName method NotesSession to establish the object and specify the name. If the name is in the form of a hierarchical name, it is treated as a hierarchical name; otherwise, it is treated as a flat name.

The following table lists the NotesName properties.

Property | Data type | Description
Abbreviated | String | (Read-only) Abbreviated form of hierarchical name.
Addr821 | String | (Read-only) Internet address in the format based on FRC821 Address Format Syntax.
Addr822Comment1 | String | (Read-only) Comment1 component of Internet address in the format based on RFC 822 Address Format.
Addr822Comment2 | String | (Read-only) Comment2 component of the Internet address is the format based on RFC 822 Address Format.
Addr822Comment3 | String | (Read-only) Comment3 component of the Internet address is the format based on RFC 822 Address Format.
Addr822LocalPart | String | (Read-only) LocalPart component of Internet address in the format based on RFC 822 Address Format.
Addr822Phrase | String | (Read-only) Phrase component of Internet address in the format based on RFC 822 Address Format.
ADMD | String | (Read-only) Administration management domain name part of a name.
Canonical | String | (Read-only) Canonical form of a hierarchical name.
Common | String | (Read-only) Common name (CN=) component of a hierarchical name.
Country | String | (Read-only) Country (C=) component of a hierarchical name.
Generation | String | (Read-only) Generation part of a name, for example, "Jr."
Given | String | (Read-only) Given part of a name.
Initials | String | (Read-only) Initials part of a name.
IsHierarchical | Boolean | (Read-only) True if the name is hierarchical.
Keyword | String | (Read-only) Country\organization\organizational unit 1\organizational unit 2\organizational unit 3\organizational unit 4.
Language | String | (Read-only) The language code associated with a name. Returns null if the property is undefined.
Organization | String | (Read-only) Organization (O=) component of a hierarchical name.
OrgUnit1 | String | (Read-only) First organizational unit (OU=) component of a hierarchical name.
OrgUnit2 | String | (Read-only) Second organizational unit (OU=) component of a hierarchical name.
OrgUnit3 | String | (Read-only) Third organizational unit (OU=) component of a hierarchical name.
OrgUnit4 | String | (Read-only) Fourth organizational unit (OU=) component of a hierarchical name.
Parent | NotesSession | (Read-only) The session that contains a Name object. For COM only.
PRMD | String | (Read-only) Private management domain name part of a name.
Surname | String | (Read-only) Surname part of a name.

See examples
Example: NotesName class


Accessing external databases through LS:DO

You can programmatically access external databases from Domino using the LotusScript Data Object (LS:DO). LS:DO is a LotusScript extension library that provides classes for working with Open Database Connectivity (ODBC) in an object-oriented, event-driven programming environment. LS:DO supports the OBDC Version 2.0 standard on multiple platforms, including Windows, OS/2, AIX, Solaris, and HP-UX. The LS:DO is available on both the Notes client and the Domino server. It works in both single- and multi-thread environments.

LS:DO is a set of three LotusScript classes, which come equipped with a powerful set of properties and methods, as well as full SQL capabilities:

  • ODBCConnection

  • ODBCQuery

  • ODBCResultSet

You can use the properties and methods in these classes to access an external database, run a SQL query, store the returned data in a result set, and then work with that result set. You can optionally send updated information back to the source database.

Working with LS:DO

With LS:DO, you can write a LotusScript program to perform the following actions:

  • Look up or retrieve data stored in external databases

  • Validate user-entered data enter against data store in external databases

  • Review data retrieved from external databases

  • Update data in external databases, either immediately or at scheduled intervals

LS:DO is especially useful for data access based on LotusScript events in Notes, such as clicking a button, exiting a field, or opening a document.

LS:DO works best for these types of operations:

  • Handling low volumes of data transfers.

    • You can use LS:DO for high volume transfers, but its performance could be significantly affected.

  • Reading and writing data in the same program.

    • LS:DO implements several properties and methods for retrieving, updating, and storing data.

  • Real-time data handling

    • LS:DO real-time data access is the best choice for optimizing data entry (for example, looking up data or validating user entries) and providing data access to mobile Notes users.

Review these sections for more information about working with LS:DO:

  • Setting up LS:DO

  • Using LS:DO

  • Tips and techniques


Setting up LS:DO

Setting up LS:DO requires several steps, in which you install any needed software, register your data sources, and then create your script. Review the following sections as you set up LS:DO for your application:

  • LS:DO requirements

  • Setting up LS:DO with ODBC

  • Creating your script


LS:DO requirements

Before you can access external databases with LS:DO, you must installed all required software on your computer.

Platforms

Notes supports LS:DO on the following platforms, provided an appropriate ODBC driver and server are available:

  • Windows 3.1, Windows 95, Windows NT

  • OS/2

  • UNIX

    • AIX, Solaris Sparc, Solaris Intel Edition, HP-UX

  • IBM S/390, AS/400 running on OS/400

    • ODBC is not available on these platforms, but you can emulate it by using LotusScript's LSXDB2 library to make back-end calls through DB2 to access a database.

Notes/Domino software

LS:DO requires the Notes client software to run. You can run scripts using LS:DO on both Notes servers and clients; however, in order to run your script on a server, you must install additionally the Notes client software on that server.

ODBC software

To use LS:DO, you need:

  • The ODBC driver manager and administrator, Version 2.0 or later.

  • ODBC drivers for the external databases you are accessing.

    • Drivers for several database programs, including Intersolv drivers, are available with Notes Release 5.

Consult the appropriate document for your platform and database software to determine whether your platform supports ODBC and how to configure it.

Client DBMS software

In some cases, the client software for the databases you are accessing must be installed on the computer that is executing your script. Consult the DBMS documentation to determine which components must be installed.

Additional software

Your platform may require additional software for using ODBC (for example, AIX requires additional ODBC driver managers); consult the documentation for your platform.


Setting up LS:DO with ODBC

Once you have installed all the necessary software, you can set up ODBC and then configure Notes to support it.

Install your ODBC drivers

The ODBC drivers you need are probably available with your database software; in addition, other products and platforms frequently supply commonly used ODBC drivers. You can download the ODBC drivers for Intersolv databases from the Lotus Web site.

AIX driver manager

If you are using LS:DO on a Domino server running on AIX, you must enable the driver manager before you run any programs. The Intersolv Driver Pack for AIX (version 3.02) contains an archived version of the driver manager libodbc.a, but LS:DO requires an executable or shared object version of the driver manager. Complete these steps to make sure you are using the executable or shared object version of the driver manager:Index "LS:DO" # "setting up on AIX" CrusaderID242

  1. In a DOS command window, enter this command:

    2. file libodbc.a
  2. If the file is an archive version, enter this command to extract the executable or shared object version (odbc.so):

    3. ar -x libodbc.a
  3. Save the archive version using a new name. For example, enter this command:

    4. copy libodbc.a libodbc.archive
  4. Enter this command to rename the extracted file so that the driver manager file is an executable or shared object:

    5. mv odbc.so libodbc.a

Register your data sources

For each type of external database that you'll be accessing, you need to specify which ODBC driver to use for accessing it. For details on registering your data sources, consult the documentation accompanying the ODBC driver manager for your platform.

Configure Domino for multi-threading

By default, Domino runs only one copy of a script at a time, queuing additional requests. If you want to enable multiple users to run your script at the time (called multi-threading), you must use the NOTES.INI statements described below.

DominoAsynchronizeAgents statement

Add this line to NOTES.INI on the Domino server to enable multi-threading:

DominoAsynchronizeAgents=1

If you omit this statement, the value defaults to 0 and multi-threading is disabled.

ODBCThreadSafeDrivers statement

Your ODBC driver manager and drivers must be thread-safe to run in a multi-threaded application. Consult with your ODBC supplier to verify that the driver is thread-safe, particularly if the ODBC package is not up to the ODBC 3.0 standard.

If all the ODBC drivers you are using are thread safe, add this statement to NOTES.INI on the Domino server:

ODBCThreadSafeDrivers=ALL

If none of the ODBC drivers you are using are thread safe, add this statement to NOTES.INI on the Domino server:

ODBCThreadSafeDrivers=NONE

If you have a combination of thread-safe and non-thread-safe drivers, you can still set up a multi-threaded environment by identifying which drivers are thread-safe and which are not, using the following two statements:

ODBCThreadSafeDrivers = driver-name [, driver-name]

ODBCNonThreadSafeDrivers = driver-name [, driver-name]

LS:DO uses the appropriate type of threading for each driver, based on these statements. If you do not specify whether a driver is thread-safe or not, LS:DO assumes that is not thread-safe.

Install additional software as needed

Your platform may require additional software for using ODBC. Be sure to consult the documentation for your platform to make sure you have all the necessary software installed.


Creating your script

Create your LotusScript program. Your script may be embedded in a form, or defined as a standalone agent.

Access the LS:DO Classes

To access the LS:DO classes in your script, you must put the following statement in the (Options) event of the (Global) object or the agent:

UseLSX "*LSXODBC"

This statement loads ODBC.LSX which makes the ODBC classes available in the programming environment, including the browser. If you do not use this statement, scripts with ODBC classes do not compile. The asterisk causes the LSX file to be determined by a search of the registry, initialization file, or preference file. The asterisk is more flexible than a platform-dependent file name.

The LSXODBC.LSS file, which defines the constants used by the LS:DO classes, is not supplied with Notes. Instead, those constants are defined when the UseLSX statement executes.

Decide where your script will execute

Once you have completed your LotusScript program, configure it to execute on either the Notes client or the Domino server. Remember, if you run the script on a server, that server must additionally have the Notes client software installed.

Client-based

The LotusScript program is stored and executes on the Notes client (workstation):

  • Requirements: The LotusScript program and all ODBC drivers used by it must be installed on each Notes client that will run the program.

  • Advantages: The program can be designed with more control over timing and resource use.

  • Disadvantages: If the program requires updates, it must be updated on each workstation. You can only run one agent at a time on the Notes client, which means an application involving multiple agents may take longer to run.

Server-based

The LotusScript program is stored and executes on a Domino server:

  • Requirements: The LotusScript program and all ODBC drivers used by it must be installed on a Domino server.

  • Advantages: If the program requires updates, only the single server copy has to be updated. The Notes server supports multi-threading, so multiple instances of agents can be run at one time, and resources will be shared.

  • Disadvantages: The user cannot run it from the Notes client. The program's timing can't be as precise as for a client-based configuration because the program competes with other server-based agents for resources.

Run on server

The LotusScript program is stored and executed on a Domino server, but a user can start it from a Notes client.

  • Requirements: The LotusScript program and all ODBC drivers used by it must be installed on a Notes server.

  • Advantages: A user can run it from the Notes client, instead of requiring access to a server. If the program requires updates, only the single server copy has to be updated. The Notes server supports multi-threading, so multiple instances of agents can be run at one time, and resources will be shared.

  • Disadvantages: The program is server-based, so its timing can't be as precise as for the client-based configuration because the program competes with other server-based agents for resources.


Using LS:DO

Once you have set up LS:DO and your script, you are ready to access your external databases. With LS:DO, you can:

  • Connect to an external database

  • Retrieve data from an external database

  • Work with data retrieved from an external database


Connecting to an external database

Create a new ODBCConnection object with "Dim New" or "Set = New." Once the object exists, you can get:

  • Software revision string with the GetLSDOMasterRevision property

  • Available data sources with the ListDataSources method

Connect to an external data source with the ConnectTo method of the ODBCConnection object. The external source must be defined in the ODBC Driver Manager at the operating system level. You can test the connection with the IsConnected method.

If the data source requires a user name and password, you can supply these as arguments to ConnectTo or let the data source prompt the user. You can suppress prompts from the data source by setting the SilentMode property to True, although intermediate software may still prompt.

After you connect to a data source, you can query and update the external tables with the ODBCQuery and ODBCResultSet objects, and can get the following information:

  • Name of the data source with the DataSourceName property

  • Names of the tables for the data source with the ListTables method

  • Names of the fields (columns) in a table with the ListFields method

  • Names of the stored procedures for the data source with the ListProcedures method

  • Status of options for the data source with the IsSupported method

When you are done using a data source to which you connected, disconnect from it with the Disconnect method.

See examples
Examples: Connecting to an external database


Retrieving data from an external database

Querying a table requires ODBCConnection, ODBCQuery, and ODBCResultSet objects. You must explicitly associate the objects by setting the Connection property of ODBCQuery and the Query property of ODBCResultSet as follows:

  • queryObject.Connection = connectionObject associates a connection with a query.

  • resultSetObject.Query = queryObject associates a query with a result set.

Specifying SQL statements

The SQL property of ODBCQuery specifies the SQL statement that your query executes. The SQL property can be any valid SQL syntax, including SELECT, CREATE TABLE, DROP TABLE, INSERT, UPDATE, and DELETE statements. For example, the following SQL statement selects all data in the STUDENTS table:

"SELECT * FROM STUDENTS"

This SQL statement selects all data in the STUDENTS table in ascending sequence by the LASTNAME field:

"SELECT * FROM STUDENTS ORDER BY LASTNAME"

This SQL statement selects only the LASTNAME and FIRSTNAME fields:

"SELECT LASTNAME, FIRSTNAME FROM STUDENTS ORDER BY LASTNAME"

Parameters

A SQL query can include parameters. The following query contains one parameter named studentNo:

qry.SQL = "SELECT * FROM STUDENTS WHERE STUDENT_NO = ?studentNo?"

You must assign the parameter a value before executing the query. The SetParameter method assigns a value to a parameter, given the name or number (starting at 1) of the parameter and the value:

Dim inputNo As String

inputNo = Inputbox$("Enter ID number", "Student ID?")

Call result.SetParameter("studentNo", inputNo)

REM Alternatively, the following could be used:

REM Call result.SetParameter(1, inputNo)

If the value of the parameter must be enclosed in single quotes, which is the case with a character value, supply the single quotes in the SetParameter method; not in the SQL statement.

Dim inputName as String

qry.SQL = "SELECT * FROM STUDENTS WHERE LASTNAME = _

          ?lastName?"

inputName = Inputbox$("Enter last name", _

                     "Student last name?")

Call result.SetParameter("studentName", "'" _

                         & inputName & "'")

The GetParameter method gets the current value of a parameter and the GetParameterName method gets the name of a parameter, given the name or number of the parameter. The NumParameters method returns the number of parameters in the current SQL statement, which enables you to use For loops to process parameters. The following code sets all the parameters in the current SQL statement using the parameter names to prompt (in this example, all the parameters require single quotes):

For i = 1 To result.NumParameters

     inputParameter = _

      Inputbox$(result.GetParameterName(i), _

      "Parameter " & i)

     Call result.SetParameter(i, "'" & inputParameter & "'")

Next

Executing SQL statements

The Execute and ExecProcedure methods of the ODBCResultSet object perform your query and retrieve the selected data. You can limit the attempt time for the query by setting the QueryExecuteTimeOut property of ODBCQuery.

The selected data becomes available as a result set that contains one row for every row selected from the table, and one column for every field selected from the table. To access the data, use the ODBCResultSet object.

Use the IsResultSetAvailable method of the ODBCResultSet objec to determine whether a query returned any data.

When you no longer need a result set, close it with the Close method of ODBCResultSet.

See examples
Examples: Retrieving data from an external database


Working with data retrieved from an external database

The ODBCResultSet class provides properties and methods to manage data retrieved with ODBCQuery. The data is stored in a result set that contains fields (columns) and rows based on what the SELECT query fetches from the external database table.

Creating a table

  1. Use the Execute method to execute a SQL query containing a CREATE TABLE statement that specifies the data types and sizes of the fields to be retrieved.

  2. Close the result set with the Close method.

  3. Execute a SQL query containing a SELECT * FROM [table name] statement to set up the column information.

  4. Populate the table using the AddRow, SetValue, and UpdateRow methods in the ODBCQueryResult object.

  5. Close the result set.

To re-use this table later in the script, execute a SQL query containing a new SELECT statement; this reinitializes the result set's properties.

To prevent this table from being updated, set the ReadOnly property to True.

Deleting a table

To delete a table, execute a SQL query that contains a DROP TABLE statement.

Updating a table

Updates include changing, deleting, and adding rows.

Changing a value in a row

To change the values in the current row, call the SetValue method one or more times to specify the new value for each field that is changing, then call the UpdateRow method to implement the changes in the external database table. Specify the column by number or name.

Call result.SetValue(1, column1Value)

Call result.SetValue(2, column2Value)

...

Call result.UpdateRow

Use the SetValue and UpdateRow methods to test the return status.

Deleting and adding rows

To delete the current row, use the DeleteRow method:

Call result.DeleteRow(tableName)

Call result.UpdateRow

To add a row:

  1. Use the AddRow method to create the AddRow workspace.

  2. Use the SetValue method one or more times to specify the value for each field in the row.

  3. Use the UpdateRow method to add the new row to the back-end database and close the AddRow workspace.

    4. Call result.AddRow

    Call result.SetValue(1, column1Value)

    Call result.SetValue(2, column2Value)

    ...

    Call result.UpdateRow

The call to AddRow creates a special AddRow workspace containing exactly one row. If you make another row current, you can go back to the AddRow workspace by specifying DB_ADDROW as the row number. The call to UpdateRow method deletes the AddRow workspace.

When you delete and add rows, the updates are not reflected in the result set. The result set retains the same number of rows and the same row numbering as before. If you want the result set to reflect updates, execute another SELECT query.

The UpdateRow method implements SQL INSERT and UPDATE statements, depending on the operation being performed; the DeleteRow method implements SQL DELETE statements. Alternatively, you can issue these statements directly with the SQL property and the Execute method, but this is not recommended.

Getting update status

The following methods provide update status:

  • IsValueAltered indicates whether a field in the result set row was changed by SetValue after being fetched or being created by AddRow.

  • GetRowStatus indicates whether the result set row was changed by SetValue as above, plus whether the row is deleted by DeleteRow, added by AddRow, updated by UpdateRow, or remains unchanged.

  • HasRowChanged indicates whether the table row in the data set has changed since being fetched--that is, whether the table value differs from the result set value as fetched. A True return value indicates that another program modified the row in the table since your program fetched the row.

Working with rows

The rows of a result set are identified by number. Row numbers are integers starting at 1 and ending at the return value of the NumRows method. NumRows does not return an accurate value until the entire result set is fetched into memory.

Moving among rows

To move among rows, use the NextRow, PrevRow, FirstRow, LastRow, and LocateRow methods. The CurrentRow property returns the number of the row that is in position for processing. The IsBeginOfData and IsEndOfData methods return True on the first and last rows, respectively.

Using the NextRow method following the Execute method moves to the first row if no other positioning methods intervene. This behavior permits you to process an entire result set in a loop of the following form:

result.Execute

Do

     result.NextRow

     code for processing one row

Loop Until result.IsEndOfData

The call to NextRow is at the top of the loop. The code that processes the row follows. The Until clause is at the end of the loop and conditionalizes the loop on IsEndOfData. Do not conditionalize the loop on the return status of NextRow because a False return status also generates an error.

If you process the result set front to back after intervening positioning methods occur (for example, for a second pass over the data), you must explicitly move to the first row and process the first row before entering the loop, as follows. (Alternatively, you can call NextRow at the bottom of the loop and process the last row after exiting the loop.)

result.FirstRow

code for processing first row

Do

     result.NextRow

     code for processing one row

Loop Until result.IsEndOfData

Likewise, if you process the result set back to front, you must explicitly move to the last row and process the last row before entering the loop, as follows. (Alternatively, you can call PrevRow at the bottom of the loop and process the first row after exiting the loop.)

result.LastRow

code for processing last row

Do

     result.PrevRow

     code for processing one row

Loop Until result.IsBeginOfData

Note The CacheLimit property of ODBCResultSet affects your ability to process a result set back to front.

The LocateRow method positions you on the first row that contains specified values for up to three fields. The search starts with the current row, proceeds in a forward direction, and returns False if a row with the specified values is not found. The following code processes all rows in the result set containing "Cambridge" in field 5 and "MA" in field 6.

result.FirstRow

Do While result.LocateRow(5, "Cambridge", 6, "MA")

     code for processing row

     If result.IsEndOfData Then Exit Do

     result.NextRow

Loop

Specify FirstRow to start the search at the beginning of the result set. The While loop terminates when LocateRow returns False. The loop explicitly exits if the row being processed (LocateRow is True) happens to be the last row. Otherwise, NextRow signals an error, and if the error is not handled, the loop is infinite on the last row.

You can tell that a memory shortage caused truncation of the result set when, on the last row, IsEndOfData is True, but NumRows are still DB_ROWSUNKNOWN.

If you set the CurrentRow property to 0, you raise an error (#545) once data has been fetched.

Modifying rows

The DeleteRow, UpdateRow, and HasRowChanged methods use SQL to complete their operations. These methods can fail when the result set contains columns that are Image or Rich Text because SQL statements cannot handle these data types correctly. To avoid failure, consider keeping two sets of results. One set can include columns of data types that SQL can handle and one set includes columns of data types that SQL cannot handle (that is, the Image and Rich Text types).

The DeleteRow, UpdateRow, and HasRowChanged methods work most efficiently when the specified column has unique values; if the column doesn't contain unique values, set an error to trap DBstsNUNQ to make sure you are accessing unique rows.

To discard the AddRow workspace and any changes that might be in it, call the Close method with the argument DB_CANCELADDROW. The rest of the result set remains open.

Retrieving a field in the current row

The GetValue method returns the value of a field in the current row. The field can be specified by name:

lastName = result.GetValue("LASTNAME")

It can also be specified by number:

lastName = result.GetValue(2)

Use the IsValueNull method to check for null values.

The data type of the return value is determined as follows:

  • If you specify a variable as a second argument, the return value is the type of the variable. This technique overrides all others. The following code returns the value of LASTNAME as a String data type.

    • Dim lastName As String

    Call result.GetValue("LASTNAME", lastName)
  • You can specify the type with FieldExpectedDataType before calling GetValue. This technique has precedence if the second argument of GetValue is not specified. The following code returns the value of LASTNAME as a String data type.

    • Call result.FieldExpectedDataType("LASTNAME", DB_CHAR)

    lastName = result.GetValue("LASTNAME")
  • If you do not use the above techniques, the LotusScript data type takes a default based on the SQL data type, as shown in the table below.

The following table lists the SQL data types, as returned by FieldNativeDataType; the corresponding default LS:DO data type constants, as specified for FieldExpectedDataType; and their LotusScript language data types as returned by Typename. The data has to be convertible to the specified type for Typename to return the correct type; otherwise LotusScript generates an exception.

SQL data type | LS:DO data type | Typename
SQL_CHAR | DB_CHAR | STRING
SQL_NUMERIC | DB_TYPE_UNDEFINED | DOUBLE
SQL_DECIMAL | DB_TYPE_UNDEFINED | DOUBLE
SQL_INTEGER | DB_SHORT | INTEGER
SQL_SMALLINT | DB_SHORT | INTEGER
SQL_FLOAT | DB_DOUBLE | DOUBLE
SQL_REAL | DB_DOUBLE | DOUBLE
SQL_DOUBLE | DB_DOUBLE | DOUBLE
SQL_DATE | DB_DATE | DATE
SQL_TIME | DB_DATETIME | DATE
SQL_TIMESTAMP | DB_TIME | DATE
SQL_VARCHAR | DB_CHAR | STRING
SQL_BINARY | DB_BINARY | STRING
SQL_VARBINARY | DB_BINARY | STRING
SQL_LONGVARCHAR | DB_CHAR | STRING
SQL_LONGVARBINARY | DB_BINARY | STRING
SQL_BIGINT | DB_LONG | LONG
SQL_TINYINT | DB_SHORT | INTEGER
SQL_BIT | DB_BINARY | STRING

Working with fields

The fields (columns) of a result set are identified by number and name. Field numbers are integers starting at 1 and ending at the return value of the NumColumns method. To access all the fields in a result set, use a loop of the form:

For n = 1 To resultSetObject.NumColumns

Field names are strings that represent the names as they appear in the data source table.

The following ODBCResultSet methods provide information on a field:

  • FieldID returns the field number, given the field name.

  • FieldInfo returns an array of information, given the number or name of a field. Named constants provide indexes into the array.

  • FieldName returns the field name, given the field number.

FieldSize returns the maximum size, given the number or name of a field.

See examples
Examples: Working with a result set


Using LS:DO: Tips and techniques

This section presents specialized topics concerned with enhancing your LS:DO application:

  • Handling an ODBC event

  • Handling an ODBC error

  • Transaction processing

  • Caching data

  • Multi-threading agents


Handling an ODBC event

Events precede and follow many methods, as listed in the documentation. They have names such as BeforeConnectTo, AfterConnectTo, BeforeNextRow, and AfterNextRow. If you write an event handler and bind it to the event with the On Event statement, the handler is called when the event occurs.

The On Event statement must state the name of the event and the name of the ODBCConnection, ODBCQuery, or ODBCResultSet object that activates the event. The following example calls a sub named AfterPositionChange after any call to the NextRow method, where result is an ODBCResultSet object:

On Event AfterNextRow From result Call AfterPositionChange

The first parameter of the subroutine is the object that activated the event. In the following example, the parameter res accepts the ODBCResultSet object that activated the AfterNextRow event:

Sub AfterPositionChange(res As ODBCResultSet)

     Messagebox res.CurrentRow,, "Current row"

End Sub

See examples
Example: Handling an ODBC event


Handling an ODBC error

The ODBCConnection, ODBCQuery, and ODBCResultSet classes all contain the following methods:

  • GetError returns the integer error number for the last operation performed by an object of that class.

  • GetErrorMessage returns the error text for the last operation performed by an object of that class.

  • GetExtendedErrorMessage returns extended error text for the last operation performed by an object of that class. If the error is originally reported by the data source, the extended error text contains the data source error message.

These methods are documented under ODBCQuery since they are the same for all three classes. The GetErrorMessage topic documents the error codes and associated error text for each error and provides examples. The documentation for each property and method provides error codes and text for the error paths it contains.

If an operation is successful, the return number is DBstsSUCCESS. Any other number indicates an error.

You can test operations on an individual basis by calling the above methods after each operation. The following code shows the technique for checking the last operation and exiting if an error occurred:

con.ConnectTo("ATDB")

If con.GetError <> DBstsSUCCESS Then

     Messagebox con.GetExtendedErrorMessage,, _

     con.GetError & " " & con.GetErrorMessage

     Exit Sub

End If

qry.SQL = "SELECT * FROM STUDENTS"

If qry.GetError <> DBstsSUCCESS Then

     Messagebox qry.GetExtendedErrorMessage,, _

     qry.GetError & " " & qry.GetErrorMessage

     Exit Sub

End If

result.Execute

If result.GetError <> DBstsSUCCESS Then

     Messagebox result.GetExtendedErrorMessage,, _

     result.GetError & " " & result.GetErrorMessage

     Exit Sub

End If

You can test operations in general with an On Error statement. If the On Error action with no error number is in effect, any operation that returns an error number other DBstsSUCCESS invokes the On Error action. Your error code should test GetError for all objects that may cause the error. The following code shows the technique for trapping any ODBC error and exiting:

     On Error Goto errorHandler

     con.ConnectTo("ATDB")

     qry.SQL = "SELECT * FROM STUDENTS"

     result.Execute

     ...

errorHandler:

     If con.GetError <> DBstsSUCCESS Then

          Messagebox con.GetExtendedErrorMessage,, _

          con.GetError & " " & con.GetErrorMessage

     End If

     If qry.GetError <> DBstsSUCCESS Then

          Messagebox qry.GetExtendedErrorMessage,, _

          qry.GetError & " " & qry.GetErrorMessage

     End If

     If result.GetError <> DBstsSUCCESS Then

          Messagebox result.GetExtendedErrorMessage,, _

          result.GetError & " " & result.GetErrorMessage

     End If

     Exit Sub

The default On Error action is Resume Next. If you don't explicitly check for errors and an error occurs, the script continues with undefined results.

See examples
Examples: GetErrorMessage method


Transaction processing

There are two basic approaches to recording updates in your back-end database: auto-commit mode and transaction mode. Many databases require you to work in auto-commit mode; however, where possible, you should work in transaction mode because it requires much less overhead.

Auto-commit mode

When you work in auto-commit mode, each row's changes are committed to the back-end database as soon as you complete them with the ODBCResultSet object's UpdateRow or DeleteRow methods. Because the changes are committed immediately, you cannot roll them back. When you are updating a single row here and there, auto-commit mode makes sense because you know your changes are recorded before you move on. But if you are modifying large numbers of rows, auto-commit mode requires an inordinate amount of overhead.

While committing your changes to the back-end database, the DBMS must lock all of the rows to be updated, as well as that portion of the database catalog relevant to those rows. In addition, the transaction log is locked so that it can be purged. While this is happening, no other users can modify the transaction log or the locked portions of the database. They must wait until those areas are unlocked, then lock them for their own updates and unlock them afterward.

When a large number of records are committed individually, the DBMS uses a considerable amount of resources managing the locking and unlocking of the transaction log, database, and catalog. The more users competing for access to the database, the more the resources required for managing updates. Users spend more time waiting for events to occur and lose the sense of concurrency that multi-processing normally provides.

If you want to work in auto-commit mode, use the AutoCommit property of the ODBCConnection object to determine whether auto-commit mode is in effect and if not, to enable it. Your DBMS may require you to work in auto-commit mode.

Transaction mode

When you work in transaction mode, all your changes since the last commit are saved in a transaction log by the DBMS; they are not recorded in the database itself until you manually initiate a commit or you terminate the connection to that database. At any time, you can roll back the updates in the transaction log, ensuring that those changes never get recorded in the back-end database.

You can time your commit actions to occur after a specified number of records have been updated, or after certain logical transactions are complete. You can additionally have any updates remaining in the transaction log committed automatically when you terminate your connection to the back-end database.

Committing updates after a number of records has changed allows you to process the records more quickly, yet periodically record changes to the back-end database so the work isn't lost in the case of some failure. For example, when updating the Department Name field in a series of employee records, you might want to commit your changes after every 100 records has been updated.

Committing updates after a logical transaction occurs allows you to ensure that the entire transaction is successful before updating the back-end database, or to roll back the changes if the transaction somehow fails before completion. For example, if you are transferring money from a savings account to a checking account, you would debit the savings account, credit the checking account, and only then commit the update to the back-end database. If crediting the checking account somehow fails, you can roll back the change to the savings account and re-try the entire transaction later.

Committing updates when you terminate your connection to the back-end database ensures that any changes remaining in the transaction log are not inadvertently lost; this is generally a good practice.

When you process records in transaction mode, you should implement some mechanism for tracking your changes so you'll know where to re-start your work if a failure forces a rollback.

Use the IsSupported method of the ODBCConnection object to determine whether transaction mode is supported by your DBMS. If it is, you can then use the AutoCommit property to determine whether auto-commit mode is enabled for the back-end database and if necessary, disable it.

While working in transaction mode, use the CommitTransactions method to manually record your updates, and the CommitOnDisconnect property to automatically record any remaining updates in the transaction log when you terminate your connection to the back-end database. Use the RollbackTransactions method to delete your updates from the transaction log without recording them in the back-end database.


Caching data

By default, LS:DO caches the data you retrieve with a query; that is, it stores the data in memory. This is useful when you are moving back and forth between rows and don't want to have to fetch them again, but it uses up memory fairly quickly.

Limiting the cache size conserves memory, but restricts the number of rows stored at one time. New rows are fetched only for methods that move to a higher-numbered row; those newly fetched rows displace older rows in the cache. Attempting to revisit a lower-numbered row that has already been flushed raises the "Cannot access requested row" error; you have to re-execute the query first.

If you plan to process a table in sequence and will not revisit processed rows, you should limit the cache. If you intend to revisit previously processed rows, cache only enough rows so you don't have to re-fetch those rows. When you limit the cache size, limit the fetch batch size accordingly so you don't fetch more rows than you can store in the cache.

Note Using the MaxRows property to limit the number of rows fetched into the result set from a large table is useful for testing.


Multi-threading agents

By default, Domino runs only one copy of an agent at a time, queuing additional requests. If you want to enable multiple users to run your agent at a time, you must enable multi-threading and run your agent on a server (the Notes client doesn't support multi-threading).

Multi-threading allows multiple copies of the agent (each copy is a thread) to run at once and share resources, rather than requiring each agent to wait for its predecessor to complete processing before starting. Although individual agent processes may run more slowly as they compete for resources, a series of agents will run faster on the whole because they use the resources more efficiently than in a single-thread environment. For example, an agent that requires 5 seconds to run in a single-thread environment may require 7 seconds to run in a multi-thread environment, but three copies of that agent might run concurrently in 10 seconds, while they would require 15 seconds to run if queued to run sequentially.

Multi-threading only works when your ODBC driver supports it. Most DBMS programs support multi-tasking, and handle data contention on the back-end.


Handling run-time errors

The Domino Designer methods raise run-time errors to flag most conditions. To process errors, you must include an error-handling routine; if you do not, the script exits when an error occurs.

Some methods return a status value or return Nothing as an object handle to flag a condition; in these cases, the return value can be checked before proceeding. Some properties indicate status and can be checked after calling a method that affects the status value.

For example, you can detect a failure of the New or Open method of NotesDatabase through any of the following indicators:

  • An attempt to use the object with a method that requires an open database raises the error ERR_NOTES_DATABASE_NOTOPEN. Be aware that the error occurs when you try to use the object after the open is attempted, not when the open is attempted. Also, using properties of the object does not raise an error.

  • The object property IsOpen is False.

  • If you used the Open method, the return value is False.

LotusScript raises run-time errors for many conditions such as file errors and arithmetic exceptions. You must handle these errors if you do not want the script to exit on an error.

To trap all errors, include an On Error statement without an error number before any executable statements. To trap a specific error, include an On Error statement with the error number before the statement that might cause the error. However, the On Error statements with numbers must follow the On Error statement without a number. For example, if you want to trap the errors ErrDatabaseDoesNotExist and ErrObjectVariableNotSet plus any other errors, you write the following On Error statements in the following order:

On Error Goto processError

On Error ErrDatabaseDoesNotExist Goto processErrDatabaseDoesNotExist

On Error ErrObjectVariableNotSet Goto processErrObjectVariableNotSet

The error constants are defined in the following files in the Domino data directory. You must include the appropriate file or files in the (Declarations) event of the object to access the error constants. You can create a script library with the %include statements and then use that script library in the options section.

  • lsxbeerr.lss defines constants for errors raised by Domino Designer back-end methods.

  • lsxuierr.lss defines constants for errors raised by Domino Designer front-end (UI) methods.

  • lserr.lss defines constants for errors raised by LotusScript.

  • lsconst.lss defines constants for use as arguments in LotusScript statements and functions.

See examples
Examples: Handling run-time errors


Using OLE custom controls

OLE custom controls, such as Lotus components, can be embedded in Domino Designer forms and are scriptable just like native objects. When a control is active (has focus), the menu is a combination of Domino Designer (File, Applet, and Window) and control items. The control's menu items may include one for itself (for example, "Spreadsheet" for a spreadsheet control) and Help--the control's help is substituted for Domino Designer help.

The Applet menu item allows you to:

  • Copy and cut the entire object using the Domino Designer internal clipboard (use the Edit menu to copy and cut selected text in the object). With the internal clipboard, a Paste operation within Domino Designer pastes the object while a Paste Special operation pastes a representation of the object (for example, a picture).

  • Copy external the entire object using the OLE clipboard. With the OLE clipboard, a Paste Special operation within Domino Designer or another application allows pasting of the object while a Paste operation pastes a representation of the object.

  • Access object properties for the control, including the name of the control, sizing, spacing, and style. To access the control's own properties, if supported by the control, use Edit - Properties.

  • Edit the control's events, which brings up the design pane.

  • Set the control's mode to design or run.

  • Freeze and unfreeze the control's events.

When you embed a control during form design and the control is active, a list of events appears in the Define box in the form's design pane. The OLE custom control can raise these events to Domino Designer and you can write actions against them.

To insert OLE custom controls through the UI

To insert an OLE custom control in a Domino Designer form or document from the UI:

  1. Open the form and position the cursor in a rich text field where you want the control.

  2. Choose Create - Object.

  3. Select "Create a new control."

  4. Select the desired control from the list. The controls are also included in the "Create a new object list"; they are flagged by a symbol with a yellow background. To insert a non-registered control, select Add Control and enter the path of the control's file.

To insert OLE custom controls through LotusScript

To insert an OLE custom control in a Domino Designer form or document from LotusScript, use the CreateObject method of NotesUIDocument in one of the form's scripts. For example, the following statement might appear in the PostOpen script for the form:

Set area2Sheet = Source.CreateObject("Area 2 Spreadsheet", _

"Lotus.Spreadsheet.1")

Source is the NotesUIDocument object for the current document. The second parameter must be the case-sensitive name of a registered OLE object that is an OLE custom control. The first parameter is a reference name that you invent. CreateObject returns a reference variable to the OLE object.

To access an existing control, use the GetObject method of NotesUIDocument in a script attached to the form. For example:

Set area2Sheet = Source.GetObject("Area 2 Spreadsheet")

To use OLE custom controls in LotusScript

You can access the properties and methods of an OLE custom control the same as a native LotusScript object. The following example sets the BackColor property for the spreadsheet control whose reference variable is area2Sheet:

area2Sheet.BackColor = 255 ' Red

You can examine the properties and methods for registered OLE custom controls in the LotusScript browser. Look under "OLE Classes."

If you insert an OLE custom control on a form through the UI, the control and its events become available in the Define and Event boxes the same as any other object on the form.

An OLE custom control that is NotesFlow-enabled may provide a mechanism for you to handle its events through the ObjectExecute script of a Domino Designer action, button, or hotspot. This technique would be useful for an OLE custom control that is not inserted on the form. For example, the spreadsheet control may supply ActionLinkSet and ActionLinkClear methods to associate events with named actions:

Call area2Sheet.ActionLinkSet _

(LC_CLICK, "Display column and row")

LC_CLICK is a constant, defined in a %Include file, that means a mouse click has occurred in the component. "Display column and row" is the name of the Domino Designer action that will handle the mouse click. You would typically put this code in the Postopen event of the form.

Create an action on the form with the name "Display column and row." In the properties box for the action, select "Publish action with OLE object" under the NotesFlow Publishing tab. "Include action in button bar" and "Include action in Notes Action menu" under the Basics tab should be deselected. Select Objectexecute from the Event box and enter the code to handle the mouse click.

See examples
Examples: Using OLE custom controls


Using OLE

The Notes client is an OLE automation controller and server.

Note This feature is not supported under OS/2, under UNIX, and on the Macintosh.

OLE automation controller

Notes is an OLE automation controller. You can use the LotusScript GetObject function to open an OLE automation object and the CreateObject function to create an OLE automation object. You can also use the CreateObject and GetObject methods of the NotesUIDocument class.

OLE automation server

Notes registers itself as an OLE automation server and provides the following OLE automation objects:

  • Notes.NotesUIWorkspace provides access to the Domino UI objects.

  • Notes.NotesSession provides access to the Domino Objects (that is, the back-end objects).

External applications can create and reference the automation objects, then work down through the object hierarchies. For example, a Visual Basic application might contain the code:

Set workspace = CreateObject("Notes.NotesUIWorkspace")

Set doc = workspace.CurrentDocument

Or:

Set session = CreateObject("Notes.NotesSession")

Messagebox session.UserName

A Notes client must be installed on the same machine as the Visual Basic program. Notes runs as a separate process when acting as an OLE automation server.

OLE automation uses late binding. You cannot create new Domino objects as in LotusScript. You must create (for example, with CreateObject) a Notes.NotesUIWorkspace or Notes.NotesSession object and work down through the hierarchies using the available methods. For example, if you want to open a Domino back-end database, create a Notes.NotesSession OLE automation object, then use the GetDatabase method of NotesSession to set a reference variable.

In Visual Basic, declare the reference variables for all Domino objects as type Object. When you finish using a Domino object, set the reference variable to Nothing to free the memory it uses.

Use dot notation, just as in LotusScript, to access an object's properties and methods.

Constants must be specified by actual numeric value rather than name. In LotusScript, you can get the value by displaying it. For example:

Messagebox ACLLEVEL_AUTHOR,, "ACLLEVEL_AUTHOR"

See examples
Examples: Using OLE


LotusScript Constants (A - C)

The following table lists the LotusScript constants that start with A-C and where they are used.

Click on any of the ranges below to view other constants:

A - C D - E F - M N - O P - S T - U V - Z

LotusScript Constant | Where used
ACLLEVEL_AUTHOR | CreateACLEntry method and InternetLevel property in the NotesACL class, Level property in the NotesACLEntry class, and the CurrentAccessLevel property, GrantAccess method, and QueryAccess method in the NotesDatabase class
ACLLEVEL_DEPOSITOR | CreateACLEntry method and InternetLevel property in the NotesACL class, Level property in the NotesACLEntry class, and the CurrentAccessLevel property, GrantAccess method, and QueryAccess method in the NotesDatabase class
ACLLEVEL_DESIGNER | CreateACLEntry method and InternetLevel property in the NotesACL class, Level property in the NotesACLEntry class, and the CurrentAccessLevel property, GrantAccess method, and QueryAccess method in the NotesDatabase class
ACLLEVEL_EDITOR | CreateACLEntry method and InternetLevel property in the NotesACL class, Level property in the NotesACLEntry class, and the CurrentAccessLevel property, GrantAccess method, and QueryAccess method in the NotesDatabase class
ACLLEVEL_MANAGER | CreateACLEntry method and InternetLevel property in the NotesACL class, Level property in the NotesACLEntry class, and the CurrentAccessLevel property, GrantAccess method, and QueryAccess method in the NotesDatabase class
ACLLEVEL_NOACCESS | CreateACLEntry method and InternetLevel property in the NotesACL class, Level property in the NotesACLEntry class, and the CurrentAccessLevel property, GrantAccess method, and QueryAccess method in the NotesDatabase class
ACLLEVEL_READER | CreateACLEntry method and InternetLevel property in the NotesACL class, Level property in the NotesACLEntry class, and the CurrentAccessLevel property, GrantAccess method, and QueryAccess method in the NotesDatabase class
ACLTYPE_MIXED_GROUP Note This constant is new with Release 5 | UserType property in the NotesACLEntry class
ACLTYPE_PERSON Note This constant is new with Release 5 | UserType property in the NotesACLEntry class
ACLTYPE_PERSON_GROUP Note This constant is new with Release 5 | UserType property in the NotesACLEntry class
ACLTYPE_SERVER Note This constant is new with Release 5 | UserType property in the NotesACLEntry class
ACLTYPE_SERVER_GROUP Note This constant is new with Release 5 | UserType property in the NotesACLEntry class
ACLTYPE_UNSPECIFIED Note This constant is new with Release 5 | UserType property in the NotesACLEntry class
ACTIONCD | Type property in the NotesItem class
ALIGN_CENTER Note This constant is new with Release 5 | Alignment property in the NotesRichTextParagraphStyle class
ALIGN_FULL Note This constant is new with Release 5 | Alignment property in the NotesRichTextParagraphStyle class
ALIGN_LEFT Note This constant is new with Release 5 | Alignment property in the NotesRichTextParagraphStyle class
ALIGN_NOWRAP Note This constant is new with Release 5 | Alignment property in the NotesRichTextParagraphStyle class
ALIGN_RIGHT Note This constant is new with Release 5 | Alignment property in the NotesRichTextParagraphStyle class
ASSISTANTINFO | Type property in the NotesItem class
ATTACHMENT | Type property in the NotesItem class
AUTHORS | Type property in the NotesItem class
COLOR_BLACK | NotesColor property in the NotesRichTextStyle class, FontColor property in the NotesViewColumn class, and BackgroundColor property in the NotesView class
COLOR_BLUE | NotesColor property in the NotesRichTextStyle class, FontColor property in the NotesViewColumn class, and BackgroundColor property in the NotesView class
COLOR_CYAN | NotesColor property in the NotesRichTextStyle class, FontColor property in the NotesViewColumn class, and BackgroundColor property in the NotesView class
COLOR_DARK_BLUE | NotesColor property in the NotesRichTextStyle class, FontColor property in the NotesViewColumn class, and BackgroundColor property in the NotesView class
COLOR_DARK_CYAN | NotesColor property in the NotesRichTextStyle class, FontColor property in the NotesViewColumn class, and BackgroundColor property in the NotesView class
COLOR_DARK_GREEN | NotesColor property in the NotesRichTextStyle class, FontColor property in the NotesViewColumn class, and BackgroundColor property in the NotesView class
COLOR_DARK_MAGENTA | NotesColor property in the NotesRichTextStyle class, FontColor property in the NotesViewColumn class, and BackgroundColor property in the NotesView class
COLOR_DARK_RED | NotesColor property in the NotesRichTextStyle class, FontColor property in the NotesViewColumn class, and BackgroundColor property in the NotesView class
COLOR_DARK_YELLOW | NotesColor property in the NotesRichTextStyle class, FontColor property in the NotesViewColumn class, and BackgroundColor property in the NotesView class
COLOR_GRAY | NotesColor property in the NotesRichTextStyle class, FontColor property in the NotesViewColumn class, and BackgroundColor property in the NotesView class
COLOR_GREEN | NotesColor property in the NotesRichTextStyle class, FontColor property in the NotesViewColumn class, and BackgroundColor property in the NotesView class
COLOR_LIGHT_GRAY | NotesColor property in the NotesRichTextStyle class, FontColor property in the NotesViewColumn class, and BackgroundColor property in the NotesView class
COLOR_MAGENTA | NotesColor property in the NotesRichTextStyle class, FontColor property in the NotesViewColumn class, and BackgroundColor property in the NotesView class
COLOR_RED | NotesColor property in the NotesRichTextStyle class, FontColor property in the NotesViewColumn class, and BackgroundColor property in the NotesView class
COLOR_WHITE | NotesColor property in the NotesRichTextStyle class, FontColor property in the NotesViewColumn class, and BackgroundColor property in the NotesView class
COLOR_YELLOW | NotesColor property in the NotesRichTextStyle class, FontColor property in the NotesViewColumn class, and BackgroundColor property in the NotesView class


LotusScript Constants (D - E)

The following table lists the LotusScript constants that start with D-E and where they are used.

Click on any of the ranges below to view other constants:

A - C D - E F - M N - O P - S T - U V - Z

LotusScript Constant | Where used
DATABASE | GetFirstDatabase method in the NotesDbDirectory class
DATETIMES | Type property in the NotesItem class
DB_REPLICATION_PRIORITY_HIGH Note This constant is new with Release 5 | Priority property in the NotesReplication class
DB_REPLICATION_PRIORITY_LOW Note This constant is new with Release 5 | Priority property in the NotesReplication class
DB_REPLICATION_PRIORITY_MED Note This constant is new with Release 5 | Priority property in the NotesReplication class
DB_REPLICATION_PRIORITY_NOTSET Note This constant is new with Release 5 Note This constant is obsolete in Release 5.0.1 | Priority property in the NotesReplication class
EFFECTS_EMBOSS | Effects property in the NotesRichTextStyle class
EFFECTS_EXTRUDE | Effects property in the NotesRichTextStyle class
EFFECTS_NONE | Effects property in the NotesRichTextStyle class
EFFECTS_SHADOW | Effects property in the NotesRichTextStyle class
EFFECTS_SUBSCRIPT | Effects property in the NotesRichTextStyle class
EFFECTS_SUPERSCRIPT | Effects property in the NotesRichTextStyle class
EMBED_ATTACHMENT | Type property in the NotesEmbeddedObject class and the EmbedObject method in the NotesRichTextItem class
EMBED_OBJECT | Type property in the NotesEmbeddedObject class and the EmbedObject method in the NotesRichTextItem class
EMBED_OBJECTLINK | Type property in the NotesEmbeddedObject class and the EmbedObject method in the NotesRichTextItem class
EMBEDDEDOBJECT | Type property in the NotesItem class
ERRORITEM | Type property in the NotesItem class
EV_ALARM | LogEvent method in the NotesLog class
EV_COMM | LogEvent method in the NotesLog class
EV_MAIL | LogEvent method in the NotesLog class
EV_MISC | LogEvent method in the NotesLog class
EV_REPLICA | LogEvent method in the NotesLog class
EV_RESOURCE | LogEvent method in the NotesLog class
EV_SECURITY | LogEvent method in the NotesLog class
EV_SERVER | LogEvent method in the NotesLog class
EV_UNKNOWN | LogEvent method in the NotesLog class
EV_UPDATE | LogEvent method in the NotesLog class


LotusScript Constants (F - M)

The following table lists the LotusScript constants that start with F-M and where they are used.

Click on any of the ranges below to view other constants:

A - C D - E F - M N - O P - S T - U V - Z

LotusScript Constant | Where used
FONT_COURIER | NotesFont property in the NotesRichTextStyle class
FONT_HELV | NotesFont property in the NotesRichTextStyle class
FONT_ROMAN | NotesFont property in the NotesRichTextStyle class
FORMULA | Type property in the NotesItem class
FT_DATABASE | FTDomainSearch, FTSearch and UnprocessedFTSearch methods in the NotesDatabase class
FT_DATE_ASC | FTDomainSearch, FTSearch and UnprocessedFTSearch methods in the NotesDatabase class
FT_DATE_DES | FTDomainSearch, FTSearch and UnprocessedFTSearch methods in the NotesDatabase class
FT_FILESYSTEM | FTDomainSearch, FTSearch and UnprocessedFTSearch methods in the NotesDatabase class
FT_FUZZY | FTDomainSearch, FTSearch and UnprocessedFTSearch methods in the NotesDatabase class
FT_SCORES | FTDomainSearch, FTSearch and UnprocessedFTSearch methods in the NotesDatabase class
FT_STEMS | FTDomainSearch, FTSearch and UnprocessedFTSearch methods in the NotesDatabase class
FT_THESAURUS | FTDomainSearch, FTSearch and UnprocessedFTSearch methods in the NotesDatabase class
HTML | Type property in the NotesItem class
ICON | Type property in the NotesItem class
ID_CERTIFIER | IDType property in the NotesRegistration class
ID_FLAT | IDType property in the NotesRegistration class
ID_HIERARCHICAL | IDType property in the NotesRegistration class
LSOBJECT | Type property in the NotesItem class
MIME_PART Note This constant is new with Release 5 | Type property in the NotesItem class


LotusScript Constants (N - O)

The following table lists the LotusScript constants that start with N-O and where they are used.

Click on any of the ranges below to view other constants:

A - C D - E F - M N - O P - S T - U V - Z

LotusScript Constant | Where used
NAMES | Type property in the NotesItem class
NOTESLINKS | Type property in the NotesItem class
NOTEREFS | Type property in the NotesItem class
NOTES_DESKTOP_CLIENT Note This constant is new with Release 5 | RegisterNewUser method in the NotesRegistration class
NOTES_FULL_CLIENT Note This constant is new with Release 5 | RegisterNewUser method in the NotesRegistration class
NOTES_LIMITED_CLIENT Note This constant is new with Release 5 | RegisterNewUser method in the NotesRegistration class
NUMBERS | Type property in the NotesItem class
OTHEROBJECT | Type property in the NotesItem class
OUTLINE_CLASS_DATABASE Note This constant is new with Release 5 | EntryClass property in the NotesOutlineEntry class
OUTLINE_CLASS_DOCUMENT Note This constant is new with Release 5 | EntryClass property in the NotesOutlineEntry class
OUTLINE_CLASS_FOLDER Note This constant is new with Release 5 | EntryClass property in the NotesOutlineEntry class
OUTLINE_CLASS_FORM Note This constant is new with Release 5 | EntryClass property in the NotesOutlineEntry class
OUTLINE_CLASS_FRAMESET Note This constant is new with Release 5 | EntryClass property in the NotesOutlineEntry class
OUTLINE_CLASS_NAVIGATOR Note This constant is new with Release 5 | EntryClass property in the NotesOutlineEntry class
OUTLINE_CLASS_PAGE Note This constant is new with Release 5 | EntryClass property in the NotesOutlineEntry class
OUTLINE_CLASS_UNKNOWN Note This constant is new with Release 5 | EntryClass property in the NotesOutlineEntry class
OUTLINE_CLASS_VIEW Note This constant is new with Release 5 | EntryClass property in the NotesOutlineEntry class
OUTLINE_OTHER_FOLDERS_TYPE Note This constant is new with Release 5 | Type property in the NotesOutlineEntry class
OUTLINE_OTHER_UNKNOWN_TYPE Note This constant is new with Release 5 | Type property in the NotesOutlineEntry class
OUTLINE_OTHER_VIEWS_TYPE Note This constant is new with Release 5 | Type property in the NotesOutlineEntry class
OUTLINE_TYPE_ACTION Note This constant is new with Release 5 | Type property in the NotesOutlineEntry class
OUTLINE_TYPE_NAMEDELEMENT Note This constant is new with Release 5 | Type property in the NotesOutlineEntry class
OUTLINE_TYPE_NOTELINK Note This constant is new with Release 5 | Type property in the NotesOutlineEntry class
OUTLINE_TYPE_URL Note This constant is new with Release 5 | Type property in the NotesOutlineEntry class


LotusScript Constants (P - S)

The following table lists the LotusScript constants that start with P-S and where they are used.

Click on any of the ranges below to view other constants:

A - C D - E F - M N - O P - S T - U V - Z

LotusScript Constant | Where used
PAGINATE_BEFORE Note This constant is new with Release 5 | Pagination property in NotesRichTextParagraphStyle class
PAGINATE_DEFAULT Note This constant is new with Release 5 | Pagination property in NotesRichTextParagraphStyle class
PAGINATE_KEEP_TOGETHER Note This constant is new with Release 5 | Pagination property in NotesRichTextParagraphStyle class
PAGINATE_KEEP_WITH_NEXT Note This constant is new with Release 5 | Pagination property in NotesRichTextParagraphStyle class
PICKLIST_CUSTOM Note This constant is new with Release 5 | PickListStrings method in the NotesUIWorkspace class
PICKLIST_NAMES Note This constant is new with Release 5 | PickListStrings method in the NotesUIWorkspace class
PICKLIST_RESOURCES Note This constant is new with Release 5 | PickListStrings method in the NotesUIWorkspace class
PICKLIST_ROOMS Note This constant is new with Release 5 | PickListStrings method in the NotesUIWorkspace class
PROMPT_OK Note This constant is new with Release 5 | Prompt method in the NotesUIWorkspace class
PROMPT_OKCANCELCOMBO Note This constant is new with Release 5 | Prompt method in the NotesUIWorkspace class
PROMPT_OKCANCELEDIT Note This constant is new with Release 5 | Prompt method in the NotesUIWorkspace class
PROMPT_OKCANCELEDITCOMBO Note This constant is new with Release 5 | Prompt method in the NotesUIWorkspace class
PROMPT_OKCANCELLIST Note This constant is new with Release 5 | Prompt method in the NotesUIWorkspace class
PROMPT_OKCANCELLISTMULT Note This constant is new with Release 5 | Prompt method in the NotesUIWorkspace class
PROMPT_PASSWORD Note This constant is new with Release 5 | Prompt method in the NotesUIWorkspace class
PROMPT_YESNO Note This constant is new with Release 5 | Prompt method in the NotesUIWorkspace class
PROMPT_YESNOCANCEL Note This constant is new with Release 5 | Prompt method in the NotesUIWorkspace class
QUERYCD | Type property in the NotesItem class
READERS | Type property in the NotesItem class
REPLICA_CANDIDATE | GetFirstDatabase method in the NotesDbDirectory class
RICHTEXT | Type property in the NotesItem class
RULER_ONE_CENTIMETER Note This constant is new with Release 5 | FirstLineLeftMargin, LeftMargin, and RightMargin properties, and SetTab and SetTabs methods in the NotesRichTextParagraphStyle class, and Position property in NotesRichTextTab class
RULER_ONE_INCH Note This constant is new with Release 5 | FirstLineLeftMargin, LeftMargin, and RightMargin properties, and SetTab and SetTabs methods in the NotesRichTextParagraphStyle class, and Position property in NotesRichTextTab class
SEV_FAILURE | LogEvent method in the NotesLog class
SEV_FATAL | LogEvent method in the NotesLog class
SEV_NORMAL | LogEvent method in the NotesLog class
SEV_WARNING1 | LogEvent method in the NotesLog class
SEV_WARNING2 | LogEvent method in the NotesLog class
SIGNATURE | Type property in the NotesItem class
SPACING_DOUBLE Note This constant is new with Release 5 | InterLineSpacing, SpacingAbove, and SpacingBelow properties in the NotesRichTextParagraphStyle class
SPACING_ONE_POINT_50 Note This constant is new with Release 5 | InterLineSpacing, SpacingAbove, and SpacingBelow properties in the NotesRichTextParagraphStyle class
SPACING_SINGLE Note This constant is new with Release 5 | InterLineSpacing, SpacingAbove, and SpacingBelow properties in the NotesRichTextParagraphStyle class
STYLE_NO_CHANGE | Bold, Effects, FontSize, Italic, NotesColor, NotesFont, Strikethrough, and the Underline properties in the NotesRichTextStyle class


LotusScript Constants (T - U)

The following table lists the LotusScript constants that start with T-U and where they are used.

Click on any of the ranges below to view other constants:

A - C D - E F - M N - O P - S T - U V - Z

LotusScript Constant | Where used
TAB_CENTER Note This constant is new with Release 5 | SetTab and SetTabs methods in the NotesRichTextParagraphStyle class, and Type property in the NotesRichTextTab class
TAB_DECIMAL Note This constant is new with Release 5 | SetTab and SetTabs methods in the NotesRichTextParagraphStyle class, and Type property in the NotesRichTextTab class
TAB_LEFT Note This constant is new with Release 5 | SetTab and SetTabs methods in the NotesRichTextParagraphStyle class, and Type property in the NotesRichTextTab class
TAB_RIGHT Note This constant is new with Release 5 | SetTab and SetTabs methods in the NotesRichTextParagraphStyle class, and Type property in the NotesRichTextTab class
TARGET_ALL_DOCS Note This constant is new with Release 5 | Target property in the NotesAgent class
TARGET_ALL_DOCS_IN_VIEW Note This constant is new with Release 5 | Target property in the NotesAgent class
TARGET_NEW_DOCS Note This constant is new with Release 5 | Target property in the NotesAgent class
TARGET_NEW_OR_MODIFIED_DOCS Note This constant is new with Release 5 | Target property in the NotesAgent class
TARGET_NONE Note This constant is new with Release 5 | Target property in the NotesAgent class
TARGET_RUN_ONCE Note This constant is new with Release 5 | Target property in the NotesAgent class
TARGET_SELECTED_DOCS Note This constant is new with Release 5 | Target property in the NotesAgent class
TARGET_UNREAD_DOCS_IN_VIEW Note This constant is new with Release 5 | Target property in the NotesAgent class
TEMPLATE | GetFirstDatabase method in the NotesDbDirectory class
TEMPLATE_CANDIDATE | GetFirstDatabase method in the NotesDbDirectory class
TEXT | Type property in the NotesItem class
TRIGGER_AFTER_MAIL_DELIVERY Note This constant is new with Release 5 | Tigger property in the NotesAgent class
TRIGGER_BEFORE_MAIL_DELIVERY Note This constant is new with Release 5 | Tigger property in the NotesAgent class
TRIGGER_DOC_PASTED Note This constant is new with Release 5 | Tigger property in the NotesAgent class
TRIGGER_DOC_UPDATE Note This constant is new with Release 5 | Tigger property in the NotesAgent class
TRIGGER_MANUAL Note This constant is new with Release 5 | Tigger property in the NotesAgent class
TRIGGER_NONE Note This constant is new with Release 5 | Tigger property in the NotesAgent class
TRIGGER_SCHEDULED Note This constant is new with Release 5 | Tigger property in the NotesAgent class
UNAVAILABLE | Type property in the NotesItem class
UNKNOWN | Type property in the NotesItem class
USERDATA | Type property in the NotesItem class
USERID | Type property in the NotesItem class


LotusScript Constants (V - Z)

The following table lists the LotusScript constants that start with V-Z and where they are used.

Click on any of the ranges below to view other constants:

A - C D - E F - M N - O P - S T - U V - Z

LotusScript Constant | Where used
VC_ALIGN_CENTER Note This constant is new with Release 5 | Alignment and HeaderAlignment properties in the NotesViewColumn class
VC_ALIGN_LEFT Note This constant is new with Release 5 | Alignment and HeaderAlignment properties in the NotesViewColumn class
VC_ALIGN_RIGHT Note This constant is new with Release 5 | Alignment and HeaderAlignment properties in the NotesViewColumn class
VC_ATTR_PARENS Note This constant is new with Release 5 | NumberAttrib property in the NotesViewColumn class
VC_ATTR_PUNCTUATED Note This constant is new with Release 5 | NumberAttrib property in the NotesViewColumn class
VC_ATTR_PERCENT Note This constant is new with Release 5 | NumberAttrib property in the NotesViewColumn class
VC_FMT_ALWAYS Note This constant is new with Release 5 | TimeZoneFmt property in the NotesViewColumn class
VC_FMT_CURRENCY Note This constant is new with Release 5 | NumberFormat property in the NotesViewColumn class
VC_FMT_DATE Note This constant is new with Release 5 | TimeDateFmt property in the NotesViewColumn class
VC_FMT_DATETIME Note This constant is new with Release 5 | TimeDateFmt property in the NotesViewColumn class
VC_FMT_FIXED Note This constant is new with Release 5 | NumberFormat property in the NotesViewColumn class
VC_FMT_GENERAL Note This constant is new with Release 5 | NumberFormat property in the NotesViewColumn class
VC_FMT_HM Note This constant is new with Release 5 | TimeFmt property in the NotesViewColumn class
VC_FMT_HMS Note This constant is new with Release 5 | TimeFmt property in the NotesViewColumn class
VC_FMT_MD Note This constant is new with Release 5 | DateFmt property in the NotesViewColumn class
VC_FMT_NEVER Note This constant is new with Release 5 | TimeZoneFmt property in the NotesViewColumn class
VC_FMT_SCIENTIFIC Note This constant is new with Release 5 | NumberFormat property in the NotesViewColumn class
VC_FMT_SOMETIMES Note This constant is new with Release 5 | TimeZoneFmt property in the NotesViewColumn class
VC_FMT_TIME Note This constant is new with Release 5 | TimeDateFmt property in the NotesViewColumn class
VC_FMT_TODAYTIME Note This constant is new with Release 5 | TimeDateFmt property in the NotesViewColumn class
VC_FMT_YM Note This constant is new with Release 5 | DateFmt property in the NotesViewColumn class
VC_FMT_YMD Note This constant is new with Release 5 | DateFmt property in the NotesViewColumn class
VC_FMT_Y4M Note This constant is new with Release 5 | DateFmt property in the NotesViewColumn class
VC_FONT_BOLD Note This constant is new with Release 5 | FontStyle property in the NotesViewColumn class
VC_FONT_ITALIC Note This constant is new with Release 5 | FontStyle property in the NotesViewColumn class
VC_FONT_STRIKEOUT Note This constant is new with Release 5 | FontStyle property in the NotesViewColumn class
VC_FONT_UNDERLINE Note This constant is new with Release 5 | FontStyle property in the NotesViewColumn class
VC_SEP_COMMA Note This constant is new with Release 5 | ListSep property in the NotesViewColumn class
VC_SEP_NEWLINE Note This constant is new with Release 5 | ListSep property in the NotesViewColumn class
VC_SEP_SEMICOLON Note This constant is new with Release 5 | ListSep property in the NotesViewColumn class
VC_SEP_SPACE Note This constant is new with Release 5 | ListSep property in the NotesViewColumn class
VIEWMAPDATA | Type property in the NotesItem class
VIEWMAPLAYOUT | Type property in the NotesItem class
VW_SPACING_DOUBLE Note This constant is new with Release 5 | Spacing property in the NotesView class
VW_SPACING_ONE_POINT_25 Note This constant is new with Release 5 | Spacing property in the NotesView class
VW_SPACING_ONE_POINT_50 Note This constant is new with Release 5 | Spacing property in the NotesView class
VW_SPACING_ONE_POINT_75 Note This constant is new with Release 5 | Spacing property in the NotesView class
VW_SPACING_SINGLE Note This constant is new with Release 5 | Spacing property in the NotesView class


Properties and methods with ECL security

The following tables list the properties and methods affected by an Execution Control List (ECL). Those properties cannot be accessed or set, and those methods do not execute on the workstation, unless the marked ECL privileges are granted to the formula's signer.

The ECL flags listed in the table are:

  • Access to current file system (file)

  • Access to current database (cur)

  • Access to environment variables (env)

  • Access to external programs (prog)

  • Ability to send mail (mail)

  • Ability to read other databases (read)

  • Ability to modify other databases (mod)

    • NotesACL | file | cur | env | prog | mail | read | mod
CreateACLEntry |  | x |  |  |  | x |
DeleteRole |  | x |  |  |  | x |
GetEntry |  | x |  |  |  | x |
GetFirstEntry |  | x |  |  |  | x |
GetNextEntry |  |  |  |  |  | x |
RenameRole |  | x |  |  |  | x |
Save |  | x |  |  |  | x | x
    NotesACLEntry | file | cur | env | prog | mail | read | mod
DisableRole |  | x |  |  |  | x |
EnableRole |  | x |  |  |  | x |
IsRoleEnabled |  | x |  |  |  | x |
New |  | x |  |  |  | x |
Remove |  | x |  |  |  | x |
    NotesAgent | file | cur | env | prog | mail | read | mod
New |  |  |  |  |  | x |
Remove |  | x |  |  |  |  | x
Run |  | x |  |  |  |  | x
RunOnServer |  |  |  |  |  |  | x

NotesDatabase | file | cur | env | prog | mail | read | mod
Categories (set) |  | x |  |  |  |  | x
Close |  |  |  |  |  | x |
Create |  |  |  |  |  |  | x
CreateCopy |  |  |  |  |  |  | x
CreateDocument |  |  |  |  |  | x |
CreateFromTemplate |  |  |  |  |  |  | x
CreateReplica |  |  |  |  |  |  | x
DelayUpdates (set) |  | x |  |  |  |  | x
FTSearch |  |  |  |  |  | x |
GetAgent |  |  |  |  |  | x |
GetDocumentByID |  |  |  |  |  | x |
GetDocumentByUNID |  |  |  |  |  | x |
GetDocumentByURL |  |  |  |  |  | x |
GetForm |  |  |  |  |  | x |
GetProfileDocument |  |  |  |  |  | x |
GetURLHeader |  |  |  |  |  | x |
GetView |  |  |  |  |  | x |
GrantAccess |  |  |  |  |  | x |
OpenByReplicaID |  |  |  |  |  | x |
OpenURLDb |  |  |  |  |  | x |
OpenWithFailover |  |  |  |  |  | x |
QueryAccess |  |  |  |  |  | x |
Remove |  | x |  |  |  |  | x
Replicate |  |  |  |  |  | x |
RevokeAccess |  |  |  |  |  | x |
Search |  |  |  |  |  | x |
SizeQuota (set) |  | x |  |  |  |  | x
Title (set) |  | x |  |  |  |  | x
UnprocessedFTSearch |  |  |  |  |  | x |
UpdateFTIndex |  |  |  |  |  | x |
NotesDocument | file | cur | env | prog | mail | read | mod
AppendItemValue |  | x |  |  |  |  | x
ComputeWithForm |  | x |  |  |  |  | x
CopyAllItems |  | x |  |  |  |  | x
CopyItem |  | x |  |  |  |  | x
CopyToDatabase |  | x |  |  |  |  | x
CreateReplyMessage |  | x |  |  | x |  | x
CreateRTItem |  | x |  |  |  |  | x
Encrypt |  | x |  |  |  |  | x
EncryptionKeys (set) |  | x |  |  |  |  | x
MakeResponse |  | x |  |  |  |  | x
New (if new note is created) |  | x |  |  |  |  | x
PutInFolder |  | x |  |  |  |  | x
Remove |  | x |  |  |  |  | x
RemoveFromFolder |  | x |  |  |  |  | x
RemoveItem |  | x |  |  |  |  | x
RenderToRTItem |  | x |  |  |  |  | x
ReplaceItemValue |  | x |  |  |  |  | x
Save |  | x |  |  |  |  | x
Send |  | x |  |  | x |  | x
Sign |  | x |  |  |  |  | x
UniversalID (set) |  | x |  |  |  |  | x
NotesDocumentCollection | file | cur | env | prog | mail | read | mod
FTSearch |  |  |  |  |  | x* |
GetFirstDocument |  |  |  |  |  | x* |
GetLastDocument |  |  |  |  |  | x* |
GetNextDocument |  |  |  |  |  | x* |
GetNthDocument |  |  |  |  |  | x* |
GetPrevDocument |  |  |  |  |  | x* |
PutAllInFolder |  | x |  |  |  |  | x
RemoveAll |  | x |  |  |  |  | x
RemoveAllFromFolder |  | x |  |  |  |  | x
StampAll |  | x |  |  |  |  | x
UpdateAll |  | x |  |  |  |  |

* For the above specified methods in the NotesDocumentCollection class, once you give access to read a database, it implies access to elements within the database. It does not explicitly check for ECL privileges.

NotesEmbeddedObject | file | cur | env | prog | mail | read | mod
ExtractFile | x |  |  |  |  |  |
New |  |  |  | x |  |  |
Remove |  | x |  |  |  |  |
NotesForm | file | cur | env | prog | mail | read | mod
FormUsers (set) |  | x |  |  |  |  |
ProtectReaders (set) |  | x |  |  |  |  |
ProtectUsers (set) |  | x |  |  |  |  |
Readers (set) |  | x |  |  |  |  |
Remove |  | x |  |  |  |  |
NotesItem | file | cur | env | prog | mail | read | mod
Abstract |  |  |  |  |  | x* |
AppendToTextList |  | x |  |  |  |  | x
Contains |  |  |  |  |  | x* |
CopyToDocument |  | x |  |  |  |  | x
DateTimeValue (set) |  | x |  |  |  |  | x
IsAuthors (set) |  | x |  |  |  |  | x
IsEncrypted (set) |  | x |  |  |  |  | x
IsNames (set) |  | x |  |  |  |  | x
IsProtected (set) |  | x |  |  |  |  | x
IsReaders (set) |  | x |  |  |  |  | x
IsSigned (set) |  | x |  |  |  |  | x
IsSummary (set) |  | x |  |  |  |  | x
New |  | x |  |  |  |  | x
Remove |  | x |  |  |  |  | x
SaveToDisk (set) |  | x |  |  |  |  | x
Values (set) |  | x |  |  |  |  | x

* For the Abstract and Contains methods in the NotesItem class, once you give access to read a database, it implies access to elements within the database. It does not explicitly check for ECL privileges.

NotesLog | file | cur | env | prog | mail | read | mod
Close |  |  |  |  | x |  |
LogAction (to database) |  |  |  |  |  |  | x
LogAction (to file) | x |  |  |  |  |  |
LogAction (to mail message) |  |  |  |  | x |  | x
LogAction (to agent) |  |  |  |  |  |  | x
LogError (to database) |  |  |  |  |  |  | x
LogError (to file) | x |  |  |  |  |  |
LogError (to mail message) |  |  |  |  | x |  | x
LogError (to agent) |  |  |  |  |  |  | x
OpenFileLog | x |  |  |  |  |  |
NotesNewsletter | file | cur | env | prog | mail | read | mod
FmtMsgWithDoclinks |  |  |  |  |  |  | x
FormatDocument |  |  |  |  |  |  | x
NotesRichTextItem | file | cur | env | prog | mail | read | mod
AddNewLine |  | x |  |  |  |  | x
AddTab |  | x |  |  |  |  | x
AppendDocLink |  | x |  |  |  |  | x
AppendRTItem |  | x |  |  |  |  | x
AppendText |  | x |  |  |  |  | x
EmbedObject (file) | x | x |  |  |  |  | x
EmbedObject (OLE) | x | x |  | x |  |  | x
GetEmbeddedObject(OLE) |  |  |  | x |  |  |
New |  | x |  |  |  |  | x
NotesSession | file | cur | env | prog | mail | read | mod
FreeTimeSearch |  |  |  |  |  | x |
GetDatabase |  |  |  |  |  | x |
GetEnvironmentString |  |  | x |  |  |  |
GetEnvironmentValue |  |  | x |  |  |  |
SetEnvironmentVar |  |  | x |  |  |  |
UpdateProcessedDoc |  |  |  |  |  |  | x
NotesUIDocument | file | cur | env | prog | mail | read | mod
Categorize |  | x |  |  |  |  |
Clear |  | x |  |  |  |  |
CreateObject |  |  |  | x |  |  |
Cut |  | x |  |  |  |  |
DeleteDocument |  | x |  |  |  |  |
FieldAppendText |  | x |  |  |  |  |
FieldClear |  | x |  |  |  |  |
FieldSetText |  | x |  |  |  |  |
GetObject |  |  |  | x |  |  |
Paste |  | x |  |  |  |  |
Save |  | x |  |  |  |  |
SaveNewVersion |  | x |  |  |  |  |
Send |  |  |  |  | x |  |
NotesUIWorkspace | file | cur | env | prog | mail | read | mod
OpenDatabase |  | x |  |  |  |  |
NotesView | file | cur | env | prog | mail | read | mod
Aliases |  |  |  |  |  | x* |
AutoUpdate |  | x |  |  |  | x* | x
Columns |  |  |  |  |  | x* |
Created |  |  |  |  |  | x* |
FTSearch |  |  |  |  |  | x* |
GetAllDocumentsByKey |  |  |  |  |  | x* |
GetChild |  |  |  |  |  | x* |
GetDocumentByKey |  |  |  |  |  | x* |
GetFirstDocument |  |  |  |  |  | x* |
GetLastDocument |  |  |  |  |  | x* |
GetNextDocument |  |  |  |  |  | x* |
GetNextSibling |  |  |  |  |  | x* |
GetNthDocument |  |  |  |  |  | x* |
GetParentDocument |  |  |  |  |  | x* |
GetPrevDocument |  |  |  |  |  | x* |
GetPrevSibling |  |  |  |  |  | x* |
IsCalendar |  |  |  |  |  | x* |
IsDefaultView |  |  |  |  |  | x* |
IsFolder |  |  |  |  |  | x* |
LastModified |  |  |  |  |  | x* |
Name |  |  |  |  |  | x* |
Parent |  |  |  |  |  | x* |
ProtectReaders |  | x |  |  |  | x* | x
Readers |  |  |  |  |  | x* | x
Refresh |  |  |  |  |  | x* |
Remove |  | x |  |  |  | x* | x
UniversalID |  |  |  |  |  | x* |

* For all the properties and methods in the NotesView class, once you give access to read a database, it implies access to elements within the database. It does not explicitly check for ECL privileges.


Button class

Represents an action, button, or hotspot on a form or document.

Note This class is not supported in COM.

Events

Click

ObjectExecute

Access

To access an action, button, or hotspot, write a script that responds to one of its events. A Button object has no properties or methods.

Usage

The Button, Field, and Navigator events provide entry points to scripts from the Notes UI.

See also
Field class
Navigator class
Using the Domino classes


Click event

Occurs when the user selects the action, button, or hotspot.

Defined in

Button class

Syntax

Click(Source as Button)

Parameters

Source

Button. Read-only. The action, button, or hotspot.

Usage

When you create a script that responds to this event, Notes creates the syntax of the event for you (including the parameter). You do not need to type it in.

See also
ObjectExecute event


ObjectExecute event

Occurs when an action, button, or hotspot is activated by an OLE2 server that is FX/Notesflow enabled.

Defined in

Button class

Syntax

ObjectExecute(Source as Button, Data as Variant)

Parameters

Source

Button. Read-only.

Data

Variant. Handle to the OLE2 server Dispatch/Automation interface.

Usage

When you create a script that responds to this event, Notes creates the syntax of the event for you (including the parameter). You do not need to type it in.

See also
Click Event


Field class

Represents a field on a form.

Note This class is not supported in COM.

Events

Entering

Exiting

Access

To access a field, write a script that responds to one of its events. A Field object has no properties or methods.

Usage

The Button, Field, and Navigator events provide entry points to scripts from the Notes UI.

See also
Button class
Navigator class
Using the Domino classes
Writing scripts and formulas for form and field events


Entering event

Occurs when the user enters a field in Edit mode.

Defined in

Field Class

Syntax

Entering(Source as Field)

Parameters

Source

Field. Read-only. The field.

Usage

When you create a script that responds to this event, Notes creates the syntax of the event for you (including the parameter). You do not need to type it in.


Exiting event

Occurs when the user exits a field in Edit mode.

Defined in

Field Class

Syntax

Exiting(Source as Field)

Parameters

Source

Field. Read-only. The field.

Usage

When you create a script that responds to this event, Notes creates the syntax of the event for you (including the parameter). You do not need to type it in.


Navigator class

Represents a navigator button, hotspot, or other object.

Note This class is not supported in COM.

Events

Click

Access

To access a navigator object, write a script that responds to its event. A Navigator object has no properties or methods.

Usage

The Button, Field, and Navigator events provide entry points to scripts from the Notes UI.

See also
Button class
Field class
Using the Domino classes


Click event

Occurs when the user selects a navigator object.

Defined in

Navigator class

Syntax

Click(Source as Navigator)

Parameters

Source

Navigator. Read-only. The navigator object.

Usage

When you create a script that responds to this event, Notes creates the syntax of the event for you (including the parameter). You do not need to type it in.


NotesACL class

Represents the access control list (ACL) of a database.

Containment

Contained by: NotesDatabase

Contains: NotesACLEntry

Properties

InternetLevel

Parent

Roles

UniformAccess

Methods

AddRole

CreateACLEntry

DeleteRole

GetEntry

GetFirstEntry

GetNextEntry

RenameRole

RemoveACLEntry

Save

Access

Every NotesDatabase contains a NotesACL object representing that database's access control list. To get it, use the ACL property in NotesDatabase.

Usage

The Database class has three methods you can use to access and modify an ACL without getting an ACL object: QueryAccess, GrantAccess, and RevokeAccess. However, using these methods at the same time an ACL object is in use may produce inconsistent results.

See examples
Examples: NotesACL class

See also
CurrentAccessLevel property (in NotesDatabase)
Examining and adjusting an access control list
Managers property (in NotesDatabase)
Using the Domino classes


InternetLevel property

Read-write. Indicates the maximum Internet access level for this database.

Note This property is new with R5.0.

Defined in

NotesACL

Data type

Integer

Syntax

To get: level% = notesACL.InternetLevel

To set: notesACL.InternetLevel = level%

Legal values

  • ACLLEVEL_NOACCESS (0)

  • ACLLEVEL_DEPOSITOR (1)

  • ACLLEVEL_READER (2)

  • ACLLEVEL_AUTHOR (3)

  • ACLLEVEL_EDITOR (4)

  • ACLLEVEL_DESIGNER (5)

  • ACLLEVEL_MANAGER (6)

Note These values are also used with the CreateACLEntry method of the NotesACL class, the Level property in the NotesACLEntry class, and the CurrentAccessLevel property, GrantAccess method, and QueryAccess method in the NotesDatabase class.

See examples
Example: InternetLevel property


Parent property

Read-only. The database that owns an ACL.

Defined in

NotesACL

Data type

NotesDatabase

Syntax

To get: Set notesDatabase = notesACL.Parent

See examples
Example: Parent property

See also
Examining and adjusting an access control list


Roles property

Read-only. All the roles defined in an access control list.

Defined in

NotesACL

Data type

Array of strings

Syntax

To get: stringArray = notesACL.Roles

Usage

Each element in the array is the name of a role. Each role name is surrounded by square brackets, for example, "[Supervisor]."

Notes Release 2 "privileges" are surrounded by parentheses. Properties and methods affecting roles, such as DisableRole and EnableRole, do not work on privileges.

See examples
Examples: Roles property

See also
AddRole method
DeleteRole method
DisableRole method (in NotesACLEntry)
EnableRole method (in NotesACLEntry)
Examining and adjusting an access control list
IsRoleEnabled method (in NotesACLEntry)
RenameRole method
Roles property (in NotesACLEntry)


UniformAccess property

Read-write. Indicates if uniform access is set.

Defined in

NotesACL class

Data type

Boolean

Syntax

To get: flag = notesACL.UniformAccess

To set: notesACL.UniformAccess = flag

Legal values

  • True indicates that Uniform access is set

  • False indicates that Uniform access is not set

Usage

In the Notes UI, this property is in the advanced section of database properties: "Enforce a consistent Access Control List across all replicas of this database."

See examples
Examples: UniformAccess property

See also
Examining and adjusting an access control list


AddRole method

Adds a role to an ACL.

Defined in

NotesACL

Syntax

Call notesACL.AddRole( name$ )

Parameter

name$

String. The name of the new role. Do not put parentheses or square brackets around the name.

See examples
Example: AddRole method

See also
DeleteRole method
DisableRole method (in NotesACLEntry)
EnableRole method (in NotesACLEntry)
Examining and adjusting an access control list
IsRoleEnabled method (in NotesACLEntry)
Roles property
Roles property (in NotesACLEntry)


CreateACLEntry method

Creates an entry in the ACL with the name and level that you specify. When used with OLE automation, this method allows you to create a NotesACLEntry object without using New.

Defined in

NotesACL

Syntax

Set notesACLEntry = notesACL.CreateACLEntry( name$, level% )

Parameters

name$

String. The name of the person, group, or server for whom you want to create an entry in the ACL.

level%

Constant. The level you want to assign to this person, group, or server in the ACL. May be any of the following:

ACLLEVEL_NOACCESS (0) | No access
ACLLEVEL_DEPOSITOR (1) | Depositor access
ACLLEVEL_READER (2) | Reader access
ACLLEVEL_AUTHOR (3) | Author access
ACLLEVEL_EDITOR (4) | Editor access
ACLLEVEL_DESIGNER (5) | Designer access
ACLLEVEL_MANAGER (6) | Manager access

Note These values are also used with the InternetLevel property of the NotesACL class, the Level property in the NotesACLEntry class, and the CurrentAccessLevel property, GrantAccess method, and QueryAccess method in the NotesDatabase class.

Return value

notesACLEntry

The newly-created entry.

Usage

You must call Save on the ACL if you want the modified ACL to be saved to disk.

For more information, see the "NotesACLEntry class."

Example: CreateACLEntry method

This script gives Shelly McPhail Editor access to a database.

Dim db As New NotesDatabase( "Warsaw", "data\discuss.nsf" )

Dim acl As NotesACL

Dim entry As NotesACLEntry

Set acl = db.ACL

Set entry = acl.CreateACLEntry _

( "Shelly McPhail", ACLLEVEL_EDITOR )

Call acl.Save

See also
Examining and adjusting an access control list
NotesACLEntry class


DeleteRole method

Deletes a role from an ACL.

Defined in

NotesACL

Syntax

Call notesACL.DeleteRole( name$ )

Parameter

name$

String. The name of the role to remove.

Usage

If the role you specified does not exist in the ACL, Notes raises the error "Role name not found."

See examples
Example: DeleteRole method

See also
AddRole method
DisableRole method (in NotesACLEntry)
EnableRole method (in NotesACLEntry)
Examining and adjusting an access control list
IsRoleEnabled method (in NotesACLEntry)
Roles property (in NotesACL)
Roles property (in NotesACLEntry)


GetEntry method

Given a name, finds its entry in an ACL.

Defined in

NotesACL

Syntax

Set notesACLEntry = notesACL.GetEntry( name$ )

Parameter

name$

String. The name whose ACL entry you want to find. The name must be an exact match, including case.

Return value

notesACLEntry

The ACL entry that matches name$. If name$ is not in the ACL, returns Nothing.

Usage

GetEntry can find people, groups, or servers in an ACL. If a person is not listed explicitly in the ACL, but is a member of a group that's listed in the ACL, GetEntry does not find that person's name. If you need this capability, use the QueryAccess method in NotesDatabase.

See examples
Examples: GetEntry method

See also
Examining and adjusting an access control list
GetFirstEntry method
GetNextEntry method
NotesACLEntry class
QueryAccess method (in NotesDatabase)


GetFirstEntry method

Returns the first entry in an ACL, usually the Default entry.

Defined in

NotesACL

Syntax

Set notesACLEntry = notesACL.GetFirstEntry

Return value

notesACLEntry

The first entry in the ACL.

See examples
Example: GetFirstEntry method

See also
Examining and adjusting an access control list
GetEntry method
GetNextEntry method
NotesACLEntry class


GetNextEntry method

Given an ACL entry, returns the next one.

Defined in

NotesACL

Syntax

Set notesACLEntry = notesACL.GetNextEntry( notesACLEntry )

Parameter

notesACLEntry

Any entry in the ACL. If you specify Nothing, this method will generate an error.

Return value

notesACLEntry

The entry following the specified notesACLEntry parameter in the ACL. Returns Nothing if there are no more entries.

See examples
Example: GetNextEntry method

See also
Examining and adjusting an access control list
GetEntry method
GetFirstEntry method
NotesACLEntry class


RenameRole method

Changes the name of a role.

Defined in

NotesACL

Syntax

Call notesACL.RenameRole( oldName$, newName$ )

Parameters

oldName$

String. The current name of the role.

newName$

String. The new name you want to give to the role.

Usage

When you rename a role, any entries in the ACL that had the old role get the new role.

See examples
Example: RenameRole method

See also
AddRole method
DisableRole method (in NotesACLEntry)
EnableRole method (in NotesACLEntry)
Examining and adjusting an access control list
Roles property (in NotesACL)
Roles property (in NotesACLEntry)


RemoveACLEntry method

Removes an entry from the ACL.

Note This method is new with Release 5.0.2b.

Note This method is supported in COM only.

Defined in

NotesACL

Syntax

Call notesACL.RemoveACLEntry( name$ )

Parameters

name$

String. The name of the person, group, or server whose entry you want to remove. You must supply the complete name but hierarchical names can be in abbreviated format. Case is not significant.

Usage

You must call Save on the ACL if you want the modified ACL to be saved to disk.

See examples
Examples: RemoveACLEntry method


Save method

Saves the changes you've made to the ACL. If you don't call Save before closing a database, the changes you've made to its ACL are lost.

Defined in

NotesACL

Syntax

Call notesACL.Save

See examples
Examples: Save method

See also
Examining and adjusting an access control list


NotesACLEntry class

Represents a single entry in an access control list. An entry may be for a person, a group, or a server.

Containment

Contained by: NotesACL

Properties

CanCreateDocuments

CanCreateLSOrJavaAgent

CanCreatePersonalAgent

CanCreatePersonalFolder

CanCreateSharedFolder

CanDeleteDocuments

IsAdminReaderAuthor

IsAdminServer

IsGroup

IsPerson

IsPublicReader

IsPublicWriter

IsServer

Level

Name

NameObject

Parent

Roles

UserType

Methods

DisableRole

EnableRole

IsRoleEnabled

New

Remove

Creation

To create a new NotesACLEntry object, use one of the following:

  • New

Note The New method is not supported in COM.

  • CreateACLEntry method in NotesACL

New creates an entry in an ACL with the name and level that you specify.

You must call Save on the ACL if you want the modified ACL to be saved to disk.

Syntax

Dim variableName As New NotesACLEntry( notesACL, name$, level% )

or

Set notesACLEntry = New NotesACLEntry( notesACL, name$, level% )

Parameters

notesACL

The ACL that contains the entry you're creating.

name$

String. The name of the person, group, or server for whom you want to create an entry in the ACL.

level%

Constant. The level you want to assign to this person, group, or server in the ACL. May be any of the following:

ACLLEVEL_NOACCESS (0) | No access
ACLLEVEL_DEPOSITOR (1) | Depositor access
ACLLEVEL_READER (2) | Reader access
ACLLEVEL_AUTHOR (3) | Author access
ACLLEVEL_EDITOR (4) | Editor access
ACLLEVEL_DESIGNER (5) | Designer access
ACLLEVEL_MANAGER (6) | Manager access

Access

NotesACL provides three ways to access an existing NotesACLEntry.

  • To access an entry in an ACL when you know its name, use GetEntry.

  • To access the first entry in the ACL, use GetFirstEntry.

  • To access entries after the first one, use GetNextEntry.

See examples
Examples: NotesACLEntry class

See also
CreateACLEntry method (in NotesACL)
Examining and adjusting an access control list
NotesACL class
Using the Domino classes


CanCreateDocuments property

Read-Write. For an entry with Author access to a database, indicates if the entry is allowed to create new documents.

Defined in

NotesACLEntry

Data type

Boolean

Syntax

To get: flag = notesACLEntry.CanCreateDocuments

To set: notesACLEntry.CanCreateDocuments = flag

Legal values

  • True indicates that the entry can create new documents in the database

  • False indicates that the entry cannot create new documents in the database

Usage

After setting this property, you must call Save on the parent NotesACL in order for the changes to take effect. If you do not call Save, your changes to the NotesACLEntry are lost.

Setting this property has no effect on an ACL entry unless the entry has Author access to a database. If an entry has Editor, Designer, Depositor, or Manager access, this property is always True. If an entry has Reader or No access, this property is always False.

See examples
Example: CanCreateDocuments property

See also
CanCreatePersonalAgent property
CanCreatePersonalFolder property
CanDeleteDocuments property
Examining and adjusting an access control list
Save method (in NotesACL)


CanCreateLSOrJavaAgent property

Read-write. For an entry with Reader access, indicates if the entry is allowed to create LotusScript or Java agents.

Note This property is new with Release 5.

Defined in

NotesACLEntry

Data type

Boolean

Syntax

To get: flag = notesACLEntry.CanCreateLSOrJavaAgent

To set: notesACLEntry.CanCreateLSOrJavaAgent = flag

Legal values

  • True indicates that the entry can create LotusScript or Java agents in the database

  • False indicates that the entry cannot create LotusScript or Java agents in the database

Usage

After setting this property, you must call Save on the parent NotesACL in order for the changes to take effect. If you do not call Save, your changes to the NotesACLEntry are lost.

See examples
Example: CanCreateLSOrJavaAgent property


CanCreatePersonalAgent property

Read-write. Indicates if an entry can create personal agents in a database.

Defined in

NotesACLEntry

Data type

Boolean

Syntax

To get: flag = notesACLEntry.CanCreatePersonalAgent

To set: notesACLEntry.CanCreatePersonalAgent = flag

Legal values

  • True indicates that the entry can create personal agents in the database

  • False indicates that the entry cannot create personal agents

Usage

After setting this property, you must call Save on the parent NotesACL in order for the changes to take effect. If you do not call Save, your changes to the NotesACLEntry are lost.

If an entry has Designer access or above, setting this property to False has no effect.

See examples
Example: CanCreatePersonalAgent property

See also
CanCreateDocuments property
CanCreatePersonalFolder property
CanDeleteDocuments property
Examining and adjusting an access control list
Save method (in NotesACL)


CanCreatePersonalFolder property

Read-write. Indicates if an entry can create personal folders in a database.

Defined in

NotesACLEntry

Data type

Boolean

Syntax

To get: flag = notesACLEntry.CanCreatePersonalFolder

To set: notesACLEntry.CanCreatePersonalFolder = flag

Legal values

  • True indicates that the entry can create personal folders in the database

  • False indicates that the entry cannot create personal folders

Usage

After setting this property, you must call Save on the parent NotesACL in order for the changes to take effect. If you do not call Save, your changes to the NotesACLEntry are lost.

If an entry has Designer access or above, setting this property to False has no effect.

See examples
Example: CanCreatePersonalFolder property

See also
CanCreateDocuments property
CanCreatePersonalAgent property
CanDeleteDocuments property
Examining and adjusting an access control list
Save method (in NotesACL)


CanCreateSharedFolder property

Read-write. For an entry with Editor access to the database, indicates if the entry can create shared folders.

Note This property is new with Release 5.

Defined in

NotesACLEntry

Data type

Boolean

Syntax

To get: flag = notesACLEntry.CanCreateSharedFolder

To set: notesACLEntry.CanCreateSharedFolder = flag

Legal values

  • True indicates that the entry can create shared folders in the database

  • False indicates that the entry cannot create shared folders in the database

Usage

After setting this property, you must call Save on the parent NotesACL in order for the changes to take effect. If you do not call Save, your changes to the NotesACLEntry are lost.

See examples
Example: CanCreateSharedFolder property


CanDeleteDocuments property

Read-Write. For an entry with Author access or above to a database, indicates if an entry can delete documents.

Defined in

NotesACLEntry

Data type

Boolean

Syntax

To get: flag = notesACLEntry.CanDeleteDocuments

To set: notesACLEntry.CanDeleteDocuments = flag

Legal values

  • True indicates that the entry can delete documents from the database

  • False indicates that the entry cannot delete documents from the database

Usage

After setting this property, you must call Save on the parent NotesACL in order for the changes to take effect. If you do not call Save, your changes to the NotesACLEntry are lost.

Setting this property has no effect on an ACL entry unless the entry has Author access or above to a database. If an entry has Reader, Depositor, or No access, this property is always False.

See examples
Example: CanDeleteDocuments property

See also
CanCreateDocuments property
CanCreatePersonalAgent property
CanCreatePersonalFolder property
Examining and adjusting an access control list
Save method (in NotesACL)


IsAdminReaderAuthor property

Read-write. Indicates if an entry that is an administration server can modify reader and author fields.

Note This property is new with Release 5.

Defined in

NotesACLEntry

Data type

Boolean

Syntax

To get: flag = notesACLEntry.IsAdminReaderAuthor

To set: notesACLEntry.IsAdminReaderAuthor = flag

Legal values

  • True indicates that the entry is an administrative server and can modify reader and author fields

  • False indicates that the entry cannot modify reader and author fields

Usage

If the ACL entry is not an administration server, setting AdminReaderAuthor to True does nothing. No error occurs and the property remains False. Use IsAdminServer to check and change the entry.

After setting this property, you must call Save on the parent NotesACL in order for the changes to take effect. If you do not call Save, your changes to the NotesACLEntry are lost.

See examples
Example: IsAdminServer and IsAdminReaderAuthor properties


IsAdminServer property

Read-write. Indicates if this entry is allowed to administer the server.

Note This property is new with Release 5.

Defined in

NotesACLEntry

Data type

Boolean

Syntax

To get: flag = notesACLEntry.IsAdminServer

To set: notesACLEntry.IsAdminServer = flag

Legal values

  • True indicates that the entry can administer the server

  • False indicates that the entry cannot administer the server

Usage

This property has no effect on UserType, IsGroup, IsPerson, and IsServer.

After setting this property, you must call Save on the parent NotesACL in order for the changes to take effect. If you do not call Save, your changes to the NotesACLEntry are lost.

See examples
Example: IsAdminServer and IsAdminReaderAuthor properties


IsGroup property

Read-write. Indicates if this is a group entry.

Note This property is new with Release 5.

Defined in

NotesACLEntry

Data type

Boolean

Syntax

To get: flag = notesACLEntry.IsGroup

To set: notesACLEntry.IsGroup = flag

Legal values

  • True indicates that this is a group entry

  • False indicates that this is not a group entry

Usage

After setting this property, you must call Save on the parent NotesACL in order for the changes to take effect. If you do not call Save, your changes to the NotesACLEntry are lost.

See examples
Example: IsGroup property


IsPerson property

Read-write. Indicates if this is a person entry.

Note This property is new with Release 5.

Defined in

NotesACLEntry

Data type

Boolean

Syntax

To get: flag = notesACLEntry.IsPerson

To set: notesACLEntry.IsPerson = flag

Legal values

  • True indicates that this is a person entry

  • False indicates that this is not a person entry

Usage

After setting this property, you must call Save on the parent NotesACL in order for the changes to take effect. If you do not call Save, your changes to the NotesACLEntry are lost.

See examples
Example: IsPerson property


IsPublicReader property

Read-write. Indicates if the current entry is a public reader of the database.

Defined in

NotesACLEntry

Data type

Boolean

Syntax

To get: flag = notesACLEntry.IsPublicReader

To set: notesACLEntry.IsPublicReader = flag

Legal values

  • True indicates that the current entry is a public reader

  • False indicates that the current entry is not a public reader

Usage

For the No Access and Depositor access levels, the "Read Public Documents" option in the ACL dialog is enabled by default. If you check the box, you set the IsPublicReader property to True. If not, the property is set to False.

For the Reader, Author, Editor, Designer, and Manager access levels, the "Read Public Documents" option in the ACL dialog is enabled and checked by default. The checkbox is greyed out and the IsPublicReader property remains set to True.

See examples
Example: IsPublicReader property

See also
IsPublicWriter property
Examining and adjusting an access control list


IsPublicWriter property

Read-write. Indicates if the current entry is a public writer of the database.

Defined in

NotesACLEntry

Data type

Boolean

Syntax

To get: flag = notesACLEntry.IsPublicWriter

To set: notesACLEntry.IsPublicWriter = flag

Legal values

  • True indicates that the current entry is a public writer

  • False indicates that the current entry is not a public writer

Usage

For the No Access, Depositor, Reader, and Author access levels, the "Write Public Documents" option in the ACL dialog is enabled by default. If you check the box, you set the IsPublicWriter property to True. If not, the property is set to False.

For the Editor, Designer, and Manager access levels, the "Write Public Documents" option in the ACL dialog is enabled and checked by default. The checkbox is greyed out and the IsPublicWriter property remains set to True.

See examples
Example: IsPublicWriter property

See also
IsPublicReader property
Examining and adjusting an access control list


IsServer property

Read-write. Indicates if this is a server entry.

Note This property is new with Release 5.

Defined in

NotesACLEntry

Data type

Boolean

Syntax

To get: flag = notesACLEntry.IsServer

To set: notesACLEntry.IsServer = flag

Legal values

  • True indicates that this is a server entry

  • False indicates that this is not a server entry

Usage

After setting this property, you must call Save on the parent NotesACL in order for the changes to take effect. If you do not call Save, your changes to the NotesACLEntry are lost.

See examples
Example: IsServer property


Level property

Read-Write. The access level this entry has for this database.

Defined in

NotesACLEntry

Data type

Constant of type integer

Syntax

To get: level% = notesACLEntry.Level

To set: notesACLEntry.Level = level%

Legal values

  • ACLLEVEL_NOACCESS (0)

  • ACLLEVEL_DEPOSITOR (1)

  • ACLLEVEL_READER (2)

  • ACLLEVEL_AUTHOR (3)

  • ACLLEVEL_EDITOR (4)

  • ACLLEVEL_DESIGNER (5)

  • ACLLEVEL_MANAGER (6)

Note These values are also used with the CreateACLEntry method and InternetLevel property in the NotesACL class, and the CurrentAccessLevel property, GrantAccess method, and QueryAccess method in the NotesDatabase class.

See examples
Examples: Level property

See also
CurrentAccessLevel property (in NotesDatabase)
Examining and adjusting an access control list


Name property

Read-Write. The name of an entry.

Defined in

NotesACLEntry

Data type

String

Syntax

To get: name$ = notesACLEntry.Name

To set: notesACLEntry.Name = name$

Usage

If you change the name of an entry, the other attributes of the entry (such as Level) are preserved.

If you specify Nothing, this method will generate an error.

See examples
Examples: Name property

See also
Examining and adjusting an access control list


NameObject property

Read-only. The name of an entry.

Note This property is new with Release 5.0.2b.

Note This property is supported in COM only.

Defined in

NotesACLEntry

Data type

NotesName

Syntax

To get: Set notesName = notesACLEntry.NameObject

See examples
Example: NameObject property


Parent property

Read-only. The access control list that contains an entry.

Defined in

NotesACLEntry

Data type

NotesACL

Syntax

To get: Set notesACL = notesACLEntry.Parent

See examples
Example: Parent property


Roles property

Read-only. The roles that are enabled for an entry.

Defined in

NotesACLEntry

Data type

Array of strings

Syntax

To get: stringArray = notesACLEntry.Roles

Usage

Each element in the array is the name of a role. Each role name is surrounded by square brackets, for example, "[Supervisor]."

Notes Release 2 "privileges" are surrounded by parentheses. Properties and methods affecting roles, such as DisableRole and EnableRole, do not work on privileges.

See examples
Example: Roles property

See also
AddRole method (in NotesACL)
DeleteRole method (in NotesACL)
DisableRole method
EnableRole method
IsRoleEnabled method
Roles property (in NotesACL)


UserType property

Read-Write. Indicates the type of user for a particular entry.

Note This property is new with Release 5.

Defined in

NotesACLEntry

Data type

Constant of type integer

Syntax

To get: usertype% = notesACLEntry.UserType

To set: notesACLEntry.UserType = usertype%

Legal values

  • ACLTYPE_UNSPECIFIED (0)

  • ACLTYPE_PERSON (1)

  • ACLTYPE_SERVER (2)

  • ACLTYPE_MIXED_GROUP (3)

  • ACLTYPE_PERSON_GROUP (4)

  • ACLTYPE_SERVER_GROUP (5)


DisableRole method

Given a role, disables the role for an entry.

Defined in

NotesACLEntry

Syntax

Call notesACLEntry.DisableRole( name$ )

Parameter

name$

String. The name of the role to disable.

Usage

If the role does not exist in the access control list, this method raises the error "Role name not found."

If the role exists in the ACL, but is already disabled for the entry, this method does nothing.

See examples
Example: DisableRole method

See also
AddRole method (in NotesACL)
DeleteRole method (in NotesACL)
EnableRole method
Examining and adjusting an access control list
IsRoleEnabled method
Roles property (in NotesACL)
Roles property (in NotesACLEntry)


EnableRole method

Given the name of a role, enables the role for an entry.

Defined in

NotesACLEntry

Syntax

Call notesACLEntry.EnableRole( name$ )

Parameter

name$

String. The name of the role to enable.

Usage

If the role does not exist in the access control list, this method raises the error "Role name not found."

If the role exists in the ACL, and is already enabled for the entry, this method does nothing.

See examples
Examples: EnableRole method

See also
DisableRole method
IsRoleEnabled method
Roles property (in NotesACL)
Roles property (in NotesACLEntry)
AddRole method (in NotesACL)
DeleteRole method (in NotesACL)
Examining and adjusting an access control list


IsRoleEnabled method

Given a role, indicates if the role is enabled for an entry.

Defined in

NotesACLEntry

Syntax

flag = notesACLEntry.IsRoleEnabled( name$ )

Parameter

name$

String. The name of the role.

Return value

True | The role is enabled for this entry.
False | The role is not enabled.

See examples
Example: IsRoleEnabled method

See also
AddRole method (in NotesACL)
DeleteRole method (in NotesACL)
DisableRole method
EnableRole method
Examining and adjusting an access control list
Roles property (in NotesACL)
Roles property (in NotesACLEntry)


Remove method

Removes an entry from an access control list.

Defined in

NotesACLEntry

Syntax

Call notesACLEntry.Remove

Usage

Once an entry is removed from an ACL, that person, server, or group may still access the database at the level permitted by the Default entry.

See examples
Example: Remove method

See also
Examining and adjusting an access control list
RevokeAccess method (in NotesDatabase)


NotesAgent class

Represents an agent. The agent may be public or personal, and may be a Release 3 macro.

Containment

Contained by: NotesSession and NotesDatabase

Properties

Comment

CommonOwner

HasRunSinceModified

HttpURL

IsEnabled

IsNotesAgent

IsPublic

IsWebAgent

LastRun

Name

NotesURL

Owner

ParameterDocID

Parent

Query

ServerName

Target

Trigger

Methods

Remove

Run

RunOnServer

Save

Access

There are two ways to access an agent.

  • To access the agent that's currently running, use the CurrentAgent property in NotesSession.

  • To access all the agents in a database, use the Agents property in NotesDatabase.

See examples
Examples: NotesAgent class

See also
Accessing agents
Using the Domino classes


Comment property

Read-only. The comment that describes an agent, as entered by the agent's designer.

Defined in

NotesAgent

Data type

String

Syntax

To get: comment$ = notesAgent.Comment

See examples
Examples: Comment property


CommonOwner property

Read-only. The name of the person who last modified and saved an agent (the agent's owner). If the owner has a hierarchical name, only the common name is returned.

Defined in

NotesAgent

Data type

String

Syntax

To get: commonOwner$ = notesAgent.CommonOwner

Usage

If the owner's name is flat (non-hierarchical), the CommonOwner name is the same as the Owner name.

See examples
Example: CommonOwner property

See also
Owner property


HasRunSinceModified property

Read-only. Indicates if an agent has run since it was created or last modified.

Note This property is new with Release 5.

Defined in

NotesAgent

Data type

Boolean

Syntax

flag = notesAgent.HasRunSinceModified

Legal values

  • True indicates that the agent has run since it was created or last modified

  • False indicates that the agent has not run since it was created or last modified

Usage

To determine the date and time when the agent last ran, use the LastRun property.


HttpURL property

Read-only. The HTTP URL of an agent.

Note This property is new with Release 5.0.2b.

Note This property is supported in COM only.

Defined in

NotesAgent

Data type

String

Syntax

To get: url$ = notesAgent.HttpURL


IsEnabled property

Read-write. Indicates if an agent is able to run or not.

Defined in

NotesAgent

Data type

Boolean

Syntax

To get: flag = notesAgent.IsEnabled

To set: notesAgent.IsEnabled = flag

Legal values

  • True indicates that the agent can be run

  • False indicates that the agent is disabled and cannot be run

Usage

This property is intended for use with scheduled agents, which can be enabled and disabled. This property always returns True for hidden agents and agents that are run from a menu.

If you change the enabled status in an agent, you must call the Save method to commit the change to disk. You must have the appropriate access privileges to the database and to the agent.

See examples
Example: IsEnabled property


IsNotesAgent property

Read-only. Indicates if an agent can run in the Notes client environment.

Note This property is new with Release 5.

Defined in

NotesAgent

Data type

Boolean

Syntax

flag = notesAgent.IsNotesAgent

Legal values

  • True indicates that the agent can run in the Notes client environment

  • False indicates that the agent cannot run in the Notes client environment

See examples
Example: IsNotesAgent property

See also
Accessing agents


IsPublic property

Read-only. Indicates if an agent is public or personal.

  • A public agent is accessible to all users of a database and is stored in the database.

  • A personal agent is accessible only to its owner and is stored in the owner's desktop file.

Defined in

NotesAgent

Data type

Boolean

Syntax

To get: flag = notesAgent.IsPublic

Legal values

  • True indicates that the agent is public

  • False indicates that the agent is personal

See examples
Example: IsPublic property


IsWebAgent property

Read-only. Indicates if an agent can run in a Web browser environment.

Note This property is new with Release 5.

Defined in

NotesAgent

Data type

Boolean

Syntax

flag = notesAgent.IsWebAgent

Legal values

  • True indicates that the agent can run in a Web browser environment

  • False indicates that the agent cannot run in a Web browser environment

See examples
Example: IsWebAgent property

See also
Accessing agents


LastRun property

Read-only. The date that an agent last ran.

Defined in

NotesAgent

Data type

Variant of type DATE

Syntax

To get: dateV = notesAgent.LastRun

Usage

If the script has never been run before, this property returns a variant containing the date-time value 12:00:00 AM.

To determine whether or not the agent ran since it was created or last modified, use the HasRunSinceModified property.

See examples
Examples: LastRun property

See also
LastExitStatus property (in NotesSession)
LastRun property (in NotesSession)


Name property

Read-only. The name of an agent. Within a database, the name of an agent may not be unique.

Defined in

NotesAgent

Data type

String

Syntax

To get: agentName$ = notesAgent.Name

See examples
Example: Name property


NotesURL property

Read-only. The Notes URL of an agent.

Note This property is new with Release 5.0.2b.

Note This property is supported in COM only.

Defined in

NotesAgent

Data type

String

Syntax

To get: url$ = notesAgent.NotesURL


Owner property

Read-only. The name of the person who last modified and saved an agent (the agent's owner).

Defined in

NotesAgent

Data type

String

Syntax

To get: ownerName$ = notesAgent.Owner

Usage

If the owner's name is hierarchical, this property returns the fully distinguished name. If the owner's name is flat (non-hierarchical), the CommonOwner name is the same as the Owner name.

See examples
Examples: Owner property

See also
CommonOwner property


ParameterDocID property

Read-only. Returns the NoteID of a document passed to the agent by Run or RunOnServer.

Note This property is new with Release 5.02.

Defined in

NotesAgent

Data type

String

Syntax

To get: paramid$ = notesAgent.ParameterDocID

Usage

Use GetDocumentByID method in NotesDatabase to retrieve a document with NoteID.

See examples
Example: Run method

See also
Accessing agents


Parent property

Read-only. The database that contains an agent.

Defined in

NotesAgent

Data type

NotesDatabase

Syntax

To get: Set notesDatabase = notesAgent.Parent

See examples
Examples: Parent property


Query property

Read-only. The text of the query used by an agent to select documents. In the Agent Builder, a query is defined by the searches added to the agent using the Add Search button.

If there is no query defined with the Add Search button, the Query property returns an empty string, even if the agent runs a formula that has its own SELECT statement or a script that selects specific documents.

Defined in

NotesAgent

Data type

String

Syntax

To get: query$ = notesAgent.Query

See examples
Examples: Query property

See also
UnprocessedDocuments property (in NotesDatabase)
UnprocessedFTSearch method (in NotesDatabase)
UnprocessedSearch method (in NotesDatabase)


ServerName property

Read-write. The name of the server on which an agent runs.

Defined in

NotesAgent

Data type

String

Syntax

To get: server$ = notesAgent.ServerName

To set: notesAgent.ServerName = server$

Usage

The value of the ServerName property depends upon whether or not the agent is scheduled:

  • If the agent is scheduled, the property returns the name of the server that the scheduled agent runs on. Since scheduled agents can only run on a single replica of a database, you designate a server name for the agent under Schedule in the Agent Builder. Therefore, the ServerName property may represent the parent database's server, or it may represent a replica's server.

  • If the agent is not scheduled, this property returns an empty string.

  • If you change the server name in an agent, you must call the Save method to commit the change to disk. You must have the appropriate access privileges to the database and to the agent.

  • If you want the agent to run on all servers, use an asterisk (*) for the server name.

See examples
Example: ServerName property

See also
IsOnServer property (in NotesSession)
ReplicaID property (in NotesDatabase)
Server property (in NotesDatabase)


Target property

Read-only. Indicates which documents this agent acts on.

Note This property is new with Release 5.

Defined in

NotesAgent

Data type

Boolean or Constant of type integer

Syntax

To get: flagIntegerConstant = notesAgent.Target

Usage

This property corresponds to "Which document(s) should it act on?" in the Designer UI for agents. The trigger limits the target possibilities. The TARGET_NONE targets are the only possibilities for their corresponding triggers.

Legal values

  • TARGET_ALL_DOCS (1) means "All documents in database"

  • TARGET_ALL_DOCS_IN_VIEW (5) means "All documents in view"

  • TARGET_NEW_DOCS (2) is not used

  • TARGET_NEW_OR_MODIFIED_DOCS (3) means "All new and modified documents since last run"

  • TARGET_NONE (0) means "Each incoming mail document," "Newly received mail documents," "Newly modified documents," or "Pasted documents"

  • TARGET_SELECTED_DOCS (4) means "Selected documents"

  • TARGET_UNREAD_DOCS_IN_VIEW (6) means "All unread documents in view"

  • TARGET_RUN_ONCE (8) means "Run once"

    Note This constant is new with Release 5.01.

See examples
Examples: Target property


Trigger property

Read-only. Indicates when this agent runs.

Note This property is new with Release 5.

Defined in

NotesAgent

Data type

Boolean or Constant of type integer

Syntax

To get: flagIntegerConstant = notesAgent.Trigger

Usage

This property corresponds to "When should this agent run?" in the Designer UI for agents.

This property determines the target possibilities. The TRIGGER_AFTER_MAIL_DELIVERY, TRIGGER_BEFORE_MAIL_DELIVERY, TRIGGER_DOC_PASTED, and TRIGGER_DOC_UPDATE triggers have only one target, which returns TARGET_NONE.

Legal values

  • TRIGGER_AFTER_MAIL_DELIVERY (2) means "After New Mail Has Arrived"

  • TRIGGER_BEFORE_MAIL_DELIVERY (6) means "Before New Mail Arrives"

  • TRIGGER_DOC_PASTED (3) means "If Documents Have Been Pasted"

  • TRIGGER_DOC_UPDATE (5) means "If Documents Have Been Created or Modified"

  • TRIGGER_MANUAL (4) means "Manually From Actions Menu," "Manually From Agent List"

  • TRIGGER_NONE (0) is not used

  • TRIGGER_SCHEDULED (1) means "On Schedule More Than Once A Day," "On Schedule Daily," "On Schedule Weekly", "On Schedule Monthly," or "On Schedule Never"

See examples
Examples: Trigger property


Remove method

Permanently deletes an agent from a database.

Defined in

NotesAgent

Syntax

Call notesAgent.Remove

Usage

Once you call this method, the NotesAgent object is Nothing and you can no longer use its methods or properties.

It is possible to use this method to delete the agent that's currently running. Use this feature with care. You must refresh the Agents view in the user interface to see that the agent has been removed.

See examples
Examples: Remove method


Run method

Runs the agent.

Defined in

NotesAgent

Syntax

status = notesAgent.Run( [ noteID$ ] )

Parameter

noteID$

String. Optional. The NoteID of a document. The value is passed to the ParameterDocID property of the called agent.

Note This parameter is new with Release 5.02.

Return value

status

Integer. Status of the operation where 0 indicates success.

Usage

You cannot run an agent recursively (cannot call it from itself).

The user cannot interact directly with a called agent. User output goes to the Domino log.

You cannot debug a called agent.

You cannot use the Notes UI classes in an agent called by this method.

See examples
Example: Run method

See also
Accessing agents


RunOnServer method

Runs the agent on the computer containing the database.

Note This method is new with Release 4.6.1.

Defined in

NotesAgent

Syntax

status = notesAgent.RunOnServer( [ noteID$ ] )

Parameter

noteID$

String. Optional. The NoteID of a document. This value is passed to the ParameterDocID property of the called agent.

Note This parameter is new with Release 5.02.

Return value

status

Integer. Status of the operation where 0 indicates success.

Usage

You cannot run an agent recursively (cannot call it from itself).

The rules governing the access level required to run an agent using the RunOnServer method are the same as for any other server-based agent. For information regarding agent security, see the topic "Setting up agent security" in the printed book Application Development with Domino Designer.

The user cannot interact directly with a called agent. User output goes to the Domino log.

You cannot debug a called agent.

On a local database, the RunOnServer method works like the Run method, that is, runs the agent on the local computer.

Note This behavior is new with Release 5.0.2. The former behavior was to issue the error message "RunOnServer must be used with a remote database."

If a Notes client invokes RunOnServer, security is through the signer of the agent.

See examples
Example: RunOnServer method

See also
Accessing agents


Save method

Saves the agent.

Note This method is new with Release 4.6.

Defined in

NotesAgent

Syntax

Call notesAgent.Save

Usage

If you change the IsEnabled property or the ServerName property in an agent, you must call the Save method to commit the change to disk. You must have the appropriate access privileges to the database and to the agent.


NotesDatabase class

Represents a Notes database.

Containment

Contained by: NotesSession, NotesDbDirectory, and NotesUIDatabase

Can contain: NotesACL, NotesAgent, NotesDocument, NotesDocumentCollection, NotesForm, NotesOutline, NotesReplication, NotesView

Properties

ACL

Agents

AllDocuments

Categories

Created

CurrentAccessLevel

DelayUpdates

DesignTemplateName

FileName

FilePath

FolderReferencesEnabled

Forms

HttpURL

IsDirectoryCatalog

IsFTIndexed

IsMultiDbSearch

IsOpen

IsPrivateAddressBook

IsPublicAddressBook

LastFTIndexed

LastModified

Managers

MaxSize

NotesURL

Parent

PercentUsed

ReplicaID

ReplicationInfo

Server

Size

SizeQuota

TemplateName

Title

UnprocessedDocuments

Views

Methods

Compact

Create

CreateCopy

CreateDocument

CreateFromTemplate

CreateOutline

CreateReplica

EnableFolder

FTDomainSearch

FTSearch

GetAgent

GetDocumentByID

GetDocumentByUNID

GetDocumentByURL

GetForm

GetOutline

GetProfileDocument

GetProfileDocCollection

GetURLHeaderInfo

GetView

GrantAccess

New

Open

OpenByReplicaID

OpenIfModified

OpenMail

OpenURLDb

OpenWithFailover

QueryAccess

Remove

Replicate

RevokeAccess

Search

UnprocessedFTSearch

UnprocessedSearch

UpdateFTIndex

Creation and access

There are several ways a script can use the NotesDatabase class to access existing databases and to create new ones.

  • To access an existing database when you know its server and file name, use New, or the GetDatabase method in NotesSession.

  • To access the database in which a script is currently running, without indicating a server or file name, use the CurrentDatabase property in NotesSession.

  • To access an existing database when you know its server and replica ID, use the OpenByReplicaID method.

  • To access an existing database when you know its server but not its file name, use the NotesDbDirectory class.

  • To access the current user's mail database, use the OpenMail method.

  • To open the default Web Navigator database, use the OpenURLDb method.

  • To access the available Address books, use the AddressBooks property in NotesSession.

  • To test for the existence of a database with a specific server and file name before accessing it, use one of these properties or methods: IsOpen, Open, OpenIfModified.

  • To create a new database from an existing database, use one of these methods: CreateCopy, CreateFromTemplate, CreateReplica.

  • To create a new database from scratch, use the Create method.

  • To access a database when you have a NotesView, NotesDocument, NotesDocumentCollection, NotesACL, or NotesAgent from that database, use the appropriate Parent (or ParentDatabase) property.

New

Note The New method is not supported in COM.

Creates a NotesDatabase object that represents the database located at the server and file name you specify, and opens the database, if possible. Unlike the behavior of New in other classes (such as NotesDocument), using New for a NotesDatabase does not create a new database on disk.

Syntax

Dim variableName As New NotesDatabase( server$, dbfile$ )

or

Set notesDatabase = New NotesDatabase( server$, dbfile$ )

Parameters

server$

String. The name of the server on which the database resides. Use an empty string ("") to indicate a database on the current computer: if the script runs on the workstation, the empty string indicates a local database; if the script runs on a server, it indicates a database on that server.

dbfile$

String. The path and file name of the database within the Notes or Domino data directory. Use empty strings for both dbfile$ and server$ if you want to open the database later. Use a full path name if the database is not within the Notes data directory.

Return value

notesDatabase

A NotesDatabase object that can be used to access the database you've specified.

  • If a database exists at the server$ and dbfile$ specified, the NotesDatabase object is open, and the script can access all its properties and methods.

  • If a database does not exist at the server$ and dbfile$ specified, the NotesDatabase object is closed. To create a new database at the specified location, use this NotesDatabase object with the Create method.

Usage

A database must be open before a script can use the properties and methods in the corresponding NotesDatabase object. In most cases, the class library automatically opens a database for you. But watch out for the following cases:

  • A script that runs on a server cannot open a database that's on a different server. An error is returned if your script attempts to do so.

  • A script that attempts to open a database to which it does not have access returns an error. A script needs at least Reader access to a database in order to open it.

  • A NotesDatabase retrieved from a NotesDbDirectory object is closed. The following properties are available on the closed database: Categories, DelayUpdates, DesignTemplateName, FileName, FilePath, IsOpen, Parent, ReplicaID, Server, SizeQuota, TemplateName, Title. To access all the other properties and methods of a database retrieved from a NotesDbDirectory, a script must explicitly open the database.

  • A NotesDatabase retrieved from the AddressBooks property in NotesSession is closed. The following properties are available on the closed database: FileName, FilePath, IsOpen, IsPrivateAddressBook, IsPublicAddressBook, Parent, Server. To access all the other properties and methods of a database retrieved from the AddressBooks property, a script must explicitly open the database.

  • A NotesDatabase retrieved using New is closed if no database exists at the server$ and dbfile$ specified. The following properties are available on the closed database: FileName, FilePath, IsOpen, Parent, and Server.

To test if a database is open, use the IsOpen property. To open a database that's closed, use Open or OpenIfModified.

Access levels

Notes returns an error when a script attempts to perform an operation for which it doesn't have appropriate access. The properties and methods that a script can successfully use on a NotesDatabase object are determined by these factors:

  • The script's access level to the database, as determined by the database access control list. The ACL determines if the script can open a database, add documents to it, remove documents from it, modify the ACL, and so on.

  • The script's access level to the server on which the database resides, as determined by the Server document in the Domino Directory. The Server document determines when an agent can run and what LotusScript features it can use.

When a script runs on a server, the script's access level to databases and servers corresponds to the access level of the script's owner (the person who last saved the script). When a script runs on a workstation, the script's access level to databases and servers corresponds to the access level of the current user.

See examples
Examples: NotesDatabase class

See also
Examining and adjusting an access control list
Handling run-time errors
Using the Domino classes


ACL property

Read-only. The access control list for a database.

Defined in

NotesDatabase

Data type

NotesACL

Syntax

To get: Set notesACL = notesDatabase.ACL

For examples, see the NotesACL class.

See examples
Examples: NotesACL class

See also
Examining and adjusting an access control list
NotesACL Class


Agents property

Read-only. All of the agents in a database.

Defined in

NotesDatabase

Data type

Array of NotesAgents

Syntax

To get: notesAgentArray = notesDatabase.Agents

Usage

Each element in the array is a NotesAgent object. If the script runs on the workstation, the array includes public agents, and personal agents that belong to the current user. If the script runs on a server, the array includes only public agents.

To set the value of an individual NotesAgent object, you need to access the array elements individually. For example, to get the first element in the array returned from the NotesDatabase object db, you could do the following:

Dim agent as NotesAgent

Set agent = db.Agents( 0 )

See examples
Examples: Agents property

See also
Accessing agents
NotesAgent class


AllDocuments property

Read-only. All the documents in a database.

Defined in

NotesDatabase

Data type

NotesDocumentCollection

Syntax

To get: Set notesDocumentCollection = notesDatabase.AllDocuments

Return value

notesDocumentCollection

An unsorted collection containing all of the documents in the database.

Usage

Since many databases contain large numbers of documents, you may use the FTSearch or Search methods instead of the AllDocuments property. Both methods return a smaller collection of documents that meet specific criteria. Using AllDocuments is, however, more efficient than using the Search method with an @All formula.

See examples
Examples: AllDocuments property

See also
Collecting all documents and unprocessed documents
FTSearch method
Search method
UnprocessedDocuments property


Categories property

Read-Write. The categories under which a database appears in the Database Library. Multiple categories are separated by a comma or semicolon.

Defined in

NotesDatabase

Data type

Variant

Syntax

To get: categoryList = notesDatabase.Categories

To set: notesDatabase.Categories = categoryList

See examples
Examples: Categories property


Created property

Read-only. The date a database was created.

Defined in

NotesDatabase

Data type

Variant of type DATE

Syntax

To get: dateV = notesDatabase.Created

See examples
Examples: Created property

See also
LastModified property


CurrentAccessLevel property

Read-only. The current user's access level to a database.

Defined in

NotesDatabase

Data type

Constant of type integer

Syntax

To get: level% = notesDatabase.CurrentAccessLevel

Legal values

  • ACLLEVEL_NOACCESS (0)

  • ACLLEVEL_DEPOSITOR (1)

  • ACLLEVEL_READER (2)

  • ACLLEVEL_AUTHOR (3)

  • ACLLEVEL_EDITOR (4)

  • ACLLEVEL_DESIGNER (5)

  • ACLLEVEL_MANAGER (6)

Note These values are also used with the CreateACLEntry method and InternetLevel property in the NotesACL class, the Level property in the NotesACLEntry class, and the GrantAccess method and QueryAccess method in the NotesDatabase class.

Usage

  • If a script runs on a workstation, the CurrentAccessLevel is determined by the access level of the current user.

  • If a script runs on a server, the CurrentAccessLevel is determined by the access level of the person who last saved the script (the script owner).

See examples
Example: CurrentAccessLevel property

See also
CommonUserName property (in NotesSession)
Examining and adjusting an access control list
GrantAccess method
NotesACL class
NotesACLEntry class
QueryAccess method
RevokeAccess method
UserName property


DelayUpdates property

Read-write. Indicates whether updates to a server are delayed (batched) for better performance.

Defined in

NotesDatabase

Data type

Boolean

Syntax

To get: flag = notesDatabase.DelayUpdates

To set: notesDatabase.DelayUpdates = flag

Legal values

  • True indicates that server updates are delayed

  • False indicates that server updates are posted immediately; this is the default

Usage

If DelayUpdates is False, the script waits for updates to the server to be posted. If you set DelayUpdates to True, server updates are cached and the script proceeds immediately. At a convenient time, the cached updates are posted. This makes for better performance but risks losing the cached updates in the event of a crash. This method applies to Save and remove operations on documents.

See examples
Example: DelayUpdates property


DesignTemplateName property

Read-only. The name of the design template from which a database inherits its design. If the database does not inherit its design from a design template, returns an empty string ("").

Defined in

NotesDatabase

Data type

String

Syntax

To get: name$ = notesDatabase.DesignTemplateName

Usage

If a database inherits a specific design element (such as a form) but not its entire design from a template, this property returns an empty string ("").

See examples
Examples: DesignTemplateName property

See also
TemplateName property
CreateFromTemplate method


FileName property

Read-only. The full file name of a database, including the extension but excluding the path.

Defined in

NotesDatabase

Data type

String

Syntax

To get: fileName$ = notesDatabase.FileName

See examples
Examples: FileName property

See also
FilePath property
Server property
Title property


FilePath property

Read-only. The path and file name of a database. The file name includes the .nsf extension.

Defined in

NotesDatabase

Data type

String

Syntax

To get: path$ = notesDatabase.FilePath

Usage

If the database is on the Notes workstation, FilePath returns the complete path (for example, C:\Notes\data\sub\db.nsf). If the database is on a Notes server, FilePath returns the path relative to the Notes data directory (for example, sub\db.nsf).

See examples
Examples: FilePath property

See also
FileName property
Server property
Title property


FolderReferencesEnabled property

Read-write. Determines what folders, if any, a document is in.

Note This property is new with Release 5.

Defined in

NotesDatabase

Data type

Boolean

Syntax

To get: flag = notesDatabase.FolderReferencesEnabled

To set: notesDatabase.FolderReferencesEnabled = flag

Usage

Not all databases support folder references, so you should first test (using db.FolderReferencesEnabled) to make sure that the database supports folder references, prior to getting the folder references for a document in the database.

Note The database must have the $FolderRef and $FolderRefInfo hidden views to support folder references. These views can be copied from the Release 5 mail template. Also, this property does not return view references.

For more information, see the FolderReferences property in the NotesDocument class.

See examples
Examples: FolderReferencesEnabled property

See also
FolderReferences property


Forms property

Read-only. All the forms in a database.

Defined in

NotesDatabase

Data type

Array of NotesForm objects

Syntax

To get: notesForm Array = notesDatabase.Forms

See examples
Example: Forms property

See also
NotesForm Class
Accessing a form


HttpURL property

Read-only. The HTTP URL of a database.

Note This property is new with Release 5.0.2b.

Note This property is supported in COM only.

Defined in

NotesDatabase

Data type

String

Syntax

To get: url$ = notesDatabase.HttpURL


IsDirectoryCatalog property

Read-only. Indicates if a database is a Directory Catalog database, also known as the Light Weight NAB, or the Enterprise Address Book.

Note This property is new with Release 5.

Defined in

NotesDatabase

Data type

Boolean

Syntax

To get: flag = notesDatabase.IsDirectoryCatalog

Legal values

  • True indicates that the database is a Directory Catalog

  • False indicates that the database is not a Directory Catalog

Usage

This property is valid only for a database retrieved through the AddressBooks property of NotesSession, and when the database is explicitly opened. For all other NotesDatabase objects, this property returns False.

See examples
Example: IsDirectoryCatalog property


IsFTIndexed property

Read-only. Indicates whether or not a database has a full-text index.

Defined in

NotesDatabase

Data type

Boolean

Syntax

To get: flag = notesDatabase.IsFTindexed

Legal values

  • True indicates that the database has a full-text index

  • False indicates that the database does not have a full-text index

See examples
Examples: IsFTIndexed property

See also
FTSearch method (in NotesView)
FTSearch method (in NotesDatabase)
FTSearchScore property (in NotesDocument)
LastFTIndexed property
Locating documents within a view or folder
UnprocessedFTSearch method
UpdateFTIndex method


IsMultiDbSearch property

Read-only. Indicates whether a database is of type "Multi DB Search."

Defined in

NotesDatabase

Data type

Boolean

Syntax

To get: flag = notesDatabase.IsMultiDbSearch

Legal values

  • True indicates that the database is of type "Multi DB Search"

  • False indicates that the database is not of type "Multi DB Search"

See examples
Example: IsMultiDbSearch property

See also
Accessing database properties
FTSearch method


IsOpen property

Read-only. Indicates whether a database is open.

Defined in

NotesDatabase

Data type

Boolean

Syntax

To get: flag = notesDatabase.IsOpen

Legal values

  • True indicates that the database is open

  • False indicates that the database is not open

Usage

A database must be open to use the NotesDatabase properties except: Categories, DelayUpdates, DesignTemplateName, FileName, FilePath, IsOpen, IsPrivateAddressBook, IsPublicAddressBook, Parent, ReplicaID, Server, SizeQuota, TemplateName, and Title.

The following methods and property do not open a database: NotesDbDirectory.GetFirstDatabase, NotesDbDirectory.GetNextDatabase, and NotesSession.AddressBooks. You must explicitly call Database.Open.

See examples
Example: IsOpen property

See also
Handling run-time errors
Open method
OpenByReplicaID method
OpenIfModified method
OpenMail method
OpenURLDb method


IsPrivateAddressBook property

Read-only. Indicates if a database is a Personal Address Book.

Defined in

NotesDatabase

Data type

Boolean

Syntax

To get: flag = notesDatabase.IsPrivateAddressBook

Legal values

  • True indicates that the database is a Personal Address Book

  • False indicates that the database is not a Personal Address Book

Usage

This property is available for NotesDatabases retrieved from the AddressBooks property in NotesSession. For other NotesDatabase objects, this property has no value, and therefore evaluates to False when used in conditional statements.

See examples
Example: IsPrivateAddressBook property

See also
AddressBooks property (in NotesSession)
IsPublicAddressBook property


IsPublicAddressBook property

Read-only. Indicates if a database is a Domino Directory.

Defined in

NotesDatabase

Data type

Boolean

Syntax

To get: flag = notesDatabase.IsPublicAddressBook

Legal values

  • True indicates that the database is a Domino Directory

  • False indicates that the database is not a Domino Directory

Usage

This property is available for NotesDatabases retrieved from the AddressBooks property in NotesSession. For other NotesDatabase objects, this property has no value, and therefore evaluates to False when used in conditional statements.

See examples
Example: IsPublicAddressBook property

See also
AddressBooks property (in NotesSession)
IsPrivateAddressBook property


LastFTIndexed property

Read-only. The date that a database's full-text index was last updated.

Defined in

NotesDatabase

Data type

Variant of type DATE

Syntax

To get: dateV = notesDatabase.LastFTIndexed

Usage

If you are using Release 5 and the database does not have a full-text index, this property returns 12:00 a.m. If you are using a release prior to Release 5, and the database does not have a full-text index, this property returns 12/30/1899.

See examples
Examples: LastFTIndexed property

See also
FTSearch method (in NotesDatabase)
FTSearch method (in NotesView)
FTSearchScore property (in NotesDocument)
IsFTIndexed property
UnprocessedFTSearch method
UpdateFTIndex method


LastModified property

Read-only. The date that a database was last modified.

Defined in

NotesDatabase

Data type

Variant of type DATE

Syntax

To get: dateV = notesDatabase.LastModified

See examples
Examples: LastModified property

See also
OpenIfModified method


Managers property

Read-only. People, servers, and groups that have Manager access to a database.

Defined in

NotesDatabase

Data type

Array of strings

Syntax

To get: stringArray = notesDatabase.Managers

Usage

Each element in the array is the name of a person, server, or group who has Manager access to the database.

See examples
Examples: Managers property

See also
CurrentAccessLevel property
GrantAccess method
NotesACL class
NotesACLEntry class
QueryAccess method
RevokeAccess method


MaxSize property

Read-only. Shows the maximum size assigned to the database when the database was created.

Note This property is new with Release 5.

Defined in

NotesDatabase

Data type

Double

Syntax

To get: size = notesDatabase.MaxSize

See examples
Example: MaxSize property


NotesURL property

Read-only. The Notes URL of a database.

Note This property is new with Release 5.0.2b.

Note This property is supported in COM only.

Defined in

NotesDatabase

Data type

String

Syntax

To get: url$ = notesDatabase.NotesURL


Parent property

Read-only. The Notes session that contains a database.

Defined in

NotesDatabase

Data type

NotesSession

Syntax

To get: Set notesSession = notesDatabase.Parent

See examples
Example: Parent property


PercentUsed property

Read-only. The percent of a database's total size that is occupied by real data (and not empty space).

Defined in

NotesDatabase

Data type

Double

Syntax

To get: used# = notesDatabase.PercentUsed

Usage

Compacting a database removes empty space in the database file.

See examples
Example: PercentUsed property

See also
Compact method
Size property


ReplicationInfo property

Read-only. Provides access to a NotesReplication object. Each NotesDatabase instance contains one NotesReplication object.

Note This property is new with Release 5.

Defined in

NotesDatabase

Data type

NotesReplication

Syntax

To get: notesReplication = notesDatabase.ReplicationInfo

See examples
Example: ReplicationInfo property


ReplicaID property

Read-only. A 16-character combination of letters and numbers that represents the replica ID of a Notes database. Any databases with the same replica ID are replicas of one another.

Defined in

NotesDatabase

Data type

String

Syntax

To get: id$ = notesDatabase.ReplicaID

See examples
Example: ReplicaID property

See also
CreateReplica method
OpenByReplicaID method
Opening and closing a database
Replicate method
Server property


Server property

Read-only. The name of the server where a database resides.

Defined in

NotesDatabase

Data type

String

Syntax

To get: serverName$ = notesDatabase.Server

Usage

If the database is on a workstation, the property returns an empty string ("").

See examples
Example: Server property

See also
FileName property
FilePath property
IsOnServer property (in NotesSession)
OpenByReplicaID method
Replicate method
ServerName property (in NotesAgent)


Size property

Read-only. The size of a database, in bytes.

Defined in

NotesDatabase

Data type

Double

Syntax

To get: size# = notesDatabase.Size

See examples
Example: Size property

See also
Compact method
PercentUsed property
SizeQuota property


SizeQuota property

Read-write. The size quota of a database, in kilobytes.

Defined in

NotesDatabase

Data type

Long

Syntax

To get: quota& = notesDatabase.SizeQuota

To set: notesDatabase.SizeQuota = quota&

Usage

The size quota for a database specifies the amount of a disk space that the server administrator is willing to provide for the database; therefore, the SizeQuota property can only be set by a script that has administrator access to the server on which the database resides. The size quota is not the same as the size limit that a user specifies when creating a new database.

If there is no size quota for the database, this property returns 0.

See examples
Example: SizeQuota property

See also
Compact method
PercentUsed property
Size property


TemplateName property

Read-only. The template name of a database, if the database is a template. If the database is not a template, returns an empty string ("").

Defined in

NotesDatabase

Data type

String

Syntax

To get: name$ = notesDatabase.TemplateName

See examples
Examples: TemplateName property

See also
CreateFromTemplate method
DesignTemplateName property


Title property

Read-Write. The title of a database.

Defined in

NotesDatabase

Data type

String

Syntax

To get: title$ = notesDatabase.Title

To set: notesDatabase.Title = title$

Usage

A script cannot change the title of the database in which the script is currently running.

See examples
Examples: Title property

See also
FileName property
FilePath property
Server property


UnprocessedDocuments property

Read-only. The documents in a database that the current agent or view action considers to be "unprocessed." The type of agent determines which documents are considered unprocessed.

Note This property is not implemented in COM.

Defined in

NotesDatabase

Data type

NotesDocumentCollection

Syntax

To get: Set notesDocumentCollection = notesDatabase.UnprocessedDocuments

Usage

This method is valid only for agent or view action scripts and may be invoked only on NotesDatabase objects obtained from the CurrentDatabase property in NotesSession. In scripts that are not a part of an agent or view action, this method returns a NotesDocumentCollection with zero documents. When invoked on a NotesDatabase object that was not obtained from the CurrentDatabase property, this method raises an error.

What documents are returned?

The following table describes the documents that are returned by the UnprocessedDocuments property.

Agent runs on: | UnprocessedDocuments returns documents that meet all of these requirements:
All documents in database | Meet the search criteria specified in Agent Builder
All new and modified documents since last run | Not been processed by this agent with UpdateProcessedDoc Just been created or modified Meet the search criteria specified in Agent Builder
All unread documents in view | Are unread and in the view Meet the search criteria specified in Agent Builder
All documents in view | Are in the view Meet the search criteria specified in Agent Builder
Selected documents or View action | Are selected in the view Meet the search criteria specified in Agent Builder
Run once | Is the current document
Newly received mail documents | Just mailed to the database Meet the search criteria specified in Agent Builder
Newly modified documents | Just modified Meet the search criteria specified in Agent Builder
Pasted documents | Just pasted into the database Meet the search criteria specified in Agent Builder

Using UpdateProcessedDoc

For agents that run on new and modified documents, newly received mail documents, pasted documents, or newly modified documents, you must use the UpdateProcessedDoc method in NotesSession to mark each document as "processed," which ensures that a document gets processed by the agent only once (unless it's modified, mailed, or pasted again). If you do not call this method for each document, the agent processes the same documents the next time it runs.

UpdateProcessedDoc marks a document as processed only for the particular agent from which it is called. Using UpdateProcessedDoc in one agent has no effect on the documents that another agent processes.

In all other agents and view actions, UpdateProcessedDoc has no effect.

View actions

When used in a view action, UnprocessedDocuments returns the same documents as an agent that runs on selected documents.

See examples
Examples: UnprocessedDocuments property

See also
AllDocuments property
Collecting all documents and unprocessed documents
CurrentDatabase property (in NotesSession)
UnprocessedFTSearch method
UnprocessedSearch method
UpdateProcessedDoc method (in NotesSession)


Views property

Read-only. The views and folders in a database.

Defined in

NotesDatabase

Data type

Array of NotesViews

Syntax

To get: notesViewArray = notesDatabase.Views

Usage

Each element of the array is a NotesView object representing a public view or folder in the database. If the database is local, personal folders are also included.

To set the value of an individual NotesView object, you need to access the array elements individually. For example, to get the first element in the array returned from the NotesDatabase object db, you could do the following:

Dim view as NotesView

Set view = db.Views( 0 )

See examples
Examples: Views property

See also
GetView method
Locating a view or folder
Locating documents within a view or folder
NotesView class


Compact method

Compacts a local database.

Defined in

NotesDatabase

Syntax

sizeDelta& = notesDatabase.Compact

Return value

sizeDelta&

Long. The difference in bytes between the size of the database before and after compacting.

Usage

This method raises an error if the database is not local.

A script cannot compact the current database (the database in which the script is running) or the desktop.dsk file.

See examples
Examples: Compact method

See also
PercentUsed property
Size property


Create method

Creates a new database on disk, using the server and file name that you specify. Because the new database is not based on a template, it's blank and does not contain any forms or views.

Note This method is supported in LotusScript only. For COM, use CreateDatabase in NotesDbDirectory.

Defined in

NotesDatabase

Syntax

Call notesDatabase.Create( server$, dbfile$, openFlag [, maxsize% ] )

Parameters

server$

String. The name of the server where you want the new database to reside. Use an empty string ("") to create a database on the current computer.

dbfile$

String. The file name of the new database.

openFlag

Boolean. Indicates if you want to open the database. Specify True if you want to open the database and False if you do not. A database must be open in order for a script to access its properties and methods. If you choose not to open the database when it's created, you can open it later with the Open or OpenIfModified method.

maxsize%

Note This parameter is new with Release 5.

Integer. Optional. The maximum size (in gigabytes) that you would like to assign to the new database. This parameter applies only to Release 4 databases or those created on a server that has not been upgraded to Release 5. Entering an integer greater than 4, generates a run-time error that says "Maximum size for database is 4 (gigabytes)" and the script fails.

Usage

Both server$ and dbfile$ can be empty strings if the NotesDatabase object was already instantiated with a server and a file name (for example, using New).

See examples
Examples: Create method

See also
Creating a database
CreateCopy method
CreateFromTemplate method
CreateReplica method
Open method
OpenIfModified method


CreateCopy method

Creates an empty copy of the current database. The copy contains the design elements of the current database, an identical access control list, and an identical title. The copy does not contain any documents and is not a replica.

Defined in

NotesDatabase

Syntax

Set notesDatabase = notesDatabase.CreateCopy( newServer$, newDbFile$ [, maxsize% ] )

Parameters

newServer$

String. The name of the server where the new database resides. Use an empty string ("") to create a copy on the current computer.

newDbFile$

String. The file name of the new copy.

maxsize%

Note This parameter is new with Release 5.

Integer. Optional. The maximum size (in gigabytes) that you would like to assign to the new database. This parameter applies only to Release 4 databases or those created on a server that has not been upgraded to Release 5. Entering an integer greater than 4, generates a run-time error that says "Maximum size for database is 4 (gigabytes)" and the script fails.

Return value

notesDatabase

The new copy.

Usage

If a database with the specified file name already exists on the newServer$, an error is raised.

Scripts running on a server can't create or access databases on other servers. Therefore, if the script runs on a server, the newServer$ parameter must correspond to the server the script is running on. There are two ways to do this:

  • Use an empty string ("") to indicate the current computer. This is the safer method.

  • Make sure the name of the server that the script runs on matches the name of the newServer$ parameter.

Scripts running on a workstation can access several different servers in a single script.

The ACL of the original database gets copied to the new database, but you may want to modify the copy's ACL. For example, you may want Manager access to the copy for yourself even if you're not a manager of the original. Use the methods GrantAccess and RevokeAccess to modify the copy's ACL.

See examples
Examples: CreateCopy method

See also
Creating a database
CreateFromTemplate method
CreateReplica method
Create method
CopyToDatabase method (in NotesDocument)


CreateDocument method

Creates a document in a database and returns a NotesDocument object that represents the new document. You must call Save if you want the new document to be saved to disk. When used with OLE automation, this method allows you to create a NotesDocument object without using New.

Defined in

NotesDatabase

Syntax

Set notesDocument = notesDatabase.CreateDocument

Return value

notesDocument

The new document.

Usage

For more information, see the NotesDocument class.

See examples
Example: CreateDocument method

See also
NotesDocument class


CreateFromTemplate method

Creates a new database from an existing database, if the "Database is a template" property is selected and the NTF extension is provided. The new database has the design elements and documents of the existing database. If the property is not selected, the source is treated as a database instead of a template, and does not convert entries such as [-Default-] in the ACL to regular ACL entries in the newly created database.

Defined in

NotesDatabase

Syntax

Set notesDatabase = notesDatabase.CreateFromTemplate( newServer$, newDbFile$, inheritFlag [, maxsize% ] )

Parameters

newServer$

String. The name of the server where the new database resides. Use an empty string ("") to create a database on the current computer.

newDbFile$

String. The file name of the new database.

inheritFlag

Boolean. Specify True if you want the new database to inherit future design changes from the template; otherwise, specify False.

maxsize%

Note This parameter is new with Release 5.

Integer. Optional. The maximum size (in gigabytes) that you would like to assign to the new database. This parameter applies only to Release 4 databases or those created on a server that has not been upgraded to Release 5. Entering an integer greater than 4, generates a run-time error that says "Maximum size for database is 4 (gigabytes)" and the script fails.

Return value

notesDatabase

The new database, which contains the forms, subforms, fields, views, folders, navigators, agents, and documents of the template.

Usage

If a database with the specified file name already exists on the newServer$, an error is raised.

Scripts running on a server can't create or access databases on other servers. Therefore, if the script runs on a server, the newServer$ parameter must correspond to the server the script is running on. There are two ways to do this:

  • Use an empty string ("") to indicate the current computer. This is the safer method.

  • Make sure the name of the server that the script runs on matches the name of the newServer$ parameter.

Scripts running on a workstation can access several different servers in a single script.

See examples
Example: CreateFromTemplate method

See also
Creating a database
Create method
CreateCopy method
CreateReplica method
DesignTemplateName property
TemplateName property


CreateOutline method

Creates a new outline within the current database and returns a NotesOutline object that represents the new outline. This method allows you to create a NotesOutline object without using New.

Note This method is new with Release 5.

Defined in

NotesDatabase

Syntax

Set notesOutline = notesDatabase.CreateOutline(outlinename$ [, defaultOutline ] )

Parameters

outlinename$

String. Specify a name for the new outline.

defaultOutline

Boolean. Optional. Specify True to generate an outline with default entries. Default behavior is False which creates a blank outline.

Return value

notesOutline

The new NotesOutline object.

Usage

If an outline already exists, this method returns an outline object that points to the existing outline.

See examples
Examples: CreateOutline method


CreateReplica method

Creates a replica of the current database at a new location. The new replica has an identical access control list.

Defined in

NotesDatabase

Syntax

Set notesDatabase = notesDatabase.CreateReplica( newServer$, newDbFile$ )

Parameters

newServer$

String. The name of the server where the replica will reside. Use an empty string ("") to create a replica on the current computer.

newDbFile$

String. The file name of the replica.

Return value

notesDatabase

The new replica.

Usage

If a database with the specified file name already exists on the newServer$, an error is raised.

Scripts running on a server can't create or access databases on other servers. Therefore, if the script runs on a server, the newServer$ parameter must correspond to the server the script is running on. There are two ways to do this:

  • Use an empty string ("") to indicate the current computer. This is the safer method.

  • Make sure the name of the server that the script runs on matches the name of the newServer$ parameter.

Scripts running on a workstation can access several different servers in a single script.

See examples
Example: CreateReplica method

See also
Creating a database
Create method
CreateCopy method
CreateFromTemplate method
OpenByReplicaID method
ReplicaID property
Replicate method


EnableFolder method

Given a folder name, enables the folder.

Note This method is new with Release 5.

Defined in

NotesDatabase

Syntax

Call notesDatabase.EnableFolder( foldername$ )

Parameters

foldername$

String. The name of the folder that you want to enable. If the folder does not exist, this method creates a folder.

Usage

Use the EnableFolder method to make sure a folder exists before calling the PutInFolder, PutAllInFolder, RemoveFromFolder, and RemoveAllFromFolder methods.


FTDomainSearch method

Conducts a Domain Search, that is, a full-text search of all databases configured in the Domain Catalog database and marked as included for multi-database indexing.

Note This method is new with Release 5.

Defined in

NotesDatabase

Syntax

Set notesDocument = notesDatabase.FTDomainSearch( query$, maxDocs% [,sortoptions% [, otheroptions% [, start% [, count% [, entryform$ ]]]]] )

Parameters

query$

String. The full-text query.

maxDocs%

Integer. The maximum number of documents you want returned from the query. Set this parameter to 0 to receive all matching documents.

sortoptions%

Integer. Optional. Use one of three constants to specify a sorting option:

  • FT_SCORES (8) sorts by relevance score (default).

  • FT_DATE_DES (32) sorts by document creation date in descending order.

  • FT_DATE_ASC (64) sorts by document creation date in ascending order.

otheroptions%

Integer. Optional. Use one of four constants to specify additional search options:

  • FT_STEMS (512) uses stem words as the basis of the search.

  • FT_DATABASE (8192) search includes Domino databases.

  • FT_FUZZY (16384) searches for related words. Need not be an exact match.

  • FT_FILESYSTEM (4096) search includes files that are not Domino databases.

Note These values are also used with the FTSearch and UnProcessedFTSearch methods in the NotesDatabase class.

start%

Integer. Optional. The starting page to return.

count%

Integer. Optional. The number of pages to return.

entryform$

The name of the search form in the domain catalog.

Return value

notesDocument

A Notes document with a formatted list of matching documents.

Usage

The databases you want included in the search must have the property "Include in multi-database indexing" set to TRUE.

The current NotesDatabase object must represent a Domain Catalog.

If you don't specify any sort options, you get the documents sorted by relevance score. If you ask for a sort by date, you don't get relevance scores.

Query syntax

To search for a word or phrase, enter the word or phrase as is, except that search keywords must be enclosed in quotes. Remember to escape quotes if you are inside a literal.

Wildcards, operators, and other syntax are permitted. For the complete syntax rules, see the topic "To use operators to refine a search" in Notes 5 help.


FTSearch method

Conducts a full-text search of all the documents in a database.

Defined in

NotesDatabase

Syntax

Set notesDocumentCollection = notesDatabase.FTSearch( query$, maxDocs% [,sortoptions [, otheroptions]] )

Parameters

query$

String. The full-text query. See below for the syntax.

maxDocs%

Integer. The maximum number of documents you want returned from the query. Set this parameter to 0 to receive all matching documents.

sortoptions

Integer. Optional. Use one of three constants to specify a sorting option:

  • FT_SCORES (8) sorts by relevance score (default).

  • FT_DATE_DES (32) sorts by document creation date in descending order.

  • FT_DATE_ASC (64) sorts by document creation date in ascending order.

otheroptions

Integer. Optional. Use one of two constants to specify additional search options:

  • FT_STEMS (512) uses stem words as the basis of the search.

  • FT_DATABASE (8192) search includes Domino databases.

  • FT_FUZZY (16384) searches for related words. Need not be an exact match.

  • FT_FILESYSTEM (4096) search includes files that are not Domino databases.

Note These values are also used with the FTDomainSearch and UnProcessedFTSearch methods in the NotesDatabase class.

Return value

notesDocumentCollection

A collection of documents that match the full-text query, sorted by the selected option.When the collection is sorted by relevance the highest relevance appears first. To access the relevance score of each document in the collection, use the FTSearchScore property in NotesDocument.

Usage

If the database is not full-text indexed, this method works, but less efficiently. To test for an index, use the IsFTIndexed property in NotesDatabase. To create an index on a local database, use the UpdateFTIndex method.

This method searches all of the documents in a database. To search only documents found in a particular view, use the FTSearch method in NotesView. To search only documents found in a particular document collection, use the FTSearch method in NotesDocumentCollection.

If you don't specify any sort options, you get the documents sorted by relevance score. If you ask for a sort by date, you don't get relevance scores. If you pass the resulting DocumentCollection to a NotesNewsletter instance, it formats its doclink report with either the document creation date or the relevance score, depending on the sort options you use.

If the database has a multi-database index, you get a multi-database search. Navigation through the resulting document collection may be slow, but you can create a newsletter from the collection.

Query syntax

To search for a word or phrase, enter the word or phrase as is, except that search keywords must be enclosed in quotes. Remember to escape quotes if you are inside a literal.

Wildcards, operators, and other syntax are permitted. For the complete syntax rules, see the topic "To use operators to refine a search" in Notes 5 help.

See examples
Examples: FTSearch method

See also
FTSearch method (in NotesDocumentCollection)
FTSearch method (in NotesView)
FTSearchScore property (in NotesDocument)
IsFTIndexed property
LastFTIndexed property
NotesDocumentCollection class
UnprocessedFTSearch method
UpdateFTIndex method


GetAgent method

Finds an agent in a database, given the agent name.

Defined in

NotesDatabase

Syntax

Set notesAgent = notesDatabase.GetAgent( agentName$ )

Parameter

agentName$

String. The name of the agent.

Return value

notesAgent

The agent whose name matches notesAgent$.

Usage

For an explanation of NoteAgents, see the NotesAgent class

See examples
Example: GetAgent method

See also
NotesAgent class


GetDocumentByID method

Finds a document in a database, given the document NoteID.

Defined in

NotesDatabase

Syntax

Set notesDocument = notesDatabase.GetDocumentByID( noteID$ )

Parameters

noteID$

String. The NoteID of a document. You can obtain this from the NoteID property of a document.

Return value

notesDocument

The document whose NoteID matches noteID$.

Usage

For an explanation of NoteIDs, see the NoteID property in NotesDocument.

See examples
Examples: GetDocumentByID method

See also
GetDocumentByUNID method
Locating a document by ID
NoteID property (in NotesDocument)
NotesDocument class
UniversalID property (in NotesDocument)


GetDocumentByUNID method

Finds a document in a database, given the document universal ID (UNID).

Defined in

NotesDatabase

Syntax

Set notesDocument = notesDatabase.GetDocumentByUNID( unid$ )

Parameters

unid$

String. The universal ID of a document. You can obtain this from the UniversalID or ParentDocumentUNID property of a document.

Return value

notesDocument

NotesDocument. The document whose universal ID matches unid$.

Usage

For an explanation of universal IDs, see the UniversalID property in NotesDocument.

See examples
Examples: GetDocumentByUNID method

See also
GetDocumentByID method
Locating a document by ID
NoteID property (in NotesDocument)
NotesDocument class
ParentDocumentUNID property (in NotesDocument)
UniversalID property (in NotesDocument)


GetDocumentByURL method

Instantiates a document in the database on which it is called and returns a NotesDocument object for it. This method is typically used for either the Server Web Navigator or Personal Web Navigator database, but can be called on any database object.

Defined in

NotesDatabase

Syntax

Set notesDocument = notesDatabase.GetDocumentByURL( URL$ [ , reload ] [ , urllist ] [ , charset$ ] [ , webusername$ ] [ , webpassword$ ] [ , proxywebusername$ ] [ , proxywebpassword$ ] [ , returnimmediately ] )

Parameters

URL$

String. The desired uniform resource locator (URL), for example, http://www.acme.com. You can enter a maximum string length of 15K.

reload

Integer. Optional. Enter 1 (True) to reload the page from its Internet server. Enter 0 (False) to load the page from the Internet only if it is not already in the Web Navigator database. Enter 2 to reload the page only if it has been modified on its Internet server. The default value is 0.

urllist

Integer. Optional. Web pages can contain URL links to other Web pages. You can specify whether to save the URLs in a field called URLLinksn in the Notes document. (The Web Navigator creates a new URLLinksn field each time the field size reaches 64K. For example, the first URLLinks field would be URLLinks1, the second would be URLLinks2, and so on.)

Specify 1 (True) if you want to save the URLs in the URLLinksn field(s). Specify 0 (False) or omit this parameter if you do not want to save the URLs in the URLLinksn field(s). If you save the URLs, you can use them in agents; for example, you could create an agent that opens Web pages in the Web Navigator database and then loads all the Web pages saved in each of the URLLinksn field(s).

Saving URLs in the URLLinksn field(s) may affect performance.

charset$

String. Optional. Enter the MIME character set (for example, ISO-2022-JP for Japanese or ISO-8859-1 for United States) that you want the Web Navigator to use when processing the Web page. Only use this parameter when the Web Navigator misdetects the correct MIME character set of the URL contents.

webusername$

String. Optional. Some Internet servers require you to obtain a username before you can access their pages. This parameter allows you to enter the username that you previously obtained from the Internet server.

webpassword$

String. Optional. Some Internet servers require you to obtain a password before you can access their pages. This parameter allows you to enter the password that you previously obtained from the Internet server.

proxywebusername$

String. Optional. Some proxy servers require that you specify a username in order to connect through them. This parameter allows you to enter the username for the proxy server. See your administrator for the username required by the proxy.

proxywebpassword$

String. Optional. Some proxy servers require that you specify a password in order to connect through them. This parameter allows you to enter the password for the proxy server. See your administrator for the password required by the proxy.

returnimmediately

Boolean. Optional. Specify True to return immediately and not wait for completion of the retrieval operation. Specify False or omit this parameter to wait for completion of the retrieval. If you specify True, GetDocumentByURL does not return the NotesDocument object representing the URL document. This parameter is useful for retrieving a URL document for offline storage purposes; in this case, you do not need the NotesDocument object and do not have to wait for completion of the operation.

Return value

notesDocument

The Notes document that represents the URL document you specified. The return value is Null if returnimmediately is True.

See examples
Example: GetDocumentByURL Method

See also
GetURLHeaderInfo method
NotesDocument class
OpenURLDb method


GetForm method

Finds a form in a database, given the form name.

Defined in

NotesDatabase

Syntax

Set notesForm = notesDatabase.GetForm( name$ )

Parameters

name$

String. The name or an alias of the form.

Return value

notesForm

The form whose name or alias matches name.

See examples
Example: GetForm method

See also
NotesForm class
Accessing a form


GetOutline method

Retrieves an existing outline within the current database and returns a NotesOutline object that represents the outline.

Note This method is new with Release 5.

Defined in

NotesDatabase

Syntax

Set notesOutline = notesDatabase.GetOutline( outlinename$ )

Parameters

outlinename$

String. The name of the outline.

Return value

notesOutline

The existing NotesOutline object that matches the outlinename$ parameter.


GetProfileDocCollection method

Given a profile name, returns a collection of profile documents that match the name.

Note This method is new with Release 5.

Defined in

NotesDatabase

Syntax

Set notesDocumentCollection = notesDatabase.GetProfileDocCollection( profilename$ )

Parameters

profilename$

String. The name of the profile document.

Return value

notesDocumentCollection

The collection of profile documents that match the given name.


GetProfileDocument method

Retrieves or creates a profile document.

Defined in

NotesDatabase

Syntax

Set notesDocument = notesDatabase.GetProfileDocument( profilename$ [ , username$] )

Parameters

profilename$

String. The name or an alias of the profile document.

username

String. Optional. The user name (key) attached to the profile document.

Return value

notesDocument

The profile document that matches the given name.

See examples
Examples: GetProfileDocument method

See also
EditProfile method (in NotesUIWorkspace)
IsProfile property (in NotesDocument)
Key property (in NotesDocument)
NameOfProfile property (in NotesDocument)


GetURLHeaderInfo method

Gets the specific Hypertext Transfer Protocol (HTTP) header information from the Uniform Resource Locator (URL). A URL is a text string used for identifying and addressing a Web resource.

Defined in

NotesDatabase

Syntax

header$ = notesDatabase.GetURLHeaderInfo( URL$ , headername$ [ , Webusername$ ] [ , Webpassword$ ] [ , Proxywebusername$ ] [ , Proxywebpassword$ ] )

Parameters

URL$

Note This parameter is optional in COM.

String. The URL for the Web page you want information on, for example, http://www.acme.com/. You can enter a maximum string length of 15K.

headername$

Note This parameter is optional in COM.

String. Enter a header string of the URL header value you want returned. The acceptable header strings are documented in the HTTP specification (available at various locations on the Internet, such as http://www.w3.org/) and are subject to change based on updated versions of the specification.

Webusername$

String. Optional. Some Internet servers require you to obtain a username before you can access their pages. This parameter allows you to enter the username that you previously obtained from the Internet server.

Webpassword$

String. Optional. Some Internet servers require you to obtain a password before you can access their pages. This parameter allows you to enter the password that you previously obtained from the Internet server.

Proxywebusername$

String. Optional. Some proxy servers require that you specify a username in order to connect through them. This parameter allows you to enter the username for the proxy server. See your administrator for the username required by the proxy.

Proxywebpassword$

String. Optional. Some proxy servers require that you specify a password in order to connect through them. This parameter allows you to enter the password for the proxy server. See your administrator for the password required by the proxy.

Return value

header$

String. The requested header. If a null value is returned, the header value that you requested was not found in the header of the URL, or the URL could not be found.

Usage

All HTTP (and META) Header names are converted so that any dashes they contain became underscores (so they can be used in Views, etc). Previously, this required all LotusScript users to convert all dashes to underscores manually. Now, with Release 5, all dashes are automatically converted to underscores.

See examples
Example: GetURLHeaderInfo method

See also
GetDocumentByURL method
OpenURLDb method


GetView method

Finds a view or folder in a database, given the name or alias of the view or folder.

Defined in

NotesDatabase

Syntax

Set notesView = notesDatabase.GetView( viewName$ )

Parameter

viewName$

String. The name of a view or folder in a database. Case insensitive. Use either the entire name of the view or folder (including backslashes for cascading views and folders), or an alias.

Return value

notesView

The view or folder whose name or synonym matches viewName$.

Usage

If the database is local, GetView returns both public and personal views and folders. If the database is on a server, GetView returns only public views and folders.

If the view is not found in the database an error is returned.

When specifying the viewName$ parameter, do not use the view name and its alias together: for example, specifying "By Author|AuthorView" does not work. Use either the view name ("By Author") or its alias ("AuthorView").

When the view or folder name contains underscores to indicate menu accelerators, you have the option of including or excluding the underscores. The method works more efficiently, however, if you include the underscores.

See examples
Examples: GetView method

See also
Locating a view or folder
Locating documents within a view or folder
NotesView class
Views property


GrantAccess method

Modifies a database access control list to provide the specified level of access to a person, group, or server.

Defined in

NotesDatabase

Syntax

Call notesDatabase.GrantAccess( name$, level% )

Parameters

name$

String. The name of the person, group, or server whose access level you want to provide or change.

level%

Integer constant. The level of access you're granting. This parameter is one of the following constants:

Level% | Meaning
ACLLEVEL_NOACCESS (0) | No access
ACLLEVEL_DEPOSITOR (1) | Depositor access
ACLLEVEL_READER (2) | Reader access
ACLLEVEL_AUTHOR (3) | Author access
ACLLEVEL_EDITOR (4) | Editor access
ACLLEVEL_DESIGNER (5) | Designer access
ACLLEVEL_MANAGER (6) | Manager access

Note These values are also used with the CreateACLEntry method and InternetLevel property in the NotesACL class, the Level property in the NotesACLEntry class, and the CurrentAccessLevel property and QueryAccess method in the NotesDatabase class.

Usage

This method changes any existing NotesACL or NotesACLEntry object associated with the database.

If the name$ already exists in the ACL, this method updates it with the access level%. Otherwise, the name is added to the ACL with level%.

You can also use this method to deny access to a person, group, or server by assigning ACLLEVEL_NOACCESS.

This method sets ACL roles to their default values.

See examples
Examples: GrantAccess method

See also
CurrentAccessLevel property
Examining and adjusting an access control list
NotesACL class
NotesACLEntry class
QueryAccess method
RevokeAccess method


Open method

Opens a database. A database must be open to access all its properties and methods. For details on accessing the properties and methods of a database, see the Usage section in NotesDatabase.

Note COM supports the Open method only as a Sub with no parameters. To open a database with parameters in COM, see OpenDatabase in NotesDbDirectory. LotusScript supports the Open method only with parameters.

Defined in

NotesDatabase

Syntax

Note The following syntax is for LotusScript.

flag = notesDatabase.Open( server$, dbfile$ )

Note The following syntax is for COM.

Call notesDatabase.Open()

Parameters

server$

String. The name of the server on which the database resides. Use an empty string ("") to indicate a database on the current computer, or for a NotesDatabase that's already assigned to a database.

dbfile$

String. The file name of the database to open. Use an empty string for a NotesDatabase that's already assigned to a database.

Return value

  • True indicates that the database exists and was opened

  • False indicates that there is no database at the location specified

Usage

Use the Open method as follows:

  • In LotusScript, to open a NotesDatabase object that's already assigned to an existing database. Both parameters must be empty strings (or both parameters must match the server and file name of the existing database):

    • db.Open( "", "" )
    The script returns an error if you try to reassign its server or file name using Open.

  • In COM, to open a NotesDatabase object that's already assigned to an existing database. No parameters are allowed:

  • In LotusScript, to open a NotesDatabase object not yet assigned to an existing database. You must specify a server and a file name. The server name parameter can be an empty string (to indicate a database on the current computer), but the file name parameter cannot be empty.

Access level to a database

You need at least Reader access to a database to call Open. An error is returned if you do not have access.

See examples
Examples: Open method

See also
Handling run-time errors
IsOpen property
OpenByReplicaID method
OpenIfModified method
Opening and closing a database
OpenMail method
OpenURLDb method


OpenByReplicaID method

Given a server name and a replica ID, opens the specified database, if it exists.

Note This method is supported in LotusScript only. For COM, use OpenDatabaseByReplicaID in NotesDbDirectory.

Defined in

NotesDatabase

Syntax

flag = notesDatabase.OpenByReplicaID( server$, replicaID$ )

Parameters

server$

String. The name of the server on which the database resides. Use an empty string ("") to indicate a database on the current computer.

replicaID$

String. The replica ID of the database that you want to open.

Return value

  • True indicates that the replica was found and opened

  • False indicates that the replica was not found on the server, or could not be opened

See examples
Example: OpenByReplicaID method

See also
Opening and closing a database
Open method
OpenIfModified method
OpenMail method
OpenURLDb method
ReplicaID Property


OpenIfModified method

Given a date, opens the specified database if it has been modified since that date.

Note This method is supported in LotusScript only. For COM, use OpenDatabaseIfModified in NotesDbDirectory.

Defined in

NotesDatabase

Syntax

flag = notesDatabase.OpenIfModified( server$, dbfile$, notesDateTime )

Parameters

server$

String. The name of the server on which the database resides. Use an empty string ("") to indicate a database on the current computer.

dbfile$

String. The file name of the database.

notesDateTime

A cutoff date. If one or more documents in the database has been modified since this date, the database is opened; if not, it is not opened.

Return value

  • True indicates that the database was opened

  • False indicates that the database was not opened

See examples
Example: OpenIfModified method

See also
NotesDateTime class
Open method
OpenByReplicaID method
Opening and closing a database
OpenMail method
OpenURLDb method


OpenMail method

Assigns a database to the current user's mail database and opens the database.

Note This method is supported in LotusScript only. For COM, use OpenMailDatabase in NotesDbDirectory.

Defined in

NotesDatabase

Syntax

Call notesDatabase.OpenMail

Usage

For a script to use this method, it must run either on a workstation or on the agent owner's mail server. Otherwise, it raises an error, since scripts running on servers cannot access databases on other servers.

  • If the script runs on a workstation, OpenMail finds the current user's mail server and database in the NOTES.INI (or Notes Preferences) file.

  • If the script runs on a server, the current user is considered to be the last person who modified the agent (the agent's owner), and OpenMail finds user's the mail server and database in the Domino Directory on the server.

See examples
Example: OpenMail method

See also
IsOpen property
Open method
OpenByReplicaID method
OpenIfModified method
Opening and closing a database
OpenURLDb method


OpenURLDb method

Finds and opens the default Web Navigator database.

Note This method is not supported in COM.

Defined in

NotesDatabase

Syntax

flag = notesDatabase.OpenURLDb

Return value

  • True indicates that the operation was successful

  • False indicates that the operation was not successful

Usage

This method returns a pointer to the location of the Web Navigator database specified by the Notes client.

See also
GetDocumentByURL method
GetURLHeaderInfo method
IsOpen property
Open method
OpenByReplicaID method
OpenIfModified method
OpenMail method


OpenWithFailover method

Opens a database on a server.

Note This method is not supported in COM.

Defined in

NotesDatabase

Syntax

flag = notesDatabase.OpenWithFailover( server$, dbfile$ )

Parameters

server$

String. The name of the primary server on which the database resides.

dbfile$

String. The file name of the database to open.

Return value

  • True indicates that the database exists and was opened

  • False indicates that there is no database with this name in the cluster

Usage

The object's Server and FilePath properties reflect the actual server that the database is opened on.

A script needs at least Reader access to a database in order to call Open. An error is returned if the script does not have access.

If the database is can't be opened on specific the server but the server belongs to a cluster, OpenWithFailover automatically looks for a replica of the specified server on the same cluster. If the method finds a replica, that database is opened instead, and the server property adjusts accordingly.

See examples
Example: OpenWithFailover method

See also
IsOpen property
Open method
OpenByReplicaID method
OpenIfModified method
Opening and closing a database
OpenURLDb method


QueryAccess method

Returns a person's, group's, or server's current access level to a database.

Defined in

NotesDatabase

Syntax

level% = notesDatabase.QueryAccess( name$ )

Parameters

name$

String. The name of the person, group, or server.

Return value

level%

Integer constant. Indicates the current access level. One of the following:

  • ACLLEVEL_NOACCESS (0)

  • ACLLEVEL_DEPOSITOR (1)

  • ACLLEVEL_READER (2)

  • ACLLEVEL_AUTHOR (3)

  • ACLLEVEL_EDITOR (4)

  • ACLLEVEL_DESIGNER (5)

  • ACLLEVEL_MANAGER (6)

Note These values are also used with the CreateACLEntry method and InternetLevel property in the NotesACL class, the Level property in the NotesACLEntry class, and the CurrentAccessLevel property and GrantAccess method in the NotesDatabase class.

Usage

This method changes any existing NotesACL or NotesACLEntry object associated with the database.

If the name$ you specify is not listed explicitly in the ACL, QueryAccess does the following:

  • If the name is a member of a group defined in the Domino Directory and that group name is listed in the access control list, QueryAccess returns the access level of the group name.

  • If the name is a member of several groups listed in the ACL, QueryAccess returns the highest access level granted to any of the groups.

  • If the name is not a member of any group, QueryAccess returns the default access level.

If the name you specify is listed explicitly in the ACL, and is also a member of one or more groups listed in the ACL, QueryAccess whichever access level is higher.

To see if a name is a member of a group, QueryAccess uses the PrimaryAddress Book known to the computer on which the script is running. If the script is running on a workstation, QueryAccess checks the Personal Address Book on the local computer. If the script is running on a server, QueryAccess checks the Domino Directory on that server.

See examples
Examples: QueryAccess method

See also
CurrentAccessLevel property
Examining and adjusting an access control list
GrantAccess method
Managers property
NotesACL class
NotesACLEntry class
RevokeAccess method


Remove method

Permanently deletes a database from disk.

Defined in

NotesDatabase

Syntax

Call notesDatabase.Remove

See examples
Example: Remove method


Replicate method

Replicates a database with its replica(s) on a given server.

Defined in

NotesDatabase

Syntax

flag = notesDatabase.Replicate( serverName$ )

Parameter

serverName$

String. The name of the server with which you want to replicate. Any replicas of the current database that exist on serverName$ will replicate.

Return value

  • True indicates that the database replicated without errors

  • False indicates that the database did not successfully replicate; document replication errors occurred

Usage

If the server does not contain a replica of the database, an error is raised.

See examples
Example: Replicate method

See also
CreateReplica method
OpenByReplicaID method
ReplicaID property
Server property


RevokeAccess method

Removes a person, group, or server from a database access control list. This resets the access level for that person, group, or server to the Default setting for the database.

Defined in

NotesDatabase

Syntax

Call notesDatabase.RevokeAccess( name$ )

Parameter

name$

String. The name of the person, group, or server whose access you want to revoke.

Usage

This method changes any existing NotesACL or NotesACLEntry object associated with the database.

Revoking access is different than assigning No Access (which you can do with the GrantAccess method). When you revoke access, you remove the name from the ACL, but the person, group, or server can still access the database at the level specified for the Default. When you use the GrantAccess method to assign No Access, the name remains in the ACL, and the person, group, or server cannot access the database, regardless of the Default setting.

Errors

The name$ must be explicitly listed in the database ACL. If it isn't, RevokeAccess raises the error: "The name is not in the list." This error is raised even if the name$ is a member of a group that is listed in the ACL.

See examples
Example: RevokeAccess method

See also
CurrentAccessLevel property
Examining and adjusting an access control list
GrantAccess method
Managers property
NotesACL class
NotesACLEntry class
QueryAccess method


Search method

Given selection criteria for a document, returns all documents in a database that meet the criteria.

Defined in

NotesDatabase

Syntax

Set notesDocumentCollection = notesDatabase.Search( formula$, notesDateTime, maxDocs% )

Parameters

formula$

String. A Notes @function formula that defines the selection criteria.

notesDateTime

A cutoff date. The method searches only documents created or modified since the cutoff date. Specify Nothing to indicate no cutoff date.

maxDocs%

Integer. The maximum number of documents you want returned. Specify 0 to receive all matching documents.

Return value

notesDocumentCollection

An unsorted collection of documents that match the selection criteria.

See examples
Examples: Search method

See also
FTSearch method
NotesDateTime class
NotesDocumentCollection class
UnprocessedSearch method


UnprocessedFTSearch method

Given selection criteria for a document, returns documents in a database that:

  • The current agent considers to be unprocessed

  • Match the query

Note This method is not implemented in COM.

Defined in

NotesDatabase

Syntax

Set notesDocumentCollection = notesDatabase.UnprocessedFTSearch( query$, maxDocs% [,sortoptions [, otheroptions]] )

Parameters

query$

String. The full-text query.

maxDocs%

Integer. The maximum number of documents you want returned from the query. Set this parameter to 0 to receive all matching documents.

sortoptions

Integer. Optional. Use one of three constants to specify a sorting option:

  • FT_SCORES (8) sorts by relevance score (default).

  • FT_DATE_DES (32) sorts by document creation date in descending order.

  • FT_DATE_ASC (64) sorts by document creation date in ascending order.

otheroptions

Integer. Optional. Use one of two constants to specify additional search options:

  • FT_STEMS (512) uses stem words as the basis of the search.

  • FT_DATABASE (8192) search includes Domino databases.

  • FT_FUZZY (16384) searches for related words. Need not be an exact match.

  • FT_FILESYSTEM (4096) search includes files that are not Domino databases.

Note These values are also used with the FTSearch method in the NotesDatabase class.

Return value

notesDocumentCollection

A sorted collection of documents that were unprocessed and match the query. The collection is sorted by relevance with highest relevance first.

Usage

This method is valid only for agent scripts and view actions, and may be invoked only on NotesDatabase objects obtained from the CurrentDatabase property in NotesSession. In scripts that are not a part of an agent or view action, this method returns a NotesDocumentCollection with zero documents. When invoked on a NotesDatabase object that was not obtained from the CurrentDatabase property, this method raises an error.

How does it work?

This method works in two parts:

  • First, it finds a collection of documents that the agent considers to be "unprocessed." The type of agent or view action determines which documents are considered to be unprocessed. This document collection is identical to that returned by the UnprocessedDocuments property.

  • Second, it conducts a full-text search on the unprocessed documents and returns a collection of those documents that match the query.

For example, in an agent that runs on all selected documents in the view, UnprocessedFTSearch searches only the selected documents, and returns those that match the query. In an agent that runs on documents that have been created or modified since last run, UnprocessedFTSearch searches only the documents that have not been marked by the UpdateProcessedDoc method in NotesSession, and returns those that match the query.

What documents are returned?

The following table describes the documents that are returned by the UnprocessedFTSearch method.

Agent runs on: | UnprocessedFTSearch returns documents that meet all of these requirements:
All documents in database | Meet the search criteria specified in Agent Builder Meet the full-text search critieria specified in this method
All new and modified documents since last run | Not processed by this agent with UpdateProcessedDoc Just been created or modified Meet the search criteria specified in Agent Builder Meet the full-text search critieria specified in this method
All unread documents in view | Are unread and in the view Meet the search criteria specified in Agent Builder Meet the full-text search criteria specified in this method
All documents in view | Are in the view Meet the search criteria specified in Agent Builder Meet the full-text search criteria specified in this method
Selected documents or View action | Are selected in the view Meet the search criteria specified in Agent Builder Meet the full-text search criteria specified in this method
Run once | Is the current document
Newly received mail documents | Not processed by this agent with UpdateProcessedDoc Just been mailed to the database Meet the search criteria specified in Agent Builder Meet the full-text search criteria specified in this method
Newly modified documents | Not been processed by this agent with UpdateProcessedDoc Just been modified Meet the search criteria specified in Agent Builder Meet the full-text search criteria specified in this method
Pasted documents | Have not been processed by this agent with UpdateProcessedDoc Have just been pasted into the database Meet the search criteria specified in Agent Builder Meet the full-text search criteria specified in this method

Using UpdateProcessedDoc

For agents that run on new and modified documents, newly received mail documents, pasted documents, or newly modified documents, you must use the UpdateProcessedDoc method in NotesSession to mark each document as "processed," which ensures that a document gets processed by the agent only once (unless it's modified, mailed, or pasted again). If you do not call this method for each document, the agent processes the same documents the next time it runs.

UpdateProcessedDoc marks a document as processed only for the particular agent from which it is called. Using UpdateProcessedDoc in one agent has no effect on the documents that another agent processes.

In all other agents and view actions, UpdateProcessedDoc has no effect.

View actions

When used in a view action, UnprocessedFTSearch returns the same documents as an agent that runs on selected documents.

Full-text indexes

If the database is not full-text indexed, this method works, but less efficiently. To test for an index, use the IsFTIndexed property. To create an index on a local database, use the UpdateFTIndex method.

See examples
Examples: UnprocessedFTSearch method

See also
FTSearch method (in NotesView)
FTSearch method
FTSearchScore property (in NotesDocument)
IsFTIndexed property
LastFTIndexed property
NotesDocumentCollection class
UnprocessedDocuments property
UnprocessedSearch method
UpdateFTIndex method
UpdateProcessedDoc method (in NotesSession)


UnprocessedSearch method

Given selection criteria for a document, returns documents in a database that:

  • The current agent considers to be unprocessed

  • Meet the criteria

  • Were created or modified since the cutoff date

Note This method is not implemented in COM.

Defined in

NotesDatabase

Syntax

Set notesDocumentCollection = notesDatabase.UnprocessedSearch( formula$, notesDateTime, maxDocs% )

Parameters

formula$

String. A Notes @function formula that defines the selection criteria.

notesDateTime

A cutoff date. The method searches only documents created or modified since the cutoff date.

maxDocs%

Integer. The maximum number of documents you want returned. Set this parameter to 0 to receive all matching documents.

Return value

notesDocumentCollection

A collection of documents that are unprocessed, match the selection criteria, and were created or modified after the cutoff date. The collection is sorted by relevance with highest relevance first.

Usage

This method is valid only for agent or view action scripts, and may be invoked only on NotesDatabase objects obtained from the CurrentDatabase property in NotesSession. In scripts that are not a part of an agent or view action, this method returns a NotesDocumentCollection with zero documents. When invoked on a NotesDatabase object that was not obtained from the CurrentDatabase property, this method raises an error.

How does it work?

This method works in two parts:

  • First, it finds a collection of documents that the agent or view action considers to be "unprocessed." The type of agent or view action determines which documents are considered to be unprocessed. This document collection is identical to that returned by the UnprocessedDocuments property.

  • Second, it conducts a search on the unprocessed documents, and returns a collection of those documents that match the selection criteria and were created or modified since the cutoff date.

For example, in an agent that runs on all selected documents in the view, UnprocessedSearch searches only the selected documents and returns those that match the selection criteria. In an agent that runs on documents that have been created or modified since last run, UnprocessedSearch searches only the documents that have not been marked by the UpdateProcessedDoc method in NotesSession, and returns those that match the selection criteria.

What documents are returned?

The following table describes the documents that are returned by the UnprocessedSearch method.

Agent runs on: | UnprocessedSearch returns documents that meet all of these requirements:
All documents in database | Meet the search criteria specified in Agent Builder Meet the @function search critieria specified in this method
All new and modified documents since last run | Not processed by this agent with UpdateProcessedDoc Just created or modified Meet the search criteria specified in Agent Builder Meet the @function search critieria specified in this method
All unread documents in view | Are unread and in the view Meet the search criteria specified in Agent Builder Meet the @function search criteria specified in this method
All documents in view | Are in the view Meet the search criteria specified in Agent Builder Meet the @function search criteria specified in this method
Selected documents or View action | Are selected in the view Meet the search criteria specified in Agent Builder Meet the @function search criteria specified in this method
Run once | Is the current document
Newly received mail documents | Just mailed to the database Meet the search criteria specified in Agent Builder Meet the @function search criteria specified in this method
Newly modified documents | Just modified Meet the search criteria specified in Agent Builder Meet the @function search criteria specified in this method
Pasted documents | Just pasted into the database Meet the search criteria specified in Agent Builder Meet the @function search criteria specified in this method

Using UpdateProcessedDoc

For agents that run on new and modified documents, newly received mail documents, pasted documents, or newly modified documents, you must use the UpdateProcessedDoc method in NotesSession to mark each document as "processed," which ensures that a document gets processed by the agent only once (unless it's modified, mailed, or pasted again). If you do not call this method for each document, the agent processes the same documents the next time it runs.

UpdateProcessedDoc marks a document as processed only for the particular agent from which it is called. Using UpdateProcessedDoc in one agent has no effect on the documents that another agent processes.

In all other agents and view actions, UpdateProcessedDoc has no effect.

View actions

When used in a view action, UnprocessedSearch returns the same documents as an agent that runs on selected documents.

See examples
Examples: UnprocessedSearch method

See also
NotesDateTime class
NotesDocumentCollection class
Search method
UnprocessedDocuments property
UnprocessedFTSearch method
UpdateProcessedDoc method (in NotesSession)


UpdateFTIndex method

Updates the database's full-text index.

Defined in

NotesDatabase

Syntax

Call notesDatabase.UpdateFTIndex( createFlag )

Parameter

createFlag

Boolean. Specify True if you want to create an index if none exists (valid only for local databases and only if the database contains at least one document). Otherwise, specify False.

Usage

Notes returns an error if you attempt to create a full-text index on a database that is not local. If the database does not contain at least one document, setting the createFlag to True will not create a full-text index.

See examples
Examples: UpdateFTIndex method

See also
Locating documents within a view or folder
FTSearch method
FTSearch method (in NotesView)
IsFTIndexed property
LastFTIndexed property
Server property
UnprocessedFTSearch method


NotesDateRange class

Represents a range of dates and times.

Containment

Contained by: NotesSession

Contains: NotesDateTime

Properties

EndDateTime

Parent

StartDateTime

Text

Creation

To create a new NotesDateRange object, you can use the CreateDateRange method in NotesSession. To initialize the object, you can do one of the following:

  • Set StartDateTime and EndDateTime to NotesDateTime values.

  • Assign to Text a string value that represents a date range. This consists of two string representations of date-time values separated by a hyphen (for example, "01/01/97 - 01/02/97").

Usage

When you set StartDateTime or EndDateTime, its value replaces the corresponding value in Text, and vice versa.

See examples
Examples: NotesDateRange class

See also
Converting between Domino Designer and LotusScript time
Using the Domino classes


EndDateTime property

Read-write. The ending date-time of a range.

Defined in

NotesDateRange

Data type

NotesDateTime

Syntax

To get: notesDateTime = notesDateRange.EndDateTime

To set: Set notesDateRange.EndDateTime = notesDateTime

Note To set the property, you must use the Set keyword.

Usage

Modifying the NotesDateTime object that EndDateTime is based on implicitly modifies EndDateTime.

If you specify Nothing, this method will generate an error.

See examples
Examples: NotesDateRange class

See also
Converting between Domino Designer and LotusScript time
StartDateTime property
Text property
CreateDateRange method in NotesSession
FreeTimeSearch method in NotesSession


Parent property

Read-only. The session that contains a DateRange object.

Note This property is new with Release 5.0.2b.

Note This property is supported in COM only.

Defined in

NotesDateRange

Data type

NotesSession

Syntax

To get: Set notesSession = notesDateRange.Parent

See examples
Examples: Parent property


StartDateTime property

Read-write. The starting date-time of a range.

Defined in

NotesDateRange

Data type

NotesDateTime

Syntax

To get: notesDateTime = notesDateRange.StartDateTime

To set: Set notesDateRange.StartDateTime = notesDateTime

Note To set the property, you must use the Set keyword.

Usage

Modifying the NotesDateTime object that StartDateTime is based on implicitly modifies StartDateTime.

If you specify Nothing, this method will generate an error.

See examples
Examples: NotesDateRange class

See also
Converting between Domino Designer and LotusScript time
EndDateTime property
Text property
CreateDateRange method in NotesSession
FreeTimeSearch method in NotesSession


Text property

Read-write. The text associated with a range.

Defined in

NotesDateRange

Data type

String

Syntax

To get: text = notesDateRange.Text

To set: notesDateRange.Text = text

See examples
Examples: NotesDateRange class

See also
Converting between Domino Designer and LotusScript time
StartDateTime property
EndDateTime property
CreateDateRange method in NotesSession
FreeTimeSearch method in NotesSession


NotesDateTime class

Represents a date and time. Provides a means of translating between the LotusScript date-time format and the Domino format.

Containment

Contained by: NotesDateRange, NotesSession

Properties

DateOnly

GMTTime

IsDST

IsValidDate

LocalTime

LSGMTTime

LSLocalTime

Parent

TimeOnly

TimeZone

ZoneTime

Methods

AdjustDay

AdjustHour

AdjustMinute

AdjustMonth

AdjustSecond

AdjustYear

ConvertToZone

New

SetAnyDate

SetAnyTime

SetNow

TimeDifference

TimeDifferenceDouble

Creation

To create a new NotesDateTime object, you can use:

  • New

Note The New method is not supported in COM.

  • CreateDateTime method in NotesSession

Given a string that represents the date and time you want, New creates an object that represents that date and time.

Syntax

Dim variableName As New NotesDateTime( dateTime$ )

or

Set notesDateTime = New NotesDateTime( dateTime$ )

Parameter

dateTime$

String. The date and time you want the object to represent. If you use an empty string (""), the date is set to a wildcard date. The Notes date-time expressions "Today" and "Yesterday" are supported.

Usage

The following information applies to New and the CreateDateTime method in NotesSession.

The dateTime$ parameter should specify a date, followed by a space, followed by a time. You can specify a date without a time component, or a time without a date component, but the TimeZone property will default to 0. For example, if the current time zone is Eastern Standard Time and 09:00 PM is specified in the dateTime$ parameter without the date, the GMTTime property will return 9:00 PM Eastern Standard Time, not 2:00 AM Greenwich Mean Time.

The date component of the dateTime$ parameter can be in any of the following formats, where "/" represents the operating system date separator:

  • MM/DD/YY
    For example, "04/16/97" represents April 16, 1997. Use this format to specify a year in the 20th century (MM is 50 or greater) or the 21st century (MM is less than 50).

  • MM/DD/YYYY
    For example, "04/16/1997" represents April 16, 1997 and "04/16/2097" represents April 16, 2097. Use this format to specify a year in any century.

  • MM/DD
    For example, "08/18" represents August 18, 1996, if 1996 is the current year. When you use this format, Domino appends the current year.

  • MM/YY
    For example, "08/96" represents August 1, 1996. When you use this format, Domino stores it as the first day of the month. Use this format to specify a year in the 20th century (MM is 50 or greater) or the 21st century (MM is less than 50).

  • MM/YYYY
    For example, "08/2096" represents August 1, 2096. When you use this format, Domino stores it as the first day of the month. Use this format to specify a year in any century.

  • "Today" or "Yesterday"

The time component of the dateTime$ parameter can be in any of the following formats, where ":" is the operating system date separator (for example, the date separator specified in Regional Settings in the Windows Control Panel). The seconds component, SS, is optional in all three:

  • HH:MM:SS PM. For example, "09:12:33 PM."

  • HH:MM:SS AM. For example, "09:12:33 AM."

  • HH:MM:SS. For example, "09:12:33." If you do not specify AM or PM, the time is treated as a military time; therefore "09:12:33" is stored as 09:12:33 AM, while "21:12:33" is stored as 09:12:33 PM.

Time zones

When you create a new NotesDateTime object, its TimeZone property is determined by the time zone setting in Domino. For example, if the script runs on a computer whose Domino time zone is set to Eastern Standard Time, the TimeZone property of any new NotesDateTime object is automatically set to 5. The GMTTime and LSGMTTime properties are also determined by the time zone setting.

Note Both the date and the time must be specified in the dateTime$ parameter, or the TimeZone property defaults to 0.

Today and Yesterday

When you create a new NotesDateTime object using an expression such as "Today" or "Yesterday," the value of the date is determined using the current date setting in Domino. These expressions have no effect on the time component of a NotesDateTime object. To set a NotesDateTime to the current date and time, use the SetNow method.

Note If these expressions are used without a time component the TimeZone property will default to 0. The parameters can be used in conjunction with a time parameter if so desired. For example: "Today 12:00:00 AM".

Storing dates in LotusScript

Unlike LotusScript date-time variants, Domino date-time items and NotesDateTime objects store a time zone and hundredths of a second (the hundredths of a second are not visible to the user). Use the NotesDateTime class if you need to store a time zone or hundredths of a second. Use LotusScript date-time variants if you only need a date and time component without a time zone or hundredths of a second.

Access

To access a date-time value stored in an item on a Notes document, use the DateTimeValue property in NotesItem.

See examples
Examples: NotesDateTime class

See also
Converting between Domino Designer and LotusScript time
Using the Domino classes


DateOnly property

Read-only. A string representing the date part of a date-time, in the local time zone.

Note This property is new with Release 4.6.

Defined in

NotesDateTime class

Data type

String

Syntax

To get: date$ = notesDateTime.DateOnly

Usage

When you set this property, it changes the value of the date-time that the object represents, and therefore affects the GMTTime, LSLocalTime, and LSGMTTime properties.

See examples
Example: DateOnly property

See also
RegistrationServer property


GMTTime property

Read-only. A string representing a date-time, converted to Greenwich Mean Time (timezone 0).

Defined in

NotesDateTime

Data type

String

Syntax

To get: gmt$ = notesDateTime.GMTTime

Usage

The Greenwich Mean Time value depends upon the IsDST and TimeZone properties of the NotesDateTime object.

See examples
Examples: GMTTime property

See also
IsDST property
LSGMTTime property
TimeZone property


IsDST property

Read-only. Indicates if the time reflects daylight-saving time.

Defined in

NotesDateTime

Data type

Boolean

Syntax

To get: flag = notesDateTime.IsDST

Legal values

  • True indicates that the current computer is set to observe daylight savings time, and daylight savings time is currently in effect (for example, from mid-April to mid-October).

  • False indicates that the current computer is set to observe daylight savings time, but daylight savings time is not currently in effect (for example, from mid-October to mid-April).

    The current computer is not set to observe daylight savings time.

    The NotesDateTime object has no time component.

See examples
Example: IsDST property


IsValidDate property

Read-only. Indicates if the string that is used to create the NotesDateTime object, is valid.

Note This property is new with Release 5.

Defined in

NotesDateTime

Data type

Boolean

Syntax

To get: flag = notesDateTime.IsValidDate

Legal values

  • True indicates that the string with which the NotesDateTime was created, is valid

  • False indicates that the string with which the NotesDateTime was created, is not valid

Usage

An empty string is considered a valid string.

If the string is invalid, a NotesDatetime will be created where the date and time will be set to wildcards.


LocalTime property

Read-Write. A string representing a date-time, in the local time zone.

Defined in

NotesDateTime

Data type

String

Syntax

To get: time$ = notesDateTime.LocalTime

To set: notesDateTime.LocalTime = time$

Usage

When you set this property, it changes the value of the date-time that the object represents, and, therefore, affects the DateOnly, GMTTime, LSLocalTime, LSGMTTime, and TimeOnly properties.

See examples
Examples: LocalTime property

See also
Converting between Domino Designer and LotusScript time
LSLocalTime property


LSGMTTime property

Read-only. A LotusScript variant representing a date-time, converted to Greenwich Mean Time (timezone 0).

Defined in

NotesDateTime

Data type

Variant of type DATE

Syntax

To get: gmtV = notesDateTime.LSGMTTime

See examples
Example: LSGMTTime property

See also
GMTTime property


LSLocalTime property

Read-Write. A LotusScript variant representing a date-time, in the local time zone.

Defined in

NotesDateTime

Data type

Variant of type DATE

Syntax

To get: timeV = notesDateTime.LSLocalTime

To set: notesDateTime.LSLocalTime = timeV

Usage

When you set this property, it changes the value of the date-time that the object represents, and therefore affects the DateOnly, GMTTime, LocalTime, LSGMTTime, and TimeOnly properties.

See examples
Examples: LSLocalTime property

See also
Converting between Domino Designer and LotusScript time
LocalTime property


Parent property

Read-only. The session that contains a DateTime object.

Note This property is new with Release 5.0.2b.

Note This property is supported in COM only.

Defined in

NotesDateTime

Data type

NotesSession

Syntax

To get: Set notesSession = notesDateTime.Parent

See examples
Examples: Parent property


TimeOnly property

Read-only. A string representing the time part of a date-time, in the local time zone.

Note This property is new with Release 4.6.

Defined in

NotesDateTime class

Data type

String

Syntax

To get: time$ = notesDateTime.TimeOnly

See examples
Example: TimeOnly property

See also
Converting between Domino Designer and LotusScript time


TimeZone property

Read-only. An integer representing the time zone of a date-time. In many cases, but not all, this integer indicates the number of hours which must be added to the time to get Greenwich Mean Time. May be positive or negative.

Defined in

NotesDateTime

Data type

Integer

Syntax

To get: zone% = notesDateTime.TimeZone

Usage

When you create a new NotesDateTime object, this property gets set according to the time zone setting of the computer on which the script runs.

The property defaults to 0 if the NotesDateTime object does not include both a time and a date.

When you access a date-time value from an item in a document using the DateTimeValue property in NotesItem, this property gets set according to the time zone stored in the item.

See examples
Examples: TimeZone property


ZoneTime property

Read-only. A string representation of the time adjusted for the TimeZone and IsDST properties.

Defined in

NotesDateTime

Data type

String

Syntax

To get: zone$ = notesDateTime.ZoneTime

Usage

Initially ZoneTime is the same as LocalTime. If you use the ConvertToZone method, changes to TimeZone and IsDST are reflected in ZoneTime, but LocalTime stays the same.

See examples
Example: ConvertToZone method

See also
ConvertToZone method
IsDST property


AdjustDay method

Increments a date-time by the number of days you specify.

Defined in

NotesDateTime

Syntax

Call notesDateTime.AdjustDay( n% [, preserveLocalTime ] )

Parameter

n%

Integer. The number of days by which to increment the date-time. Can be positive or negative.

preserveLocalTime

Boolean. Optional. Affects adjustments that cross daylight savings boundaries. Specify True to increment or decrement the GMT time by one hour such that a 24-hour adjustment yields the same local time in the new day. If this parameter is False or omitted, GMT time remains as adjusted and local time gains or loses an hour.

See examples
Examples: AdjustDay method

See also
AdjustHour method
AdjustMinute method
AdjustMonth method
AdjustSecond method
AdjustYear method


AdjustHour method

Increments a date-time by the number of hours you specify.

Defined in

NotesDateTime

Syntax

Call notesDateTime.AdjustHour( n% [, preserveLocalTime ] )

Parameter

n%

Integer. The number of hours by which to increment the date-time. Can be positive or negative.

preserveLocalTime

Boolean. Optional. Affects adjustments that cross daylight savings boundaries. Specify True to increment or decrement the GMT time by one hour such that a 24-hour adjustment yields the same local time in the new day. If this parameter is False or omitted, GMT time remains as adjusted and local time gains or loses an hour.

Usage

If the NotesDateTime object consists of only a date component, this method has no effect as long as the adjustment is less than the number of hours in a day.

The number of hours by which you increment a NotesDateTime object can cause the date component to be adjusted, too. For example, if n% is 24, the date component changes to the next calendar day.

See examples
Examples: AdjustHour method

See also
AdjustDay method
AdjustMinute method
AdjustMonth method
AdjustSecond method
AdjustYear method


AdjustMinute method

Increments a date-time by the number of minutes you specify.

Defined in

NotesDateTime

Syntax

Call notesDateTime.AdjustMinute( n% [, preserveLocalTime ] )

Parameter

n%

Integer. The number of minutes by which to increment the date-time. Can be positive or negative.

preserveLocalTime

Boolean. Optional. Affects adjustments that cross daylight savings boundaries. Specify True to increment or decrement the GMT time by one hour such that a 24-hour adjustment yields the same local time in the new day. If this parameter is False or omitted, GMT time remains as adjusted and local time gains or loses an hour.

Usage

If the NotesDateTime object consists of only a date component, this method has no effect as long as the adjustment is less than the number of minutes in a day.

The number of minutes by which you increment a NotesDateTime object can cause the date component to be adjusted, too. For example, if n% is 1440, the date component changes to the next calendar day.

See examples
Examples: AdjustMinute method

See also
AdjustDay method
AdjustHour method
AdjustMonth method
AdjustSecond method
AdjustYear method


AdjustMonth method

Increments a date-time by the number of months you specify.

Defined in

NotesDateTime

Syntax

Call notesDateTime.AdjustMonth( n% [ , preserveLocalTime ] )

Parameter

n%

Integer. The number of months by which to increment the date-time. Can be positive or negative.

preserveLocalTime

Boolean. Optional. Affects adjustments that cross daylight savings boundaries. Specify True to increment or decrement the GMT time by one hour such that a 24-hour adjustment yields the same local time in the new day. If this parameter is False or omitted, GMT time remains as adjusted and local time gains or loses an hour.

Usage

The number of months by which you increment a NotesDateTime object can cause the year to be incremented. For example, if n% is 12, the date component changes to the next calendar year.

See examples
Examples: AdjustMonth method

See also
AdjustDay method
AdjustHour method
AdjustMinute method
AdjustSecond method
AdjustYear method


AdjustSecond method

Increments a date-time by the number of seconds you specify.

Defined in

NotesDateTime

Syntax

Call notesDateTime.AdjustSecond( n% [, preserveLocalTime ] )

Parameter

n%

Integer. The number of seconds by which to increment the date-time. Can be positive or negative.

preserveLocalTime

Boolean. Optional. Affects adjustments that cross daylight savings boundaries. Specify True to increment or decrement the GMT time by one hour such that a 24-hour adjustment yields the same local time in the new day. If this parameter is False or omitted, GMT time remains as adjusted and local time gains or loses an hour.

Usage

If the NotesDateTime object consists of only a date component, this method has no effect.

See examples
Examples: AdjustSecond method

See also
AdjustDay method
AdjustHour method
AdjustMinute method
AdjustMonth method
AdjustYear method


AdjustYear method

Increments a date-time by the number of years you specify.

Defined in

NotesDateTime

Syntax

Call notesDateTime.AdjustYear( n% [, preserveLocalTime ] )

Parameter

n%

Integer. The number of years by which to increment the date-time. Can be positive or negative.

preserveLocalTime

Boolean. Optional. Affects adjustments that cross daylight savings boundaries. Specify True to increment or decrement the GMT time by one hour such that a 24-hour adjustment yields the same local time in the new day. If this parameter is False or omitted, GMT time remains as adjusted and local time gains or loses an hour.

Usage

The number of years by which you increment a NotesDateTime object can cause the century to change. If this happens, the year is represented with four digits instead of two, such as 08/18/2001.

See examples
Examples: AdjustYear method

See also
AdjustDay method
AdjustHour method
AdjustMinute method
AdjustMonth method
AdjustSecond method


ConvertToZone method

Changes the TimeZone and IsDST properties as specified.

Defined in

NotesDateTime

Syntax

Call notesDateTime.ConvertToZone( newzone, dst )

Parameters

newzone

Integer. A time zone. Could be negative.

dst

Boolean. Indicates whether daylight savings is in effect (True) or not (False).

Usage

These changes affect the ZoneTime property.

The GMTTime and the LocalTime properties do not change.

See examples
Example: ConvertToZone method

See also
IsDST property
ZoneTime property


SetAnyDate method

Sets the date component to a wildcard value, which means it matches any date. The time component is unaffected.

Defined in

NotesDateTime

Syntax

Call notesDateTime.SetAnyDate

Usage

This method is useful when passing the object as an argument to other methods.

A NotesDateTime object for which you have invoked this method may not be convertible to string format.

See also
SetAnyTime method
SetNow method


SetAnyTime method

Sets the time component to a wildcard value, which means it matches any time. The date component is unaffected.

Defined in

NotesDateTime

Syntax

Call notesDateTime.SetAnyTime

Usage

This method is useful when passing the object as an argument to other methods.

A date-time object for which you have invoked this method may not be convertible to string format.

See also
SetAnyDate method
SetNow method


SetNow method

Sets the value of a date-time to now (today's date and current time).

Defined in

NotesDateTime

Syntax

Call notesDateTime.SetNow

Usage

This method works by taking a snapshot of the current date-time at the moment that the method is executed. After the method executes, the value of the NotesDateTime object does not update itself to always reflect the current date-time. Its value only changes if you change it explicitly.

See examples
Examples: SetNow method

See also
SetAnyDate method
SetAnyTime method


TimeDifference method

Finds the difference in seconds between one date-time and another.

Defined in

NotesDateTime

Syntax

difference& = notesDateTime.TimeDifference( notesDateTime )

Parameter

notesDateTime

NotesDateTime. Any date-time value.

Return value

difference&

Long. The current date-time minus the specified notesDateTime, in seconds.

See examples
Example: TimeDifference method


TimeDifferenceDouble method

Finds the difference in seconds between one date-time and another.

Note This method is new with Notes Release 5.

Defined in

NotesDateTime

Syntax

difference# = notesDateTime.TimeDifferenceDouble( notesDateTime )

Parameter

notesDateTime

NotesDateTime. Any date-time value.

Return value

difference#

Double. The current date-time minus the specified notesDateTime, in seconds.


NotesDbDirectory class

Represents the Notes databases on a specific server or local computer.

Containment

Contained by: NotesSession

Contains: NotesDatabase

Properties

Name

Parent

Methods

CreateDatabase

GetFirstDatabase

GetNextDatabase

OpenDatabase

OpenDatabaseByReplicaID

OpenDatabaseIfModified

OpenMailDatabase

Creation

You create a new NotesDbDirectory object using the name of the server you want to access. You can use:

  • New

Note The New method is not supported in COM.

  • GetDbDirectory method in NotesSession

Syntax

Dim variableName as New NotesDbDirectory( serverName$ )

or

Set notesDbDirectory = New NotesDbDirectory( serverName$ )

Parameter

serverName$

String. The name of the server whose database files you want to navigate. Use an empty string ("") to indicate the current computer.

See examples
Example: NotesDbDirectory class

See also
Locating a database on a server and local disk
Using the Domino classes


Name property

Read-only. The name of the server whose database directory you are searching. This property is set when you create a database directory.

Defined in

NotesDbDirectory

Data type

String

Syntax

To get: serverName$ = notesDbDirectory.Name

Usage

This property returns an empty string ("") for NotesDbDirectory objects that represent the current computer.

See examples
Example: Name property

See also
Locating a database on a server and local disk


Parent property

Read-only. The session that contains a DbDirectory object.

Note This property is new with Release 5.0.2.

Note This property is supported in COM only.

Defined in

NotesDbDirectory

Data type

NotesSession

Syntax

To get: Set notesSession = notesDbDirectory.Parent

See examples
Examples: Parent property


CreateDatabase method

Creates a new database, using the server and filename that you specify.

Note This method is new with Release 5.0.2b.

Note This method is supported in COM only. For LotusScript, use Create in NotesDatabase.

Defined in

NotesDbDirectory

Syntax

Set notesDatabase = notesDbDirectory.CreateDatabase( dbfile$ [ , open ] )

Parameters

dbfile$

The file name of the new database.

open

Boolean. True (default) to open the database.

Return value

notesDatabase

The newly created database.

Usage

If you do not open the database, only a subset of its properties is available. See IsOpen in NotesDatabase.

This method raises ERR_NOTES_ERROR2 (error 0FA5) if the database already exists.

See examples
Examples: CreateDatabase method


GetFirstDatabase method

Returns the first database on a server (or local computer), using the file type you specify.

Defined in

NotesDbDirectory

Syntax

Set notesDatabase = notesDbDirectory.GetFirstDatabase( fileType% )

Parameter

fileType%

Constant of type Integer. Indicates the kind of database file you want to retrieve from the server.

fileType% | Indicates
DATABASE (1247) for LotusScript NOTES_DATABASE (1247) for COM | Any Notes database (.nsf, .nsg, or .nsh file)
TEMPLATE (1248) | Any Notes database template (.ntf file)
REPLICA_CANDIDATE (1245) | Any Notes database or template not disabled for replication
TEMPLATE_CANDIDATE (1246) | Any Notes database or template

Return value

notesDatabase

The first database, of the specified fileType%, located in the directory. The database is closed. To open it, use the Open or OpenIfModified method in NotesDatabase.

Usage

Each time you call this method, the database directory is reset and a new search is conducted. If you're searching for template files, for example, a new call to GetFirstDatabase with the parameter DATABASE (LotusScript) or NOTES_DATABASE (COM) will start searching the directory from the beginning, this time for database files.

See examples
Example: GetFirstDatabase method

See also
GetNextDatabase method
Locating a database on a server and local disk
NotesDatabase class
Opening and closing a database


GetNextDatabase method

Returns the next database in a directory, using the file type specified in the GetFirstDatabase method.

Defined in

NotesDbDirectory

Syntax

Set notesDatabase = notesDbDirectory.GetNextDatabase

Return value

notesDatabase

The next database located on the server. Once you exhaust the directory, returns Nothing. The database is closed. To open it, use the Open or OpenIfModified method in NotesDatabase.

See examples
Example: GetNextDatabase method

See also
GetFirstDatabase method
Locating a database on a server and local disk
NotesDatabase class
Opening and closing a database


OpenDatabase method

Opens a database.

Note This method is new with Release 5.0.2b.

Note This method is supported in COM only. For LotusScript, use Open in NotesDatabase.

Defined in

NotesDbDirectory

Syntax

Set notesDatabase = notesDbDirectory.OpenDatabase( dbfile$ [ , failover ] )

Parameters

dbfile$

The file name of the database to open.

open

Boolean. If True and the database cannot be opened on the current server, an attempt is made to open it on another server in the cluster (if there is a cluster). The object's Server and FilePath properties reflect the server that the database is opened on. Default is False.

Return value

notesDatabase

The opened database.

Usage

This method usually raises ERR_SYS_FILE_NOT_FOUND (error 0FA3) if the database does not exist. However, other errors may occur or the method may return an object with blank properties.

See examples
Examples: OpenDatabase method


OpenDatabaseByReplicaID method

Opens a database with a specified replica ID.

Note This method is new with Release 5.0.2b.

Note This method is supported in COM only. For LotusScript, use the OpenByReplicaID method in NotesDatabase.

Defined in

NotesDbDirectory

Syntax

Set notesDatabase = notesDbDirectory.OpenDatabaseByReplicaID( rid$ )

Parameter

rid$

The replica ID of the database that you want to open.

Return value

notesDatabase

The opened database.

Usage

This method usually raises ERR_SYS_FILE_NOT_FOUND (error 0FA3) if the database does not exist. However, other errors may occur or the method may return an object with blank properties.

See examples
Examples: OpenDatabaseByReplicaID method


OpenDatabaseIfModified method

Opens a database if it has been modified since a specified date.

Note This method is new with Release 5.0.2b.

Note This method is supported in COM only. For LotusScript, use the OpenIfModified method in NotesDatabase.

Defined in

NotesDbDirectory

Syntax

Set notesDatabase = notesDbDirectory.OpenDatabaseIfModified( dbfile$ , notesDateTime )

Parameters

dbfile$

The file name of the database that you want to open.

notesDateTime

A cutoff date. If one or more documents in the database were modified since this date, the database is opened; if not, it is not opened.

Return value

notesDatabase

The opened database.

Usage

This method raises error 023C if the database has not been modified since the specified date.

This method usually raises ERR_SYS_FILE_NOT_FOUND (error 0FA3) if the database does not exist. However, other errors may occur or the method may return an object with blank properties.

See examples
Examples: OpenDatabaseIfModified


OpenMailDatabase method

Opens the current user's mail database.

Note This method is new with Release 5.0.2b.

Note This method is supported in COM only. For LotusScript, use the OpenMail method in NotesDatabase.

Defined in

NotesDbDirectory

Syntax

Set notesDatabase = notesDbDirectory.OpenMailDatabase( )

Return value

notesDatabase

The opened database.

Usage

The value of the parent NotesDbDirectory does not matter except that it must be set. It can be the local or any server directory.

See examples
Examples: OpenMailDatabase method


NotesDocument class

Represents a document in a database.

Containment

Contained by: NotesDatabase, NotesDocumentCollection, NotesNewsletter, NotesUIDocument, NotesView, NotesViewEntry

Contains: NotesEmbeddedObject, NotesItem, NotesRichTextItem

Properties

Authors

ColumnValues

Created

EmbeddedObjects

EncryptionKeys

EncryptOnSend

FolderReferences

FTSearchScore

HasEmbedded

HttpURL

IsDeleted

IsNewNote

IsProfile

IsResponse

IsSigned

IsUIDocOpen

IsValid

Items

Key

LastAccessed

LastModified

NameOfProfile

NoteID

NotesURL

ParentDatabase

ParentDocumentUNID

ParentView

Responses

SaveMessageOnSend

SentByAgent

Signer

SignOnSend

Size

UniversalID

Verifier

Methods

AppendItemValue

ComputeWithForm

CopyAllItems

CopyItem

CopyToDatabase

CreateReplyMessage

CreateRichTextItem

Encrypt

GetAttachment

GetFirstItem

GetItemValue

HasItem

MakeResponse

New

PutInFolder

Remove

RemoveFromFolder

RemoveItem

RenderToRTItem

ReplaceItemValue

Save

Send

Sign

Creation

To create a new NotesDocument object, use one of the following:

  • New

Note The New method is not supported in COM.

  • CreateDocument method in NotesDatabase

Given a database, New creates a document in the database and returns a NotesDocument object that represents the document. You must call Save if you want the new document to be saved to disk.

Syntax

Dim variableName As New NotesDocument( notesDatabase )

or

Set notesDocument = New NotesDocument( notesDatabase )

Parameter

notesDatabase

The database in which to create a new document.

Access

There are several ways to access an existing document.

  • To get a document based on its position in a view, use a NotesView.

  • To get a document based on its position in a response hierarchy, use a NotesView.

  • To get a document based on its NoteID or UNID, use GetDocumentByID or GetDocumentByUNID in NotesDatabase.

  • To get all the documents in a database, use AllDocuments in NotesDatabase.

  • To get all the documents that match a full-text search query of a view or a database, use FTSearch in NotesView or NotesDatabase.

  • To get all the documents in a database that meet search criteria, where the criteria are defined using formula language, use Search in NotesDatabase.

  • To get documents in a database that have not been processed by the current agent, use UnprocessedDocuments, UnprocessedFTSearch, or UnprocessedSearch in NotesDatabase.

  • To get all of the documents that are responses to a particular document, use the Responses property in NotesDocument.

  • To get a response document's parent document, use the ParentDocumentUNID property in NotesDocument and the GetDocumentByUNID method in NotesDatabase.

Once you have a view, you can navigate to a specific document using methods in the NotesView class.

Once you have a collection of documents, you can navigate to a specific document using methods in the NotesDocumentCollection class.

Saving changes

After you create, modify, or delete a document, you must save the changes by calling the Save method.

If you don't call Save before the script finishes, all of your changes to a NotesDocument are lost. Call Save every time you want to keep your changes.

When you call Save, the document is saved to disk even if you don't add any items to it.

Additional properties

In addition to the properties listed, you can also treat an item name as a property of a NotesDocument object. For example, the following line of script sets the value of the Subject item in a document to "Hello":

doc.Subject = "Hello"

For more information, see the AppendItemValue and ReplaceItemValue methods.

Encryption

A script attempts to decrypt an encrypted document the first time the script accesses one of the NotesDocument properties or methods. If decryption fails, an error is raised.

See examples
Examples: NotesDocument class

See also
Creating a document in LotusScript (c)
Using the Domino classes


Authors property

Read-only. The names of the people who have saved a document.

Defined in

NotesDocument

Data type

Array of strings

Syntax

To get: authorArray = notesDocument.Authors

Usage

If a name is hierarchical, this property returns the fully distinguished name.

This property does not return the names of people who have permission to edit a document (as found in an item of type Authors). Therefore, the people returned by the Authors property and the people listed in an Authors item may differ.

See examples
Examples: Authors property

See also
Created property
IsAuthors Property (in NotesItem)
LastModified property
Signer property
Verifier property


ColumnValues property

Read-only. An array of values, each element of which corresponds to a column value in the document's parent view. The first value in the array is the value that appears in the view's first column for the document, the second value is the one that appears in the second column, and so on. The value of each element of the array is the result of the corresponding column's formula and the items on the current document. Some elements in the array might have no value.

If you do not access the document through a view, this property has no value.

Defined in

NotesDocument

Data type

Array of variants

Syntax

To get: valueArray = notesDocument.ColumnValues

Usage

If a document contains an item that's visible in a view, the ColumnValues property provides efficient access to its value. Accessing the item's value directly is less efficient.

This property returns a value for each column in the parent view, regardless of whether the column is considered "Responses-only." For example, if the third column in a view is responses-only, doc.ColumnValues( 2 ) evaluates the column formula for the document and returns a result, whether the document is a response or not.

When UI-only functions such as @IsExpandable and @DocNumber are used as column formulas in the parent view, the values of these columns are not returned.

See examples
Examples: ColumnValues property

See also
Columns property (in NotesView)
NotesView class
NotesViewColumn class


Created property

Read-only. The date a document was created.

Defined in

NotesDocument

Data type

Variant of type DATE

Syntax

To get: dateV = notesDocument.Created

Usage

This property is useful when you're writing a script to archive documents. You can compare the date that a document is created with a cutoff date. If the document is created before the date, you archive it.

See examples
Examples: Created property

See also
LastModified property
LastAccessed property


EmbeddedObjects property

Read-only. The OLE/2 and OLE/1 embedded objects in a document.

Note EmbeddedObjects is not supported on OS/2, on UNIX, and on the Macintosh.

Defined in

NotesDocument

Data type

Array of NotesEmbeddedObjects

Syntax

To get: notesEmbeddedObjectArray = notesDocument.EmbeddedObjects

Usage

Unlike the EmbeddedObjects property in NotesRichTextItem, this property does not include file attachments or OLE/1 objects created in Notes Release 3.

This property does include OLE/2 and OLE/1 objects created in Notes Release 4. It also includes objects in the document that were originally embedded in the document's form. Such objects must have been activated, modified, and re-saved in order to be returned by this property (otherwise they remain a part of the form, not the document).

See examples
Examples: EmbeddedObjects property

See also
EmbeddedObjects property (in NotesRichTextItem)
EmbedObject method (in NotesRichTextItem)
GetAttachment method
GetEmbeddedObject method (in NotesRichTextItem)
HasEmbedded property
NotesEmbeddedObject class


EncryptionKeys property

Read-Write. The key(s) used to encrypt a document. The Encrypt method uses these keys when it encrypts the document.

Defined in

NotesDocument

Data type

String or array of strings

Syntax

To get: stringArray = notesDocument.EncryptionKeys

To set: notesDocument.EncryptionKeys = stringArray

notesDocument.EncryptionKeys = string$

Usage

When you get the value of this property, it always returns an array of strings. When you set the value of this property, you can use either a single string (if there's only one key) or an array of strings.

Each element in the EncryptionKeys array contains the name of an encryption key you want to use to encrypt the document. The document can be decrypted by any user who posesses one of the keys. If there are no encryption keys specified for a document, the document is encrypted with the current user's public key and can only be decrypted by that user.

You must call the Encrypt and Save methods to actually encrypt the document in the database. Since encryption works differently when a document is mailed, the EncryptionKeys property has no effect when a document is encrypted when mailed.

The name of each encryption key in a document is stored in a text item called SecretEncryptionKeys. This property returns the contents of the item.

See examples
Examples: EncryptionKeys property

See also
Encrypt method
EncryptOnSend property
IsEncrypted property (in NotesItem)
Save method


EncryptOnSend property

Read-Write. Indicates if a document is encrypted when mailed.

Defined in

NotesDocument

Data type

Boolean

Syntax

To get: flag = notesDocument.EncryptOnSend

To set: notesDocument.EncryptOnSend = flag

Legal values

  • True indicates that the document is encrypted when mailed

  • False indicates that the document is not encrypted when mailed

Usage

To encrypt a document when mailed, this method looks for the public key of each recipient in the Domino Directory. If it cannot find a recipient's public key, the method sends an unencrypted copy of the document to that recipient. All other recipients receive an encrypted copy of the document.

This property has no effect on whether a document is encrypted when saved to a database.

See examples
Examples: EncryptOnSend property

See also
Mailing a document
Encrypt method
EncryptionKeys property
IsEncrypted property (in NotesItem)
SaveMessageOnSend property
SignOnSend Property


FolderReferences property

Read only. Shows what folders have references to a particular document.

Note This property is new with Release 5.

Defined in

NotesDocument

Data type

Array of strings

Syntax

To get: StringArray = notesDocument.FolderReferences

Usage

Note The database must have the $FolderRef and $FolderRefInfo hidden views to support folder references. These views can be copied from the Release 5 mail template. Also, this property does not return view references.

Not all databases support folder references, so prior to getting the folder references for a document in the database, you should make sure that the database supports folder references by making a call to db.FolderReferencesEnabled.

For more information, see the FolderRefsEnabled property in the NotesDatabase class.

See examples
Example: FolderReferences property


FTSearchScore property

Read-only. The full-text search score of a document, if it was retrieved as part of a full-text search.

Defined in

NotesDocument

Data type

Integer

Syntax

To get: score% = notesDocument.FTSearchScore

Usage

If a document is in more than one NotesDocumentCollection or NotesViewEntryCollection, its score is that of the last collection it was retrieved from. The score is correct unless you get the score from the current object after retrieving the same document from another collection.

Documents added to a collection have a search score of 0.

Documents deleted from a view have a search score of 0.

The score is determined by the number of target words that are found in the document, the term weights assigned to the target words, and any proximity operators in the search query. If the document is not retrieved as part of a full-text search, returns 0. If the document is retrieved using an FTSearch method on a database without a full-text index, returns an unpredictable number.

See examples
Examples: FTSearchScore property

See also
FTSearch method (in NotesDatabase)
FTSearch method (in NotesView)
IsFTIndexed property (in NotesDatabase)
LastFTIndexed property (in NotesDatabase)
UnprocessedFTSearch method (in NotesDatabase)
UpdateFTIndex method (in NotesDatabase)


HasEmbedded property

Read-only. Indicates if a document contains one or more embedded objects, object links, or file attachments.

Note HasEmbedded is not supported on OS/2, on UNIX, and on the Macintosh.

Defined in

NotesDocument

Data type

Boolean

Syntax

To get: flag = notesDocument.HasEmbedded

Legal values

  • True indicates that the document contains one or more embedded objects, object links, or file attachments

  • False indicates that the document does not contain any embedded objects, object links, or file attachments

See examples
Examples: HasEmbedded property

See also
EmbeddedObjects property (in NotesDocument)
EmbeddedObjects property (in NotesRichTextItem)
EmbedObject method (in NotesRichTextItem)
GetAttachment method
GetEmbeddedObject method (in NotesRichTextItem)
NotesEmbeddedObject class
Working with an embedded object


HttpURL property

Read-only. The HTTP URL of a document.

Note This property is new with Release 5.0.02b.

Note This property is supported in COM only.

Defined in

NotesDocument

Data type

String

Syntax

To get: url$ = notesDocument.HttpURL


IsDeleted property

Read-only. Indicates if a document has been deleted or not.

Note This property is new with Release 5.

Defined in

NotesDocument

Data type

Boolean

Syntax

To get: flag = notesDocument.IsDeleted

Legal values

  • True indicates that the document has been deleted

  • False indicates that the document has not been deleted

See examples
Examples: IsDeleted property


IsNewNote property

Read-only. Indicates if a document is new. A document is new if it hasn't been saved.

Defined in

NotesDocument

Data type

Boolean

Syntax

To get: flag = notesDocument.IsNewNote

Legal values

  • True indicates that the document was created, but has not been saved

  • False indicates that the document has been saved

See examples
Example: IsNewNote property

See also
Save method


IsProfile property

Read-only. Indicates if a NotesDocument object is a profile document.

Defined in

NotesDocument

Data type

Boolean

Syntax

To get: flag = notesDocument.IsProfile

Legal values

  • True indicates that the document is a profile document

  • False indicates that the document is not a profile document

See examples
Example: IsProfile property

See also
EditProfile method (in NotesUIWorkspace)
GetProfileDocument method (in NotesDatabase)
Key property
NameOfProfile property


IsResponse property

Read-only. Indicates if a document is a response to another document.

Defined in

NotesDocument

Data type

Boolean

Syntax

To get: flag = notesDocument.IsResponse

Legal values

  • True indicates that the document is a response to another document

  • False indicates that the document is not a response

See examples
Example: IsResponse property

See also
GetChild method (in NotesView)
GetParentDocument method (in NotesView)
Locating documents within a view or folder
MakeResponse method
ParentDocumentUNID property
Responses property


IsSigned property

Read-only. Indicates if a document contains a signature.

Defined in

NotesDocument

Data type

Boolean

Syntax

To get: flag = notesDocument.IsSigned

Legal values

  • True indicates that the document contains one or more signatures

  • False indicates that the document does not contain signatures

Usage

To access the signatures, you must find the items of type SIGNATURE in the document.

See examples
Example: IsSigned property

See also
Sign method
Signer property
SignOnSend property
Type property (in NotesItem)
Verifier property


IsUIDocOpen property

Read-only. Indicates if a NotesDocument object (back-end document) is accessed through a NotesUIDocument object (front-end document).

Defined in

NotesDocument

Data type

Boolean

Syntax

To get: flag = notesDocument.IsUIDocOpen

Legal values

  • True indicates that the back-end document is from a front-end document

  • False indicates that the back-end document is not from a front-end document

See examples
Example: IsUIDocOpen property

See also
Accessing document properties
NotesUIDocument class


IsValid property

Read-only. Indicates if a Document object represents an existing document (not a delete stub).

Defined in

NotesDocument

Data type

Boolean

Syntax

To get: flag = notesDocument.IsValid

Legal values

  • True indicates that the document exists

  • False indicates that the document is a delete stub

Usage

You should call IsValid only once after getting a Document object. Use IsDeleted to see if a valid document is deleted while you are working on it.

See examples
Example: IsValid property


Items property

Read-only. All the items in a document. An item is any piece of data stored in a document.

Defined in

NotesDocument

Data type

Array of NotesItems

Syntax

To get: notesItemArray = notesDocument.Items

Usage

To set the value of an individual NotesItem object, you need to access the array elements individually. For example, to get the first element in the array returned from the NotesDocument object doc, you could do the following:

Dim item As NotesItem

Set item = doc.Items( 0 )

See examples
Examples: Items property

See also
AppendItemValue method
GetFirstItem method
GetItemValue method
Getting an item and its values
HasItem method
ReplaceItemValue method
NotesItem class
Working with an embedded object


Key property

Read-only. If a profile document, the user name (key) of the profile.

Defined in

NotesDocument

Data type

String

Syntax

To get: string$ = notesDocument.Key

See examples
Example: IsProfile property

See also
EditProfile method (in NotesUIWorkspace)
GetProfileDocument method (in NotesDatabase)
IsProfile property
NameOfProfile property


LastAccessed property

Read-only. The date a document was last modified or read by a Notes client.

Defined in

NotesDocument

Data type

Variant of type DATE

Syntax

To get: dateV = notesDocument.LastAccessed

See examples
Examples: LastAccessed property

See also
Created property
LastModified property


LastModified property

Read-only. The date a document was last modified.

Defined in

NotesDocument

Data type

Variant of type DATE

Syntax

To get: dateV = notesDocument.LastModified

See examples
Examples: LastModified property

See also
Created property
LastAccessed property


NameOfProfile property

Read-only. If a profile document, the name of the profile.

Defined in

NotesDocument

Data type

String

Syntax

To get string = notesDocument.NameOfProfile

See examples
Example: IsProfile property

See also
EditProfile method (in NotesUIWorkspace)
GetProfileDocument method (in NotesDatabase)
IsProfile property
Key property


NoteID property

Read-only. The NoteID of a document, which is an 8-character combination of letters and numbers that uniquely identifies a document within a particular database.

Defined in

NotesDocument

Data type

String

Syntax

To get: noteid$ = notesDocument.NoteID

Usage

A typical Note ID looks like this: 000020FA. A NoteID represents the location of a document within a specific database file, so documents which are replicas of one another generally have different NoteIDs. A NoteID does not change, unless the document is deleted.

See examples
Example: NoteID property

See also
GetDocumentByID method (in NotesDatabase)
ParentDocumentUNID property
UniversalID property


NotesURL property

Read-only. The Notes URL of a document.

Note This property is new with Release 5.0.02b.

Note This property is supported in COM only.

Defined in

NotesDocument

Data type

String

Syntax

To get: url$ = notesDocument.NotesURL


ParentDatabase property

Read-only. The database that contains a document.

Defined in

NotesDocument

Data type

NotesDatabase

Syntax

To get: Set notesDatabase = notesDocument.ParentDatabase

See examples
Examples: ParentDatabase property

See also
ParentView property


ParentDocumentUNID property

Read-only. The universal ID of a document's parent, if the document is a response. Returns an empty string ("") if a document doesn't have a parent.

Defined in

NotesDocument

Data type

String

Syntax

To get: parentUnid$ = notesDocument.ParentDocumentUNID

Usage

When used in conjunction with the GetDocumentByUNID method in NotesDatabase, the ParentDocumentUNID property allows you to find the parent document for any document.

For more information on universal IDs, see the UniversalID property.

See examples
Examples: ParentDocumentUNID property

See also
GetDocumentByUNID Method (in NotesDatabase)
IsResponse property
UniversalID property


ParentView property

Read-only. The view from which a document was retrieved, if any. If the document was retrieved directly from the database or a document collection, returns Nothing.

Defined in

NotesDocument

Data type

NotesView

Syntax

To get: Set notesView = notesDocument.ParentView

See examples
Example: ParentView property

See also
ParentDatabase property


Responses property

Read-only. The immediate responses to a document.

Defined in

NotesDocument

Data type

NotesDocumentCollection

Syntax

To get: Set notesDocumentCollection = notesDocument.Responses

Usage

Each document in the collection is an immediate response to the first document. Responses-to-responses are not included. If the current document has no responses, the NotesDocumentCollection contains zero documents.

Responses-to-Responses

This property returns only immediate responses to a document, but you can write a recursive sub or function to access all the descendants of a particular document. A recursive sub calls itself, the same way that a non-recursive sub calls any other sub or function.

See examples
Examples: Responses property

See also
GetChild method (in NotesView)
GetNextSibling method (in NotesView)
GetParentDocument method (in NotesView)
GetPrevSibling method (in NotesView)
IsResponse property
Locating documents within a view or folder
MakeResponse method
NotesDocumentCollection class
ParentDocumentUNID property


SaveMessageOnSend property

Read-Write. Indicates if a document is saved to a database when mailed. Only applies to new documents that have not yet been saved.

Defined in

NotesDocument

Data type

Boolean

Syntax

To get: flag = notesDocument.SaveMessageOnSend

To set: notesDocument.SaveMessageOnSend = flag

Legal values

  • True indicates that the document is saved when mailed

  • False indicates that the document is not saved when mailed

Usage

When SaveMessageOnSend is True, the document is saved just after being mailed.

See examples
Examples: SaveMessageOnSend property

See also
CreateReplyMessage method
EncryptOnSend property
Save method
Send method
SignOnSend property


SentByAgent property

Read-only. Indicates if a document was mailed by a script.

Defined in

NotesDocument

Data type

Boolean

Syntax

To get: flag = notesDocument.SentByAgent

Legal values

  • True indicates that the document was mailed by a script

  • False indicates that the document was mailed by a person

Usage

In agents that respond to mail messages, you can use this property to make sure that the agent is not responding to mail that was sent by another agent (or other script).

This property returns True if the document was mailed by any script, not just an agent script.

Documents sent by a script contain an item called $AssistMail whose value is set to 1. When a script uses the Send method to mail a document, the method automatically creates this item on the document.

See examples
Examples: SentByAgent property

See also
CreateReplyMessage method
Send method


Signer property

Read-only. The name of the person who created the signature, if a document is signed.

Defined in

NotesDocument

Data type

String

Syntax

To get: signer$ = notesDocument.Signer

Usage

If a document is not signed, returns an empty string ("").

See examples
Example: Signer property

See also
IsSigned property
Sign method
SignOnSend property
Verifier property


SignOnSend property

Read-Write. Indicates if a document is signed when mailed.

Defined in

NotesDocument

Data type

Boolean

Syntax

To get: flag = notesDocument.SignOnSend

To set: notesDocument.SignOnSend = flag

Legal values

  • True indicates that the document is signed when mailed

  • False indicates that the document is not signed when mailed

See examples
Examples: SignOnSend property

See also
EncryptOnSend property
IsSigned property
SaveMessageOnSend property
Sign method
Signer property
Verifier property


Size property

Read-only. The size of a document in bytes, which includes the size of any file attachments on the document.

Defined in

NotesDocument

Data type

Long

Syntax

To get: size& = notesDocument.Size

See examples
Example: Size property


UniversalID property

Read-write. The universal ID of a document, which is a 32-character combination of hexadecimal digits (0-9, A-F) that uniquely identifies a document across all replicas of a database. If two documents in replica databases share the same universal ID, the documents are replicas.

The universal ID is also known as the unique ID or UNID.

Defined in

NotesDocument

Data type

String

Syntax

To get: unid$ = notesDocument.UniversalID

To set: notesDocument.UniversalID = unid$

Usage

If you modify the UNID of an existing document, it becomes a new document.

If you set the UNID of a document the same as another document, you get run-time error 4000 when you attempt to save the document.

You can also use @DocumentUniqueID to get the Universal ID of a document. In a field formula, you must, however, use @Text to view the result in hexadecimal digits. Otherwise the function only creates a link to the ID.

See examples
Examples: UniversalID property

See also
GetDocumentByUNID method (in NotesDatabase)
NoteID property
ParentDocumentUNID property


Verifier property

Read-only. The name of the certificate that verified a signature, if a document is signed.

Defined in

NotesDocument

Data type

String

Syntax

To get: verifier$ = notesDocument.Verifier

See examples
Example: Verifier property

See also
IsSigned property
Sign method
Signer property


AppendItemValue method

Creates a new item in a document and sets the item value.

Defined in

NotesDocument

Syntax

Set notesItem = notesDocument.AppendItemValue( itemName$, value )

Parameters

itemName$

String. The name of the new item.

value

The value of the new item. The data type of the new item depends upon the data type of the value that you place in it.

Data type of value | Resulting notesItem
String | Text item containing value
Array of strings | Text item containing each element of value
Integer | Number item containing value
Array of integers | Number item containing each element of value
Variant of type DATE | Date-time item containing value
Array of variants, where each variant is of type DATE | Date-time item containing each element of value
NotesDateTime | Date-time item containing the date-time represented by the object
NotesItem | Item whose data type matches the NotesItem type and whose value(s) match the NotesItem value(s)

Return value

notesItem

The new item.

Usage

To keep the new item in the document, you must call the Save method after calling AppendItemValue.

If the document already has an item called itemName$, AppendItemValue does not replace it. Instead, it creates another item of the same name, and gives it the value you specify.

The IsSummary property of the new item defaults to True, which means that the item value can be displayed in a view or folder.

"Extended class" syntax

You can also create an item in a document using the NotesDocument "extended class" syntax, which eliminates the need for AppendItemValue. For example, you have the following script:

Dim item As NotesItem

Set item = doc.AppendItemValue _

( "Subject", "Update on stock options" )

Call doc.Save( False, True )

You can achieve the same result by doing the following:

doc.Subject = "Update on stock options"

Call doc.Save( False, True )

This syntax lets you treat NotesDocument as an "extended class" by using an item name as if it were a property of NotesDocument. In the example above, "Subject" is used as if it is a property of the NotesDocument class. The result is the same as if you used AppendItemValue, but note these differences in behavior:

  • If an item of the specified name already exists, AppendItemValue creates a new item with the same name. The extended class syntax, however, replaces the existing item with the new value.

  • AppendItemValue returns a NotesItem object representing the item you just created.

See examples
Examples: AppendItemValue method

See also
Creating an item and assigning values
GetItemValue method
HasItem method
NotesItem class
ReplaceItemValue method


ComputeWithForm method

Validates a document by executing the default value, translation, and validation formulas, if any are defined in the document form.

Defined in

NotesDocument

Syntax

flag = notesDocument.ComputeWithForm( doDataTypes, raiseError )

Parameters

doDataTypes

Boolean. The method ignores this parameter. Specify either True or False.

raiseError

Boolean. If True, an error is raised if the validation fails. If False, no error is raised; instead, the method returns False if validation fails.

Return value

  • True indicates that there are no errors on the document

  • False indicates that there are errors on the document

Usage

Notes determines the form for the document using:

  1. The form stored in the document, if any.

  2. The contents of the Form item, if no form is stored in the document. Be sure to specify a Form item if the database default form does not represent the items in the document.

  3. The database default form, if the document does not have a Form item.

In the Notes user interface, you must use a form to create a document. The document must meet the form's requirements for input validation, and the user interface informs you if the document does not meet these requirements. With the Notes classes, you can create a document without a form. The ComputeWithForm method provides a means of checking that the data you've placed in a document meets a form's requirements, although (unlike in the user interface) you can still save a document if the ComputeWithForm returns False or raises an error.

When you create a new document, however, no form item exists in the back-end. To avoid having ComputeWithForm fall back to the default form, put a Form field on your form when you create it. That way, you start with something in the back-end, and you get the expected results from your new document. Otherwise, you can get results from fields that exist only in the default form, but not the document you create.

See examples
Example: ComputeWithForm method


CopyAllItems method

Given a destination document, copies all of the items in the current document into the destination document. The item names are unchanged.

Defined in

NotesDocument

Data Type

Boolean

Syntax

Call notesDocument.CopyAllItems( notesDocument [, replace ] )

Parameters

notesDocument

The destination document.

replace

Boolean. If True, the items in the destination document are replaced. If False (default), the items in the destination document are addended.

See examples
Example: CopyAllItems method

See also
AppendItemValue method
Copying an item
CopyItem method
CopyItemToDocument method (in NotesItem)
GetFirstItem method
Items property
NotesItem class
ReplaceItemValue method


CopyItem method

Given an item, copies it into the current document and optionally assigns the copied item a new name.

Defined in

NotesDocument

Syntax

Set notesItem = notesDocument.CopyItem( notesItem, newName$ )

OR

Call notesDocument.CopyItem( notesItem, newName$ )

Use the Call statement when the program does not require the return value. Use the Set statement if the program requires the return value. Both statements yield the same results for this method.

Parameters

notesItem

The item, usually from another document, that you want to copy. If you specify Nothing, this method will generate an error.

newName$

String. The name to assign to the copied item. Specify an empty string ("") to retain the item's existing name.

Return value

notesItem

A copy of the specified notesItem parameter, identical except for its newName$.

See examples
Example: CopyItem method

See also
AppendItemValue method
CopyAllItems method
Copying an item
CopyItemToDocument method (in NotesItem)
GetFirstItem method
HasItem method
NotesItem class
RemoveItem method
ReplaceItemValue method


CopyToDatabase method

Copies a document into the specified database.

Defined in

NotesDocument

Syntax

Set notesDocument = notesDocument.CopyToDatabase( notesDatabase )

Parameter

notesDatabase

The database in which you want a copy of the document. If you specify Nothing, this method will generate an error.

Return value

notesDocument

The new document in the specified notesDatabase.

See examples
Example: CopyToDatabase method

See also
CopyAllItems method
Copying a document
NotesDatabase class
Remove method


CreateReplyMessage method

Creates a new document that is formatted as a reply to the current document.

Defined in

NotesDocument

Syntax

Set notesDocument = notesDocument.CreateReplyMessage( all )

Parameter

all

Boolean. If True, the new document recipient list contains all the recipients of the original. If False, the new document recipient list contains only the sender of the original.

Return value

notesDocument

A reply to the current document.

Usage

The new document does not contain a Subject item. If you want one, the script must explicitly add it to the document.

The new document does not get automatically mailed. If you want to mail it, the script must explicitly call the Send method.

See examples
Examples: CreateReplyMessage method

See also
Mailing a document
Send method
SentByAgent property


CreateRichTextItem method

Creates a new rich text item in a document, using a name you specify, and returns the corresponding NotesRichTextItem object. When used with OLE automation, this method allows you to create a new rich text item and NotesRichTextItem object without using New.

Defined in

NotesDocument

Syntax

Set notesRichTextItem = notesDocument.CreateRichTextItem( name$ )

Parameter

name$

String. The name of the new rich text item.

Return value

notesRichTextItem

The newly-created item.

Usage

For more information, see the NotesRichTextItem class.

See examples
Example: CreateRichTextItem method

See also
NotesRichTextItem class


Encrypt method

Encrypts a document in a database.

Defined in

NotesDocument

Syntax

Call notesDocument.Encrypt

Usage

The encrypted document is not written to disk until you call the Save method. Only the items for which the IsEncrypted property is True are encrypted. Items for which the IsEncrypted property is False remain visible to any user, even if the user does not have the proper encryption key.

If the EncryptionKeys property is set with one or more named keys, those keys are used to encrypt the document. Any user who has one of the encryption keys can decrypt the document. If there are no encryption keys specified, the document is encrypted with the user's public key, in which case only the user who encrypted the document can decrypt it.

If the script is running on a server, it must have permission to use Encrypt.

Since mail encryption works differently, don't use this method if you want to mail an encrypted document. Instead, set the EncryptOnSend property to True, and use the Send method.

See examples
Examples: Encrypt method

See also
EncryptionKeys property
EncryptOnSend property
IsEncrypted property (in NotesItem)
Save method
Send method


GetAttachment method

Given the name of a file attachment, returns a NotesEmbeddedObject representing the attachment. You can use this method to find file attachments which are not contained in a rich text item (such as an attachment in a Release 2 database), as well as file attachments that are contained in a rich text item.

Define in

NotesDocument

Syntax

Set notesEmbeddedObject = notesDocument.GetAttachment( fileName$ )

Parameter

fileName$

String. The name of the file attachment you want.

Return value

notesEmbeddedObject

A NotesEmbeddedObject that represents the file attachment. Returns Nothing if an attachment by the specified name is not found.

Usage

The Parent property for the returned NotesEmbeddedObject returns Nothing, since it was not accessed through a NotesRichTextItem.

See examples
Examples: GetAttachment method

See also
EmbeddedObjects property (in NotesDocument)
EmbeddedObjects property (in NotesRichTextItem)
EmbedObject method (in NotesRichTextItem)
GetEmbeddedObject method (in NotesRichTextItem)
NotesEmbeddedObject class
Working with an embedded object


GetFirstItem method

Given a name, returns the first item of the specified name belonging to the document.

Defined in

NotesDocument

Syntax

Set notesItem = notesDocument.GetFirstItem( name$ )

Parameter

name$

String. The name of the item you want to find.

Return value

notesItem

The first item with name$. Returns Nothing if the document does not contain an item with name$.

Usage

A document may contain more than one item of the same name. To access other than the first item, use the Items property of NotesDocument. This code gets all items named "Item33":

Forall item In doc.Items

     If item.Name = "Item33" Then

          ' Process one item

     End If

End Forall

If the value of a field is computed for display, the value is not stored as an item. The value is inaccessible from a NotesDocument object, unless the object is accessed as the Document property of NotesUIDocument, and GetFirstItem returns Nothing. In some cases, you can use LotusScript to access the field value another way. For example, if a document has a DateComposed field that's computed for display with a formula @Created, use the Created property in NotesDocument.

Using this method to get rich text items

The compiler raises an error if you try to set the return value of GetFirstItem equal to a NotesRichTextItem object. This is because a NotesItem is not necessarily a NotesRichTextItem, and the compiler has no way of knowing whether the name$ you specify actually corresponds to a rich text item. For example:

Dim doc As NotesDocument

Dim rtitem As NotesRichTextItem

'...set value of doc...

Set rtitem = doc.GetFirstItem( "Body" )

'compiler complains

The solution to this problem is to declare a variant, set it equal to the return value of GetFirstItem, and then treat the variant as a NotesRichTextItem. For example:

Dim doc As NotesDocument

Dim rtitem As Variant

'...set value of doc...

Set rtitem = doc.GetFirstItem( "Body" )

If ( rtitem.Type = RICHTEXT ) Then

  '...use NotesRichTextItem methods...

End If

See examples
Examples: GetFirstItem method

See also
CopyAllItems method
CopyItem method
GetItemValue method
Getting an item and its values
HasItem method
NotesItem class
RemoveItem method


GetItemValue method

Given the name of an item, returns the value of that item in a document.

Defined in

NotesDocument

Syntax

valueArray = notesDocument.GetItemValue( itemName$ )

Parameter

itemName$

String. The name of an item.

Return value

value

The value or values contained in itemName$. The data type of the value depends on the data type of the item.

Notes item type | Value return type
Rich text | String. The text in the item, rendered into plain text
Text or text list (includes Names, Authors, and Readers item types) | Array of strings
Number or number list | Array of doubles
Date-time or range of date-time values | Array of variants of type Date
When GetItemValue returns an array, each element in the array corresponds to a value in the item. If the item contains a single value, the array has just one element.

Usage

For text, number, and time-date items, GetItemValue always returns an array, even when there is only a single value in the item. If you know the item contains only a single value, access the first element in the array, which is at index 0. If you know the item contains multiple values, but you don't know how many, iterate over the array elements using the Forall statement.

"Extended class" syntax

You can also access the contents of an item directly, without using GetItemValue. The following two statements are equivalent:

t = lastDoc.GetItemValue( "Topic" )

t = lastDoc.Topic

This syntax lets you access and modify items the same way you access and modify other NotesDocument properties. The return value is the same, that is, an array of values for text, number, or time-date items, and a string for rich text items.

You can set the value of an item with this syntax, too:

mailMemo.Subject = "Update on stock options"

Call mailMemo.Save( False, True )

For more information about setting an item value with this syntax, see the AppendItemValue and ReplaceItemValue methods.

See examples
Examples: GetItemValue method

See also
AppendItemValue method
GetFirstItem method
Getting an item and its values
HasItem method
ReplaceItemValue method
Values property (in NotesItem)


HasItem method

Given the name of an item, indicates if that item exists on the document.

Defined in

NotesDocument

Syntax

flag = notesDocument.HasItem( itemName$ )

Parameter

itemName$

String. The name of an item.

Return value

  • True indicates that an item with itemName$ exists in the document

  • False indicates that there is no item with itemName$ in the document

See examples
Examples: HasItem method

See also
AppendItemValue method
CopyAllItems method
CopyItem method
GetFirstItem method
GetItemValue method
NotesItem class
RemoveItem method
ReplaceItemValue method


MakeResponse method

Makes one document a response to another document. The two documents must be in the same database.

Defined in

NotesDocument

Syntax

Call notesDocument1.MakeResponse( notesDocument2 )

Parameter

notesDocument2

The document to which notesDocument1 becomes a response. If you specify Nothing, this method will generate an error.

Usage

You must call Save after this method if you want to save the change you have made.

See examples
Example: MakeResponse method

See also
Locating documents within a view or folder
IsResponse property
Save method


PutInFolder method

Adds a document to the specified folder. If the folder does not exist in the document's database, it is created.

Defined in

NotesDocument

Syntax

Call notesDocument.PutInFolder( folderName$ [, createonfail ] )

Parameter

folderName$

String. The name of the folder in which to place the document. The folder may be personal if the script is running on the workstation. If the folder is within another folder, specify a path to it, separating folder names with backward slashes, for example, "Vehicles\Bikes".

createonfail

Boolean. Optional. Specify True so that a folder will be created if it does not exist.

Usage

If the document is already inside the folder you specify, PutInFolder does nothing. If you specify a path to a folder, and none of the folders exists, the method creates all of them for you. For example:

Call doc.PutInFolder( Vehicles\Bikes )

If neither Vehicles nor Bikes exists, PutInFolder creates both, placing the Bikes folder inside the Vehicles folder.

This method cannot add the first document to a folder that is "Shared, Personal on first use."

See examples
Examples: PutInFolder method

See also
Locating documents within a view or folder
RemoveFromFolder Method


Remove method

Permanently deletes a document from a database.

Defined in

NotesDocument

Syntax

flag = notesDocument.Remove( force )

Parameter

force

Boolean. If True, the document is deleted even if another user modifies the document after the script opens it. If False, the document is not deleted if another user modifies it.

Return value

  • True indicates that the document was successfully deleted

  • False indicates that the document was not deleted, because another user modified it and the force parameter is set to False

Usage

If you access a NotesDocument object through the Document property of NotesUIDocument, you can't delete the back-end document. If you could, the UI rendition would have no basis. You must access the document strictly through the back-end.

A deleted document cannot be used as a basis for navigation in a view or a document collection.

See examples
Examples: Remove method

See also
Removing a document
RemoveAll method (in NotesDocumentCollection)


RemoveFromFolder method

Removes a document from the specified folder.

Defined in

NotesDocument

Syntax

Call notesDocument.RemoveFromFolder( folderName$ )

Parameter

folderName$

String. The name of the folder from which to remove the document. The folder may be personal if the script is running on a workstation. If the folder is within another folder, specify a path to it, separating folder names with backward slashes, for example, "Vehicles\Bikes".

Usage

The method does nothing if the document is not in the folder you specify, or if the folder you specify does not exist.

See examples
Examples: RemoveFromFolder method

See also
Locating documents within a view or folder
PutInFolder method


RemoveItem method

Given the name of an item, deletes the item from a document.

Defined in

NotesDocument

Syntax

Call notesDocument.RemoveItem( itemName$ )

Parameter

itemName$

String. The name of the item to delete from the document. If more than one item has itemName$, all items with this name are deleted. If there is no item with itemName$, the method does nothing.

Usage

You can achieve the same result with the Remove method in the NotesItem class.

Remember to call Save to save your changes to a document.

See examples
Examples: RemoveItem method

See also
CopyAllItems method
CopyItem method
GetFirstItem method
HasItem method
NotesItem class
Remove method (in NotesItem)
Removing an item


RenderToRTItem method

Creates a picture of a document and places it into a rich text item you specify. The picture is created using both the document and its form, Therefore, the form's input translation and validation formulas are executed.

Defined in

NotesDocument

Syntax

flag = notesDocument.RenderToRTItem( notesRichTextItem )

Parameter

notesRichTextItem

The destination for the picture. If you specify Nothing, this method will generate an error.

Return value

flag

Boolean. If True, the method was successful. If False, the method was not successful and the rich text item remains unchanged. This can happen if an input validation formula fails on the document's form.

See examples
Example: RenderToRTItem method

See also
NotesRichTextItem class


ReplaceItemValue method

Replaces all items of the specified name with one new item, which is assigned the specified value. If the document does not contain an item with the specified name, the method creates a new item and adds it to the document.

Defined in

NotesDocument

Syntax

Set notesItem = notesDocument.ReplaceItemValue( itemName$, value )

Parameters

itemName$

String. The name of the item(s) you want to replace.

value

The value of the new item. The data type of the item depends upon the data type of value, and does not need to match the data type of the old item.

Note ReplaceItemValue method will take the NotesDateTime object as input directly.

Data type of value | Resulting notesItem
String | Text item containing value
Array of strings | Text item containing each element of value
Integer | Number item containing value
Array of integers | Number item containing each element of value
Variant of type DATE | Date-time item containing value
Array of variants, where each variant is of type DATE | Date-time item containing each element of value
NotesDateTime | Date-time item containing the date-time represented by the object
NotesItem | Item whose data type matches the NotesItem type and whose value(s) match the NotesItem value(s)

Return value

notesItem

The new item, which replaces all previous items that had itemName$. The new item has a new value, which may be of a different data type than the old item.

Usage

The IsSummary property of the item defaults to False, which means that the item value cannot be displayed in a view or folder. You must explicitly set IsSummary to True if you want the value to be displayed in a view or folder.

"Extended class" syntax

You can also change an item's value using the NotesDocument "extended class" syntax, which eliminates the need for ReplaceItemValue. For example, you have the following script:

Dim item As NotesItem

Set item = doc.ReplaceItemValue _

( "Subject", "Update on stock options" )

Call doc.Save( False, True )

You can achieve the same result by doing the following:

doc.Subject = "Update on stock options"

Call doc.Save( False, True )

This syntax lets you treat NotesDocument as an "extended class" by using an item name as if it were a property of NotesDocument. In the example above, "Subject" is used as if it is a property of the NotesDocument class. The result is the same as if you used ReplaceItemValue, except that ReplaceItemValue returns a NotesItem object representing the item you just created, and the IsSummary property defaults to True.

See examples
Examples: ReplaceItemValue method

See also
AppendItemValue Method
Creating an item and assigning values
GetItemValue method
NotesItem Class


Save method

Saves any changes you have made to a document.

Defined in

NotesDocument

Syntax

flag = notesDocument.Save( force, createResponse [ , markRead ])

Parameters

force

Boolean. If True, the document is saved even if someone else edits and saves the document while the script is running. The last version of the document that was saved wins; the earlier version is discarded.

If False, and someone else edits the document while the script is running, the createResponse argument determines what happens.

createResponse

Boolean. If True, the current document becomes a response to the original document (this is what the replicator does when there's a replication conflict). If False, the save is canceled. If the force parameter is True, the createResponse parameter has no effect.

markRead

Boolean. If True, the document is marked as read. If False (default), the document is not marked as read.

Return value

  • True indicates that the document was successfully saved

  • False indicates that the document was not saved

See examples
Examples: Save method

See also
Copying an item
Creating an item and assigning values
Locating documents within a view or folder
Mailing a document
Refreshing a view or folder
Removing an item


Send method

Mails a document to the recipients you specify.

Defined in

NotesDocument

Syntax

Call notesDocument.Send( attachForm [, recipients ] )

Parameters

attachForm

Boolean. If True, the form is stored and sent along with the document. If False, it isn't.

recipients

String or array of strings. Optional. The recipients of the document, which may include people, groups, or mail-in databases.

Usage

If you have only Reader access to a database, you can run a LotusScript agent that creates and sends a document, but the agent will not work if you attach a file to that document.

There are two kinds of items that can affect the mailing of the document when you use Send:

  • If the document contains additional recipient items, such as CopyTo or BlindCopyTo, Notes mails the documents to these recipients.

  • If the document contains items to control the routing of mail, such as DeliveryPriority, DeliveryReport, or ReturnReceipt, Notes uses these when sending the document.

Sending the form increases the size of the document, but insures that the recipient can see all of the items on the document.

The Send method automatically creates an item called $AssistMail on the sent document. The SentByAgent property uses this item to determine if a document was mailed by a script.

If a script runs on a workstation, the mailed document contains the current user name in the From item. If a script is a scheduled agent running on a server, the mailed document contains the agent signer's name in the From item.

See examples
Examples: Send method

See also
EncryptOnSend property
Mailing a document
Making a Domino newsletter
SaveMessageOnSend property
SentByAgent property
SignOnSend property


Sign method

Signs a document.

Defined in

NotesDocument

Syntax

Call notesDocument.Sign

Usage

If you want the signature to be saved, you must call the Save method after signing the document.

If the script is running on a server, this method has no effect.

See examples
Example: Sign method

See also
IsSigned property
Mailing a document
Signer property
SignOnSend property
Verifier property


NotesDocumentCollection class

Represents a collection of documents from a database, selected according to specific criteria.

Containment

Contained by: NotesDatabase, NotesSession , NotesUIDatabase, NotesUIView

Contains: NotesDocument

Properties

Count

IsSorted

Parent

Query

Methods

AddDocument

DeleteDocument

FTSearch

GetDocument

GetFirstDocument

GetLastDocument

GetNextDocument

GetNthDocument

GetPrevDocument

PutAllInFolder

RemoveAll

RemoveAllFromFolder

StampAll

UpdateAll

Access

A NotesDocumentCollection represents a subset of all the documents in a database. The documents in the subset are determined by the NotesDatabase method or property you use to search the database, which can be any of the following:

  • AllDocuments property

  • UnprocessedDocuments property

  • Search method

  • UnprocessedSearch method

  • FTSearch method

  • UnprocessedFTSearch method

The Responses property in NotesDocument also returns a NotesDocumentCollection.

Usage

Both NotesDocumentCollection and NotesView objects provide access to documents within a database. Use a NotesDocumentCollection object if:

  • You want to act on a specific set of documents that meet certain criteria.

  • There is no view in the database that contains every document you need to search.

  • You do not need to navigate the documents' response hierarchies.

Views are a more efficient means of accessing documents because they are already indexed by the database itself. However, they do not necessarily provide access to the documents that you want.

Ordering of documents

The documents in a collection are ordered when the collection results from a full-text search; otherwise, the documents are unordered.

Current pointer

A current pointer is maintained for document collections. All navigation methods set the current pointer to the retrieved document with the following exceptions. Add and delete methods do not move the current pointer. The following methods set the current pointer to the first document: FTSearch, RemoveAll (remote IIOP only), PutAllInFolder, RemoveAllFromFolder, and StampAll.

Deletion stubs

A deletion stub is returned for a document deleted after creation of the collection or for a document to which you do not have read access. Use IsValid in NotesDocument to check whether a document is real (True) or a deletion stub (False).

See examples
Examples: NotesDocumentCollection class

See also
Collecting all documents and unprocessed documents
Using the Domino classes


Count property

Read-only. The number of documents in a collection.

Defined in

NotesDocumentCollection

Data type

Long

Syntax

To get: numDocs& = notesDocumentCollection.Count

See examples
Examples: Count property

See also
GetNthDocument method


IsSorted property

Read-only. Indicates if the documents in a collection are sorted. A collection is sorted only when it results from a full-text search of a database.

Defined in

NotesDocumentCollection

Data type

Boolean

Syntax

To get: flag = notesDocumentCollection.IsSorted

Legal values

  • True indicates that the documents in the collection are sorted

  • False indicates that the documents in the collection are not sorted

Usage

When a collection is sorted, the documents are sorted by relevance score with the most-relevant document appearing first. A relevance score is a number assigned to each document that matches a particular full-text search query. The number is related to the number of matches that were found in the document.

See examples
Example: IsSorted property

See also
FTSearch method (in NotesDatabase)
FTSearchScore property (in NotesDocument)
UnprocessedFTSearch method (in NotesDatabase)


Parent property

Read-only. The database that contains a document collection.

Defined in

NotesDocumentCollection

Data type

NotesDatabase

Syntax

To get: Set notesDatabase = notesDocumentCollection.Parent

See examples
Example: Parent property


Query property

Read-only. The text of the query that produced a document collection, if the collection results from a full-text or other search.

Defined in

NotesDocumentCollection

Data type

String

Syntax

To get: query$ = notesDocumentCollection.Query

Usage

For collections produced without a search (for example, using the AllDocuments property in NotesDatabase), this property returns an empty string ("").

See examples
Examples: Query property

See also
FTSearch method (in NotesDatabase)
Search method (in NotesDatabase)


AddDocument method

Adds a document to a document collection.

Note This method is new with Release 5.

Defined in

NotesDocumentCollection

Syntax

Call notesDocumentCollection.AddDocument(document [ , checkDups ] )

Parameter

document

The document to be added. If you specify Nothing, this method generates an error.

checkDups

Note This parameter is for COM only. It is not implemented currently.

Boolean. Optional. Checks for duplicate documents. If True, checks for duplicate documents. Defaults to False.

Usage

For sorted collections, the document will be appended. For unsorted collections, the document will be inserted using an internal algorithm. Sorted collections include all ViewEntryCollections and DocumentCollections created from FTSearch (including DocumentCollections modified by calling the FTSearch method on the collection). All other DocumentCollections are unsorted.

See examples
Example: AddDocument method


DeleteDocument method

Deletes a document from a collection (not from the disk).

Note This method is new with Release 5.

Defined in

NotesDocumentCollection

Syntax

Call notesDocumentCollection.DeleteDocument(notesdocument)

Parameter

notesdocument

The document to be deleted. If you specify Nothing, this method will generate an error.

Usage

The specified document must have originated in this collection. If the document does not exist in the collection, or if it was removed from the database by a RemoveAll operation, an error will be raised.

See examples
Example: DeleteDocument method


FTSearch method

Conducts a full-text search of all the documents in a Notes database collection, and reduces the collection to those documents that match.

Defined in

NotesDocumentCollection

Syntax

Call notesDocumentCollection.FTSearch( query$, maxDocs% )

Parameters

query$

String. The full-text query. See below for the syntax.

maxDocs%

Integer. The maximum number of documents you want returned from the query. Set this parameter to 0 to receive all matching documents.

Usage

This method moves the current pointer to the first document in the collection.

The collection of documents that match the full-text query are sorted by relevance with highest relevance first. You can access the relevance score of each document in the collection using the FTSearchScore property in NotesDocument.

If the database is not full-text indexed, this method works, but less efficiently. To test for an index, use the IsFTIndexed property in NotesDatabase. To create an index on a local database, use the UpdateFTIndex method.

This method searches all of the documents in a document collection. To search all of the documents in a database, use the FTSearch method in NotesDatabase. To search only documents found in a particular view, use the FTSearch method in NotesView or FTSearch method in NotesViewEntryCollection.

Query syntax

To search for a word or phrase, enter the word or phrase as is, except that search keywords must be enclosed in quotes. Remember to escape quotes if you are inside a literal.

Wildcards, operators, and other syntax are permitted. For the complete syntax rules, see the topic "To use operators to refine a search" in Notes 5 help.

See examples
Example: FTSearch method

See also
Collecting documents by searching
FTSearch method (in NotesDatabase)
FTSearch method (in NotesView)
FTSearchScore property (in NotesDocument)
IsFTIndexed property
LastFTIndexed property
UnprocessedFTSearch method
UpdateFTIndex method


GetDocument method

Returns the entry in the collection that corresponds to the specified document.

Note This method is new with Release 5.

Defined in

NotesDocumentCollection

Syntax

Set notesDocument = notesDocumentCollection.GetDocument( notesDocument )

Parameter

notesDocument

Any document in the collection. If you specify Nothing, this method will generate an error.

Return value

notesDocument

The document that matches the notesDocument parameter. If the specified document doesn't exist, returns Nothing.

See examples
Examples: GetDocument method


GetFirstDocument method

Gets the first document in a collection.

Defined in

NotesDocumentCollection

Syntax

Set notesDocument = notesDocumentCollection.GetFirstDocument

Return value

notesDocument

The first document in the collection. If there are no documents in the collection, returns Nothing.

See examples
Example: GetFirstDocument method

See also
Collecting all documents and unprocessed documents
GetLastDocument method
GetNextDocument method
GetNthDocument method
GetPrevDocument method
NotesDocument class


GetLastDocument method

Gets the last document in a collection.

Defined in

NotesDocumentCollection

Syntax

Set notesDocument = notesDocumentCollection.GetLastDocument

Return value

notesDocument

The last document in the collection. If there are no documents in the collection, returns Nothing.

See examples
Example: GetLastDocument method

See also
Collecting all documents and unprocessed documents
GetFirstDocument method
GetNextDocument method
GetPrevDocument method
GetNthDocument method
NotesDocument class


GetNextDocument method

Given a document, finds the document immediately following it in a collection.

Defined in

NotesDocumentCollection

Syntax

Set notesDocument = notesDocumentCollection.GetNextDocument( notesDocument )

Parameter

notesDocument

Any document in the collection. If you specify Nothing, this method will generate an error.

Return value

notesDocument

The document following the notesDocument parameter in the collection. If there is no next document, returns Nothing.

See examples
Example: GetNextDocument method

See also
Collecting all documents and unprocessed documents
GetFirstDocument method
GetLastDocument method
GetNthDocument method
GetPrevDocument method
NotesDocument class


GetNthDocument method

Given a position number, returns the document at that position in a collection.

Defined in

NotesDocumentCollection

Syntax

Set notesDocument = notesDocumentCollection.GetNthDocument( n% )

Parameter

n%

Integer. A number indicating the document to return. Use 1 to indicate the first document in the collection, 2 to indicate the second document, and so on.

Return value

notesDocument

The document in the nth position in the collection. If there is no document at the specified position, returns Nothing.

Usage

This method is most efficient for collections you generate from a full-text search. For collections that you generate from other search methods in the NotesDatabase class, GetFirstDocument and GetNextDocument are more efficient.

See examples
Examples: GetNthDocument method

See also
Collecting all documents and unprocessed documents
GetFirstDocument method
GetLastDocument method
GetNextDocument method
GetPrevDocument method
NotesDocument class


GetPrevDocument method

Given a document, finds the document immediately preceding it in a collection.

Defined in

NotesDocumentCollection

Syntax

Set notesDocument = notesDocumentCollection.GetPrevDocument( notesDocument )

Parameter

notesDocument

Any document in the collection. If you specify Nothing, this method will generate an error.

Return value

notesDocument

The document preceding the notesDocument parameter in the collection. If there is no previous document, returns Nothing.

See examples
Example: GetPrevDocument method

See also
Collecting all documents and unprocessed documents
GetFirstDocument method
GetLastDocument method
GetNextDocument method
GetNthDocument method
NotesDocument class


PutAllInFolder method

Adds all the documents in the collection to the specified folder. If the folder does not exist in the document's database, it is created.

Defined in

NotesDocumentCollection

Syntax

Call notesDocumentCollection.PutAllInFolder( folderName$ [, createonfail ] )

Parameter

folderName$

String. The name of the folder in which to place the documents. The folder may be personal if the script is running on the workstation. If the folder is within another folder, specify a path to it, separating folder names with backward slashes, for example, "Vehicles\Bikes".

createonfail

Note This parameter is new with Release 5.

Boolean. Optional. If True (default), creates the folder if one does not already exist.

Usage

If a document is already inside the folder you specify, PutAllInFolder does nothing for that document. If you specify a path to a folder, and none of the folders exist, the method creates all of them for you. For example:

Call doc.PutAllInFolder( Vehicles\Bikes )

If neither Vehicles nor Bikes exists, PutAllInFolder creates both, placing the Bikes folder inside the Vehicles folder.

See examples
Example: PutAllInFolder method

See also
Locating documents within a view or folder
RemoveAllFromFolder method
PutInFolder method
RemoveFromFolder method


RemoveAll method

Permanently deletes all documents in a collection from a database.

Defined in

NotesDocumentCollection

Syntax

Call notesDocumentCollection.RemoveAll( force )

Parameters

force

Boolean. If True, the collection will be empty. If False, there may be documents remaining in the collection after the RemoveAll executes.

See examples
Example: RemoveAll method

See also
Removing a document
Remove method (in NotesDocument)


RemoveAllFromFolder method

Removes all documents in the collection from the specified folder.

Defined in

NotesDocumentCollection

Syntax

Call notesDocumentCollection.RemoveAllFromFolder( folderName$ )

Parameters

folderName$

String. The name of the folder from which to remove the document. The folder may be personal if the script is running on a workstation. If the folder is within another folder, specify a path to it, separating folder names with backward slashes, for example, "Vehicles\Bikes".

Usage

The method does nothing for documents not in the folder you specify. This method does nothing if the folder you specify does not exist.

See examples
Example: RemoveAllFromFolder method

See also
Locating documents within a view or folder
PutAllInFolder method
PutInFolder method
RemoveFromFolder method


StampAll method

Replaces the value of a specified name in all documents in a collection.

Defined in

NotesDocumentCollection

Syntax

Call notesDocumentCollection.StampAll( itemname , value )

Parameters

itemname

String. The name of the item.

value

A value appropriate for the item type.

Usage

If the item does not exist, it is created.

The item values are immediately written to the back-end documents. You do not have to use the Save method of NotesDocument after StampAll. However, any documents modified by your script must be saved before calling StampAll.

This method does not modify existing NotesDocument objects. Documents must be retrieved again to see the changes.

See examples
Example: StampAll method

See also
Creating an item and assigning values
Savel method


UpdateAll method

Marks all documents in a collection as processed by an agent.

Defined in

NotesDocumentCollection

Syntax

Call notesDocumentCollection.UpdateAll

Usage

See the UpdateProcessedDoc method in NotesSession for a description of the update process.

See examples
Example: UpdateAll method

See also
Collecting all documents and unprocessed documents
NotesDocument class
UnprocessedDocuments property (in NotesDatabase)
UnprocessedFTSearch method (in NotesDatabase)
UnprocessedSearch method (in NotesDatabase)
UpdateProcessedDoc method (in NotesSession)


NotesEmbeddedObject class

Represents any one of the following:

  • An embedded object

  • An object link

  • A file attachment

Some methods and properties that are available for embedded and linked objects are unavailable for file attachments.

Containment

Contained by: NotesDocument and NotesRichTextItem

Properties

Class

FileSize

FitBelowFields

FitToWindow

Name

Object

Parent

RunReadOnly

Source

Type

Verbs

Methods

Activate

DoVerb

ExtractFile

Remove

Creation

To create a new object, object link, or file attachment, use the EmbedObject method in NotesRichTextItem.

Access

There are several ways to access an existing object, object link, or file attachment:

  • To access an object, object link, or attachment when you know its name and the rich text item that contains it, use GetEmbeddedObject in NotesRichTextItem.

  • To access all the objects, object links, and attachments in a particular rich text item, use EmbeddedObjects in NotesRichTextItem.

  • To access the objects and object links in a particular document, including those that are not contained within a particular rich text item, use EmbeddedObjects in NotesDocument. This property does not return file attachments or objects and object links created in Notes Release 3.

See examples
Examples: NotesEmbeddedObject class

See also
Using the Domino classes
Working with an embedded object


Class property

Read-only. The name of the application which created an object.

Defined in

NotesEmbeddedObject

Data type

String

Syntax

To get: className$ = notesEmbeddedObject.Class

Usage

For file attachments, this property returns an empty string ("").

See examples
Example: Class property

See also
Name property
Source property
Type property


FileSize property

Read-only. The size of a file attachment, in bytes.

Defined in

NotesEmbeddedObject

Data type

Long

Syntax

To get: size& = notesEmbeddedObject.FileSize

Usage

Returns 0 for embedded objects and links.

See examples
Example: FileSize property


FitBelowFields property

Read-Write. Sizes the embedded object to fit below the first layout in the document. The embedded object takes over the entire document window below the layout, when activated.

Note This property is new with Release 4.6.2.

Defined in

NotesEmbeddedObject

Data type

Boolean

Syntax

To get: flag = notesEmbeddedObject.FitBelowFields

To set: notesEmbeddedObject.FitBelowFields = flag

Legal values

  • True indicates that the embedded object will take over the document window after first layout when activated.

  • False indicates the default. Normal in-place activation

Usage

This property can only be set when the embedded object is an OLE control (ActiveX control or OCX).

UI behavior of the embedded object is the same as if it did not have FitBelowFields set.

If the embedded object supports ActiveX document (DocObject) and has requested this behavior from Notes, Notes will only honor this request if FitToWindow or FitBelowField is set. Since controls are run when a document is opened in Edit mode (and in read-only mode if RunReadOnly is set), the object immediately takes over the window below the layout.

Because of the results of this property, it is suggested that the document have only one object and it should have this property set. An embedded object can not have both this property and the FitToWindow property set. The layout region and object behave in tandem, moving and sizing together, always keeping the same relative positions. The automatic scrolling of the layout region when the window is sized to be smaller than the layout has been disabled/removed for this relationship.


FitToWindow property

Read-Write. Sizes the embedded object to fit the document window. The embedded object takes over the entire document window when activated.

Note This property is new with Release 4.6.2.

Defined in

NotesEmbeddedObject

Data type

Boolean

Syntax

To get: flag = notesEmbeddedObject.FitToWindow

To set: notesEmbeddedObject.FitToWindow = flag

Legal values

  • True indicates that the embedded object will take over the document window when activated.

  • False indicates the default. Normal in-place activation.

Usage

Available when the embedded object is an OLE embedded object or an OLE control (ActiveX control or OCX).

UI behavior of the embedded object is the same as if it did not have FitToWindow set.

If the embedded object supports ActiveX document (DocObject) and has requested this behavior from Notes, Notes will only honor this request if FitToWindow or FitBelowFields is set. Since controls are run when a document is opened in Edit mode (and in read-only mode if RunReadOnly is set), the object immediately takes over the window. OLE embedded objects take over the window when they are UI activated. As a result of the activation, any other objects or Notes fields will be hidden/painted over/wiped out.

Because of the results of this property, it is suggested that the document have only one object and it should have this property set. An embedded object can not have both this property and the FitBelowFields property set.


Name property

Read-only. The name used to reference an embedded object or object link.

Defined in

NotesEmbeddedObject

Data type

String

Syntax

To get: name$ = notesEmbeddedObject.Name

Usage

For file attachments, this property returns an empty string (""). If the embedded object or object link does not have a name, this property returns an empty string ("").

If the embedded object or object link was created using the EmbedObject method in NotesRichTextItem, this property returns the name$ parameter that was used with EmbedObject.

For an unnamed object as shown below,

Set object = rtitem.EmbedObject ( EMBED_OBJECT, "", _

   "c:\notes\data\sample.bmp", "" )

Print object.Name

The printed result is "Bitmap Image", which corresponds to the Registry default name.

If the embedded object or object link was created using the Notes user interface, this property returns the name of the object as it appears in the Properties box.

See examples
Example: Name property

See also
EmbedObject method


Object property

Read-only. If an embedded object has been loaded into memory, returns the OLE handle (IDispatch handle). If the OLE object supports OLE Automation, you can invoke the methods and properties of the object using the handle.

Defined in

NotesEmbeddedObject

Data type

Variant

Syntax

To get: Set handleV = notesEmbeddedObject.Object

Usage

This property may or may not return a valid OLE handle for object links, depending upon the application used to create the object link.

See also
Activate method


Parent property

Read-only. The rich text item that holds an object.

Defined in

NotesEmbeddedObject

Data type

NotesRichTextItem

Syntax

To get: Set notesRichTextItem = notesEmbeddedObject.Parent

Usage

When you get an embedded object from a document, it does not contain a RichTextItem parent. Calling the Parent property on such an embedded object will return Nothing.


RunReadOnly property

Read-Write. Runs the embedded object when reading the document.

Note This property is new with R4.6.2.

Defined in

NotesEmbeddedObject

Data type

Boolean

Syntax

To get: flag = notesEmbeddedObject.RunReadOnly

To set: notesEmbeddedObject.RunReadOnly = flag

Legal values

  • True indicates that the control runs when the document is in Read-only mode.

  • False indicates the default. Does not run the control when the document is in Read-only mode.

Usage

This property can only be set when the embedded object is an OLE control (ActiveX control or OCX).

The control is in-place activated (but not UI activated) when the document is in Read-only mode.

Any control with this property set may allow editing during Read-only mode, but no changes are saved.

This property is not applicable to embedded OLE objects since they can be activated in Read-only mode without changes being saved.


Source property

Read-only.

  • If the NotesEmbeddedObject is an embedded object or object link, this property returns the internal name that Notes uses to refer to the source document.

  • If the NotesEmbeddedObject is a file attachment, this property returns the file name of the original file.

Defined in

NotesEmbeddedObject

Data type

String

Syntax

To get: source$ = notesEmbeddedObject.Source

Usage

If the NotesEmbeddedObject is a file attachment returned from the EmbedObject method in NotesRichTextItem, the Source property returns the full path and file name of the attachment. If the NotesEmbeddedObject is a file attachment obtained from another property or method, the Source property returns only the file name of the attachment.

See examples
Example: Source property

See also
Class property
EmbedObject method (in NotesRichTextItem)
Name property
Type property


Type property

Read-only. Indicates if a NotesEmbeddedObject is an embedded object, an object link, or a file attachment.

Defined in

NotesEmbeddedObject

Data type

Constant of type Integer

Syntax

To get: type% = notesEmbeddedObject.Type

Return Values

  • EMBED_ATTACHMENT (1454)

  • EMBED_OBJECT (1453)

  • EMBED_OBJECTLINK (1452)

Note The above constants are also used with the EmbedObject method in the NotesRichTextItem class.

See examples
Example: Type property

See also
Class property
Name property
Source property


Verbs property

Read-only. The verbs that an object supports, if the object is an OLE/2 embedded object.

Defined in

NotesEmbeddedObject

Data type

Array of strings

Syntax

To get: stringArray = notesEmbeddedObject.Verbs

Usage

To invoke a verb on an object, use the DoVerb method.

For an embedded object of type Attachment, Domino/Notes generates the following error:

Error 4246: No embedded object is present, cannot perform this action.

See examples
Example: Verbs property

See also
DoVerb method


Activate method

Causes an embedded object or object link to be loaded by OLE.

Defined in

NotesEmbeddedObject

Syntax

Set handleV = notesEmbeddedObject.Activate( show )

Parameter

show

Boolean. If True, the server application displays its user interface. If False, the server application hides its user interface.

Return value

handleV

Variant. The OLE handle to the object. Returns Nothing if the embedded object or object link does not support OLE automation.

Usage

Scripts running on a server must set the show parameter to False.

This method raises an error if you invoke it on a NotesEmbeddedObject that is a file attachment.

This method may or may not return a valid OLE handle for object links, depending upon the application used to create the object link.

See examples
Examples: Activate method

See also
Object property


DoVerb method

Given the name of a verb, executes the verb in an embedded object.

Note This method is treated as a Sub in COM.

Defined in

NotesEmbeddedObject

Syntax

variant = notesEmbeddedObject.DoVerb( verb$ )

Parameter

verb$

String. The name of one of the object's verbs.

Return value

variant

Variant. Always empty.

See also
Verbs property


ExtractFile method

Copies a file attachment to disk.

Defined in

NotesEmbeddedObject

Syntax

Call notesEmbeddedObject.ExtractFile( path$ )

Parameter

path$

String. The path and file name where you want to store the extracted file on disk.

Usage

For embedded objects and object links, this method raises an error.

See examples
Example: ExtractFile method

See also
FileSize property
GetAttachment method (in NotesDocument)
Remove method


Remove method

Permanently deletes an embedded object, object link, or file attachment.

Defined in

NotesEmbeddedObject

Syntax

Call notesEmbeddedObject.Remove

Usage

After calling the Remove method, you must call the Save method in NotesDocument to save the change that you made.

See examples
Example: Remove method

See also
Save method (in NotesDocument)


NotesForm class

Represents a form in a database.

Containment

Contained by: NotesDatabase

Properties

Aliases

Fields

FormUsers

HttpURL

IsSubForm

Name

NotesURL

Parent

ProtectReaders

ProtectUsers

Readers

Methods

Remove

Access

There are two ways to access a form:

  • To get all the forms in a database, use the Forms property in NotesDatabase.

  • To get a form by its name, use the GetForm method in NotesDatabase.

You can't get access to private forms belonging to other people.

See examples
Example: NotesForm class

See also
Accessing a form
Using the Domino classes


Aliases property

Read-only. The aliases of a form.

Defined in

NotesForm

Data type

Array of strings

Syntax

To get: stringArray = notesForm.Aliases

Usage

When you use GetForm, this property returns all but the first in the list of all the form's names. The Names property returns the first name in the list.

IsEmpty is True for this property if the form has no aliases.

See examples
Example: Aliases property

See also
Accessing a form
Name property


Fields property

Read-only. The names of all the fields of a form.

Defined in

NotesForm

Data type

Array of strings

Syntax

To get: stringArray = notesForm.Fields

See examples
Example: Fields property

See also
Accessing a form


FormUsers property

Read-write. The contents of the $FormUsers field. When you create a form and specify who can create the documents, those names are stored in the $FormUsers field.

Defined in

NotesForm

Data type

Array of strings

Syntax

To get: stringArray = notesForm.FormUsers

To set: notesForm.FormUsers = stringArray

Usage

This property accepts an array of strings or a single string. Setting this property replaces prior values.

See examples
Examples: FormUsers property

See also
Accessing a form
ProtectUsers property


HttpURL property

Read-only. The HTTP URL of a form.

Note This property is new with Release 5.0.2b.

Note This property is supported in COM only.

Defined in

NotesForm

Data type

String

Syntax

To get: url$ = notesForm.HttpURL


IsSubForm property

Read-only. Indicates if form is a subform.

Defined in

NotesForm

Data type

Boolean

Syntax

To get: flag = notesForm.IsSubForm

Legal values

  • True indicates that the document is a subform

  • False indicates that the document is not a subform

See examples
Example: IsSubForm property

See also
Accessing a form


Name property

Read-only. The name of a form.

Defined in

NotesForm

Data type

String

Syntax

To get: string = notesForm.Name

Usage

This property returns the first name associated with a form. Use the Aliases property to return any additional names.

See examples
Example: Name property

See also
Accessing a form
Aliases Property


NotesURL property

Read-only. The Notes URL of a form.

Note This property is new with Release 5.0.2b.

Note This property is supported in COM only.

Defined in

NotesForm

Data type

String

Syntax

To get: url$ = notesForm.NotesURL


Parent property

Read-only. The database that contains a Form object.

Note This property is new with Release 5.0.2b.

Note This property is supported in COM only.

Defined in

NotesForm

Data type

NotesDatabase

Syntax

To get: Set notesDatabase = notesForm.Parent

See examples
Examples: Parent property


ProtectReaders property

Read-Write. Protects $Readers items from being overwritten by replication.

Defined in

NotesForm

Data type

Boolean

Syntax

To get: flag = notesForm.ProtectReaders

To set: notesForm.ProtectReaders = flag

Legal values

  • True indicates that the items are protected

  • False indicates that the items are not protected

See examples
Example: ProtectReaders property

See also
Accessing a form
Readers property


ProtectUsers property

Read-Write. Protects $FormUsers items from being overwritten by replication.

Defined in

NotesForm

Data type

Boolean

Syntax

To get: flag = notesForm.ProtectUsers

To set: notesForm.ProtectUsers = flag

Legal values

  • True indicates that the items are protected

  • False indicates that the items are not protected

See examples
Example: ProtectUsers property

See also
Accessing a form
FormUsers property


Readers property

Read-Write. The contents of the $Readers field.

Defined in

NotesForm

Data type

Array of strings

Syntax

To get: stringArray = notesForm.Readers

To set: notesForm.Readers = stringArray

Usage

This property accepts an array of strings or a single string. Setting this property replaces prior values.

See examples
Examples: Readers property

See also
Accessing a form
ProtectReaders property


Remove method

Permanently deletes a form from a database.

Defined in

NotesForm

Syntax

Call notesForm.Remove

See examples
Example: Remove method

See also
Accessing a form


NotesInternational class

Represents the international settings in the operating environment, for example, the Windows Control Panel international settings. When any of these settings is changed in the operating environment, Domino recognizes the new settings immediately.

Containment

Contained by: NotesSession

Properties

AMString

CurrencyDigits

CurrencySymbol

DateSep

DecimalSep

IsCurrencySpace

IsCurrencySuffix

IsCurrencyZero

IsDateDMY

IsDateMDY

IsDateYMD

IsDST

IsTime24Hour

Parent

PMString

ThousandsSep

TimeSep

TimeZone

Today

Tomorrow

Yesterday

Access

Access a NotesInternational object for the current session through the International property of NotesSession.

See examples
Example: NotesInternational class

See also
Accessing international settings
Using the Domino classes


AMString property

Read-only. The string that denotes AM time, for example, "AM" in English.

Defined in

NotesInternational

Data type

String

Syntax

To get: string = notesInternational.AMString

See examples
Example: AMString property

See also
Accessing international settings
IsTime24Hour property
PMString property
TimeSep property
TimeZone property


CurrencyDigits property

Read only. Indicates the number of decimal digits in number format.

Defined in

NotesInternational

Data type

Integer

Syntax

To get: flag = notesInternational.CurrencyDigits

See examples
Example: DecimalSep property

See also
Accessing international settings
DecimalSep property
IsCurrencyZero property
ThousandsSep property


CurrencySymbol property

Read-only. The symbol that indicates a number is currency, for example, the dollar sign.

Defined in

NotesInternational

Data type

String

Syntax

To get: string = notesInternational.CurrencySymbol

See examples
Example: CurrencySymbol property

See also
Accessing international settings
IsCurrencySpace property
IsCurrencySuffix property


DateSep property

Read-only. The character used to separate months, days, and years, for example, the slash.

Defined in

NotesInternational

Data type

String

Syntax

To get: string = notesInternational.DateSep

See examples
Example: DateSep property

See also
Accessing international settings
IsDateDMY property
IsDateMDY property
IsDateYMD property
IsDST property
Today property
Tomorrow property
Yesterday property


DecimalSep property

Read-only. The decimal separator in number format, for example, the decimal point.

Defined in

NotesInternational

Data type

String

Syntax

To get: string = notesInternational.DecimalSep

See examples
Example: DecimalSep property

See also
Accessing international settings
CurrencyDigits property
IsCurrencyZero property
ThousandsSep property


IsCurrencySpace property

Read-only. Indicates if the currency format has a space between the currency symbol and the number.

Defined in

NotesInternational

Data type

Boolean

Syntax

To get: flag = notesInternational.IsCurrencySpace

Legal values

  • True indicates that the currency format has a space between the currency symbol and the number

  • False indicates that the currency format does not have a space between the currency symbol and the number

Usage

Under UNIX, this property is derived from the language installed on your machine as indicated by the environment variable LANG.

See examples
Example: CurrencySymbol property

See also
Accessing international settings
CurrencySymbol property
IsCurrencySuffix property


IsCurrencySuffix property

Read-only. Indicates if the currency symbol follows the number in the currency format.

Defined in

NotesInternational

Data type

Boolean

Syntax

To get: flag = notesInternational.IsCurrencySuffix

Legal values

  • True indicates that the currency symbol follows the number

  • False indicates that the currency symbol precedes the number

See examples
Example: CurrencySymbol property

See also
Accessing international settings
CurrencySymbol property
IsCurrencySpace property


IsCurrencyZero property

Read-only. Indicates if fractions have a zero before the decimal point in number format.

Defined in

NotesInternational

Data type

Boolean

Syntax

To get: flag = notesInternational.IsCurrencyZero

Legal values

  • True indicates that fractions have a zero before the decimal point

  • False indicates that fractions do not have a zero before the decimal point

Usage

You cannot use this property on the UNIX platform.

See examples
Example: DecimalSep property

See also
Accessing international settings
CurrencyDigits property
DecimalSep property
ThousandsSep property


IsDateDMY property

Read-only. Indicates if the order of the date format is day-month-year.

Defined in

NotesInternational

Data type

Boolean

Syntax

To get: flag = notesInternational.IsDateDMY

Legal values

  • True indicates the order of the date format is day-month-year

  • False indicates the order of the date format is not day-month-year

See examples
Example: DateSep property

See also
Accessing international settings
DateSep property
IsDateMDY property
IsDateYMD property
IsDST property
Today property
Tomorrow property
Yesterday property


IsDateMDY property

Read-only. Indicates if the order of the date format is month-day-year.

Defined in

NotesInternational

Data type

Boolean

Syntax

To get: flag = notesInternational.IsDateMDY

Legal values

  • True indicates the order of the date format is month-day-year

  • False indicates the order of the date format is not month-day-year

See examples
Example: DateSep property

See also
Accessing international settings
DateSep property
IsDateDMY property
IsDateYMD property
IsDST property
Today property
Tomorrow property
Yesterday property


IsDateYMD property

Read-only. Indicates if the order of the date format is year-month-day.

Defined in

NotesInternational

Data type

Boolean

Syntax

To get: flag = notesInternational.IsDateYMD

Legal values

  • True indicates the order of the date format is year-month-day

  • False indicates the order of the date format is not year-month-day

See examples
Example: DateSep property

See also
Accessing international settings
DateSep property
IsDateDMY property
IsDateMDY property
IsDST property
Today property
Tomorrow property
Yesterday property


IsDST property

Read-only. Indicates if the time format reflects daylight savings time.

Defined in

NotesInternational

Data type

Boolean

Syntax

To get: flag = notesInternational.IsDST

Legal values

  • True indicates that the time format reflects daylight savings time

  • False indicates that the time format does not reflect daylight savings time


IsTime24Hour property

Read-only. Indicates if the time format is 24-hour.

Defined in

NotesInternational

Data type

Boolean

Syntax

To get: flag = notesInternational.IsTime24Hour

Legal values

  • True indicates that the time format is 24-hour

  • False indicates that the time format is 12-hour

See examples
Example: AMString property

See also
Accessing international settings
AMString property
PMString property
TimeSep property
TimeZone property


Parent property

Read-only. The session that contains a NotesInternational object.

Note This property is new with Release 5.0.2b.

Note This property is supported in COM only.

Defined in

NotesInternational

Data type

NotesSession

Syntax

To get: Set notesSession = notesInternational.Parent

See examples
Examples: Parent property


PMString property

Read-only. The string that denotes PM time, for example, "PM" in English.

Defined in

NotesInternational

Data type

String

Syntax

To get: string = notesInternational.PMString

See examples
Example: AMString property

See also
Accessing international settings
AMString property
IsTime24Hour property
TimeSep property
TimeZone property


ThousandsSep property

Read only. The thousands separator in number format, for example, the comma.

Defined in

NotesInternational

Data type

String

Syntax

To get: string = notesInternational.ThousandsSep

See examples
Example: DecimalSep property

See also
Accessing international settings
CurrencyDigits property
DecimalSep property
IsCurrencyZero property


TimeSep property

Read-only. The character used to separate hours, minutes, and seconds, for example, the colon.

Defined in

NotesInternational

Data type

String

Syntax

To get: string = notesInternational.TimeSep

See examples
Example: AMString property

See also
Accessing international settings
AMString property
IsTime24Hour property
PMString property
TimeZone property


TimeZone property

Read-only. An integer representing the time zone. In many cases, but not all, this integer indicates the number of hours which must be added to the time to get Greenwich Mean Time. May be positive or negative.

Defined in

NotesInternational

Data type

Integer

Syntax

To get: zone% = notesInternational.TimeZone

See examples
Example: AMString property

See also
Accessing international settings
AMString property
IsTime24Hour property
PMString property
TimeSep property


Today property

Read-only. The string that means today in a time-date specification, for example, "Today" in English.

Defined in

NotesInternational

Data type

String

Syntax

To get: string = notesInternational.Today

See examples
Example: DateSep property

See also
Accessing international settings
DateSep property
IsDateDMY property
IsDateMDY property
IsDateYMD property
IsDST property
Tomorrow property
Yesterday property


Tomorrow property

Read-only. The string that means tomorrow in a time-date specification, for example, "Tomorrow" in English.

Defined in

NotesInternational

Data type

String

Syntax

To get: string = notesInternational.Tomorrow

See examples
Example: DateSep property

See also
Accessing international settings
DateSep property
IsDateDMY property
IsDateMDY property
IsDateYMD property
IsDST property
Today property
Yesterday property


Yesterday property

Read-only. The string that means yesterday in a time-date specification, for example, "Yesterday" in English.

Defined in

NotesInternational

Data type

String

Syntax

To get: string = notesInternational.Yesterday

See examples
Example: DateSep property

See also
Accessing international settings
DateSep property
IsDateDMY property
IsDateMDY property
IsDateYMD property
IsDST property
Today property
Tomorrow property


NotesItem class

Represents a specific piece of data in a document.

In the user interface, Notes displays items in a document through fields on a form. When a field on a form and an item in a document have the same name, the field displays the item (for example, the Subject field displays the Subject item).

All of the items in a document are accessible through LotusScript, regardless of what form is used to display the document in the user interface.

Derived Classes

NotesRichTextItem inherits from NotesItem class.

Containment

Contained by: NotesDocument

Properties

DateTimeValue

IsAuthors

IsEncrypted

IsNames

IsProtected

IsReaders

IsSigned

IsSummary

LastModified

Name

Parent

SaveToDisk

Text

Type

ValueLength

Values

Methods

Abstract

AppendToTextList

Contains

CopyItemToDocument

GetMIMEEntity

New

Remove

Creation

There are two ways to create a new NotesItem object:

  • To create one from scratch, use New, or ReplaceItemValue in NotesDocument.

Note The New method is not supported in COM.

  • To create a new NotesItem object from one that already exists, use CopyItemToDocument, or CopyItem, or ReplaceItemValue in NotesDocument.

Given a document, New creates an item on the document with a name and value that you specify. The data type of the item depends on the value you give it.

You must call Save on the document if you want the modified document to be saved to disk. The document won't display the new item in the user interface unless there is a field of the same name on the form used to display the document.

Syntax

Dim variableName As New NotesItem( notesDocument, name$, value
[, specialType% ] )

or

Set notesItem = New NotesItem( notesDocument, name$, value [, specialType% ] )

Parameters

notesDocument

The document on which to create the item.

name$

String. The name of the new item.

value

The value to assign to the new item. The data type of value determines the type of item that Notes creates:

Value data type | Notes item type
String | Text (if specialType% is used, may be Names, Readers, or Authors)
Array of Strings | Text (if specialType% is used, may be Names, Readers, or Authors)
Integer, Long, Single, Double, Currency | Number
Array of Integers, Longs, Singles, Doubles, or Currencies | Number
Variant of type DATE | Time
Array of Variants of type DATE | Time

specialType%

Optional. Constant of type integer. Indicates if a text item should be of type Names, Readers, or Authors. Must be one of the following constants: NAMES, READERS, or AUTHORS. To use specialType%, the value parameter must be a string or array of strings.

Usage

When you create a NotesItem using New, the IsSummary property of the item defaults to False, which means that the item value cannot be displayed in a view or folder.

Access

There are several ways to access an existing NotesItem object.

  • To access an item when you know its name, use GetFirstItem in NotesDocument.

  • To access all the items in a document, use Items in NotesDocument.

Accessing items directly from a document

For convenience, NotesDocument has methods you can use to access items without declaring a NotesItem object. All you need to know is the name of the item:

  • To get an item's value, use GetItemValue.

  • To set an item's value, use ReplaceItemValue.

  • To check for the existence of a particular item in a document, use HasItem.

  • To delete an item from a document, use RemoveItem.

In addition, you can treat an item name as a property of a NotesDocument object. For example, the following line of script sets the value of the Subject item in a document to "Hello":

doc.Subject = "Hello"

Rich text fields

NotesRichTextItem, which inherits the properties and methods of NotesItem, has additional properties and methods you can use to manipulate a rich text item.

Saving Changes

After you create or modify an item, you must save the changes by calling the parent document's Save method.

If you don't call Save before the script finishes, all of your changes to a NotesItem object are lost.

See examples
Examples: NotesItem class

See also
Creating an item and assigning values
Using the Domino classes


DateTimeValue property

Read-Write. For a date-time item, returns a NotesDateTime object representing the value of the item. For items of other types, returns Nothing.

Defined in

NotesItem

Data type

NotesDateTime

Syntax

To get: notesDateTime = notesItem.DateTimeValue

To set: notesItem.DateTimeValue = notesDateTime

Usage

Can be set to Nothing.

Unlike LotusScript date-time variants, Notes date-time items and NotesDateTime objects store a time zone and hundredths of a second. Use the DateTimeValue property if you need to retain an item's time zone or hundredths of a second component.

See examples
Examples: DateTimeValue property

See also
Type property


IsAuthors property

Read-Write. Indicates whether an item is of type Authors. An Authors item contains a list of Notes user names, indicating people who have Author access to a particular document.

Defined in

NotesItem

Data type

Boolean

Syntax

To get: flag = notesItem.IsAuthors

To set: notesItem.IsAuthors= flag

Legal values

  • True indicates that the item is of type Authors

  • False indicates that the item is not of type Authors

Usage

An Authors item is stored as text and its Type property returns TEXT. Use IsAuthors to determine if a text item is also an Authors item.

The IsSummary property is set to True when setting the IsAuthors property. Therefore you do not have to explicitly set the summary flag.

See examples
Example: IsAuthors property

See also
Authors Property (in NotesDocument)
IsNames property
IsReaders property
Type property


IsEncrypted property

Read-Write. Indicates if an item is encrypted.

Defined in

NotesItem

Data type

Boolean

Syntax

To get: flag = notesItem.IsEncrypted

To set: notesItem.IsEncrypted = flag

Legal values

  • True indicates that the item is encrypted

  • False indicates that the item is not encrypted

Usage

If you set this property to True, the item is not actually encrypted until you call the Encrypt method on the parent NotesDocument.

See examples
Example: IsEncrypted property

See also
Encrypt method (in NotesDocument)
EncryptOnSend property (in NotesDocument)
EncryptionKeys property (in NotesDocument)
IsSigned property
IsProtected property


IsNames property

Read-write. Indicates if an item is a Names item. A Names item contains a list of Notes user names.

Defined in

NotesItem

Data type

Boolean

Syntax

To get: flag = notesItem.IsNames

To set: notesItem.IsNames= flag

Legal values

  • True indicates that the item is a Names item

  • False indicates that the item is not a Names item

Usage

A Names item is stored as text and its Type property returns TEXT. Use IsNames to determine if a text item is also a Names item.

The IsSummary property is set to True when setting the IsNames property therefore you do not have to explicitly set the summary flag.

See examples
Example: IsNames property

See also
IsAuthors property
IsReaders property
Type property


IsProtected property

Read-Write. Indicates if a user needs at least Editor access to modify an item.

Defined in

NotesItem

Data type

Boolean

Syntax

To get: flag = notesItem.IsProtected

To set: notesItem.IsProtected = flag

Legal values

  • True indicates that you need at least Editor access to modify the item

  • False indicates that you do not need Editor access to modify the item. You can modify it as long as you have Author access or better


IsReaders property

Read-Write. Indicates whether an item is of type Readers. A Readers item contains a list of Notes user names, indicating people who have Reader access to a particular document.

Defined in

NotesItem

Data type

Boolean

Syntax

To get: flag = notesItem.IsReaders

To set: notesItem.IsReaders= flag

Legal values

  • True indicates that the item is of type Readers

  • False indicates that the item is not of type Readers

Usage

A Readers item is stored as text and its Type property returns TEXT. Use IsReaders to determine if a text item is also a Readers item.

The IsSummary property is set to True when setting the IsReaders property. Therefore you do not have to explicitly set the summary flag.

See examples
Example: IsReaders property

See also
IsAuthors property
IsNames property
Type property


IsSigned property

Read-Write. Indicates if an item contains a signature.

Defined in

NotesItem

Data type

Boolean

Syntax

To get: flag = notesItem.IsSigned

To set: notesItem.IsSigned = flag

Legal values

  • True indicates that the item is signed

  • False indicates that the item is not signed

See also
IsEncrypted property
IsProtected property


IsSummary property

Read-Write. Indicates if an item can appear in a view or folder.

Defined in

NotesItem

Data type

Boolean

Syntax

To get: flag = notesItem.IsSummary

To set: notesItem.IsSummary = flag

Legal values

  • True indicates that the item is a summary

  • False indicates that the item is not a summary

Usage

Rich text cannot appear in a view, so the IsSummary property for a NotesRichTextItem always returns False.

When you create a new item using New, the IsSummary property for the item defaults to False.

When you create a new item using the AppendItemValue method in NotesDocument, or the extended class syntax, the IsSummary property for the item defaults to True.

See examples
Examples: IsSummary property

See also
Creating an item and assigning values


LastModified property

Read-only. The date that an item was last modified.

Defined in

NotesItem

Data type

Variant of type DATE

Syntax

To get: dateV = notesItem.LastModified


Name property

Read-only. The name of an item.

Defined in

NotesItem

Data type

String

Syntax

To get: itemName$ = notesItem.Name

Usage

There may be multiple items in a document with the same name.

All file attachments have the name $FILE.

See examples
Example: Name property


Parent property

Read-only. The document that contains an item.

Defined in

NotesItem

Data type

NotesDocument

Syntax

To get: Set notesDocument = notesItem.Parent

See examples
Example: Parent property


SaveToDisk property

Read-Write. Indicates if an item is saved to disk when the document is saved.

Defined in

NotesItem

Data type

Boolean

Syntax

To get: flag = notesItem.SaveToDisk

To set: notesItem.SaveToDisk = flag

Legal values

  • True indicates the default. The item is saved to disk when the document is saved.

  • False indicates that the item is not saved to disk when the document is saved.

Usage

If you mark an existing item as not to be saved, it disappears from disk the next time you save the document.

See examples
Examples: SaveToDisk property

See also
Accessing item properties
Save method (in NotesDocument)


Text property

Read-only. A plain text representation of an item's value.

Defined in

NotesItem

Data type

String

Syntax

To get: itemText$ = notesItem.Text

Usage

Multiple values in a list are separated by semicolons in the returned string. If an item's value is large, the returned string may be truncated.

For rich text items, this property skips non-text data such as bitmaps and file attachments.

For HTML items, this property returns Null.

See examples
Examples: Text property

See also
Accessing item properties


Type property

Read-only. The data type of an item.

Defined in

NotesItem

Data type

Constant of type long

Syntax

To get: itemType% = notesItem.Type

Legal values

  • ACTIONCD (16) means saved action CD records; non-Computable; canonical form

  • ASSISTANTINFO (17) means saved assistant information; non-Computable; canonical form

  • ATTACHMENT (1084) means file attachment

  • AUTHORS (1076) means authors

  • DATETIMES (1024) means date-time value or range of date-time values

  • EMBEDDEDOBJECT (1090) means embedded object

  • ERRORITEM (256) means an error occurred while accessing the type

  • FORMULA (1536) means Notes formula

  • HTML (21) means HTML source text

  • ICON (6) means icon

  • LSOBJECT (20) means saved LotusScript Object code for an agent

  • MIME_PART (25) means MIME support

  • NAMES (1074) means names

  • NOTELINKS (7) means link to a database, view, or document

  • NOTEREFS (4) means reference to the parent document

  • NUMBERS (768) means number or number list

  • OTHEROBJECT (1085) means other object

  • QUERYCD (15) means saved query CD records; non-Computable; canonical form

  • READERS (1075) means readers

  • RICHTEXT (1) means rich text

  • SIGNATURE (8) means signature

  • TEXT (1280) means text or text list

  • UNAVAILABLE (512) means the item type isn't available

  • UNKNOWN (0) means the item type isn't known

  • USERDATA (14) means user data

  • USERID (1792) means user ID name

  • VIEWMAPDATA (18) means saved ViewMap dataset; non-Computable; canonical form

  • VIEWMAPLAYOUT (19) means saved ViewMap layout; non-Computable; canonical form

Usage

You can also test for Names, Readers, and Authors items with:

  • IsNames

  • IsReaders

  • IsAuthors

See examples
Example: Type property

See also
Working with an embedded object


ValueLength property

Read-only. The number of bytes in the database used to store the item's values. This number includes internal overhead.

Defined in

NotesItem

Data type

Long

Syntax

To get: size% = notesItem.ValueLength

See examples
Example: ValueLength property

See also
Abstract method
FileSize property (in NotesEmbeddedObject)
Size property (in NotesDocument)
Values property


Values property

Read-Write. The value(s) that an item holds.

Defined in

NotesItem

Data type

The data type depends upon the type of the item.

Item type | Values data type
Rich text | String. The text in the field, rendered into plain text
Text or text list (includes Names, Authors, and Readers item types) | Array of strings
Number or number list | Array of doubles
Date-time or range of date-time values | Array of doubles
Attachment | Array of strings. The name of the attachment in element 0.

Syntax

To get: valueArray = notesItem.Values

To set: notesItem.Values = valueArray

Usage

For text, number, date-time items, and attachments this property always returns an array, even when there is only a single value in the item. If you know the item contains only a single value, access the first element in the array, which is at index 0. If you know the item contains multiple values, but you don't know how many, iterate over the array using the Forall statement.

For attachments, the attachment name can be passed to the GetAttachment method in NotesDocument.

This property returns the same value(s) for an item as the GetItemValue method in NotesDocument.

See examples
Example: Values property

See also
Accessing item properties
Creating an item and assigning values
Getting an item and its values
GetItemValue method (in NotesDocument)
ReplaceItemValue method (in NotesDocument)
Type property


Abstract method

Abbreviates the contents of a text item.

Defined in

NotesItem

Syntax

abbreviation$ = notesItem.Abstract( maxAbstract&, dropVowels, useDictionary )

Parameters

maxAbstract&

Long. The maximum length of the abbreviation$.

dropVowels

Boolean. Specify True if you want to drop vowels from the words in the item. Otherwise, specify False.

useDictionary

Boolean. Specify True if you want to use the table of abbreviations in NOTEABBR.TXT. Otherwise, specify False.

Return value

abbreviation$

String. The contents of the item, with vowels dropped and abbreviations substituted (if specified), then truncated to fit to maxSize&.

See also
ValueLength property


AppendToTextList method

For an item that's a text list, adds a new value to the item without erasing any existing values.

Defined in

NotesItem

Syntax

Call notesItem.AppendToTextList( newValue )

Parameter

newValue

String or array of strings. The string(s) you want to add to the item.

See examples
Examples: AppendToTextList method

See also
AppendItemValue method (in NotesDocument)
ReplaceItemValue method (in NotesDocument)
Values property


Contains method

Given a value, checks if the value matches at least one of the item's values exactly.

Defined in

NotesItem

Syntax

flag = notesItem.Contains( value )

Parameter

value

String, number, or variant of type DATE.

Return Values

  • True indicates that the value matches one of the values in the item

  • False indicates that the value does not match any of the values in the item

Usage

This method cannot search a text item to see if it contains a specific word--rather, it's intended to check a text list, number list, or date-time range to see if one of the values in the list or range matches value.

If value is a distinguished name, and if the item contains Notes user names, the distinguished name matches the common version of the hierarchical name.

See examples
Examples: Contains method

See also
AppendToTextList method
Values property


CopyItemToDocument method

Copies an item to a specified document.

Defined in

NotesItem

Syntax

Set notesItem = notesItem.CopyItemToDocument( notesDocument, newName$ )

Parameters

notesDocument

The document on which to create the item. If you specify Nothing, this method will generate an error.

newName$

String. The name of the new item. Specify an empty string ("") if you want to keep the name of the original item.

Return value

notesItem

The new item in the specified notesDocument, with a newName$.

See examples
Example: CopyItemToDocument method

See also
CopyAllItems method (in NotesDocument)
Copying an item
CopyItem method (in NotesDocument)
NotesDocument class


GetMIMEEntity method

Returns the MIME entity that this Item represents, typically the ""Body" field of a mailed Internet document of RFC822 and subsequent MIME RFCXXX formats.

Note This method is new with Release 5.02.

Defined in

NotesItem

Syntax

To get: notesMIMEEntity = notesItem.GetMIMEEntity

Return value

notesMIMEEntity

The MIME entity of the current item.

See examples
Examples: NotesMIMEEntity class

See also
NotesMIMEEntity class


Remove method

Permanently deletes an item from a document.

Defined in

NotesItem

Syntax

Call notesItem.Remove

Usage

After calling the Remove method, you must call the Save method in NotesDocument in order to save the change that you have made.

You can achieve the same result with the RemoveItem method in the NotesDocument class.

See examples
Example: Remove method

See also
RemoveItem method (in NotesDocument)
Removing an item
Save method


NotesLog class

Enables you to record actions and errors that take place during a script's execution. You can record actions and errors in:

  • A Notes database

  • A mail memo

  • A file (for scripts that run locally)

  • An agent log

Containment

Contained by: NotesSession

Properties

LogActions

LogErrors

NumActions

NumErrors

OverwriteFile

Parent

ProgramName

Methods

Close

LogAction

LogError

LogEvent

New

OpenAgentLog

OpenFileLog

OpenMailLog

OpenNotesLog

Creation

To create a new log, you can use:

  • New

Note The New method is not supported in COM.

  • CreateLog method in NotesSession

Syntax

Dim variableName As New NotesLog( programName$ )

or

Set notesLog = New NotesLog( programName$ )

Parameter

programName$

String. A name that identifies the log.

Usage

Once you create a log using New, you use one of the following methods to open it before you begin logging:

  • To log to a database, use the OpenNotesLog method.

  • To log to a mail memo, use the OpenMailLog method.

  • To log to a file (only available to scripts running locally), use the OpenFileLog method.

  • To log to an agent log, use the OpenAgentLog method. This method only works if used from an agent script.

You must explicitly log each action and error using the following methods:

  • To log an action, use LogAction.

  • To log an error, use LogError.

Notes does not automatically log actions or errors for you.

See examples
Examples: NotesLog class

See also
Making a Domino log
Using the Domino classes


LogActions property

Read-Write. Indicates if action logging is enabled or not.

Defined in

NotesLog

Data type

Boolean

Syntax

To get: flag = notesLog.LogActions

To set: notesLog.LogActions = flag

Return value

  • True indicates that action logging is enabled. This is the default.

  • False indicates that action logging is disabled.

Usage

The LogAction method has no effect while the LogActions property is False.

See examples
Example: LogActions property

See also
LogAction method
NumActions property


LogErrors property

Read-Write. Indicates if error logging is enabled or not.

Defined in

NotesLog

Data type

Boolean

Syntax

To get: flag = notesLog.LogErrors

To set: notesLog.LogErrors = flag

Return value

  • True indicates that error logging is enabled. This is the default.

  • False indicates that error logging is disabled.

Usage

The LogError method has no effect while the LogErrors property is False.

See examples
Example: LogErrors property

See also
LogError method
NumErrors property


NumActions property

Read-only. The number of actions logged so far.

Defined in

NotesLog

Data type

Integer

Syntax

To get: actions% = notesLog.NumActions

See examples
Examples: NumActions property

See also
LogAction method
LogActions property


NumErrors property

Read-only. The number of errors logged so far.

Defined in

NotesLog

Data type

Integer

Syntax

To get: errors% = notesLog.NumErrors

See examples
Examples: NumErrors property

See also
LogError method
LogErrors property


OverwriteFile property

Read-Write. For a log that records to a file, indicates if the log should write over the existing file or append to it. This property has no effect on logs that record to a mail message or database.

Defined in

NotesLog

Data type

Boolean

Syntax

To get: flag = notesLog.OverwriteFile

To set: notesLog.OverwriteFile = flag

Legal values

  • True indicates that the existing log file is written over

  • False indicates that the existing log file is appended to

Usage

To write over an existing log file, you must set this property to True before calling the OpenFileLog method.

See examples
Examples: OverwriteFile property

See also
OpenFileLog method


Parent property

Read-only. The session that contains a NotesLog object.

Note This property is new with Release 5.0.2b.

Note This property is supported in COM only.

Defined in

NotesLog

Data type

NotesSession

Syntax

To get: Set notesSession = notesLog.Parent

See examples
Examples: Parent property


ProgramName property

Read-Write. The name that identifies the script whose actions and errors you're logging. The name is the same as the name specified with New or CreateLog.

Defined in

NotesLog

Data type

String

Syntax

To get: programName$ = notesLog.ProgramName

To set: notesLog.ProgramName = programName$

See examples
Example: ProgramName property


Close method

Closes a log.

Defined in

NotesLog

Syntax

Call notesLog.Close

Usage

If you are logging to a mail message, Close sends the mail message to its recipient(s).

See examples
Example: Close method

See also
Making a Domino log
OpenMailLog method


LogAction method

Records an action in a log.

Defined in

NotesLog

Syntax

Call notesLog.LogAction( description$ )

Parameter

description$

String. A description of the action that the script performed, as you want it to appear in the log.

Usage

The behavior of this method depends upon the type of log you've opened.

  • If you opened a Notes database using OpenNotesLog, this method creates a new document in the database. The A$ACTION item in the document contains the description$. For more information about the items that the document contains, see the OpenNotesLog method.

  • If you opened a mail memo using OpenMailLog, this method adds description$ to the Body item of the memo, along with the current date and time.

  • If you opened a file using OpenFileLog, this method adds description$ to the next line of the file, along with the log's ProgramName and the current date and time.

See examples
Examples: LogAction method

See also
LogActions property
Making a Domino log
NumActions property
OpenNotesLog method
OpenMailLog method
OpenFileLog method


LogError method

Records an error in a log.

Defined in

NotesLog

Syntax

Call notesLog.LogError( code%, description$ )

Parameters

code%

Integer. A number indicating which error occurred.

description$

String. A description of the error that occurred, as you want it to appear in the log.

Usage

The behavior of this method depends upon the type of log you've opened.

  • If you opened a Notes database using OpenNotesLog, this method creates a new document in the database. The A$ERRCODE item in the document contains the code% and the A$ERRMSG item contains the description$. For more information about the items that the document contains, see the OpenNotesLog method.

  • If you opened a mail memo using OpenMailLog, this method adds code% and description$ to the Body item of the memo, along with the current date and time.

  • If you opened a file using OpenFileLog, this method adds code% and description$ to the next line of the file, along with the log's ProgramName and the current date and time.

See examples
Examples: LogError method

See also
LogErrors property
Making a Domino log
NumErrors property
OpenFileLog method
OpenMailLog method
OpenNotesLog method


LogEvent method

Sends a Notes event out to the network. Only scripts running on a server can use this method.

Defined in

NotesLog

Syntax

Call notesLog.LogEvent( message$, queuename$, type%, severity% )

Parameters

message$

String. The message to send to the network.

queuename$

String. The name of the queue. Notes picks a queue if you send an empty string ("").

type%

Constant. Indicates the kind of event being logged. May be any of the following:

EV_ALARM (8)

EV_COMM (1)

EV_MAIL (3)

EV_MISC (6)

EV_REPLICA (4)

EV_RESOURCE (5)

EV_SECURITY (2)

EV_SERVER (7)

EV_UNKNOWN (0)

EV_UPDATE (9)

severity%

Constant. Indicates the severity of the event being logged. May be any of the following:

SEV_FAILURE (2)

SEV_FATAL (1)

SEV_NORMAL (5)

SEV_WARNING1 (3)

SEV_WARNING2 (4)

Usage

This method does not affect any other open logs (database, file, or mail). Using the LogAction or LogError methods has no effect on event logging.

See also
IsOnServer property (in NotesSession)
LogAction method
LogError method
Making a Domino log


OpenAgentLog method

Opens the agent log for the current agent.

Defined in

NotesLog

Syntax

Call notesLog.OpenAgentLog

Usage

This method stores output in the agent log and fails if there is no current agent running. To display an agent log, select the agent and choose Agent - Log.

See examples
Example: OpenAgentLog method

See also
Making a Domino log


OpenFileLog method

Starts logging to a specified disk file. This method returns an error if you call it on a server.

Defined in

NotesLog

Syntax

Call notesLog.OpenFileLog( path$ )

Parameter

path$

String. The path and file name of the log file. If the file does not exist, the method creates it for you. If a directory in the path does not exist, the method raises an error.

Usage

If an agent is signed by a user that has unrestricted access then this method can be called on the server.

To write over an existing log file, you must set the OverwriteFile property to True before calling the OpenFileLog method.

Logging actions and errors

For information on how actions and errors get logged to a database log, see the LogAction and LogError methods.

See examples
Examples: OpenFileLog method

See also
Making a Domino log
OverwriteFile property


OpenMailLog method

Opens a new mail memo for logging. The memo is mailed when the log's Close method is called, or when the object is deleted.

Defined in

NotesLog

Syntax

Call notesLog.OpenMailLog( recipientsV, subject$ )

Parameters

recipientsV

String or array of strings. The recipients of the mail memo. Can be a string containing the name of a single user or an array of strings containing the names of several users.

subject$

String. The subject of the mail memo.

Usage

When you call this method, it opens the current user's mail database, as specified in the Address Book, and uses this database to create and send the mail memo. The memo is not saved to the database.

Logging actions and errors

For information on how actions and errors get logged to a mail log, see the LogAction and LogError methods.

See examples
Examples: OpenMailLog method

See also
Making a Domino log


OpenNotesLog method

Opens a specified Notes database for logging.

Defined in

NotesLog

Syntax

Call notesLog.OpenNotesLog( server$, dbfile$ )

Parameters

server$

String. The server on which the database log resides. Use an empty string ("") to indicate the current computer. If the script runs on the workstation, the empty string indicates a local database. If the script runs on a server, it indicates a database on that server.

dbfile$

String. The path and file name of the database. If you specify "" for a server name, you must specify the full path to the log database, including the drive letter.

Usage

One document is created in the database for each error or action that you log. Each document has a Form item set to "Log Entry" and contains the following items:

Item | Contents
A$PROGNAME | The ProgramName property
A$LOGTIME | The date and time that the error or action was logged
A$USER | The user of the script at the time the error or action was logged
A$LOGTYPE | Indicates either "Error" or "Action"
A$ACTION | A description of the action (actions only)
A$ERRCODE | The error code (errors only)
A$ERRMSG | A description of the error (errors only)

The StdR4AgentLog template

The StdR4AgentLog template (ALOG4.NTF) is designed to display the action and error documents that a NotesLog creates. If the dbfile$ you specify inherits its design from this template, you can use the database's main view to see each of the items listed above. Several agents can log to the same server$ and dbfile$. The database categorizes each action and error according to the A$PROGNAME item.

Opening a database

  • A script that runs on a server cannot open a database that's on a different server. An error is returned if your script attempts to do so.

  • A script that attempts to open a database to which it does not have access returns an error. A script needs at least Reader access to a database in order to open it.

Logging actions and errors

For information on how actions and errors get logged to a database log, see the LogAction and LogError methods.

See examples
Examples: OpenNotesLog method

See also
Making a Domino log


NotesMIMEEntity class

Represents an item of type MIME (Multipurpose Internet Mail Extensions).

Note This class is new with Release 5.02

Containment

Contained by: NotesItem

Properties

ContentAsText

ContentSubtype

ContentType

Headers

Methods

GetFirstChildEntity

GetNextSibling

GetParentEntity

Access

To access the MIME material within a NotesDocument, use the ConvertMIME property in NotesSession to override normal conversion of MIME_PART items to rich text, then call the GetFirstItem method in NotesDocument, and the GetMIMEEntity method in NotesItem.

See examples
Examples: NotesMIMEEntity class

See also
ConvertMime property
GetMIMEEntity method


ContentAsText property

Read-only. Returns the text content of a MIME entity.

Defined in

NotesMIMEEntity

Data type

String

Syntax

To get: string = notesMIMEEntity.ContentAsText

Usage

No data conversion is performed on the content before returning it to the caller.

See examples
Examples: NotesMIMEEntity class


ContentSubType property

Read-only. Returns the sub-type of a defined content type of a MIME entity. For example, if the RFC822 field "Content Type" contains "text/html," the ContentSubType property returns "html."

Defined in

NotesMIMEEntity

Data type

String

Syntax

To get: string = notesMIMEEntity.ContentSubType

See examples
Examples: NotesMIMEEntity class

See also
ContentType property


ContentType property

Read-only. Returns the content type of a MIME entity.

Defined in

NotesMIMEEntity

Data type

String

Syntax

To get: string = notesMIMEEntity.ContentType

Usage

The content type describes the data in the body of a MIME entity. The defined content types are text, multipart, message, application, audio, image, and video. For example, if the RFC822 field "Content Type" contains "image/gif," the ContentType property returns "image."

See examples
Examples: NotesMIMEEntity class

See also
ContentSubType property


Headers property

Read-only. Returns the RFC822 header fields, as one string. Headers are separated by the new line escape values.

Defined in

NotesMIMEEntity

Data type

String

Syntax

To get: string = notesMIMEEntity.Headers

See examples
Examples: NotesMIMEEntity class


GetFirstChildEntity method

Returns the first child MIMEEntity that is contained within a nested multipart MIMEEntity.

Defined in

NotesMIMEEntity

Syntax

Set notesMIMEEntityfirstchild = notesMIMEEntity.GetFirstChildEntity()

Return value

notesMIMEEntityfirstchild

NotesMIMEEntity. The first child MIME entity. For example, if the parent entity is at Lev_0, then GetFirstChildEntity returns the MIMEEntity at Lev_0_0. If the child entity has siblings, using this notational convention, they would be at Lev_0_1, Lev_0_2, and so on.

See examples
Examples: NotesMIMEEntity class

See also
GetParentEntity method
GetNextSibling method


GetNextSibling method

Returns the MIMEEntity immediately following the current MIMEEntity, contained at the same level as the current MIMEEntity within a nested multipart MIMEEntity.

Defined in

NotesMIMEEntity

Syntax

Set notesMIMEEntitynextsibling = notesMIMEEntity.GetNextSibling()

Return value

notesMIMEEntitynextsibling

NotesMIMEEntity. The next sibling MIME entity. For example, if the current MIMEEntity is Lev_0_0, then GetNextSibling returns the MIMEEntity at Lev_0_1, or returns null if there is no sibling at Lev_0_1.

See examples
Examples: NotesMIMEEntity class

See also
GetFirstChildEntity method
GetParentEntity method


GetParentEntity method

Returns the outer/parent MIMEEntity that contains the current MIMEEntity.

Defined in

NotesMIMEEntity

Syntax

Set notesMIMEEntityparent = notesMIMEEntity.GetParentEntity()

Return value

notesMIMEEntityparent

NotesMIMEEntity. The parent MIME entity. For example, if the current MIMEEntity is at Lev_0_2_1, GetParentEntity will return the parent MIMEEntity at Lev_0_2. If there is no parent, because the current MIMEEntity is at Lev_0 and is the outermost entity, then GetParentEntity returns null.

See examples
Examples: NotesMIMEEntity class

See also
GetFirstChildEntity method
GetNextSibling method


NotesName class

Represents a user or server name.

Containment

Contained by: NotesSession

Properties

Abbreviated

Addr821

Addr822Comment1

Addr822Comment2

Addr822Comment3

Addr822LocalPart

Addr822Phrase

ADMD

Canonical

Common

Country

Generation

Given

Initials

IsHierarchical

Keyword

Language

Organization

OrgUnit1

OrgUnit2

OrgUnit3

OrgUnit4

Parent

PRMD

Surname

Methods

New

Creation

To create a new NotesName object, use one of the following:

  • New method

Note The New method is not supported in COM.

  • CreateName method of NotesSession

Syntax

Dim variableName As New NotesName( name$ )

or

Set notesName = New NotesName( name$ )

Parameters

name$

String. A user or server name. If the name is not in the format of an abbreviated or canonical hierarchical name, it is treated as a flat name.

Usage

The properties of this class can be interrogated to distinguish different elements of the name.

See examples
Example: NotesName class

See also
Representing a name
Using the Domino classes


Abbreviated property

Read-only. A hierarchical name in abbreviated form.

Defined in

NotesName class

Data type

String

Syntax

To get: string$ = notesName.Abbreviated

See examples
Example: NotesName class

See also
Canonical property
IsHierarchical


Addr821 property

Read-only. Internet address in the format based on RFC821 Address Format Syntax.

Note This property is new with Release 5.

Defined in

NotesName class

Data type

String

Syntax

To get: string$ = notesName.Addr821


Addr822Comment1 property

Read-only. Comment1 component of Internet address in the format based on RFC 822 Address Format Syntax.

Note This property is new with Release 5.

Defined in

NotesName class

Data type

String

Syntax

To get: string$ = notesName.Addr822Comment1


Addr822Comment2 property

Read-only. Comment2 component of Internet address in the format based on RFC 822 Address Format Syntax.

Note This property is new with Release 5.

Defined in

NotesName class

Data type

String

Syntax

To get: string$ = notesName.Addr822Comment2


Addr822Comment3 property

Read-only. Comment3 component of Internet address in the format based on RFC 822 Address Format Syntax.

Note This property is new with Release 5.

Defined in

NotesName class

Data type

String

Syntax

To get: string$ = notesName.Addr822Comment3


Addr822LocalPart property

Read-only. LocalPart component of Internet address in the format based on RFC 822 Address Format Syntax.

Note This property is new with Release 5.

Defined in

NotesName class

Data type

String

Syntax

To get: string$ = notesName.Addr822LocalPart


Addr822Phrase property

Read-only. Phrase component of Internet address in the format based on RFC 822 Address Format Syntax.

Note This property is new with Release 5.

Defined in

NotesName class

Data type

String

Syntax

To get: string$ = notesName.Addr822Phrase


ADMD property

Read-only. The administration management domain name (ADMD) associated with the name.

Defined in

NotesName class

Data type

String

Syntax

To get: string$ = notesName.ADMD

See examples
Example: NotesName class


Canonical property

Read-only. A hierarchical name in canonical form.

Defined in

NotesName class

Data type

String

Syntax

To get: string$ = notesName.Canonical

See examples
Example: NotesName class

See also
Abbreviated property
IsHierarchical


Common property

Read-only. The common name component of a hierarchical name (CN=), or the entire name if it is flat.

Defined in

NotesName class

Data type

String

Syntax

To get: string$ = notesName.Common

See examples
Example: NotesName class

See also
Country property
Organization property
OrgUnit1 property
OrgUnit2 property
OrgUnit3 property
OrgUnit4 property


Country property

Read-only. The country component of a hierarchical name (C=).

Defined in

NotesName class

Data type

String

Syntax

To get: string$ = notesName.Country

See examples
Example: NotesName class

See also
Common property
Keyword property
Organization property
OrgUnit1 property
OrgUnit2 property
OrgUnit3 property
OrgUnit4 property


Generation property

Read-only. The generation part of a name, for example, "Jr."

Defined in

NotesName class

Data type

String

Syntax

To get: string$ = notesName.Generation

See examples
Example: NotesName class

See also
Given property
Initials property
Surname property


Given property

Read-only. The given part of a name.

Defined in

NotesName class

Data type

String

Syntax

To get: string$ = notesName.Given

See examples
Example: NotesName class

See also
Generation property
Initials property
Surname property


Initials property

Read-only. The initials part of a name.

Defined in

NotesName class

Data type

String

Syntax

To get: string$ = notesName.Initials

See examples
Example: NotesName class

See also
Generation property
Given property
Surname property


IsHierarchical property

Read-only. Indicates if a name is hierarchical.

Defined in

NotesName class

Data type

Boolean

Syntax

To get: flag = notesName.IsHierarchical

Legal values

  • True indicates that the name is hierarchical

  • False indicates that the name is not hierarchical

See examples
Example: NotesName class

See also
Abbreviated property
Canonical property


Keyword property

Read-only. The following components of a hierarchical name in the order shown separated by backslashes: country\organization\organizational unit 1\.organizational unit 2\.organizational unit 3\.organizational unit 4.

Defined in

NotesName class

Data type

String

Syntax

To get: string$ = notesName.Keyword

See examples
Example: NotesName class

See also
Country property
Organization property
OrgUnit1 property
OrgUnit2 property
OrgUnit3 property
OrgUnit4 property


Language property

Read-only. The language code associated with an alternate user name. Returns null if the property is undefined.

Note This property is new with Release 5.

Defined in

NotesName class

Data type

String

Syntax

To get: string$ = notesName.Language

Usage

This property is always NULL for the primary user name, which has no associated language.

The language tags are as follows:

Tag | Language
af | Afrikaans
af-za | Afrikaans - South Africa
ar | Arabic - United Arab Emirates
ar-bh | Arabic - Bahrain
ar-dz | Arabic - Algeria
ar-iq | Arabic - Iraq
ar-jo | Arabic - Jordan
ar-kw | Arabic - Kuwait
ar-lb | Arabic - Lebanon
ar-ly | Arabic - Libyan Arab Jamahiriya
ar-ma | Arabic - Morocco
ar-om | Arabic - Oman
ar-qa | Arabic - Qatar
ar-sa | Arabic - Saudi Arabia
ar-sy | Arabic - Syrian Arab Republic
ar-tn | Arabic - Tunisia
ar-ye | Arabic - Yemen
be | Byelorussian
bg | Bulgarian
ca | Catalan
cs | Czech
da | Danish
de | German
de-at | German - Austria
de-ch | German - Switzerland
de-li | German - Liechtenstein
de - lu | German - Luxembourg
el | Greek
en | English - United States
en-au | English - Australia
en-ca | English - Canada
en-gb | English - United Kingdom
en-ie | English - Ireland
en-jm | English - Jamaica
en-nz | English - New Zealand
en-za | English - South Africa
es | Spain (traditional collation)
es-ar | Spanish - Argentina
es-bo | Spanish - Bolivia
es-cl | Spanish - Chile
es-co | Spanish - Columbia
es-cr | Spanish - Costa Rica
es-do | Spanish - Dominican Republic
es-ec | Spanish - Ecuador
es-gt | Spanish - Guatemala
es-mx | Spanish - Mexico
es-pa | Spanish - Panama
es-pe | Spanish - Peru
es-py | Spanish - Paraguay
es-uy | Spanish - Uruguay
es-ve | Spanish - Venezuela
et | Estonian
fi | Finnish
fr | French
fr-be | French - Belgium
fr-ca | French - Canada
fr-ch | French - Switzerland
fr-lu | French - Luxembourg
he | Hebrew
hr | Croatian
hu | Hungarian
it | Italian
it-ch | Italian - Switzerland
ja | Japanese
ko | Korean
lt | Lithuanian
lv | Latvian
mk | Macedonian
nl | Dutch
no | Norwegian
pl | Polish
pl-pl | Polish - Poland
pt | Portuguese
pt-br | Portuguese - Brazil
ro | Romanian
ru | Russian
sk | Slovak
sl | Slovenian
sq | Albanian
sr | Serbian
sv | Swedish
th | Thai
tr | Turkish
uk | Ukranian
vi | Vietnamese
zh-cn | Chinese - China
zh-sg | Chinese - Singapore
zh-tw | Chinese - Taiwan

See examples
Example: Language property


Organization property

Read-only. The organization component of a hierarchical name (O=).

Defined in

NotesName

Data type

String

Syntax

To get: flag = notesName.Organization

See examples
Example: NotesName class

See also
Common property
Country property
Keyword property
OrgUnit1 property
OrgUnit2 property
OrgUnit3 property
OrgUnit4 property


OrgUnit1 property

Read-only. The first organizational unit of a hierarchical name (OU=).

Defined in

NotesName

Data type

String

Syntax

To get: string$ = notesName.OrgUnit1

See examples
Example: NotesName class

See also
Common property
Country property
Keyword property
Organization property
OrgUnit2 property
OrgUnit3 property
OrgUnit4 property


OrgUnit2 property

Read-only. The second organizational unit component of a hierarchical name (OU=).

Defined in

NotesName

Data type

String

Syntax

To get: string$ = notesName.OrgUnit2

See examples
Example: NotesName class

See also
Common property
Country property
Keyword property
Organization property
OrgUnit1 property
OrgUnit3 property
OrgUnit4 property


OrgUnit3 property

Read-only. The third organizational unit component of a hierarchical name (OU=).

Defined in

NotesName

Data type

String

Syntax

To get: string$ = notesName.OrgUnit3

See examples
Example: NotesName class

See also
Common property
Country property
Keyword property
Organization property
OrgUnit1 property
OrgUnit2 property
OrgUnit4 property


OrgUnit4 property

Read-only. The fourth organizational unit component of a hierarchical name (OU=).

Defined in

NotesName

Data type

String

Syntax

To get: string$ = notesName.OrgUnit4

See examples
Example: NotesName class

See also
Common property
Country property
Keyword property
Organization property
OrgUnit1 property
OrgUnit2 property
OrgUnit3 property


Parent property

Read-only. The session that contains a NotesName object.

Note This property is new with Release 5.0.2b.

Note This property is supported in COM only.

Defined in

NotesName

Data type

NotesSession

Syntax

To get: Set notesSession = notesName.Parent

See examples
Examples: Parent property


PRMD property

Read-only. The private management domain name (PRMD) of the name.

Defined in

NotesName class

Data type

String

Syntax

To get: string$ = notesName.PRMD

See examples
Example: NotesName class


Surname property

Read-only. The surname part of the name.

Defined in

NotesName class

Data type

String

Syntax

To get: string$ = notesName.Surname

See examples
Example: NotesName class

See also
Generation property
Given property
Initials property


NotesNewsletter class

A document or set of documents that contains information from, or links to, several other documents.

Containment

Contained by: NotesSession

Contains: NotesDocument

Properties

DoScore

DoSubject

Parent

SubjectItemName

Methods

FormatDocument

FormatMsgWithDoclinks

New

Creation

To create a new NotesNewsletter, you use a NotesDocumentCollection containing the documents you want, and one of the following:

  • New

Note The New method is not supported in COM.

  • CreateNewsletter method in NotesSession

Syntax

Dim variableName As New NotesNewsletter( notesDocumentCollection )

or

Set notesNewsletter = New NotesNewsletter( notesDocumentCollection )

Parameter

notesDocumentCollection

The documents that you want included in the newsletter.

Usage

Once you create a newsletter with New, there are two things you can do with it:

  • Use the FormatDocument method to create a new document with a rendering (snapshot) of one of the documents in the collection.

  • Use the FormatMsgWithDoclinks method to create a new document with links to each of the documents in the collection.

See examples
Examples: NotesNewsletter class

See also
Making a Domino newsletter
Using the Domino classes


DoScore property

Read-Write. For a newsletter document created using the FormatMsgWithDoclinks method, indicates if the newsletter includes each document's relevance score.

Defined in

NotesNewsletter

Data type

Boolean

Syntax

To get: flag = notesNewsletter.DoScore

To set: notesNewsletter.DoScore = flag

Legal values

  • True indicates that the newsletter includes each document's relevance score; default

  • False indicates that the newsletter does not include relevance scores

Usage

For a newsletter document created using the FormatDocument method, this property has no effect.

This property applies only to newsletters whose collections are sorted; for example, a collection produced by a call to the FTSearch method in NotesDatabase. If a newsletter's collection is unsorted, this property has no effect.

For examples, see the FormatMsgWithDoclinks method.

See examples
Examples: FormatMsgWithDoclinks method

See also
FTSearch method (in NotesDatabase)
FTSearchScore property (in NotesDocument)
NotesDocumentCollection class
UnprocessedFTSearch method (in NotesDatabase)


DoSubject property

Read-Write. For a newsletter document created using the FormatMsgWithDoclinks method, indicates if the newsletter includes a string describing the subject of each document.

Defined in

NotesNewsletter

Data type

Boolean

Syntax

To get: flag = notesNewsletter.DoSubject

To set: notesNewsletter.DoSubject = flag

Legal values

  • True indicates that the newsletter includes a subject line for each document; default

  • False indicates that the newsletter does not include subject lines

Usage

For a newsletter document created using the FormatDocument method, this property has no effect.

This property must be used in conjunction with the SubjectItemName property, which determines the item used as a subject line (for example, "Subject," "Topic," or "Description"). If you do not specify a SubjectItemName, the DoSubject property has no effect.

You must set both SubjectItemName and DoSubject before calling FormatMsgWithDoclinks.

For examples, see the FormatMsgWithDoclinks method.

See examples
Examples: FormatMsgWithDoclinks method

See also
FormatMsgWithDoclinks method
SubjectItemName property


Parent property

Read-only. The session that contains a Newsletter object.

Note This property is new with Release 5.0.2b.

Note This property is supported in COM only.

Defined in

NotesNewsletter

Data type

NotesSession

Syntax

To get: Set notesSession = notesNewsletter.Parent

See examples
Examples: Parent property


SubjectItemName property

Read-Write. For a newsletter document created using the FormatMsgWithDoclinks method, indicates the name of the item on a newsletter's documents which contains the text you want to use as a subject line.

Defined in

NotesNewsletter

Data type

String

Syntax

To get: name$ = notesNewsletter.SubjectItemName

To set: notesNewsletter.SubjectItemName = name$

Usage

For a newsletter document created using the FormatDocument method, this property has no effect.

This property must be used in conjunction with the DoSubject property, which determines whether or not a subject line is included in the newsletter. For example, if the DoSubject property is True and SubjectItemName is "Topic," then the newsletter contains the contents of each document's Topic item next to the document's link. If the DoSubject property is False, the SubjectItemName property has no effect.

You must set both SubjectItemName and DoSubject before calling FormatMsgWithDoclinks.

For examples, see the FormatMsgWithDoclinks method.

See examples
Examples: FormatMsgWithDoclinks method

See also
DoSubject property
FormatMsgWithDoclinks method


FormatDocument method

Creates a new document in the given database, containing a rendering (picture) of a specified document in the newsletter's collection. This is similar to forwarding a document, which displays a picture of the forwarded document.

Defined in

NotesNewsletter

Syntax

Set notesDocument = notesNewsletter.FormatDocument( notesDatabase, n% )

Parameters

notesDatabase

The database in which to create the newsletter document. If you do not specify a notesDatabase, the document is created in the user's default mail database.

n%

Integer. A number indicating the document to render. Use 1 to indicate the first document in the collection, 2 to indicate the second document, and so on.

Return value

notesDocument

A document in notesDatabase, containing a rendering of the nth document in the collection. The rendering is placed into the Body item.

Usage

If you want to save the rendered document, you must explicitly call the Save method on the NotesDocument. The document is saved to the notesDatabase you specify.

If you want to mail the rendered document, you must explicitly call the Send method on the NotesDocument.

See examples
Examples: FormatDocument method

See also
Making a Domino newsletter
NotesDatabase class
NotesDocument class
NotesDocumentCollection class
Save method (in NotesDocument)
Send method (in NotesDocument)


FormatMsgWithDoclinks method

Creates a newsletter document in the given database that contains a link to each document in the newsletter's collection.

Defined in

NotesNewsletter

Syntax

Set notesDocument = notesNewsletter.FormatMsgWithDoclinks( notesDatabase )

Parameter

notesDatabase

The database in which to create the newsletter document. If you do not specify a notesDatabase, the document is created in the user's default mail database.

Return value

notesDocument

A document that contains a link to each document in the newsletter's collection; also contains the name of notesDatabase and the text of the original query that produced the collection, if any.

Usage

The Body item of the returned notesDocument contains the following:

  • The file name of the database that contains the documents in the newsletter collection.

  • A link to each document in the newsletter collection.

  • If the collection is sorted and the DoScore property is True, the relevance score of each document.

  • If the DoSubject property is True and the SubjectItemName property has a value, a title for each document. You must set these properties before calling the FormatMsgWithDoclinks method.

  • The query that produced the newsletter's collection.

If you want to save the newsletter, you must explicitly call the Save method on the NotesDocument. The document will be saved to the notesDatabase you specify.

If you want to mail the newsletter, you must explicitly call the Send method on the NotesDocument.

See examples
Examples: FormatMsgWithDoclinks method

See also
DoSubject property
DoScore property
Making a Domino newsletter
NotesDatabase class
NotesDocument class
Save method (in NotesDocument)
Send method (in NotesDocument)
SubjectItemName property


NotesOutline class

Represents an outline in a database.

Note This class is new with Release 5.

Containment

Contained by: NotesDatabase

Contains: NotesOutlineEntry

Properties

Alias

Comment

Name

ParentDatabase

Methods

AddEntry

CreateEntry

CreateEntryFrom

GetChild

GetFirst

GetLast

GetNext

GetNextSibling

GetParent

GetPrev

GetPrevSibling

MoveEntry

RemoveEntry

Save

Creation and access

An outline resides within a database and is referenced via the programmatic name of the outline. You can create or access an outline through the following NotesDatabase methods:

CreateOutline

GetOutline

Usage

An outline supports a hierarchy of OutlineEntries and the NotesOutline class provides methods for navigation and manipulation of the individual OutlineEntries.

See examples
Examples: NotesOutline class

See also
Accessing an outline


Alias property

Read-Write. Alias name of the outline, used for programmatic access.

Defined in

NotesOutline

Data type

String

Syntax

To get: alias$ = notesOutline.Alias

To set: notesOutline.Alias = alias$

See examples
Examples: Alias property

See also
Accessing an outline


Comment property

Read-Write. A brief description of the outline.

Defined in

NotesOutline

Data type

String

Syntax

To get: comment$ = notesOutline.Comment

To set: notesOutline.Comment = comment$

See examples
Examples: Comment property

See also
Accessing an outline


Name property

Read-Write. Programmatic name for accessing an outline.

Defined in

NotesOutline

Data type

String

Syntax

To get: name$ = notesOutline.Name

To set: notesOutline.Name = name$

See examples
Examples: Name property

See also
Accessing an outline


ParentDatabase property

Read-only. The parent database that contains an Outline object.

Note This property is new with Release 5.0.2b.

Note This property is supported in COM only.

Defined in

NotesOutline

Data type

NotesDatabase

Syntax

To get: Set notesDatabase = notesOutline.ParentDatabase

See examples
Examples: ParentDatabase property


AddEntry method

Adds a new entry to the outline.

Note This method is not supported in COM.

Note This method is obsolete as of Release 5.0.2, but is supported for backward compatibility. Use CreateEntry to add a new entry to an outline.

Defined in

NotesOutline

Syntax

Call notesOutline.AddEntry (newEntry [, refEntry ] [, moveAfter ] [, AsChild ] )

Parameters

newEntry

NotesOutlineEntry. The entry you want to add to the outline. If you specify Nothing, this method will generate an error.

refEntry

NotesOutlineEntry. Optional. The reference entry before or after which you want to insert the new entry. If you omit this parameter the entry is added to the end of the outline. Specify to add the first entry to an empty outline.

moveAfter

Boolean. Optional. Specify True to move the new entry after the reference entry, and False to move the entry before the reference entry.

AsChild

Boolean. Optional. Specify True if you want the new entry to be added as a child to the reference entry, and False If you want the new entry to be added as a sibling entry. Default is False.

See also
Accessing an outline
CreateEntry method


CreateEntry method

Creates a new entry and adds it to the outline.

Defined in

NotesOutline

Syntax

Set notesOutlineEntry = notesOutline.CreateEntry (name$ [, refEntry ] [, addAfter ] [, asChild ] )

Parameters

Note All the parameters except name$ are new in Release 5.0.2.

name$

String. The name of the entry you want to create.

refentry

NotesOutlineEntry. Optional. The reference entry before or after which you want to insert the new entry. If you omit this parameter the entry is added to the end of the outline after the last top level entry.

Note This parameter is required in COM. Specify "Nothing" to get the default.

addAfter

Boolean. Optional. Specify True to place the new entry after the reference entry, and False to place the entry before the reference entry.

asChild

Boolean. Optional. Specify True if you want the new entry to be added as a child to the reference entry, and False If you want the new entry to be added as a sibling entry. The default is False.

Return value

notesOutlineEntry

The new OutlineEntry that is automatically added to the outline.

Usage

You must Save the outline or the effect of this method is lost when the program exits.

See examples
Examples: CreateEntry method

See also
Accessing an outline


CreateEntryFrom method

Creates a copy of an existing outline entry.

Note This method is new with Release 5.0.2.

Defined in

NotesOutline

Syntax

Set notesOutlineEntry = notesOutline.CreateEntryFrom(entry [ ,refentry ] [,addAfter] [,asChild ] )

Parameters

entry

NotesOutlineEntry. The entry to be copied.

refentry

NotesOutlineEntry. Optional. The reference entry before or after which you want to insert the new entry. If you omit this parameter the entry is added to the end of the outline after the last top level entry.

addAfter

Boolean. Optional. Specify True to place the new entry after the reference entry, and False to place the entry before the reference entry.

asChild

Boolean. Optional. Specify True if you want the new entry to be added as a child to the reference entry, and False If you want the new entry to be added as a sibling entry. The default is False.

Return value

notesOutlineEntry

The new outline entry.

Usage

You must Save the outline or the effect of this method is lost when the program exits.

See examples
Example: CreateEntryFrom method

See also
Accessing an outline


GetChild method

Returns the child of the specified entry.

Note This method is new with Release 5.0.2.

Note This method is obsolete in Release 5.0.3.

Note This method is not supported in COM.

Defined in

NotesOutline

Syntax

Set notesOutlineEntry = notesOutline.GetChild(entry )

Parameters

entry

NotesOutlineEntry. The parent entry.

Return value

notesOutlineEntry

The child of the specified entry.

See examples
Example: GetChild method

See also
Accessing an outline


GetFirst method

Gets the first entry of an outline.

Defined in

NotesOutline

Syntax

Set notesOutlineEntry = notesOutline.GetFirst()

Return value

notesOutlineEntry

The first entry of the outline.

See examples
Examples: GetFirst method

See also
Accessing an outline


GetLast method

Gets the last entry of an outline.

Defined in

NotesOutline

Syntax

Set notesOutlineEntry = notesOutline.GetLast()

Return value

notesOutlineEntry

The last entry of the outline.

See examples
Examples: GetLast method

See also
Accessing an outline


GetNext method

Given an entry in an outline, returns the entry immediately following it.

Defined in

NotesOutline

Syntax

Set notesOutlineEntry = notesOutline.GetNext(notesOutlineEntry)

Parameters

notesOutlineEntry

The current entry in the outline. If you specify Nothing, this method will generate an error.

Return value

notesOutlineEntry

The entry following the notesOutlineEntry parameter in the outline.

See examples
Examples: GetNext method

See also
Accessing an outline


GetNextSibling method

Given an entry in an outline, returns the entry immediately following it at the same level.

Defined in

NotesOutline

Syntax

Set notesOutlineEntry = notesOutline.GetNextSibling(notesOutlineEntry)

Parameters

notesOutlineEntry

The current entry in the outline. If you specify Nothing, this method will generate an error.

Return value

notesOutlineEntry

The entry following the notesOutlineEntry parameter in the outline at the same level.

See examples
Examples: GetNextSibling method

See also
Accessing an outline


GetParent method

Given a response entry in an outline, returns its parent entry.

Defined in

NotesOutline

Syntax

Set notesOutlineEntry = notesOutline.GetParent(notesOutlineEntry)

Parameters

notesOutlineEntry

The current entry in the outline.

Return value

notesOutlineEntry

The parent entry of the notesOutlineEntry parameter in the outline.

See examples
Examples: GetParent method

See also
Accessing an outline


GetPrev method

Given an entry in an outline, returns the entry immediately preceding it.

Defined in

NotesOutline

Syntax

Set notesOutlineEntry = notesOutline.GetPrev(notesOutlineEntry)

Parameters

notesOutlineEntry

The current entry in the outline. If you specify Nothing, this method will generate an error.

Return value

notesOutlineEntry

The entry preceding the notesOutlineEntry parameter in the outline.

See examples
Examples: GetPrev method

See also
Accessing an outline


GetPrevSibling method

Given an entry in an outline, returns the entry immediately preceding it at the same level.

Defined in

NotesOutline

Syntax

Set notesOutlineEntry = notesOutline.GetPrevSibling(notesOutlineEntry)

Parameters

notesOutlineEntry

The current entry in the outline. If you specify Nothing, this method will generate an error.

Return value

notesOutlineEntry

The entry preceding the notesOutlineEntry parameter in the outline at the same level

See examples
Examples: GetPrevSibling method

See also
Accessing an outline


MoveEntry method

Moves an outline entry and subentries from one location to another.

Defined in

NotesOutline

Syntax

Call notesOutline.MoveEntry(currentEntry, refEntry [, moveAfter ] [, AsChild ] )

Parameters

currentEntry

NotesOutlineEntry. The entry that needs to be moved within the outline. If you specify Nothing, this method will generate an error.

refEntry

NotesOutlineEntry. The reference entry before or after which you want to insert the current entry.

moveAfter

Boolean. Optional. Specify True to move the current entry after the reference entry, and False to move the current entry before the reference entry. Default is True.

AsChild

Boolean. Optional. Specify True if you want the new entry to be added as a child to the reference entry, and False If you want the new entry to be added as a sibling entry. The default is False.

Note The parameter default changed to False in Release 5.0.2.

Usage

You must Save the outline or the effect of this method is lost when the program exits.

Moving an entry to the beginning of the outline makes it a top-level (level 0) entry.

See examples
Example: MoveEntry method

See also
Accessing an outline


RemoveEntry method

Deletes an entry and its subentries from an outline.

Defined in

NotesOutline

Syntax

Call notesOutline.RemoveEntry(currentEntry )

Parameters

currentEntry

NotesOutlineEntry. The entry being removed. Cannot be Nothing.

Usage

You must Save the outline or the effect of this method is lost when the program exits.

An attempt to access entries removed with this method generates an error.

See examples
Example: RemoveEntry method

See also
Accessing an outline


Save method

Saves any changes you have made to the outline.

Defined in

NotesOutline

Syntax

Call notesOutline.Save()

Usage

You must save the outline before the program exits or the effect of a method that changes the outline is lost. These methods include AddEntry, CreateEntry, MoveEntry, and RemoveEntry.

See also
Accessing an outline


NotesOutlineEntry class

Represents an entry within an outline. For a detailed explanation of outline and outline entry, see the "Designing Outlines" chapter in the Application Development Guide.

Note This class is new with Release 5.

Containment

Contained by: NotesOutline

Properties

Alias

Database

Document

EntryClass

Formula

FrameText

HasChildren

HideFormula

ImagesText

IsHidden

IsHiddenFromNotes

IsHiddenFromWeb

IsInThisDb

IsPrivate

KeepSelectionFocus

Label

Level

NamedElement

Parent

Type

URL

UseHideFormula

View

Methods

SetAction

SetNamedElement

SetNoteLink

SetURL

Creation

OutlineEntries are nodes contained within an outline. Each outline entry has a set of properties that characterize the entry. To create a new OutlineEntry object, use the CreateEntry method in NotesOutline.

See also
Accessing an outline


Alias property

Read-Write. Alias name of the outline entry, used for programmatic access.

Defined in

NotesOutlineEntry

Data type

String

Syntax

To get: alias$ = notesOutlineEntry.Alias

To set: notesOutlineEntry.Alias = alias$

See examples
Examples: Alias property

See also
Accessing an outline


Database property

Read-only. The database that is the resource link for an outline entry, or null.

Defined in

NotesOutlineEntry

Data type

NotesDatabase

Syntax

To get: Set notesDatabase = notesOutlineEntry.Database

Usage

This property applies if the outline entry Type property is OUTLINE_TYPE_NOTELINK or OUTLINE_TYPE_NAMEDELEMENT and the EntryClass property is OUTLINE_CLASS_DATABASE, OUTLINE_CLASS_DOCUMENT, or OUTLINE_CLASS_VIEW.

See examples
Example: Database property

See also
Accessing an outline


Document property

Read-only. The document that is the resource link for an outline entry, or null.

Defined in

NotesOutlineEntry

Data type

NotesDocument

Syntax

To get: Set notesDocument = notesOutlineEntry.Document

Usage

This property applies if the outline entry Type property is OUTLINE_TYPE_NOTELINK and the EntryClass property is OUTLINE_CLASS_DOCUMENT.

See also
Accessing an outline


EntryClass property

Read-only. Class of outline entry.

Defined in

NotesOutlineEntry

Data type

Integer

Syntax

To get: entryclass% = notesOutlineEntry.EntryClass

Legal values

  • OUTLINE_CLASS_DATABASE (2194)

  • OUTLINE_CLASS_DOCUMENT (2190)

  • OUTLINE_CLASS_FOLDER (2197)

  • OUTLINE_CLASS_FORM (2192)

  • OUTLINE_CLASS_FRAMESET (2195)

  • OUTLINE_CLASS_NAVIGATOR (2193)

  • OUTLINE_CLASS_PAGE (2196)

  • OUTLINE_CLASS_UNKNOWN (2189)

  • OUTLINE_CLASS_VIEW (2191)

See also
Accessing an outline


Formula property

Read-only. Formula of an action outline, or an empty string.

Defined in

NotesOutlineEntry

Data type

String

Syntax

To get: formula$ = notesOutlineEntry.Formula

Usage

This property applies if the outline entry Type property is OUTLINE_TYPE_ACTION.

See examples
Examples: Formula property

See also
Accessing an outline


FrameText property

Read-Write. The name of the target frame in which you want the entry to appear.

Defined in

NotesOutlineEntry

Data type

String

Syntax

To get: frame$ = notesOutlineEntry.FrameText

To set: notesOutlineEntry.FrameText = frame$

See examples
Examples: FrameText property

See also
Accessing an outline


HasChildren property

Read-only. Indicates whether an entry contains child entries.

Defined in

NotesOutlineEntry

Data type

Boolean

Syntax

To get: flag = notesOutlineEntry.HasChildren

Legal values

  • True indicates that the entry contains child entries

  • False indicates that the entry does not contain child entries

See examples
Examples: HasChildren property

See also
Accessing an outline


HideFormula property

Read-Write. A formula that determines when an entry is hidden, or an empty string.

Note This property is new with Release 5.01.

Defined in

NotesOutlineEntry

Data type

String

Syntax

To get: image$ = notesOutlineEntry.HideFormula

To set: notesOutlineEntry.HideFormula = image$

Usage

The hide formula must be a valid Notes formula that evaluates to a boolean value.

UseHideFormula determines if the hide formula is used.

See examples
Examples: IsHidden, IsHiddenFromNotes, IsHiddenFromWeb, HideFormula, and UseHideFormula properties

See also
Accessing an outline


ImagesText property

Read-Write. The name of the image file you would use to add an icon to your entry.

Defined in

NotesOutlineEntry

Data type

String

Syntax

To get: image$ = notesOutlineEntry.ImagesText

To set: notesOutlineEntry.ImagesText = image$

See examples
Examples: ImagesText property

See also
Accessing an outline


IsHidden property

Read-Write. Indicates if an entry is hidden in the current user context (read) or hides an entry in all contexts (write).

Note This property has new semantics with Release 5.0.1.

Note This property is obsolete in Release 5.0.3.

Note This property is not supported in COM.

Defined in

NotesOutlineEntry

Data type

Boolean

Syntax

To get: flag = notesOutlineEntry.IsHidden

To set: notesOutlineEntry.IsHidden = flag

Legal values

  • True indicates that the entry is hidden

  • False indicates that the entry is shown in the UI

Usage

The current user context can be the Notes client or a Web browser.

To read and write the hide properties with precision, see IsHiddenFromNotes, IsHiddenFromWeb, HideFormula, and UseHideFormula.

See examples
Examples: IsHidden, IsHiddenFromNotes, IsHiddenFromWeb, HideFormula, and UseHideFormula properties

See also
Accessing an outline


IsHiddenFromNotes property

Read-Write. Indicates if an entry is hidden in the context of the Notes client.

Note This property is new with Release 5.0.1.

Defined in

NotesOutlineEntry

Data type

Boolean

Syntax

To get: flag = notesOutlineEntry.IsHiddenFromNotes

To set: notesOutlineEntry.IsHiddenFromNotes = flag

Legal values

  • True indicates that the entry is hidden in the Notes client

  • False indicates that the entry displays in the Notes client

See examples
Examples: IsHidden, IsHiddenFromNotes, IsHiddenFromWeb, HideFormula, and UseHideFormula properties

See also
Accessing an outline


IsHiddenFromWeb property

Read-Write. Indicates if an entry is hidden in the context of a Web browser.

Note This property is new with Release 5.0.1.

Defined in

NotesOutlineEntry

Data type

Boolean

Syntax

To get: flag = notesOutlineEntry.IsHiddenFromWeb

To set: notesOutlineEntry.IsHiddenFromWeb = flag

Legal values

  • True indicates that the entry is hidden in a Web browser

  • False indicates that the entry displays in a Web browser

See examples
Examples: IsHidden, IsHiddenFromNotes, IsHiddenFromWeb, HideFormula, and UseHideFormula properties

See also
Accessing an outline


IsInThisDB property

Read-only. Indicates if an entry refers to an element within the current database.

Defined in

NotesOutlineEntry

Data type

Boolean

Syntax

To get: flag = notesOutlineEntry.IsInThisDB

Legal values

  • True indicates that the entry is in the current database

  • False indicates that the entry is not in the current database

See examples
Examples: IsInThisDB property

See also
Accessing an outline


IsPrivate property

Read-only. Indicates if an entry is specific to an individual.

Defined in

NotesOutlineEntry

Data type

Boolean

Syntax

To get: flag = notesOutlineEntry.IsPrivate

Legal values

  • True indicates that the entry is specific to an individual

  • False indicates that the entry is not specific to an individual

See examples
Examples: IsPrivate property

See also
Accessing an outline


KeepSelectionFocus property

Read-Write. Indicates if an entry keeps selection focus.

Note This property is new with Release 5.0.1.

Defined in

NotesOutlineEntry

Data type

Boolean

Syntax

To get: flag = notesOutlineEntry.KeepSelectionFocus

To set: notesOutlineEntry.KeepSelectionFocus = flag

Legal values

  • True indicates that the entry keeps selection focus

  • False indicates that the entry does not keep selection focus

See examples
Examples: KeepSelectionFocus property

See also
Accessing an outline


Label property

Read-Write. Label for an entry.

Defined in

NotesOutlineEntry

Data type

String

Syntax

To get: text$ = notesOutlineEntry.Label

To set: notesOutlineEntry.Label = text$

See examples
Examples: Label property

See also
Accessing an outline


Level property

Read-only. Indicates the level of this entry.

Defined in

NotesOutlineEntry

Data type

Long

Syntax

To get: level& = notesOutlineEntry.Level

Usage

Level 0 is the top level.

See examples
Examples: Level property

See also
Accessing an outline


NamedElement property

Read-only. The named element referenced by an outline entry (or the alias name if available), or an empty string

Defined in

NotesOutlineEntry

Data type

String

Syntax

To get: element$ = notesOutlineEntry.NamedElement

Usage

This property applies if the outline entry Type property is OUTLINE_TYPE_NAMEDELEMENT.

See also
Accessing an outline


Parent property

Read-only. The outline that contains an OutlineEntry object.

Note This property is new with Release 5.0.2b.

Note This property is supported in COM only.

Defined in

NotesOutlineEntry

Data type

NotesOutline

Syntax

To get: Set notesOutline = notesOutlineEntry.Parent

See examples
Examples: Parent property


Type property

Read-only. Type of outline entry.

Defined in

NotesOutlineEntry

Data type

Constant of type Long

Syntax

To get: entrytype& = notesOutlineEntry.Type

Legal values

  • OUTLINE_OTHER_FOLDERS_TYPE (1589)

  • OUTLINE_OTHER_UNKNOWN_TYPE (1591)

  • OUTLINE_OTHER_VIEWS_TYPE (1588)

  • OUTLINE_TYPE_ACTION (2188)

  • OUTLINE_TYPE_NAMEDELEMENT (2187)

  • OUTLINE_TYPE_NOTELINK (2186)

  • OUTLINE_TYPE_URL (2185)

See examples
Examples: Type property

See also
Accessing an outline


URL property

Read-only. The URL of an outline entry, or an empty string.

Defined in

NotesOutlineEntry

Data type

String

Syntax

To get: url$ = notesOutlineEntry.URL

Usage

This property applies if the outline entry Type property is OUTLINE_TYPE_URL.

See examples
Examples: URL property

See also
Accessing an outline


UseHideFormula property

Read-Write. Indicates if an entry is hidden when the hide formula is True.

Note This property is new with Release 5.0.1.

Defined in

NotesOutlineEntry

Data type

Boolean

Syntax

To get: flag = notesOutlineEntry.UseHideFormula

To set: notesOutlineEntry.UseHideFormula = flag

Legal values

  • True indicates that the entry is hidden when the hide formula is True

  • False indicates that the entry displays regardless of the hide formula

Usage

See HideFormula for the text of the hide formula.

See examples
Examples: IsHidden, IsHiddenFromNotes, IsHiddenFromWeb, HideFormula, and UseHideFormula properties

See also
Accessing an outline


View property

Read-only. The view that is the resource link for an outline entry, or null.

Defined in

NotesOutlineEntry

Data type

NotesView

Syntax

To get: Set notesView = notesOutlineEntry.View

Usage

This property applies if the outline entry Type property is OUTLINE_TYPE_NOTELINK and the EntryClass property is OUTLINE_CLASS_DOCUMENT or OUTLINE_CLASS_VIEW.

See also
Accessing an outline


SetAction method

Specifies a formula for an action outline entry.

Note This method is treated as a Sub in COM.

Defined in

NotesOutlineEntry

Syntax

flag = notesOutlineEntry.SetAction( formula$ )

Parameters

formula$

String. A Domino formula.

Return value

  • True indicates that the action is set successfully

  • False indicates that the action is not set successfully

Usage

This method sets the outline entry Type property to OUTLINE_TYPE_ACTION.

See also
Accessing an outline


SetNamedElement method

Specifies a named element for an outline entry.

Note This method is treated as a Sub in COM.

Defined in

NotesOutlineEntry

Syntax

flag = notesOutlineEntry.SetNamedElement( notesDatabase, elementName$ , entryclass%)

Parameters

notesDatabase

The database containing the named element.

elementName$

String. The name of a database element.

entryclass%

Integer. The entry class for the named element.

Return value

  • True indicates that the named element is set successfully

  • False indicates that the named element is not set successfully

Usage

This method sets the outline entry Type property to OUTLINE_TYPE_NAMEDELEMENT and the EntryClass property depending on the named element. See the EntryClass property.

See also
Accessing an outline


SetNoteLink method

Specifies a resource link for an outline entry.

Note This method is treated as a Sub in COM.

Defined in

NotesOutlineEntry

Syntax

Note The following syntax is for LotusScript.

flag = notesOutlineEntry.SetNoteLink(notesDatabase, notesView, notesDocument )

Note The following syntax is for COM.

Call notesOutlineEntry.SetNoteLink(Obj )

Parameters

notesDatabase

The database that is the resource link.

notesView

The view that is the resource link.

notesDocument

The document that is the resource link.

Obj

Unknown. The database, view, or document that is the resource link.

Return value

  • True indicates that the resource link is set successfully

  • False indicates that the resource link is not set successfully

Usage

Only one object should be specified: either the notesDatabase, the notesView, or the notesDocument. If you are specifying a notesView as the resource link for an outline entry, the notesDatabase parameter must be passed in as an empty object. If you are specifying a notesDocument, the notesDatabase and notesView parameters must be passed in as empty objects.

This method sets the outline entry Type property to OUTLINE_TYPE_NOTELINK and the EntryClass property to OUTLINE_CLASS_DATABASE, OUTLINE_CLASS_DOCUMENT, or OUTLINE_CLASS_VIEW depending on the type of object passed to the method.

See examples
Examples: SetNoteLink method

See also
Accessing an outline


SetURL method

Specifies a URL as the resource link for an outline entry.

Note This method is treated as a Sub in COM.

Defined in

NotesOutlineEntry

Syntax

flag = notesOutlineEntry.SetURL( url$ )

Parameters

url$

String. A URL.

Return value

  • True indicates that the URL is set successfully

  • False indicates that the URL is not set successfully

Usage

This method sets the outline entry Type property to OUTLINE_TYPE_URL.

See also
Accessing an outline


NotesRegistration class

Represents the creation or administration of an ID file.

Note This class is new with Release 4.6.

Properties

AltOrgUnit

AltOrgUnitLang

CertifierIDFile

CreateMailDb

Expiration

IDType

IsNorthAmerican

MinPasswordLength

OrgUnit

RegistrationLog

RegistrationServer

StoreIDInAddressbook

UpdateAddressbook

Methods

AddCertifierToAddressbook

AddServerToAddressbook

AddUserProfile

AddUserToAddressbook

CrossCertify

DeleteIDOnServer

GetIDFromServer

GetUserInfo

New

Recertify

RegisterNewCertifier

RegisterNewServer

RegisterNewUser

SwitchToID

Usage

When using the RegisterNewCertifier, RegisterNewServer, and the RegisterNewUser methods, you need to set all the properties before calling these methods. The only "optional" property is the RegistrationLog. You cannot save the updates to the certlog.nsf unless this property is set.

newreg.RegistrationLog = "certlog.nsf"

newreg.IDType = ID_HIERARCHICAL

newreg.Expiration = CertExpireDate

newreg.MinPasswordLength = length%

newreg.IsNorthAmerican = True

newreg.CertifierIDFile = certidfile

newreg.RegistrationServer = db.Server

newreg.OrgUnit = org

newreg.CreateMailDb = True

newreg.StoreIDInAddressbook = True

newreg.UpdateAddressbook = False

When using the CrossCertify, DeleteIDOnServer, GetIDFromServer, and the Recertify methods, you must set the RegistrationServer property before calling these methods; otherwise you will get an error message:

"Missing Registration Argument" or "Required registration argument not provided"

Some methods have overlapping functionality:

RegisterNewUser method overlaps the functionality of AddUserToAddressbook

RegisterNewServer method overlaps the functionality of AddServerToAddressbook

RegisterNewUserCertifier method overlaps the functionality of AddCertifierToAddressbook

The key to using both methods together is the Updateaddressbook property. This property when set to False, causes the AddCertifierToAddressbook, AddServerToAddressbook, and AddUserToAddressbook methods to update the NAB.

Note If you set UpdateAddressbook property to True when using a RegisterNewUser, RegisterNewServer, or RegisterNewCertifier method AND use any of the AddCertifierToAddressbook, AddServerToAddressbook, or AddUserToAddressbook methods, you will get TWO NAB entries for the user, server or certifier. Not recommended.

Creation

To create a new NotesRegistration object, use the New method.

Note The New method is not supported in COM.

Syntax

Dim variableName As New NotesRegistration

or

Set notesRegistration = New NotesRegistration

See examples
Examples: NotesRegistration class

See also
Using the Domino classes


AltOrgUnit property

Read-Write. Alternate names for the organizational unit to use when creating ID files.

Note This property is new with Release 5.0.2.

Defined in

NotesRegistration

Data type

String array

Syntax

To get: stringArray = notesRegistration.AltOrgUnit


AltOrgUnitLang property

Read-Write. Alternate name language for the organizational unit to use when creating ID files.

Note This property is new with Release 5.0.2.

Defined in

NotesRegistration

Data type

String array

Syntax

To get: stringArray = notesRegistration.AltOrgUnitLang

To set: notesRegistration.AltOrgUnitLang = stringArray


CertifierIDFile property

Read-Write. The complete file specification of the certifier ID to use when creating IDs.

Defined in

NotesRegistration class

Data type

String

Syntax

To get: string$ = notesRegistration.CertifierIDFile

To set: notesRegistration.CertifierIDFile = string$

Usage

Specify the complete path, for example, c:\notes\data\cert.id.

See also
RegistrationServer property


CreateMailDb property

Read-Write. Indicates whether a mail database is created with the ID file when calling RegisterNewUser.

Defined in

NotesRegistration class

Data type

Boolean

Syntax

To get: flag = notesRegistration.CreateMailDb

To set: notesRegistration.CreateMailDb = flag

Legal values

  • True indicates that a mail database is created

  • False indicates that a mail database is not created; it will be created during setup


Expiration property

Read-Write. The expiration date to use when creating ID files.

Defined in

NotesRegistration class

Data type

Variant of type DATE

Syntax

To get: date = notesRegistration.Expiration

To set: notesRegistration.Expiration = date

Usage

Can be set to Nothing.

The OrgUnit property needs to be set before you specify the expiration date for the new certifier. That is, you can set the expiration date for a new certifier of type OrgUnit only.


IDType property

Read-Write. The type of ID file to create when calling RegisterNewUser, RegisterNewServer, and RegisterNewCertifier.

Defined in

NotesRegistration class

Data type

Constant of type Integer

Syntax

To get: type% = notesRegistration.IDType

To set: notesRegistrationID.IDType = type%

Legal values

  • ID_FLAT (171) to create a flat ID

  • ID_HIERARCHICAL (172) to create a hierarchical ID

  • ID_CERTIFIER (173) to create a flat or hierarchical ID depending on whether the certifier is flat or hierarchical

See also
CertifierIDFile property


IsNorthAmerican property

Read-Write. indicates whether an ID file is NorthAmerican. Useful when calling RegisterNewUser, RegisterNewServer, and RegisterNewCertifier.

Defined in

NotesRegistration class

Data type

Boolean

Syntax

To get: flag = notesRegistration.IsNorthAmerican

To set: notesRegistrationID.IsNorthAmerican = flag

Legal values

  • True indicates that the ID file is North American; default

  • False indicates that the ID file is not North American


MinPasswordLength property

Read-Write. The minimum number of characters required for a password in an ID file when calling RegisterNewUser, RegisterNewServer, and RegisterNewCertifier.

Defined in

NotesRegistration class

Data type

Integer

Syntax

To get: length% = notesRegistration.MinPasswordLength

To set: notesRegistrationID.MinPasswordLength = length%

Usage

This property defines the minimum password length required for subsequent changes to the password by the user. The password used when the certifier is created is not restricted by the MinPasswordLength property.


OrgUnit property

Read-Write. The organizational unit to use when creating ID files.

Defined in

NotesRegistration class

Data type

String

Syntax

To get: string$ = notesRegistration.OrgUnit

To set: notesRegistration.OrgUnit = string$

See also
CertifierIDFile property


RegistrationLog property

Read-Write. The log file to use when creating IDs.

Defined in

NotesRegistration class

Data type

String

Syntax

To get: string$ = notesRegistration.RegistrationLog

To set: notesRegistration.RegistrationLog = string$

Usage

Notes is designed to read the Keyword parameter called Log from the NOTES.INI file. You can set the RegistrationLog to any name you want; but if, for example, you set RegistrationLog = "reg.nsf", you have to make sure that the Keyword Log in NOTES.INI is set to Log=reg.nsf,.....

See also
NotesLog class


RegistrationServer property

Read-Write. The server to use when creating IDs. This property is used only when the created ID is stored in the server Address Book, or when a mail database is created for the new user.

Defined in

NotesRegistration class

Data type

String

Syntax

To get: string$ = notesRegistration.RegistrationServer

To set: notesRegistration.RegistrationServer = string$

See also
CertifierIDFile property


StoreIDInAddressbook property

Read-Write. Indicates whether the ID file is stored in the server Address Book.

Defined in

NotesRegistration class

Data type

Boolean

Syntax

To get: flag = notesRegistration.StoreIDInAddressbook

To set: notesRegistration.StoreIDInAddressbook = flag

Legal values

  • True indicates that the ID is stored in the Address Book

  • False indicates that the ID is not stored in the Address Book

See also
UpdateAddressbook property


UpdateAddressbook property

Read-Write. Indicates whether the server entry in the Address Book is updated when the ID file is created when calling RegisterNewUser, RegisterNewServer, and RegisterNewCertifier.

Defined in

NotesRegistration class

Data type

Boolean

Syntax

To get: flag = notesRegistration.UpdateAddressbook

To set: notesRegistration.UpdateAddressbook = flag

Legal values

  • True that the Address Book is updated

  • False indicates that the Address Book is not updated

See also
StoreIDInAddressbook property


AddCertifierToAddressbook method

Adds the certifier ID file to the Address Book.

Defined in

NotesRegistration class

Syntax

Call notesRegistration.AddCertifierToAddressbook(idfile$ [, certpw$ [, location$ [, comment$]]])

Parameters

idfile$

String. The certifer ID file to be added to the Address Book. Specify the complete path; for example, c:\notes\data\cert.id.

certpw$

String. The password for the certifier ID file.

location$

String. The contents of the location field in the Address Book record.

comment$

String. The contents of the comment field in the Address Book record.

Usage

This method requires only the given arguments. No properties need to be set.

See examples
Example: AddCertifierToAddressbook Method

See also
AddServerToAddressbook method
AddUserProfile method
AddUserToAddressbook method
CertifierIDFile property


AddServerToAddressbook method

Adds a server to the Address Book.

Defined in

NotesRegistration class

Syntax

Call notesRegistration.AddServerToAddressbook( idfile$, server$, domain$ [, userpw$ [, network$ [, adminname$ [, title$ [,location$ [, comment$]]]]]])

Parameters

idfile$

String. The ID file for the server to be added to the Address Book. Specify the full path; for example, c:\notes\data\server.id.

server$

String. The name of the server to be added to the Address Book.

domain$

String. The domain of the server to be added to the Name and Address.book.

userpw$

String. The server's password for the specified ID file.

network$

String. The notes named network (NNN) on which the server runs..

adminname$

String. The full name of the administrator of the server.

title$

String. The contents of the title field of the Name and Address book record.

location$

String. The contents of the location field of the Name and Address book record.

comment$

String. The contents of the comment field of the Name and Address book record.

Usage

This method requires only the given arguments. StoreIDInAddressbook is the only property that can affect the functionality of this method.

See examples
Example: AddServerToAddressbook method

See also
AddCertifierToAddressbook method
AddUserToAddressbook method


AddUserProfile method

Adds the name of a setup profile to the user's person record.

Defined in

NotesRegistration class

Syntax

Call notesRegistration.AddUserProfile( username$, profilename$)

Parameters

username$

String. The username whose person record will be updated with the setup profile.

profilename$

String. The name of the setup profile document to be added to the person record.

Usage

This method requires that you give it the server on which the Address Book is located. If you do not set the RegistrationServer property, the following error will occur:

"Required registration argument not provided"

See examples
Example: AddUserProfile method

See also
EditProfile method
GetProfileDocument method


AddUserToAddressbook method

Adds a user to the Address Book.

Defined in

NotesRegistration class

Syntax

Call notesRegistration.AddUserToAddressbook( idfile$, fullname$, lastname$ [, userpw$ [, firstname$ [, middle$ [, mailserver$ [, maildbpath$ [, fwdaddress$ [,location$ [, comment$]]]]]]]] )

Parameters

idfile$

String.The ID file for the user to be added to the Address Book. Specify the full path, for example, c:\notes\data\cert.id.

fullname$

String. The user's full name.

lastname$

String. The user's last name.

userpw$

String. The user's password for the specified ID file.

firstname$

String. The user's first name.

middle$

String. The user's middle initial.

mailserver$

String. The full name of the user's mail server.

mailidpath$

String. The full mail pathname for the specified ID file.

fwdaddress$

String. The user's forwarding mail address.

location$

String. The contents of the location field in the Address Book record.

comment$

String. The contents of the comment field in the Address Book record.

Usage

This method requires only the given arguments. StoreIDInAddressBook is the only property that can affect the functionality of this method.

See examples
Example: AddUserToAddressbook method

See also
AddCertifierToAddressbook method
AddServerToAddressbook method


CrossCertify method

Cross certifies an ID file.

Defined in

NotesRegistration class

Data Type

Boolean

Syntax

Call notesRegistration.CrossCertify( idfile$ [,certpw$ [, comment$]])

Parameters

idfile$

String. The ID file to be cross-certified. Specify the full path; for example, c:\notes\data\user.id.

certpw$

String. The password for the certifier ID file.

comment$

String. The contents of the comment field in the Name and Address book record.

Usage

CrossCertify method can only run in the front-end on a client, since it requires you to enter the certifier password in a dialog box at runtime.

This method requires that you give it the path to the certifier ID. If you do not set the CertifierIDFile property, you will get the following error:

"Certifier ID path not supplied."

In addition, you can also set the Expiration property. The Expiration property can be used if a specific expiration date is required.

Note This method will prompt you for the user ID password.

See examples
Example: CrossCertify method

See also
AddCertifierToAddressbook method
CertifierIDFile property


DeleteIDOnServer method

Deletes an ID file from the server.

Defined in

NotesRegistration class

Syntax

Call notesRegistration.DeleteIDOnServer(username$, isserverid )

Parameters

username$

String. The username attached to the ID file.

isserverid

Boolean. True if the name you query represents a server ID. False if the name is that of a person. While the information always comes from the designated server's Address Book, this argument helps you to choose a view to search.

Usage

This method requires that you specify the server containing the Address Book. If you do not set the RegistrationServer property, the following error occurs:

"Required registration argument not provided"

See examples
Example: DeleteIDOnServer method

See also
GetIDFromServer method


GetIDFromServer method

Gets an ID file from the server.

Defined in

NotesRegistration class

Syntax

Call notesRegistration.GetIDFromServer( username$, filepath$, isserverid )

Parameters

username$

String.The username attached to the Id file.

filepath$

String. The full path of the ID file; for example, c:\notes\data\server.id.

isserverid

Boolean. True if the name you query represents a server ID. False if the name is that of a person. While the information always comes from the designated server's Address Book, this argument helps you to choose a view to search.

Usage

This method requires that you specify the server containing the Address Book. If you do not set the RegistrationServer property, the following error occurs:

"Required registration argument not provided"

See examples
Example: GetIDFromServer method

See also
DeleteIDOnServer method


GetUserInfo method

Gets information about the user from the server.

Defined in

NotesRegistration class

Syntax

Call notesRegistration.GetUserInfo( username$ [, retmailServer$ [, retmailFile$ [, retmailDomain$ [, retmailSystem% [ , retprofile$ ]]]]])

Parameters

username$

String. The username attached to the ID file.

retMailServer$

String. Returns the name of the user's mail server.

retMailFile$

String. Returns the name of the user's mail file.

retMailDomain$

String. Returns the name of the user's mail domain.

retMailSystem%

Integer. Returns an integer representing the name of the user's mail system, as shown below:

Notes | 1
CC Mail | 2
Other Internet Mail | 5
POP or IMAP | 6
X400 | 4
Other | 3
None | 100

retProfile$

String. Returns the name of the user's profile document.

Usage

Note All parameters for this method require datatype suffix characters to compile.

This method requires that you give it the server on which the Address Book is located. If you do not set the RegistrationServer property, the following error will occur:

"Required registration argument not provided"

The parameters, except for the first, are return values.

See examples
Example: GetUserInfo method


ReCertify method

Recertifies an ID file.

Defined in

NotesRegistration class

Syntax

Call notesRegistration.ReCertify( idfile$ [,certpw$ [, comment$]])

Parameters

idfile$

String. The ID file to be recertified. Specify the full path; for example, c:\notes\data\cert.id.

certpw$

String. The password for the certifier ID file.

comment$

String. The contents of the comment field in the Address Book record.

Usage

ReCertify method can only run in the front-end on a client, since it requires you to enter the certifier password in a dialog box at runtime.

This method requires that you give it the path to the certifier ID. If you do not set the CertifierIDFile property, you will get the following error:

"Certifier ID path not supplied."

In addition, you can also set the Expiration property. The Expiration property can be used if a specific expiration date is required.

Note This method will prompt you for the user ID password.

See examples
Example: ReCertify method


RegisterNewCertifier method

Registers a new certfier ID file.

Defined in

NotesRegistration class

Syntax

Call notesRegistration.RegisterNewCertifier( organization$, idfile$, certpw$ [, country$ ]] )

Parameters

organization$

String. The organization to which the new certifier ID belongs.

idfile$

String. The ID file to be registered. Specify the full path; for example, c:\notes\data\cert.id.

certpw$

String. The password for the certifier ID file.

country$

String. The country code that is attached to the certifier.

Usage

This method only requires the given arguments.

The OrgUnit property needs to be set before you specify the expiration date for the new certifier. That is, you can set the expiration date for a new certifier of type OrgUnit only.

See examples
Example: RegisterNewCertifier method

See also
AddCertifierToAddressbook method


RegisterNewServer method

Registers a new server ID file.

Defined in

NotesRegistration class

Syntax

Call notesRegistration.RegisterNewServer( server$, idfile$, domain$ [, servpw$ [, certpw$ [, location$ [, comment$ [, network$ [, adminname$ [, title$]]]]]]] )

Parameters

server$

String. The name of the server to which the server ID file belongs.

idfile$

String. The ID file to be registered. Specify the complete path; for example, c:\notes\data\server.id.

domain$

String. The domain to which the server belongs.

servpw$

String. The password for the server ID file.

certpw$

String. The password for the certifier ID file.

location$

String. The contents of the location field in the Address Book record.

comment$

String. The contents of the comment field in the Address Book record.

network$

String. The Notes named network (NNN) on which the server runs.

adminname$

String. The full name of the server administrator.

title$

String. The contents of the title field in the Address Book record.

Usage

This method requires that you give it the path to the certifier ID. If you do not set the CertifierIDFile property, you will get the following error:

"Certifier ID path not supplied."

In addition, you can set other properties depending on your needs.

See examples
Example: RegisterNewServer method

See also
RegisterNewCertifier method
RegisterNewUser method


RegisterNewUser method

Registers a new user ID file.

Defined in

NotesRegistration class

Syntax

Call notesRegistration.RegisterNewUser( lastname$, idfile$, regserver$ [, firstname$ [, middle$ [, certpw$ [, location$ [, comment$ [, maildbpath$ [, fwddomain$ [, userpw$ [, usertype% [, altname [, altnamelang ]]]]]]]]]]] )

Parameters

lastname$

String. The last name of the user to be registered.

idfile$

String. The ID file to be registered. Specify the complete path; for example, c:\notes\data\user.id.

regserver$

String. The name of the user's mail server.

firstname$

String. The user's first name.

middle$

String. The user's middle initial.

certpw$

String. The password for the certifier ID file.

location$

String. The contents of the location field in the Address Book record.

comment$

String. The contents of the comment field in the Address Book record.

maildbpath$

String. The path of the user's mail file relative to the mail directory; for example, mail\jones.nsf.

fwddomain$

String. The forwarding domain for the user's mail file.

userpw$

String. The user password.

usertype%

Note This parameter is new with Release 5.

Constant of type Integer. Indicates the type of client to be created. May be one of the following.

altname

Note This parameter is new with Release 5.0.2.

String. The alternate user name.

altnamelang

Note This parameter is new with Release 5.0.2.

String. The language for the alternate user name.

NOTES_DESKTOP_CLIENT (175) | Desktop client
NOTES_FULL _CLIENT (176) | Default, full client
NOTES_LIMITED_CLIENT (174) | Mail client

Usage

This method requires that you give it the path to the certifier ID. If you do not set the CertifierIDFile property, you will get the following error:

"Certifier ID path not supplied."

In addition, you can set other properties depending on your needs.

This method uses the same language element of the AltOrgUnit property with the altnamelang parameter for a new user's alternate organization name. If the AltOrgUnit property has no element, or does not have the same language element as altnamelang, the new user will have an alternate name without an alternate organization name.

When the AltOrgUnitLang property contains multiple elements of the same language, the first element will be used.

See examples
Example: RegisterNewUser method


SwitchToID method

Switches to a different ID file.

Defined in

NotesRegistration class

Syntax

Call notesRegistration.SwitchToID( idfile$ [ , userpw$ ])

Parameters

idfile$

String. The ID file to which you want to switch. Specify the complete path; for example, c:\notes\data\user.id.

userpw$

String. The user password.

Usage

This method only requires the given arguments. No properties need to be set.

SwitchToID method will switch IDs on a client, but will not switch IDs on a server. You will get an error if you use this method on a server.

See examples
Example: SwitchToID method


NotesReplication class

Represents the replication settings of a database.

Note This class is new with Release 5.

Containment

Contained by: NotesDatabase

Properties

Abstract

CutoffDate

CutoffDelete

CutoffInterval

Disabled

IgnoreDeletes

IgnoreDestDeletes

Priority

Methods

ClearHistory

Reset

Save

Creation

Each database object has exactly one associated Replication object. Use the ReplicationInfo property in NotesDatabase to get the Replication object. Use this object to access and change the replication settings of a database.

See examples
Examples: Replication class


Abstract property

Read-Write. Indicates if large documents should be truncated and attachments removed during replication.

Defined in

NotesReplication

Data type

Boolean

Syntax

To get: flag = notesReplication.Abstract

To set: notesReplication.Abstract = flag

Legal values

  • True indicates that large documents will be truncated and attachments removed

  • False indicates that large documents should be replicated in their entirety

See examples
Example: Abstract property


CutoffDate property

Read-only. Today's date minus the cutoff interval.

Defined in

NotesReplication

Data type

Variant

Syntax

To get: timedate = notesReplication.CutoffDate

See examples
Example: CutoffDate property


CutoffDelete property

Read-Write. Indicates if documents that are older than cutoff date should be automatically deleted.

Defined in

NotesReplication

Data type

Boolean

Syntax

To get: flag = notesReplication.CutoffDelete

To set: notesReplication.CutoffDelete = flag

Legal values

  • True indicates that documents older than the cutoff date will be deleted automatically

  • False indicates that old documents will not be deleted

See examples
Example: CutoffDelete property


CutoffInterval property

Read-Write. Number of days after which documents are automatically deleted if CutoffDelete is in effect.

Defined in

NotesReplication

Data type

Long

Syntax

To get: interval = notesReplication.CutoffInterval

To set: notesReplication.CutoffInterval = interval

See examples
Example: CutoffInterval property


Disabled property

Read-Write. Indicates if replication is disabled.

Defined in

NotesReplication

Data type

Boolean

Syntax

To get: flag = notesReplication.Disabled

To set: notesReplication.Disabled = flag

Legal values

  • True to disable replication

  • False to enable replication

See examples
Example: Disabled property


IgnoreDeletes property

Read-Write. Indicates if outgoing deletions should not be replicated to other databases.

Defined in

NotesReplication

Data type

Boolean

Syntax

To get: flag = notesReplication.IgnoreDeletes

To set: notesReplication.IgnoreDeletes = flag

Legal values

  • True to not replicate outgoing deletions

  • False to replicate outgoing deletions

See examples
Example: IgnoreDeletes property


IgnoreDestDeletes property

Read-Write. Indicates if incoming deletions should not be replicated to the current database.

Defined in

NotesReplication

Data type

Boolean

Syntax

To get: flag = notesReplication.IgnoreDestDeletes

To set: notesReplication.IgnoreDestDeletes = flag

Legal values

  • True to not replicate incoming deletions

  • False to replicate incoming deletions

See examples
Example: IgnoreDestDeletes property


Priority property

Read-Write. Replication priority.

Defined in

NotesReplication

Data type

Constant of type Long

Syntax

To get: flag = notesReplication.Priority

To set: notesReplication.Priority = flag

Legal values

  • DB_REPLICATION_PRIORITY_LOW (1547)

  • DB_REPLICATION_PRIORITY_MED (1548)

  • DB_REPLICATION_PRIORITY_HIGH (1549)

  • DB_REPLICATION_PRIORITY_NOTSET (1565)

Note The constant DB_REPLICATION_PRIORITY_NOTSET (1565) is obsolete in Release 5.0.1.

See examples
Example: Priority property


ClearHistory method

Clears the replication history.

Defined in

NotesReplication

Syntax

Call notesReplication.ClearHistory()

See examples
Example: ClearHistory method


Reset method

Resets the replication properties to their last saved values.

Defined in

NotesReplication

Syntax

Call notesReplication.Reset()

See examples
Example: Reset method


Save method

Saves the replication properties.

Defined in

NotesReplication

Syntax

Call notesReplication.Save()

Usage

If you don't call the Save method before closing the database, any changes to the replication properties are lost.

See examples
Example: Save method


NotesRichTextItem class

Represents an item of type rich-text.

Base class

Inherits from: NotesItem

Containment

Contained by: NotesDocument

Contains: NotesEmbeddedObject

Property

EmbeddedObjects

Methods

AddNewLine

AddPageBreak

AddTab

AppendDocLink

AppendParagraphStyle

AppendRTItem

AppendStyle

AppendText

EmbedObject

GetEmbeddedObject

GetFormattedText

New

Creation

To create a new NotesRichTextItem object, use one of the following:

  • New

Note The New method is not supported in COM.

  • CreateRichTextItem method in NotesDocument

Given a document, New creates a rich-text item on the document, with the name you specify.

Syntax

Dim variableName As New NotesRichTextItem( notesDocument , name$ )

or

Set notesRichTextItem = New NotesRichTextItem( notesDocument , name$ )

Parameters

notesDocument

The document on which to create a new rich-text item.

name$

String. The name of the new rich-text item.

Access

To access an existing NotesRichTextItem object, use the GetFirstItem method in NotesDocument.

Usage

Because NotesRichTextItem inherits from NotesItem, all of the NotesItem properties and methods can be used on a NotesRichTextItem, too.

When you change the value of a NotesRichTextItem object, the change is not written to disk until you call the Save method for the parent NotesDocument.

If you specify a new NotesRichTextItem object but do not add content to it, an item is not created when the document is saved.

See examples
Examples: NotesRichTextItem class

See also
Using the Domino classes
Working with a rich-text item


EmbeddedObjects property

Read-only. All the embedded objects, object links, and file attachments contained in a rich-text item.

Note EmbeddedObjects is not supported on OS/2 and on the Macintosh.

Defined in

NotesRichTextItem

Data type

Array of NotesEmbeddedObjects

Syntax

To get: notesEmbeddedObjectArray = notesRichTextItem.EmbeddedObjects

Usage

This property includes OLE/1 and OLE/2 embedded objects and object links as well as file attachments.

If you need access to OLE/2 embedded objects that exist in a document but are not part of a rich-text item (for example, because the object was originally created on the document's form), use the EmbeddedObjects property in NotesDocument.

See examples
Examples: EmbeddedObjects property

See also
EmbeddedObjects property (in NotesDocument)
EmbedObject method
GetAttachment method (in NotesDocument)
GetEmbeddedObject method
HasEmbedded property (in NotesDocument)
NotesEmbeddedObject class
Working with an embedded object


AddNewLine method

Appends one or more new lines (carriage returns) to the end of a rich-text item.

Defined in

NotesRichTextItem

Syntax

Call notesRichTextItem.AddNewLine( n% [, forceParagraph ])

Parameter

n%

Note In COM this parameter is optional and defaults to 1.

Integer. The number of new lines to append.

forceParagraph

Boolean. Optional. If True, forces the new line to be a paragraph separator. If False, the new line is added, but does not force a new paragragh. True by default.

See examples
Example: AddNewLine method

See also
AddTab method
AppendText method


AddPageBreak method

Places a hard page break at the end of a NotesRichTextItem.

Note This method is new with Release 5.

Defined in

NotesRichTextItem

Syntax

Call notesRichTextItem.AddPageBreak([RTPStyleNotesRichTextParagraphStyle])

Parameter

RTPStyle

Optional. RichTextParagraphStyle. Starts the new page with the specified paragraph style.

Usage

This method may be called with or without the RichTextParagraphStyle object as a parameter. If the optional parameter is supplied, the new page will begin with the paragraph style.

See examples
Example: AddPageBreak method

See also
Pagination property


AddTab method

Appends one or more tabs to the end of a rich-text item.

Defined in

NotesRichTextItem

Syntax

Call notesRichTextItem.AddTab( n% )

Parameter

n%

Note In COM this parameter is optional and defaults to 1.

Integer. The number of tabs to append.

See examples
Examples: AddTab method

See also
AddNewLine method
AppendText method


AppendDocLink method

Given a database, view, or document to link to, adds a link to the end of a rich-text item.

Defined in

NotesRichTextItem

Syntax

Call notesRichTextItem.AppendDocLink( linkTo, comment$ [, HotSpotText$ ])

Parameters

linkTo

NotesDatabase, NotesView, or NotesDocument. The database, view, or document to which you want to create a link.

comment$

String. The text that appears when a user presses and holds the mouse pointer over the link.

HotSpotText$

Note This parameter is new with Release 5.

Optional. String. If supplied, the HotSpotText will appear in the RichTextItem as boxed text which can be clicked on with the mouse to follow the link. In this case, no other token appears in the text.

See examples
Examples: AppendDocLink method

See also
Working with a rich-text item


AppendParagraphStyle method

Appends a paragraph style at the end of a NotesRichTextItem. Text following the paragraph style is rendered using that paragraph style's attributes.

Note This method is new with Release 5.

Defined in

NotesRichTextItem

Syntax

Call notesRichTextItem.AppendParagraphStyle( RTPStyleNotesRichTextParagraphStyle )

Parameters

RTPStyle

NotesRichTextParagraphStyle object. The paragraph style to be appended.

See examples
Example: AppendParagraphStyle method


AppendRTItem method

Appends the contents of one rich-text item to the end of another rich-text item.

Defined in

NotesRichTextItem

Syntax

Call notesRichTextItem.AppendRTItem( notesRichTextItem2 )

Parameters

notesRichTextItem2

The item to be appended. If you specify Nothing, this method will generate an error.

See examples
Examples: AppendRTItem method

See also
Working with a rich-text item


AppendStyle method

Appends a style to the end of a rich-text item. Text following the style is rendered using that style's attributes until another style is appended.

Note This method is new with Release 4.6.

Defined in

NotesRichTextItem

Syntax

Call notesRichTextItem.AppendStyle( notesRichTextStyle )

Parameters

notesRichTextStyle

NotesRichTextStyle object. The style to append.

Usage

AppendStyle does not affect text appended by AppendRTItem.

See examples
Example: NotesRichTextStyle class

See also
CreateRichTextStyle
NotesRichTextStyle
Working with a rich-text item


AppendText method

Appends text to the end of a rich-text item. The text is rendered with the current style of the item (such as bold or italics).

Defined in

NotesRichTextItem

Syntax

Call notesRichTextItem.AppendText( text$ )

Parameters

text$

String. The text to append.

See examples
Example: AppendText method

See also
AddNewLine method
AddTab method
GetFormattedText method
Working with a rich-text item


EmbedObject method

Given the name of a file or an application, does one of the following:

  • Attaches the file you specify to a rich-text item.

  • Embeds an object in a rich-text item. The object is created using either the application or the file you specify.

  • Places an object link in a rich-text item. The link is created using the file you specify.

Note EmbedObject is not supported on OS/2, on UNIX, and on the Macintosh.

Defined in

NotesRichTextItem

Syntax

Set notesEmbeddedObject = notesRichTextItem.EmbedObject( type%, class$, source$, [ name$ ] )

Parameters

type%

Constant. Indicates if you want to create an attachment, an embedded object, or a object link. May be any of the following:

EMBED_ATTACHMENT (1454)

EMBED_OBJECT (1453)

EMBED_OBJECTLINK (1452)

Note The above constants are also used with the Type property in the NotesEmbeddedObject class.

class$

String.

  • If you are using EMBED_OBJECT and want to create an empty embedded object from an application, use this parameter to specify the name of the application (for example, "1-2-3 Worksheet") and specify an empty string ("") for source$. Case-sensitive.

  • If you are using EMBED_OBJECTLINK or EMBED_ATTACHMENT, specify an empty string ("").

source$

String.

  • If you are using EMBED_OBJECT and want to create an embedded object from a file, use this parameter to specify the name of the file, and specify an empty string ("") for class$.

  • If you are using EMBED_ATTACHMENT or EMBED_OBJECTLINK, use this parameter to specify the name of the file to attach or link.

name$

String. Optional. Name by which you can reference the NotesEmbeddedObject later. This parameter is only used for OLE/2 objects and does not include attachments.

Return value

notesEmbeddedObject

The newly attached file, embedded object, or linked object.

Usage

For this method to work you must set a default view in the database.

Files can be attached on any Notes platform, but objects and links can only be created on platforms supporting OLE.

Files can be embedded as OLE/2 objects only on platforms supporting OLE, but they can be embedded as OLE/1 objects on any Notes platform (if the file is of a supported type, such as a Lotus® application data file).

See examples
Examples: EmbedObject method

See also
EmbeddedObjects property (in NotesDocument)
EmbeddedObjects property (in NotesRichTextItem)
GetAttachment method (in NotesDocument)
GetEmbeddedObject method
HasEmbedded property (in NotesDocument)
NotesEmbeddedObject class
Working with a rich-text item


GetEmbeddedObject method

Given the name of an embedded object or an object link in a rich-text item, returns the corresponding NotesEmbeddedObject.

Note GetEmbeddedObject is not supported on OS/2, on UNIX, and on the Macintosh.

Defined in

NotesRichTextItem

Syntax

Set notesEmbeddedObject = notesRichTextItem.GetEmbeddedObject( name$ )

Parameter

name$

String. The name of the object to find.

To find an embedded object or object link, use the name of the object or link as it appears in the InfoBox, or as designated in the EmbedObject method.

Return value

notesEmbeddedObject

The object, if found. Otherwise, returns Nothing.

Usage

If you modify the object returned by GetEmbeddedObject in your script, the changes are saved, but the rendering of the object in the document is not updated until you manually activate the object.

See examples
Examples: GetEmbeddedObject method

See also
EmbeddedObjects property (in NotesDocument)
EmbeddedObjects property (in NotesRichTextItem)
EmbedObject method
GetAttachment method (in NotesDocument)
HasEmbedded property (in NotesDocument)
NotesEmbeddedObject class
Working with a rich-text item


GetFormattedText method

Returns the contents of a rich-text item as plain text.

Defined in

NotesRichTextItem

Syntax

plainText$ = notesRichTextItem.GetFormattedText( tabstrip, lineLength% )

Parameters

tabstrip

Boolean. If True, tabs are stripped out of the resulting plain text. If False, tabs are not stripped out.

lineLength%

Integer. Number of characters at which to wrap lines of text. By setting this parameter to zero (default), the word wrap is actually occurring at 80 characters (the default line length). Use this parameter only if the line contains whitespace. For example, "This is a school." Words without whitespace will not be wrapped.

Return value

plainText$

String. The contents of the rich-text item, as plain text.

Usage

This method omits non-text data, such as bitmaps and file attachments.

See examples
Examples: GetFormattedText method

See also
AppendText method
Text property (in NotesItem)
Working with a rich-text item


NotesRichTextParagraphStyle class

Represents rich-text paragraph attributes.

Note This class is new with Release 5.

Containment

Contained by: NotesSession

Contains: NotesRichTextTab

Properties

Alignment

FirstLineLeftMargin

InterLineSpacing

LeftMargin

Pagination

RightMargin

SpacingAbove

SpacingBelow

Tabs

Methods

ClearAllTabs

SetTab

SetTabs

Creation

To create a new NotesRichTextParagraphStyle object, use the CreateRichTextParagraphStyle method in NotesSession.

Access

Use a NotesRichTextParagraphStyle object with the AppendParagraphStyle method in NotesRichTextItem.

See examples
Example: NotesRichTextParagraphStyle class


Alignment property

Read-Write. Alignment attribute of a rich-text paragraph.

Defined in

NotesRichTextParagraphStyle

Data type

Constant of type Integer

Syntax

To get: alignment% = notesRichTextParagraphStyle.Alignment

To set: notesRichTextParagraphStyle.Alignment = alignment%

Legal values

  • ALIGN_CENTER (3)

  • ALIGN_FULL (2)

  • ALIGN_LEFT (0)

  • ALIGN_NOWRAP (4)

  • ALIGN_RIGHT (1)

See examples
Example: Alignment property

See also
Alignment property


FirstLineLeftMargin property

Read-Write. First line left margin attribute of a rich-text paragraph.

Defined in

NotesRichTextParagraphStyle

Data type

Long

Syntax

To get: margin = notesRichTextParagraphStyle.FirstLineLeftMargin

To set: notesRichTextParagraphStyle.FirstLineLeftMargin = margin

Legal values

  • RULER_ONE_INCH (1440)

  • RULER_ONE_CENTIMETER (567)

Usage

The unit of measure for this property is a "twip," where 1440 twips = 1 inch and 537 twips = 1 centimeter.

The above constants are also used with the LeftMargin and RightMargin properties and the SetTab and SetTabs methods in the NotesRichTextParagraphStyle class, as well as the Position property in the NotesRichTextTab class.

See examples
Example: FirstLineLeftMargin property

See also
LeftMargin property
RightMargin property


InterLineSpacing property

Read-Write. Interline spacing attribute of a rich-text paragraph.

Defined in

NotesRichTextParagraphStyle

Data type

Constant of type Integer

Syntax

To get: spacing% = notesRichTextParagraphStyle.InterLineSpacing

To set: notesRichTextParagraphStyle.InterLineSpacing = spacing%

Legal values

  • SPACING_DOUBLE (4)

  • SPACING_ONE_POINT_50 (2)

  • SPACING_SINGLE (0)

The above constants are also used with the SpacingAbove and SpacingBelow properties of the NotesRichTextParagraphStyle class.

See examples
Example: InterLineSpacing property

See also
SpacingAbove property
SpacingBelow property
Spacing property


LeftMargin property

Read-Write. Left margin attribute of a rich-text paragraph.

Defined in

NotesRichTextParagraphStyle

Data type

Long

Syntax

To get: margin = notesRichTextParagraphStyle.LeftMargin

To set: notesRichTextParagraphStyle.LeftMargin = margin

Legal values

  • RULER_ONE_INCH (537)

  • RULER_ONE_CENTIMETER (567)

Usage

The unit of measure for this property is a "twip," where 1440 twips = 1 inch and 537 twips = 1 centimeter.

The above constants are also used iwith the FirstLineLeftMargin and RightMargin properties and the SetTab and SetTabs methods in the NotesRichTextParagraphStyle class, as well as the Position property in the NotesRichTextTab class.

See examples
Example: LeftMargin property

See also
FirstLineLeftMargin property
RightMargin property


Pagination property

Read-Write. Pagination attribute of a rich-text paragraph.

Defined in

NotesRichTextParagraphStyle

Data type

Constant of type Integer

Syntax

To get: pagination% = notesRichTextParagraphStyle.Pagination

To set: notesRichTextParagraphStyle.Pagination = pagination%

Legal values

  • PAGINATE_BEFORE (1)

  • PAGINATE_DEFAULT (0)

  • PAGINATE_KEEP_TOGETHER (4)

  • PAGINATE_KEEP_WITH_NEXT (2)

Usage

You can set one of the above pagination options before you call the AddPageBreak method in NotesRichTextItem.


RightMargin property

Read-Write. Right margin attribute of a rich-text paragraph.

Defined in

NotesRichTextParagraphStyle

Data type

Long

Syntax

To get: margin = notesRichTextParagraphStyle.RightMargin

To set: notesRichTextParagraphStyle.RightMargin = margin

Legal values

  • RULER_ONE_INCH (1440)

  • RULER_ONE_CENTIMETER (537)

Usage

The unit of measure for this property is a "twip," where 1440 twips = 1 inch and 537 twips = 1 centimeter.

The above constants are also used with the FirstLineLeftMargin and LeftMargin properties and the SetTab and SetTabs methods in the NotesRichTextParagraphStyle class, as well as the Position property in the NotesRichTextTab class.

See examples
Example: RightMargin property

See also
FirstLineLeftMargin property
LeftMargin property


SpacingAbove property

Read-Write. Spacing above attribute of a rich-text paragraph.

Defined in

NotesRichTextParagraphStyle

Data type

Constant of type Integer

Syntax

To get: spacing% = notesRichTextParagraphStyle.SpacingAbove

To set: notesRichTextParagraphStyle.SpacingAbove = spacing%

Legal values

  • SPACING_DOUBLE (4)

  • SPACING_ONE_POINT_50 (2)

  • SPACING_SINGLE (0)

The above constants are also used with the InterLineSpacing and SpacingBelow properties of the NotesRichTextParagraphStyle class.

See examples
Example: SpacingAbove property

See also
InterLineSpacing property
Spacing property
SpacingBelow property


SpacingBelow property

Read-write. Spacing below attribute of a rich-text paragraph.

Defined in

NotesRichTextParagraphStyle

Data type

Constant of type integer

Syntax

To get: spacing% = notesRichTextParagraphStyle.SpacingBelow

To set: notesRichTextParagraphStyle.SpacingBelow = spacing%

Legal values

  • SPACING_DOUBLE (4)

  • SPACING_ONE_POINT_50 (2)

  • SPACING_SINGLE (0)

The above constants are also used with the InterLineSpacing and SpacingAbove properties of NotesRichTextParagraphStyle class.

See examples
Example: SpacingBelow property

See also
InterLineSpacing property
SpacingAbove property
Spacing property


Tabs property

Read-only. Tabs in a rich-text paragraph style.

Defined in

NotesRichTextParagraphStyle

Data type

Variant

Syntax

To get: tabs = notesRichTextParagraphStyle.Tabs


ClearAllTabs method

Clears all tabs in a rich-text paragraph style.

Defined in

NotesRichTextParagraphStyle

Syntax

Call notesRichTextParagraphStyle.ClearAllTabs()

See examples
Example: ClearAllTabs method

See also
SetTab method
SetTabs method


SetTab method

Sets a tab in a rich-text paragraph style.

Defined in

NotesRichTextParagraphStyle

Syntax

Call notesRichTextParagraphStyle.SetTab( position, type% )

Parameters

position

Long. Position of the tab.

  • RULER_ONE_CENTIMETER (567)

  • RULER_ONE_INCH (1440)

type%

Note In COM, this parameter is optional.

Constant of type Integer. Type of tab.

  • TAB_CENTER (3)

  • TAB_DECIMAL (2)

  • TAB_LEFT (0)

  • TAB_RIGHT (1)

Usage

The unit of measure for this property is a "twip," where 1440 twips = 1 inch and 537 twips = 1 centimeter.

The above Ruler constants are also used with the LeftMargin, RightMargin, and FirstLineLeftMargin properties and the SetTabs method in the NotesRichTextParagraphStyle class, as well as the Position property in the NotesRichTextTab class.

See examples
Example: SetTab method

See also
SetTabs method
ClearAllTabs method


SetTabs method

Sets tabs at even intervals in a rich-text paragraph style.

Defined in

NotesRichTextParagraphStyle

Syntax

Call notesRichTextParagraphStyle.SetTabs( number%, startposition, interval, type% )

Parameters

number%

Integer. Number of tabs to be set.

startposition

Long. Position of the first tab.

  • RULER_ONE_CENTIMETER (567)

  • RULER_ONE_INCH (1440)

interval

Note In COM, this parameter is optional and defaults to 1.

Long. Interval between tabs.

  • RULER_ONE_CENTIMETER (567)

  • RULER_ONE_INCH (1440)

type%

Constant of type Integer. Type of tab.

  • TAB_CENTER (3)

  • TAB_DECIMAL (2)

  • TAB_LEFT (0)

  • TAB_RIGHT (1)

Usage

The unit of measure for this property is a "twip," where 1440 twips = 1 inch and 537 twips = 1 centimeter.

The above Ruler constants are also used with the LeftMargin, RightMargin, and FirstLineLeftMargin properties and the SetTab method in the NotesRichTextParagraphStyle class, as well as the Position property in the NotesRichTextTab class.

See examples
Example: SetTabs method

See also
SetTab method
ClearAllTabs method


NotesRichTextStyle class

Represents rich-text attributes.

Note This class is new with Release 4.6.

Containment

Contained by: NotesSession

Properties

Bold

Effects

FontSize

Italic

NotesColor

NotesFont

Parent

PassThruHTML

Strikethrough

Underline

Creation

To create a new NotesRichTextStyle object, use the CreateRichTextStyle method in NotesSession.

Access

Use a NotesRichTextStyle object with the AppendStyle method of NotesRichTextItem.

At creation, all the NotesRichTextStyle properties are STYLE_NO_CHANGE.

See examples
Example: NotesRichTextStyle class

See also
Using the Domino classes
Working with a rich-text item


Bold property

Read-Write. Bold rich-text attribute.

Note This property is new with Release 4.6.

Defined in

NotesRichTextStyle

Data type

Boolean or constant of type Integer

Syntax

To get: flag = notesRichTextStyle.Bold

To set: notesRichTextStyle.Bold = flag

Legal values

  • True for bold

  • False for non-bold

  • STYLE_NO_CHANGE (255) to maintain the previous state

See examples
Example: Bold property

See also
Working with a rich-text item


Effects property

Read-Write. Effects as listed below.

Note This property is new with Release 4.6.

Defined in

NotesRichTextStyle

Data type

Constant of type Integer

Syntax

To get: effects = notesRichTextStyle.Effects

To set: notesRichTextStyle.Effects = effects

Legal values

  • EFFECTS_EMBOSS (4)

  • EFFECTS_EXTRUDE (5)

  • EFFECTS_NONE (0)

  • EFFECTS_SHADOW (3)

  • EFFECTS_SUBSCRIPT (2)

  • EFFECTS_SUPERSCRIPT (1)

  • STYLE_NO_CHANGE (255)

See examples
Example: Effects property

See also
Working with a rich-text item


FontSize property

Read-Write. Font size in points.

Note This property is new with Release 4.6.

Defined in

NotesRichTextStyle

Data type

Integer

Syntax

To get: fontSize% = notesRichTextStyle.FontSize

To set: notesRichTextStyle.FontSize = fontSize%

Legal values

  • An integer value representing a font size of range 1 to 250.

  • STYLE_NO_CHANGE (255) to maintain the previous state.

See examples
Example: FontSize property

See also
Working with a rich-text item


Italic property

Read-Write. Italic rich-text attribute.

Note This property is new with Release 4.6.

Defined in

NotesRichTextStyle

Data type

Boolean or constant of type Integer

Syntax

To get: flag = notesRichTextStyle.Italic

To set: notesRichTextStyle.Italic = flag

Legal values

  • True for italic

  • False for non-italic

  • STYLE_NO_CHANGE (255) to maintain the previous state

See examples
Example: Italic property

See also
Working with a rich-text item


NotesColor property

Read-Write. Color rich-text attribute as listed below.

Note This property is new with Release 4.6.

Defined in

NotesRichTextStyle

Data type

Constant of type Integer

Syntax

To get: notesColor= notesRichTextStyle.NotesColor

To set: notesRichTextStyle.NotesColor = notesColor

Legal values

  • COLOR_BLACK (0)

  • COLOR_BLUE (4)

  • COLOR_CYAN (7)

  • COLOR_DARK_BLUE (10)

  • COLOR_DARK_CYAN (13)

  • COLOR_DARK_GREEN (9)

  • COLOR_DARK_MAGENTA (11)

  • COLOR_DARK_RED (8)

  • COLOR_DARK_YELLOW (12)

  • COLOR_GRAY (14)

  • COLOR_GREEN (3)

  • COLOR_LIGHT_GRAY (15)

  • COLOR_MAGENTA (5)

  • COLOR_RED (2)

  • COLOR_WHITE (1)

  • COLOR_YELLOW (6)

  • STYLE_NO_CHANGE (255)

Note These values are also used with the FontColor property in the NotesViewColumn class, and the BackgroundColor property of the NotesView class.

See examples
Example: NotesColor property

See also
Working with a rich-text item


NotesFont property

Read-Write. Font rich-text attribute as listed below.

Note This property is new with Release 4.6.

Defined in

NotesRichTextStyle

Data type

Constant of type Integer

Syntax

To get: notesFont = notesRichTextStyle.NotesFont

To set: notesRichTextStyle.NotesFont = notesFont

Legal values

  • FONT_COURIER (4)

  • FONT_HELV (1)

  • FONT_ROMAN (0)

  • STYLE_NO_CHANGE (255)

See examples
Example: NotesFont property

See also
Working with a rich-text item


Parent property

Read-only. The session that contains a RichTextStyle object.

Note This property is new with Release 5.0.2b.

Note This property is supported in COM only.

Defined in

NotesRichTextStyle

Data type

NotesSession

Syntax

To get: Set notesSession = notesRichTextStyle.Parent

See examples
Examples: Parent property


PassThruHTML property

Read-Write. HTML attribute as listed below.

Note This property is new with Release 5.

Defined in

NotesRichTextStyle

Data type

Boolean or constant of type Integer

Syntax

To get: flagIntegerConstant = notesRichTextStyle.PassThruHTML

To set: notesRichTextStyle.PassThruHTML = flagIntegerConstant

Legal values

  • True for pass-thru HTML

  • False for non-pass-thru HTML

  • STYLE_NO_CHANGE (255) to maintain the previous state

Usage

HTML text may be embedded in a NotesRichTextItem by setting this property and then calling the AppendText method. These attributes are useful when the document is served up to the Web. The text may be visible or invisible when displayed by the Domino Designer Editor, controlled by View options.

See examples
Example: PassThruHTML property


Strikethrough property

Read-Write. Strikethrough rich-text attribute.

Note This property is new with Release 4.6.

Defined in

NotesRichTextStyle

Data type

Boolean or constant of type Integer

Syntax

To get: flag = notesRichTextStyle.Strikethrough

To set: notesRichTextStyle.Strikethrough = flag

Legal values

  • True for strikethrough

  • False for non-strikethrough

  • STYLE_NO_CHANGE (255) to maintain the previous state

See examples
Example: Strikethrough property

See also
Working with a rich-text item


Underline property

Read-Write. Underline rich-text attribute.

Note This property is new with Release 4.6.

Defined in

NotesRichTextStyle

Data type

Boolean or constant of type Integer

Syntax

To get: flag = notesRichTextStyle.Underline

To set: notesRichTextStyle.Underline = flag

Legal values

  • True for underline

  • False for non-underline

  • STYLE_NO_CHANGE (255) to maintain the previous state

See examples
Example: Underline property

See also
Working with a rich-text item


NotesRichTextTab class

Represents rich-text tab attributes.

Note This class is new with Release 5.

Containmet

Contained by: NotesRichTextParagraphStyle

Properties

Position

Type

Methods

Clear

Creation

To create a new NotesRichTextTab object, use SetTab method or SetTabs method in NotesRichTextParagraphStyle.

Access

Use a RichTextTab object obtained from Tabs property and ClearAllTabs method in NotesRichTextParagraphStyle.


Position property

Read-only. Position of a tab in a rich-text paragraph style.

Defined in

NotesRichTextTab

Data type

Long

Syntax

To get: position& = notesRichTextTab.Position

Legal values

  • RULER_ONE_INCH (1440)

  • RULER_ONE_CENTIMETER (537)

Usage

The unit of measure for this property is a "twip," where 1440 twips = 1 inch and 537 twips = 1 centimeter.

The above Ruler constants are also used with the LeftMargin, RightMargin, and FirstLineLeftMargin properties and the SetTab and SetTabs methods in the NotesRichTextParagraphStyle class.


Type property

Read-only. Type of tab.

Defined in

NotesRichTextTab

Data type

Integer

Syntax

To get: type% = notesRichTextTab.Type

Legal values

  • TAB_CENTER (3)

  • TAB_DECIMAL (2)

  • TAB_LEFT (0)

  • TAB_RIGHT (1)

Note The above constants are also used with the SetTab and SetTabs methods of the NotesRichTextParagraphStyle class.


Clear method

Clears a tab.

Defined in

NotesRichTextTab

Syntax

Call notesRichTextTab.Clear()


NotesSession class

Represents the environment of the current script, providing access to environment variables, Address Books, information about the current user, and information about the current Notes platform and release number.

Containment

Contains: NotesAgent, NotesDatabase, NotesDateRange, NotesDateTime, NotesDbDirectory, NotesDocumentCollection, NotesInternational, NotesLog, NotesNewsletter, NotesRichTextParagraphStyle, NotesTimer

Properties

AddressBooks

CommonUserName

ConvertMime

CurrentAgent

CurrentDatabase

DocumentContext

EffectiveUserName

HttpURL

International

IsOnServer

LastExitStatus

LastRun

NotesBuildVersion

NotesURL

NotesVersion

Platform

SavedData

ServerName

URLDatabase

UserName

UserNameList

UserNameObject

Methods

CreateDateRange

CreateDateTime

CreateLog

CreateName

CreateNewsletter

CreateRegistration

CreateRichTextParagraphStyle

CreateRichTextStyle

CreateTimer

Evaluate

FreeTimeSearch

GetDatabase

GetDbDirectory

GetEnvironmentString

GetEnvironmentValue

Initialize

InitializeUsingNotesUserName

New

Resolve

SetEnvironmentVar

UpdateProcessedDoc

Creation and access

To access the current session, use New.

Syntax

Dim variableName As New NotesSession

or

Set notesSession = New NotesSession

To access the current session from a NotesDatabase object, use the Parent property in NotesDatabase.

Usage

Since there can only be one session per script, the New method always returns the same object each time you call it.

See examples
Example: NotesSession class

See also
Using the Domino classes


AddressBooks property

Read-only. The Address Books, both public and personal, that are known to the current script.

Defined in

NotesSession

Data type

Array of NotesDatabases

Syntax

To get: notesDatabaseArray = notesSession.AddressBooks

Usage

To find out if an address book is public or personal, use the IsPublicAddressBook and IsPrivateAddressBook properties of a database. You can test these properties before opening the database.

The databases in the AddressBooks array are closed. To access all the properties and methods of one of the databases, you must open the database with the Open or OpenIfModified method in NotesDatabase. The following properties, however, are available even when the database is closed:

  • FileName

  • FilePath

  • IsOpen

  • IsPublicAddressBook

  • IsPrivateAddressBook

  • Parent

  • Server

If the script runs on a workstation, both public and personal address books are included. If the script runs on a server, only public address books on the server are included.

See examples
Examples: AddressBooks property

See also
NotesDatabase class
Open method
OpenIfModified method


CommonUserName property

Read-only. The common name portion of the current user's name.

Defined in

NotesSession

Data type

String

Syntax

To get: commonName$ = notesSession.CommonUserName

Usage

When a script runs on the workstation, the user is the person running Notes. When a script runs on the server, the user is the server. For agents that run on a server, therefore, this property returns the common name of the server.

If the user's name is flat (non-hierarchical), the CommonUserName is the same as the UserName.

See examples
Examples: CommonUserName property

See also
UserName property
EffectiveUserName property


ConvertMime property

Read-Write. Indicates if items of type MIME_PART are converted to rich text upon NotesItem instantiation.

Note This property is new with Release 5.

Defined in

NotesSession

Data type

Boolean

Syntax

To get: flag = notesSession.ConvertMime

To set: notesSession.ConvertMime = flag

Legal values

  • (Default) True indicates that MIME items are converted to rich text

  • False indicates that MIME items are not converted

See examples
Examples: NotesMIMEEntity class

See also
Accessing session properties
Type property
NotesMIMEEntity class


CurrentAgent property

Read-only. The agent that's currently running.

Note This property is not implemented in COM.

Defined in

NotesSession

Data type

NotesAgent

Syntax

To get: notesAgent = notesSession.CurrentAgent

See examples
Examples: CurrentAgent property

See also
Accessing agents
CurrentDatabase property
LastExitStatus property
LastRun property
SavedData property


CurrentDatabase property

Read-only. The database in which the current script resides. This database may or may not be open.

Note This property is not implemented in COM.

Defined in

NotesSession

Data type

NotesDatabase class

Syntax

To get: notesDatabase = notesSession.CurrentDatabase

Usage

This property allows you to access a database without having to place its server and file name in a script. Using CurrentDatabase can make scripts more easily portable from one database to another.

See examples
Examples: CurrentDatabase property

See also
CurrentAgent property
Opening and closing a database


DocumentContext property

Read-only. The in-memory document when an agent starts.

Note This property is not implemented in COM.

Defined in

NotesSession

Data type

NotesDocument

Syntax

To get: notesDocument = notesSession.DocumentContext

Usage

For an agent activated in a view through the Notes client UI, the in-memory document is the document highlighted in the view.

For an agent run from a browser with the OpenAgent URL command, the in-memory document is a new document containing an item for each CGI (Common Gateway Interface) variable supported by Domino. Each item has the name and current value of a supported CGI variable. (No design work on your part is needed; the CGI variables are available automatically.)

For an agent run from a browser with @Command[ToolsRunMacro], the in-memory document is the current document. In the case of WebQueryOpen, this is the document before Domino converts it to HTML and sends it to the browser; in the case of WebQuerySave, this is the document before Domino saves it. If the form on which the document is based contains a field named the same as a Domino-supported CGI variable, the in-memory document also contains the value of that variable. (You must explicitly design the CGI variables into the form, for example, as hidden fields.)

See "Table of CGI Variables" in the printed book Application Development with Domino Designer for a list of the Domino-supported CGI variables.

Through the C or C++ API, an external program can create an in-memory document, then run an agent. The agent can use this property to access the in-memory document.

You cannot use the encrypt and remove methods on the Document object returned by DocumentContext, nor use the compact method on the Database object that contains the Document object returned by DocumentContext.

See examples
Examples: DocumentContext property


EffectiveUserName property

Read-only. The user name that is in effect for the current script.

  • For a script running on a workstation, this is the name of the current user.

  • For a script running on a server, this is the name of the script's owner (the person who last saved the script).

Defined in

NotesSession

Data type

String

Syntax

To get: name$ = notesSession.EffectiveUserName

Usage

In general, the EffectiveUserName and UserName properties return the same value for a given script. The exceptions are agent scripts that run on a server, where EffectiveUserName is the name of the script's owner and UserName is the name of the server on which the script is running.

If the user name is hierarchical, this property returns the fully distinguished name. To get only the common name, use the CommonUserName property in NotesSession. To get only the common name of the owner of a script that runs on a server, use the CommonOwner property in NotesAgent.

See examples
Example: EffectiveUserName property

See also
CommonOwner property (in NotesAgent)
CommonUserName property
UserName property


HttpURL property

Read-only. The HTTP URL of a session.

Note This property is new with Release 5.0.2b.

Note This property is supported in COM only.

Defined in

NotesSession

Data type

String

Syntax

To get: url$ = notesSession.HttpURL


International property

Read-only. The international (regional) settings for your operating environment.

Defined in

NotesSession

Data type

NotesInternational

Syntax

To get: notesInternational = notesSession.International

See examples
Example: NotesInternational class

See also
Accessing international settings


IsOnServer property

Read-only. Indicates if a script is running on a server.

Defined in

NotesSession

Data type

Boolean

Syntax

To get: flag = notesSession.IsOnServer

Legal values

  • True indicates that the script is running on a server

  • False indicates that the script is running on a workstation

Usage

A script is running on a server if it is part of an agent on a server-based database, and the agent has one of the following triggers:

  • When new mail arrives

  • When documents have been created or modified

  • On schedule hourly, daily, weekly, or monthly

The IsOnServer property returns False for scripts activated by the paste trigger.

See examples
Example: IsOnServer property

See also
Server property (in NotesDatabase)
ServerName property (in NotesAgent)


LastExitStatus property

Read-only. The exit status code returned by the Agent Manager the last time the current agent ran.

Defined in

NotesSession

Data type

Long

Syntax

To get: code% = notesSession.LastExitStatus

Usage

This property returns 0 if the agent ran without errors.

See examples
Example: LastExitStatus property

See also
LastRun property


LastRun property

Read-only. The date when the current agent was last executed.

Defined in

NotesSession

Data type

Variant of type DATE

Syntax

To get: dateV = notesSession.LastRun

Usage

If the script has never been run before, this property returns a variant containing the date-time value 12:00:00 AM.

See examples
Example: LastRun property

See also
LastExitStatus property
LastRun property (in NotesAgent)


NotesBuildVersion property

Read-only. The Notes build version in which a selected document resides.

Note This method is new with Release 5.

Defined in

NotesSession

Data type

Long

Syntax

To get: long = notesSession.NotesBuildVersion

Usage

If the script runs on a workstation, this property returns the workstation's release number. If the script runs on a server, it returns the server's release number.

See examples
Example: NotesBuildVersion property


NotesURL property

Read-only. The Notes URL of a session.

Note This property is new with Release 5.0.2b.

Note This property is supported in COM only.

Defined in

NotesSession

Data type

String

Syntax

To get: url$ = notesSession.NotesURL


NotesVersion property

Read-only. The release of Notes in which the current script is running.

Defined in

NotesSession

Data type

String

Syntax

To get: version$ = notesSession.NotesVersion

Usage

If the script runs on a workstation, this property returns the workstation's release number. If the script runs on a server, it returns the server's release number.

See examples
Example: NotesVersion property


Platform property

Read-only. The name of the platform in which the current script is running.

Defined in

NotesSession

Data type

String

Syntax

To get: platform$ = notesSession.Platform

Legal values

"Macintosh" | Macintosh®
"MS-DOS" | MS-DOS®
"Netware" | NetWare®
"OS/2v1" | OS/2® 16-bit
"OS/2v2" | OS/2 32-bit
"Windows/16" | Windows 16-bit
"Windows/32" | Windows 32-bit
"UNIX" | UNIX® (Sun™, SCO®, HP-UX™, AIX®)
"Linux" | UNIX®

Usage

If the script runs on a workstation, this property returns the name of the workstation's platform. If the script runs on a server, it returns the name of the server's platform.

See examples
Example: Platform property

See also
NotesVersion property


SavedData property

Read-only. A document that an agent script uses to store information inbetween invocations. The script can use the information in this document the next time the script runs.

Defined in

NotesSession

Data type

NotesDocument

Syntax

To get: notesDocument = notesSession.SavedData

Usage

This property is valid only for agent scripts. In any other script, SavedData returns Nothing.

The SavedData document is created when you save an agent, and it is stored in the same database as the agent. The document replicates, but is not displayed in views.

Each time you edit and re-save an agent, its SavedData document is deleted and a new, blank one is created. When you delete an agent, its SavedData document is deleted.

See examples
Examples: SavedData property


ServerName property

Read-only. The full name of the server that the session is running on.

Note This property is new with Release 5.0.2b.

Note This property is supported in COM only.

Defined in

NotesSession

Data type

String

Syntax

To get: name$ = notesSession.ServerName

Usage

If the server name is hierarchical, this property returns the fully distinguished name.

This property is null if the session is not running on a server.

See examples
Examples: ServerName property


URLDatabase property

Read-only. A database object representing the default Web Navigator database.

Note This property is new with Release 5.0.2b.

Note This property is supported in COM only.

Defined in

NotesSession

Data type

NotesDatabase

Syntax

To get: Set notesDatabase = notesSession.URLDatabase

See examples
Examples: URLDatabase property


UserName property

Read-only. The current user's name.

  • For a script running on a workstation, this is the name of the current user.

  • For a script running on a server, this is the name of the server.

Defined in

NotesSession

Data type

String

Syntax

To get: name$ = notesSession.UserName

Usage

If the user name is hierarchical, this property returns the fully distinguished name. To get only the common name, use the CommonUserName property in NotesSession. To get only the common name of the owner of a script that runs on a server, use the CommonOwner property in NotesAgent.

See examples
Examples: UserName property

See also
CommonOwner property (in NotesAgent)
CommonUserName property
CurrentAccessLevel property (in NotesDatabase)
EffectiveUserName property


UserNameList property

Read-only. Returns all the usernames on a session, including primary and alternate names.

Note This property is new with Release 5.

Note This property is not implemented in COM.

Defined in

NotesSession

Data type

Array of NotesName

Syntax

To get: notesNameArray = notesSession.UserNameList

Usage

The first element of this array is associated with the primary username, and the second element is associated with the alternate username. For a user who has only the primary username, UserNameList property returns an array of a single NotesName element.


UserNameObject property

Read-only. The name, in the form of a NotesName object, of the user or server that created the session.

Note This property is new with Release 5.0.2b.

Note This property is supported in COM only.

Defined in

NotesSession

Data type

NotesName

Syntax

To get: Set notesName = notesSession.UserNameObject

See examples
Examples: UserNameObject property


CreateDateRange method

Creates a new NotesDateRange object.

Defined in

NotesSession

Syntax

Set notesDateRange = notesSession.CreateDateRange( )

Return value

notesDateRange

The newly-created date range object.

Usage

For more information, see the NotesDateRange class.

See examples
Examples: NotesDateRange class

See also
Converting Between Notes and LotusScript time
NotesDateRange class


CreateDateTime method

Given a string that represents the date and time you want, creates a new NotesDateTime object that represents that date and time. When used with OLE automation, this method allows you to create a NotesDateTime object without using New.

Note This method is not supported in COM.

Defined in

NotesSession

Syntax

Set notesDateTime = notesSession.CreateDateTime( dateTime$ )

Parameter

dateTime$

String. The date and time you want the object to represent. If you use an empty string (""), the date is set to a wildcard date. The Notes date-time expressions "Today" and "Yesterday" are supported.

Return value

notesDateTime

The newly-created date-time.

Usage

For more information on acceptable formats for the dateTime$ parameter, see the NotesDateTime class.

See examples
Example: CreateDateTime method

See also
NotesDateTime class


CreateLog method

Creates a new NotesLog object with the name you specify. When used with OLE automation, this method allows you to create a NotesLog object without using New.

Defined in

NotesSession

Syntax

Set notesLog = notesSession.CreateLog( programName$ )

Parameter

programName$

String. A name that identifies the script whose actions and errors you want to log.

Return value

notesLog

The newly-created log.

Usage

For more information, see the NotesLog class.

See examples
Example: CreateLog method

See also
NotesLog class


CreateName method

Creates a new NotesName object. When used with OLE automation, this method allows you to create a NotesName object without using the New method of NotesName.

Defined in

NotesSession

Syntax

Set notesName = notesSession.CreateName( name$ , [ language$ ] )

Parameters

name$

String. A user or server name. If the name is not in the format of an abbreviated or canonical hierarchical name, it is treated as a flat name.

language$

String. Optional. The language code associated with a username.

Usage

For more information, see the NotesName class.

See examples
Example: CreateName method

See also
Representing a name
NotesName class


CreateNewsletter method

Given a NotesDocumentCollection containing the documents you want, creates a new NotesNewsletter. When used with OLE automation, this method allows you to create a NotesNewsletter object without using New.

Defined in

NotesSession

Syntax

Set notesNewsletter = notesSession.CreateNewsletter( notesDocumentCollection )

Parameter

notesDocumentCollection

The documents that you want included in the newsletter. Can be Nothing.

Return value

notesNewsletter

The newly-created newsletter.

Usage

For more information, see the NotesNewsletter class.

See examples
Example: CreateNewsletter method

See also
NotesDocumentCollection class
NotesNewsletter class


CreateRegistration method

Creates a new NotesRegistration object.

Note This method is new with Release 5.0.2b.

Note This method is supported in COM only.

Defined in

NotesSession

Syntax

Set notesRegistration = notesSession.CreateRegistration( )

Return value

NotesRegistration

The newly-created registration object.

Usage

For more information, see the NotesRegistration class.


CreateRichTextParagraphStyle method

Creates a new RichTextParagraphStyle object.

Note This method is new with Release 5.

Defined in

NotesSession

Syntax

Set notesRichTextParagraphStyle =notesSession.CreateRichTextParagraphStyle( )

Return value

notesRichTextParagraphStyle

The newly created RichTextParagraphStyle object.

Usage:

Refer to the NotesRichTextParagraphStyle class for descriptions and examples.

See examples
Example: CreateRichTextParagraphStyle method


CreateRichTextStyle method

Creates a NotesRichTextStyle object.

Note This method is new with Release 4.6.

Defined in

NotesSession

Syntax

Set notesRichTextStyle = notesSession.CreateRichTextStyle( )

Return value

notesRichTextStyle

The newly-created NotesRichTextStyle object.

Usage

For more information, see the NotesRichTextStyle class.

See examples
Example: NotesRichTextStyle class

See also
AppendStyle
NotesRichTextStyle
Working with a rich-text item


CreateTimer method

Creates a NotesTimer object.

Note This method is not supported in COM.

Defined in

NotesSession

Syntax

Set notesTimer = notesSession.CreateTimer( )

Return value

notesTimer

The newly-created timer.

Usage

Since this method has no parameters, you must set the Interval and Comment properties as required.

For more information, see the NotesTimer class.

See examples
Examples: CreateTimer method

See also
NotesTimer class


Evaluate method

Evaluates a Domino formula.

Note This method is new with Release 5.0.2b.

Note This method is supported in COM only.

Defined in

NotesSession

Syntax

variant = notesSession.Evaluate( formula$, doc )

Parameters

formula$

String. The formula.

doc

NotesDocument. The formula context. Cannot be null.

Return value

variant

The result of the evaluation. A scalar result is returned.

Usage

The formula takes the field from the specified document.

@Functions that affect the user interface do not work in the Evaluate method. These include: @Command, @DbManager, @DbName, @DbTitle, @DDEExecute, @DDEInitiate, @DDEPoke, @DDETerminate, @DialogBox, @PickList, @PostedCommand, @Prompt, and @ViewTitle.

You cannot change a document with the Evaluate method; you can only get a result. To change a document, write the result to the document with a method such as NotesDocument.ReplaceItemValue.

See examples
Examples: Evaluate method


FreeTimeSearch method

Searches for free time slots for calendaring and scheduling.

Defined in

NotesSession

Syntax

Set notesDateRange = notesSession.FreeTimeSearch( window, duration, names [, firstfit ] )

Parameters

window

NotesDateRange. Starting and ending times within which to search for a match. If you specify Nothing, this method wiil generate an error.

duration

Integer. The length in minutes of the free-time interval you want to schedule.

names

String or an array of strings. The name or names of the people or groups whose free time you want to schedule. If you specify Nothing, this method wiil generate an error.

firstfit

Boolean. True if you just want the first matching date range. False if you want all matching times. Defaults to False.

Return value

notesDateRange

Array of NotesDateRange objects, or an array of empty objects if there are no matches.

See examples
Example: FreeTimeSearch method

See also
NotesDateRange class


GetDatabase method

Creates a NotesDatabase object that represents the database located at the server and file name you specify, and opens the database, if possible. When used with OLE automation, this method allows you to create a NotesDatabase object without using New. It does not create a new database on disk.

Defined in

NotesSession

Syntax

Set notesDatabase = notesSession.GetDatabase( server$, dbfile$ [, createonfail ] )

Parameters

server$

String. The name of the server on which the database resides. Use an empty string ("") to indicate a database on the current computer: if the script runs on the workstation, the empty string indicates a local database; if the script runs on a server, it indicates a database on that server.

dbfile$

String. The file name and location of the database within the Notes data directory. Use empty strings for both dbfile$ and server$ if you want to open the database later. Use a full path name if the database is not within the Notes data directory.

createonfail

Note This parameter is new with Release 5.

Boolean. Optional. Specify True (default) to create the database if it does not exist.

Return value

notesDatabase

A NotesDatabase object that can be used to access the database you've specified.

  • If a database exists at the server$ and dbfile$ specified, the NotesDatabase object is open, and the script can access all its properties and methods.

  • If a database does not exist at the server$ and dbfile$ specified, the NotesDatabase object is closed. To create a new database at the specified location if one does not exist, specify True for createonfail.

Usage

For more information, see the NotesDatabase class.

See examples
Example: GetDatabase method

See also
NotesDatabase class


GetDbDirectory method

Creates a new NotesDbDirectory object using the name of the server you want to access. When used with OLE automation, this method allows you to create a NotesDbDirectory object without using New.

Defined in

NotesSession

Syntax

Set notesDbDirectory = notesSession.GetDbDirectory( serverName$ )

Parameter

serverName$

String. The name of the server whose database files you want to navigate. Use an empty string ("") to indicate the current computer.

Return value

notesDbDirectory

The directory on the server you specified.

Usage

For more information, see the NotesDbDirectory class.

See examples
Example: GetDbDirectory method

See also
NotesDbDirectory class


GetEnvironmentString method

Given the name of a string environment variable, retrieves its value.

Defined in

NotesSession

Syntax

value$ = notesSession.GetEnvironmentString( name$ [ , system ] )

Parameters

name$

String. The name of the environment variable to get.

system

Boolean. Optional. If True, the method uses the exact name$ of the environment variable. If False, the method prepends "$" to the name$ before retrieving its value. If you omit this parameter it defaults to False.

Return value

value$

String. The value of the environment variable.

Usage

If the script runs on a workstation, this method retrieves the environment variable from the current user's NOTES.INI (or Notes Preferences) file. If the script runs on a server, this method retrieves the environment variable from the server's NOTES.INI file, subject to administrative restrictions (see "Restricting agents on servers" in Administration Help or the "Administrator's Guide").

See examples
Examples: GetEnvironmentString method

See also
GetEnvironmentValue method
SetEnvironmentVar method
Using environment variables


GetEnvironmentValue method

Given the name of a numeric environment variable, retrieves its value.

Defined in

NotesSession

Syntax

valueV = notesSession.GetEnvironmentValue( name$ [ , system ] )

Parameter

name$

String. The name of the environment variable to get.

system

Boolean. Optional. If True, the method uses the exact name$ of the environment variable. If False, the method prepends "$" to the name$ before retrieving its value. If you omit this parameter, it defaults to False.

Return value

valueV

Variant. The value of the environment variable.

Usage

User must be listed in the server document/agent manager section in order to access environment variables (NOTES.INI file) through LotusScript or Java.

If the script runs on a workstation, this method retrieves the environment variable from the current user's NOTES.INI (or Notes Preferences) file. If the script runs on a server, this method retrieves the environment variable from the server's NOTES.INI file, subject to administrative restrictions. For more information, see "Restricting agents on servers" in Domino 5 Administration Help.

See examples
Examples: GetEnvironmentValue method

See also
GetEnvironmentString method
SetEnvironmentVar method
Using environment variables


Initialize method

Initializes a COM session with the current user ID.

Note This method is new with Release 5.0.2b.

Note This method is supported in COM only.

Defined in

NotesSession

Syntax

Call notesSession.Initialize( [ password$ ] )

Parameters

password$

String. Optional. The password must match the user ID password. If you do not specify a password, you will be prompted for a password as required and as the software permits. If the software does not support prompting (for example, VBScript under ASP/IIS), you must supply the password or the user ID must not have one.

Usage

This method can be used on a computer with a Notes Client or Domino Server.

This method assumes that you trust the local Domino or Notes installation.

Access to the Domino Objects is as a client if the user ID is not specified as a server in the local Domino Directory or Notes Directory. Otherwise, access is as a server. As a client, you can access any server that accepts your user ID. As a server, you can access only the local server.

See examples
Examples: Initialize method

See also
InitializeUsingNotesUserName method
Accessing the Domino Objects through COM


InitializeUsingNotesUserName method

Initializes a COM session with a specified user name.

Note This method is new with Release 5.0.2b.

Note This method is supported in COM only.

Defined in

NotesSession

Syntax

Call notesSession.InitializeUsingNotesUserName( name$ [ , password$ ] )

Parameters

name$

String. The user name. Can be an empty string. If you specify a name, this method looks it up in the local Domino Directory and permits access to the local server depending on the "Server Access" and "COM Restrictions" settings. If you do not specify a name, access is granted if the server permits Anonymous access.

password$

String. Optional. The password must match the Internet password associated with the name.

Usage

This method can be used only on a computer with a Domino Server. You can access only the local server through the Domino Objects.

This method assumes that you trust the local Domino installation.

See examples
Examples: InitializeUsingNotesUserName method

See also
Initialize method
Accessing the Domino Objects through COM


Resolve method

Returns the Domino object that a URL addresses.

Note This method is new with Release 5.0.2b.

Note This method is supported in COM only.

Defined in

NotesSession

Syntax

unknown = notesSession.Resolve( url$ )

Parameters

url$

String. A URL that addresses a Domino object.

Return Value

unknown

A Database, View, Form, Document, or Agent object. You must cast the return value to the expected type.


SetEnvironmentVar method

Sets the value of a string or numeric environment variable.

Defined in

NotesSession

Syntax

Call notesSession.SetEnvironmentVar( name$, valueV [, issystemvar] )

Parameters

name$

String. The name of the environment variable to set.

valueV

Variant. The value of the environment variable. Date values are converted to strings.

issystemvar

Boolean. Optional. If True, no dollar sign character ("$") is prepended to the variable name. Defaults to False.

Usage

User must be a member, or a member of a group that is explicitly stated in the list of who can run unrestricted LotusScript or Java agents. This list can be found on the security tab in the server's server document which is contained in the server's Name and Address book.

If an environment variable called name$ already exists, it gets the new value. Otherwise, a new environment variable is added to the NOTES.INI (or Notes Preferences) file.

SetEnvironmentVar prepends a dollar sign character ("$") to the name$ before setting the value of the environment variable, unless you specify issystemvar as False or have already included a "$" as the first character of the name$. When you examine the environment variable in the NOTES.INI (or Notes Preferences) file, you see the "$" character. When retrieving environment variables with the GetEnvironmentString or GetEnvironmentValue methods, you have the option of including or omitting the "$" from the variable name.

If a script runs on a workstation, the user's environment variable is set. If a script runs on a server, the server's environment variable is set, subject to administrative restrictions. For more information, see "Restricting agents on servers" in Domino 5 Administration Help.

Errors

If valueV is not an appropriate data type, SetEnvironmentVar raises the error: "Environment variables must be strings, dates, or integers."

See examples
Examples: SetEnvironmentVar method

See also
GetEnvironmentString method
GetEnvironmentValue method
Using environment variables


UpdateProcessedDoc method

Marks a document as processed by an agent.

Defined in

NotesSession

Syntax

Call notesSession.UpdateProcessedDoc( notesDocument )

Parameter

notesDocument

The document to be marked as processed.

Usage

You use this method in conjunction with the UnprocessedDocuments property, the UnprocessedFTSearch method, or the UnprocessedSearch method in NotesDatabase. This method is intended for agent scripts that run "If Documents Have Been Created or Modified." In other scripts (agent or otherwise), this method has no effect.

What does it do?

UpdateProcessedDoc ensures that a document gets processed by an agent only once. For example, when an agent runs a script to process all new and modified documents since last run, the script can use UnprocessedDocuments, UnprocessedFTSearch, or UnprocessedSearch (all in NotesDatabase) to get the newly-created and newly-modified documents. The script must use UpdateProcessedDoc to mark the documents that it has already processed.

Without UpdateProcessedDoc, the UnprocessedDocuments property returns all the documents in the database, and the UnprocessedFTSearch and UnprocessedSearch methods return all the documents in the database that meet their respective criteria, regardless of whether the documents have already been searched in a previous invocation of the agent.

UpdateProcessedDoc marks a document as processed only for the particular agent from which it is called. Using UpdateProcessedDoc in one agent has no effect on the documents that another agent processes.

See examples
Example: UpdateProcessedDoc method

See also
NotesDocument class
UnprocessedDocuments property (in NotesDatabase)
UnprocessedFTSearch method (in NotesDatabase)
UnprocessedSearch method (in NotesDatabase)
UpdateAll method (in NotesDocumentCollection)


NotesTimer class

Represents a mechanism for triggering an event every fixed number of seconds.

Note This class is not supported in COM.

Containment

Contained by: NotesSession

Properties

Comment

Enabled

Interval

Method

New

Event

Alarm

Creation

To create a new NotesTimer object, use New.

Syntax

Dim variableName As New NotesTimer( interval [, comment] )

or

Set notestimer = New NotesTimer( interval [, comment] )

Parameters

interval%

The interval in seconds for calling the event handler for the timer. This parameter sets the Interval property. The interval is not guaranteed; other activities on the computer involving script may delay the event.

comment$

String. Any comment. This parameter sets the Comment property.

Usage

NotesTimer is intended for use in Notes UI objects and not agents.

Ensure that the NotesTimer object is declared at a global level. If you declare it in a sub such as PostOpen that responds to an event, it is destroyed when the sub exits. So you would use Dim without the New syntax at the global level and the Set statement in the executable code.

After setting the NotesTimer object, use the On Event statement to establish an event handler for the Alarm event. Then write the event handler as a user sub.

A new NotesTimer object is enabled by default. You must set the Enabled property to disable the object.

See examples
Examples: NotesTimer class

See also
Using the Domino classes


Comment property

Read-Write. Any comment.

Defined in

NotesTimer

Data type

String

Syntax

To get: string = notesTimer.Comment

To set: notesTimer.Comment = string

See examples
Examples: NotesTimer class

See also
Alarm event
Enabled property
Interval property


Enabled property

Read-Write. Indicates if the NotesTimer object is active.

Defined in

NotesTimer

Data type

Boolean

Syntax

To get: flag = notesTimer.Enabled

To get: notesTimer.Enabled = flag

Legal values

  • True indicates that the NotesTimer object is active

  • False indicates that the NotesTimer object is not active

Usage

This property is True by default.

See examples
Examples: NotesTimer class

See also
Alarm event
Comment property
Interval property


Interval property

Read-Write. The interval in seconds at which the handler for the Alarm event is called.

Defined in

NotesTimer

Data type

Integer

Syntax

To get: interval% = notesTimer.Interval

To set: notesTimer.Interval = interval%

Usage

The interval is not guaranteed; other activities on the computer involving script may delay the event.

See examples
Examples: NotesTimer class

See also
Alarm event
Comment property
Enabled property


Alarm event

Occurs for an enabled NotesTimer object at the specified interval.

Defined in

NotesTimer

Syntax

Alarm( Source as NotesTimer )

Parameters

Source

NotesTimer. Read-only. The timer.

Usage

You need to establish the handler for this event in an On Event statement. You have to write the handler as a user sub.

See examples
Examples: NotesTimer class

See also
Comment property
Enabled property
Interval property


NotesUIDatabase class

Represents the database that's currently open in the Notes workspace.

Note This class is not supported in COM.

Containment

Contained by: NotesUIWorkspace

Contains: NotesDatabase, NotesDocumentCollection

Properties

Database

Documents

Methods

OpenNavigator

OpenView

Events

PostDocumentDelete

PostDragDrop

PostOpen

QueryClose

QueryDocumentDelete

QueryDocumentUndelete

QueryDragDrop

Access

There are two ways to access the current database:

  • Use the CurrentDatabase property in NotesUIWorkspace.

  • Write a script that responds to a NotesUIDatabase event. Use the source parameter of the event to access the properties and methods.

See examples
Example: NotesUIDatabase class

See also
NotesUIView class
Using the Domino classes


Database property

Read-only. The back-end database that corresponds to the currently open database.

Defined in

NotesUIDatabase

Data type

NotesDatabase

Syntax

To get: Set notesDatabase = notesUIDatabase.Database

See examples
Example: Database property

See also
Documents property


Documents property

Read-only. All the documents that the current NotesUIDatabase event is working on.

Defined in

NotesUIDatabase

Data type

NotesDocumentCollection

Syntax

To get: Set notesDocumentCollection = notesUIDatabase.Documents

See examples
Example: NotesUIDatabase class

See also
Database property


OpenNavigator method

Opens a navigator in the database.

Note This method is new with Release 5.

Defined in

NotesUIDatabase class

Syntax

Call notesUIDatabase.OpenNavigator( navigatorName$ [, fullWindow] )

Parameter

navigatorName$

String. The name of the navigator you want to open.

fullWindow

Boolean. Optional. Specify True if the navigator should be opened in its own window.


OpenView method

Opens a view in the database.

Defined in

NotesUIDatabase class

Syntax

Call notesUIDatabase.OpenView( viewName$ [, key$] [, newinstance] )

Parameter

viewName$

String. The name of the view you want to open.

key$

Note This parameter is new with Release 5.

String. Optional. The value to scroll to.

newinstance

Note This parameter is new with Release 5.

Boolean. Optional. Specify True if the view should be opened in a new window.

See examples
Example: OpenView method

See also
NotesView class


PostDocumentDelete event

Occurs just after a document is deleted (cleared or cut).

Defined in

NotesUIDatabase class

Syntax

PostDocumentDelete(Source as Notesuidatabase)

Parameter

Source

NotesUIDatabase. Read-only. The current database.

Usage

When you create a script that responds to this event, Notes creates the syntax of the event for you (including the parameters). You do not need to type it in.

Unauthorized users can execute any script that responds to this event, since PostDocumentDelete occurs before Notes verifies user authorization. Do not enter a script that you want only authorized users to execute.

See examples
Example: NotesUIDatabase class

See also
PostOpen event
QueryClose event
QueryDocumentDelete event
QueryDocumentUndelete event


PostDragDrop event

Occurs just after drag and drop operation in a database.

Note This event is new with Release 5.

Defined in

NotesUIDatabase class

Syntax

PostDragDrop(Source As Notesuidatabase, EntryName, Continue As Variant)

Parameters

Source

NotesUIDatabase. Read-only. The current database.

EntryName

The alias name of the design element the event is executed against. This name can be found in the Design view of that element.

Continue As Variant

Boolean. Read-Write. Indicates whether or not the dragdrop operation will proceed. Set this parameter to False if you do not want the operation to proceed.

Usage

When you create a script that responds to this event, Notes creates the syntax of the event for you (including the parameters). You do not need to type it in.


PostOpen event

Occurs after the NotesUIView QueryOpen and NotesIUView PostOpen events are triggered.

Defined in

NotesUIDatabase class

Syntax

PostOpen(Source As Notesuidatabase)

Parameters

Source

NotesUIDatabase. Read-only. The current database.

Usage

When you create a script that responds to this event, Notes creates the syntax of the event for you (including the parameters). You do not need to type it in.

See examples
Example: NotesUIDatabase class

See also
PostDocumentDelete event
QueryClose event (_UIDB)
QueryDocumentDelete event
QueryDocumentUndelete event


QueryClose event

Occurs just before the database closes.

Defined in

NotesUIDatabase class

Syntax

QueryClose(Source As Notesuidatabase, Continue As Variant)

Parameters

Source

NotesUIDatabase. Read-only. The current database.

Continue

Boolean. Read-Write. Indicates whether or not the database will be closed. Set this parameter to False if you do not want the database to be closed.

Usage

When you create a script that responds to this event, Notes creates the syntax of the event for you (including the parameters). You do not need to type it in.

See also
PostDocumentDelete event
PostOpen event (_UIDB)
QueryDocumentDelete event
QueryDocumentUndelete event


QueryDocumentDelete event

Occurs just before a document or selected set of documents is deleted (cleared or cut).

Defined in

NotesUIDatabase class

Syntax

QueryDocumentDelete(Source As Notesuidatabase, Continue As Variant)

Parameters

Source

NotesUIDatabase. Read-only. The current database.

Continue

Boolean. Read-Write. Indicates whether or not the document(s) will be deleted. Set this paramter to False if you do not want the document(s) to be deleted.

Usage

When you create a script that responds to this event, Notes creates the syntax of the event for you (including the parameters). You do not need to type it in.

See examples
Example: NotesUIDatabase class

See also
PostDocumentDelete event
PostOpen event (_UIDB)
QueryClose event (_UIDB)
QueryDocumentUndelete event


QueryDocumentUndelete event

Occurs just before a document or selected set of documents is undeleted.

Defined in

NotesUIDatabase class

Parameter

Syntax

QueryDocumentUndelete(Source As Notesuidatabase, Continue As Variant)

Parameters

Source

NotesUIDatabase. Read-only. The current view.

Continue

Boolean. Read-Write. Indicates whether or not the document(s) will be undeleted. Set this parameter to False if you do not want the document(s) to be undeleted.

Usage

When you create a script that responds to this event, Notes creates the syntax of the event for you (including the parameters). You do not need to type it in.

See examples
Example: NotesUIDatabase class

See also
PostDocumentDelete event
PostOpen event (_UIDB)
QueryClose event (_UIDB)
QueryDocumentDelete event


QueryDragDrop event

Occurs before the DragDrop operation is executed.

Note This event is new with Release 5.

Defined in

NotesUIDatabase class

Syntax

QueryDragDrop(Source As Notesuidatabase, EntryName, Continue As Variant)

Parameters

Source

NotesUIDatabase. Read-only. The current database.

EntryName

The alias name of the design element the event is executed against. This name can be found in the Design view of that element.

Continue As Variant

Boolean. Read-Write. Indicates whether or not the dragdrop operation will proceed. Set this parameter to False if you do not want the operation to proceed.

Usage

When you create a script that responds to this event, Notes creates the syntax of the event for you (including the parameters). You do not need to type it in.


NotesUIDocument class

Represents the document that's currently open in the Notes workspace.

Note This class is not supported in COM.

Containment

Contained by: NotesUIWorkspace

Contains: NotesDocument

Properties

AutoReload

CurrentField

DialogBoxCanceled

Document

EditMode

FieldHelp

HiddenChars

HorzScrollBar

InPreviewPane

IsNewDoc

PreviewDocLink

PreviewParentDoc

Ruler

WindowTitle

Methods

Categorize

Clear

Close

CollapseAllSections

Copy

CreateObject

Cut

DeleteDocument

DeselectAll

ExpandAllSections

FieldAppendText

FieldClear

FieldContains

FieldGetText

FieldSetText

FindFreeTimeDialog

FindFreeTimeDialogEx

FindString

Forward

GetObject

GetSelectedText

GotoBottom

GotoField

GotoNextField

GotoPrevField

GotoTop

Import

InsertText

NavBarSetText

NavBarSpinnerStart

NavBarSpinnerStop

Paste

Print

Refresh

RefreshHideFormulas

Reload

Save

SaveNewVersion

SelectAll

Send

SpellCheck

Events

PostModeChange

PostOpen

PostRecalc

PostSave

QueryClose

QueryModeChange

QueryOpen

QuerySave

Access

There are four ways to get the current document:

  • Use the CurrentDocument property in NotesUIWorkspace.

  • Write a script that responds to a NotesUIDocument event. Use the source parameter of the event to access the properties and methods.

  • If you want to create a new document in a database and access it, use the ComposeDocument method in NotesUIWorkspace.

  • If you want to open the currently highlighted document and access it, use the EditDocument method in NotesUIWorkspace.

See examples
Example: NotesUIDocument class

See also
Accessing the current document
Using the Domino classes


AutoReload property

Read-Write. Indicates whether or not the current document should be refreshed whenever the corresponding back-end document changes. Refreshing the current document updates its representation in memory, and visually on the workspace, to reflect the changes that have been made to the back-end document.

Defined in

NotesUIDocument

Data type

Boolean

Syntax

To get: flag = notesUIDocument.AutoReload

To set: notesUIDocument.AutoReload = flag

Legal values

  • True indicates that the current document will be automatically reloaded any time there is a change

  • False indicates that the current document will not automatically be reloaded; use the Reload method to reload it

Usage

Modifications made to non-rich text items on the back-end document accessed through the Document property appear on the current document immediately; AutoReload is unnecessary. Modifications made to non-rich text items on the corresponding back-end document accessed from the front-end document but not through the Document property (for example, if you use GetDocumentByUNID) do not appear immediately unless AutoReload is True. To make the modifications appear when AutoReload is False, call the Reload method or close the document and reopen it.

Modifications made to rich text items on the back-end document do not appear on the current document until it is closed and reopened.

Modifications made to items on the corresponding back-end document accessed outside the front-end document (for example, by an agent or another user) do not appear unless the document is closed and reopened.

See examples
Example: AutoReload property

See also
Document property
Reload method


CurrentField property

Read-only. The name of the field that the cursor is in.

Defined in

NotesUIDocument

Data type

String

Syntax

To get: fieldName$ = notesUIDocument.CurrentField

Usage

This property is valid only when the document is in Edit mode. If it's in Read mode, CurrentField returns an empty string ("").

See examples
Examples: CurrentField property

See also
Accessing the current document
EditMode Property
GotoField method
GotoNextField method
GotoPrevField method


DialogBoxCanceled property

Read-only. Indicates if a user cancels a dialog.

Defined in

NotesUIDocument

Data type

Boolean

Syntax

To get: flag = notesUIDocument.DialogBoxCanceled

Legal values

  • True indicates that the user exited the dialog by clicking Cancel or pressing ESC

  • False indicates that the user exited the dialog by clicking OK

Usage

You can access this property when the NotesUIDocument processes the QueryClose event from a document that has been brought up in a dialog. You can bring up the document through either the DialogBox method of NotesUIWorkspace, or through the @DialogBox function.

See examples
Example: DialogBoxCanceled Property

See also
QueryClose event
DialogBox method


Document property

Read-only. The back-end document that corresponds to the currently open document.

Defined in

NotesUIDocument

Data type

NotesDocument

Syntax

To get: Set notesDocument = notesUIDocument.Document

Usage

Modifications made to non-rich text items on the back-end document accessed through this property appear on the current document immediately. Modifications made to non-rich text items on the corresponding back-end document accessed from the front-end document but not through this property (for example, if you use GetDocumentByUNID) do not appear immediately unless the AutoReload property is True. To make the modifications appear when the AutoReload property is False, call the Reload method or close the document and reopen it.

Modifications made to rich text items on the back-end document do not appear on the current document until it is closed and reopened.

Modifications made to items on the corresponding back-end document accessed outside the front-end document (for example, by an agent or another user) do not appear unless the document is closed and reopened.

See examples
Example: Document Property

See also
Accessing the current document
AutoReload property
IsNewDoc property
Reload method


EditMode property

Read-Write. Indicates if a document is in Edit mode.

Defined in

NotesUIDocument

Data type

Boolean

Syntax

To get: flag = notesUIDocument.EditMode

To set: notesUIDocument.EditMode = flag

Legal values

  • True indicates that the document is in Edit mode

  • False indicates that the document is in Read mode

See examples
Example: EditMode property

See also
IsNewDoc property
PostModeChange event
QueryModeChange event


FieldHelp property

Read-Write. Indicates if field Help for a document is displayed.

Defined in

NotesUIDocument

Data type

Boolean

Syntax

To get: flag = notesUIDocument.FieldHelp

To set: notesUIDocument.FieldHelp = flag

Legal values

  • True indicates that field help is visible

  • False indicates that field help is hidden

Usage

You can set this property only when the document is in Edit mode.

See examples
Example: FieldHelp property

See also
EditMode property


HiddenChars property

Read-Write. Indicates if the hidden characters in a document (such as tabs and carriage returns) are displayed.

Defined in

NotesUIDocument

Data type

Boolean

Syntax

To get: flag = notesUIDocument.HiddenChars

To set: notesUIDocument.HiddenChars = flag

Legal values

  • True indicates that hidden characters are visible

  • False indicates that hidden characters are hidden

Usage

You can set this property only when the document is in Edit mode.

Hidden characters are visible only in rich text fields.

See examples
Examples: HiddenChars property

See also
EditMode property


HorzScrollBar property

Read-Write. Indicates if a document's horizontal scroll bar is displayed.

Defined in

NotesUIDocument

Data type

Boolean

Syntax

To get: flag = notesUIDocument.HorzScrollBar

To set: notesUIDocument.HorzScrollBar = flag

Legal values

  • True indicates that the horizontal scroll bar is visible

  • False indicates that the horizontal scroll bar is hidden

See examples
Example: HorzScrollBar property


InPreviewPane property

Read-only. Indicates if the document is being accessed from the preview pane.

Defined in

NotesUIDocument

Data type

Boolean

Syntax

To get: flag = notesUIDocument.InPreviewPane

Legal values

  • True indicates that the document is being accessed from the preview pane

  • False indicates that the document was opened by the user

Usage

If the preview pane is open in a view, the script has access to the document when the user highlights it in the view and it appears in the preview pane. This property lets you know that the document is being accessed in this manner rather than an explicit open.

See examples
Example: InPreviewPane property


IsNewDoc property

Read-only. Indicates if a document is new. A new document is one that hasn't been saved.

Defined in

NotesUIDocument

Data type

Boolean

Syntax

To get: flag = notesUIDocument.IsNewDoc

Legal values

  • True indicates that the document is new, and hasn't been saved

  • False indicates that the document is not new, and has been saved

See examples
Example: IsNewDoc property

See also
Accessing the current document
EditMode property
Save method


PreviewDocLink property

Read-Write. Indicates if a link's preview pane is displayed.

Defined in

NotesUIDocument

Data type

Boolean

Syntax

To get: flag = notesUIDocument.PreviewDocLink

To set: notesUIDocument.PreviewDocLink = flag

Legal values

  • True indicates that the preview pane is displayed

  • False indicates that the preview pane is not displayed

Usage

If there is no link on the current document, the preview pane is empty.

See examples
Example: PreviewDocLink property

See also
PreviewParentDoc property


PreviewParentDoc property

Read-Write. Indicates if the parent document's preview pane is displayed.

Defined in

NotesUIDocument

Data type

Boolean

Syntax

To get: flag = notesUIDocument.PreviewParentDoc

To set: notesUIDocument.PreviewParentDoc = flag

Legal values

  • True indicates that the parent document's preview pane is displayed

  • False indicates that the parent document's preview pane is not displayed

Usage

If the current document does not have a parent, the preview pane is empty.

See examples
Example: PreviewParentDoc property

See also
PreviewDoclink property


Ruler property

Read-Write. Indicates if the ruler is displayed.

Defined in

NotesUIDocument

Data type

Boolean

Syntax

To get: flag = notesUIDocument.Ruler

To set: notesUIDocument.Ruler = flag

Legal values

  • True indicates that the ruler is displayed

  • False indicates that the ruler is not displayed

Usage

You can set this property only when the document is in Edit mode.

See examples
Examples: Ruler property

See also
EditMode property


WindowTitle property

Read-only. The window title of a document.

Defined in

NotesUIDocument

Data type

String

Syntax

To get: title$ = notesUIDocument.WindowTitle

See examples
Example: WindowTitle property

See also
Accessing the current document


Categorize method

Given the name of a category, places a document in the category.

Defined in

NotesUIDocument

Syntax

Call notesUIDocument.Categorize( [ categoryName$ ] )

Parameter

categoryName$

String. Optional. The name of the category. Omit this parameter if you want to prompt the user for a category using the Categorize dialog box.

Errors

If the document has not been saved, you get an error: "Cannot categorize unsaved document."

See examples
Example: Categorize method

See also
IsNewDoc property


Clear method

Deletes the current selection from a document. The current selection can be anything in an editable field, such as text or graphics.

Defined in

NotesUIDocument

Syntax

Call notesUIDocument.Clear

Usage

This method is valid only when the document is in Edit mode.

The selection is not copied to the clipboard. If you want to remove the selection and place it on the clipboard, use the Cut method.

Error

If nothing is selected, you get an error: "Document command is not available."

See examples
Example: Clear method

See also
Copy method
Cut method
EditMode property
Paste method


Close method

Closes a document.

Defined in

NotesUIDocument

Syntax

Call notesUIDocument.Close

Usage

If the user has edited the document, Notes displays a dialog box asking if the user would like to save the changes.

See examples
Example: Close method

See also
QueryClose event
Save method


CollapseAllSections method

Collapses all the sections in a document.

Defined in

NotesUIDocument

Syntax

Call notesUIDocument.CollapseAllSections

Usage

A section can be on a form or in a rich text field in a document. When you call this method, each section collapses regardless of the expand and collapse settings it has on the form or document.

See examples
Example: CollapseAllSections method

See also
ExpandAllSections method


Copy method

Copies the current selection in a document to the Clipboard. The current selection can be anything on the document, such as text or graphics.

Defined in

NotesUIDocument

Syntax

Call notesUIDocument.Copy

Usage

If the user has something on the Clipboard, it is lost when you call this method.

See examples
Example: Copy method

See also
Clear method
Cut method
Paste method
SelectAll method


CreateObject method

In a document in Edit mode, creates an OLE object in the current rich text field.

Note CreateObject is not supported under OS/2, under UNIX, and on the Macintosh.

Defined in

NotesUIDocument

Syntax

Set handleV = notesUIDocument.CreateObject( [ name$ [ , type$ _
[ , filePath$ ] ] ] )

Parameters

name$

String. Optional. The name you want to use to refer to the object.

type$

String. Optional. The type of object you want to create. The type you specify must correspond to an entry in the OLE registry and is case-sensitive. The method creates an empty instance of the specified object type. If you specify a type, you must omit the filePath$ parameter.

filePath$

String. Optional. The path and file name of the source document you want to use to create an object. The method creates an object from the file. If you specify a file path, you must specify an empty string ("") for the type$ parameter.

Return value

handleV

Variant. A handle to the OLE object.

Usage

You must specify either a type$ or a filePath$, but not both. If you specify a filePath$, you create the object in a rich text field. You must, however, code a GetObject statement to give LotusScript a handle on the object.

The current document must be open in Edit mode and the cursor must be in an editable rich text field.

With no parameters, this method displays the Create Object dialog box, which allows the user to select the object to create.

See examples
Example: CreateObject method

See also
GetObject method


Cut method

Cuts the current selection from a document and places it on the Clipboard. The current selection can be anything in an editable field, such as text or graphics.

Defined in

NotesUIDocument

Syntax

Call notesUIDocument.Cut

Usage

This method is valid only when the document is in Edit mode.

If the user has something on the Clipboard, it is lost when you call this method.

See examples
Example: Cut method

See also
Clear method
Copy method
Paste method
SelectAll method


DeleteDocument method

Marks the current document for deletion and closes it. The NotesUIDocument object is no longer available once you call this method.

Defined in

NotesUIDocument

Syntax

Call notesUIDocument.DeleteDocument

Usage

The document is not actually deleted from the database until the user refreshes the view or closes the database, and chooses to delete the marked document.

If the current document is already marked for deletion, this method closes the document, leaving the deletion mark in place.

Errors

This method is invalid when the document is in Edit mode: "Document command is not available."

If you try to use the NotesUIDocument object after calling this method, Notes raises an error: "NotesUIDocumentWnd is no longer valid."

See examples
Examples: DeleteDocument method

See also
Close method
EditMode property
QueryClose event


DeselectAll method

Deselects any selections in a document.

Defined in

NotesUIDocument

Syntax

Call notesUIDocument.DeselectAll

Usage

If there is nothing selected, this method raises the error "Document command is not available."

See examples
Example: DeselectAll method

See also
Clear method
Copy method
CurrentField property
Cut method
EditMode property
Paste method
SelectAll method


ExpandAllSections method

Expands all the sections in a document.

Defined in

NotesUIDocument

Syntax

Call notesUIDocument.ExpandAllSections

Usage

A section can be on a form or in a rich text field in a document. When you call this method, each section expands regardless of the expand and collapse settings it has on the form or document.

See examples
Example: ExpandAllSections method

See also
CollaspeAllSections method


FieldAppendText method

Appends a text value into a field in a document without removing the existing contents of the field.

Defined in

NotesUIDocument

Syntax

Call notesUIDocument.FieldAppendText( fieldName$, text$ )

Parameters

fieldName$

String. The field into which you want to append text$. The field must be editable. Specify an empty string ("") to append the text to the current field.

text$

String. The value you want to append to the field.

Usage

This method is valid only when the document is in Edit mode.

If there is already some text in the field, the new text is added directly after the last character of the existing text.

Errors

If the fieldName$ does not exist on the document, this method returns the error "Cannot locate field definition for fieldName$."

If the document is not in Edit mode, this method returns the error "You must be in Edit mode to change the value of a field."

See examples
Examples: FieldAppendText method

See also
CurrentField property
EditMode property
FieldClear method
FieldContains method
FieldGetText method
FieldSetText method


FieldClear method

Clears the contents of a field in a document.

Defined in

NotesUIDocument

Syntax

Call notesUIDocument.FieldClear( [ fieldName$ ] )

Parameter

fieldName$

String. Optional. The name of the field you want to clear. The field must be editable. If you don't specify a fieldName$, the current field is cleared.

Usage

This method is valid only when the document is in Edit mode.

See examples
Example: FieldClear method

See also
CurrentField property
EditMode property
FieldAppendText method
FieldContains method
FieldGetText method
FieldSetText method


FieldContains method

In an open document, checks if a field contains a specific text value.

Defined in

NotesUIDocument

Syntax

flag = notesUIDocument.FieldContains( fieldName$, textValue$ )

Parameters

fieldName$

String. The name of the field you want to check. Specify an empty string ("") to check the contents of the current field.

textValue$

String. The value you want to check for.

Return value

flag

Boolean. Returns True if the field contains the textValue$. Otherwise returns False.

See examples
Example: FieldContains method

See also
CurrentField property
FieldAppendText method
FieldClear method
FieldGetText method
FieldSetText method


FieldGetText method

In a document in read or Edit mode, returns the contents of a field you specify, as a string. If the field is of type numbers or date-time, its contents are converted to a string.

Defined in

NotesUIDocument

Syntax

textValue$ = notesUIDocument.FieldGetText( [ fieldName$ ] )

Parameter

fieldName$

String. Optional. The name of the field whose contents you want. If you don't specify a fieldName$, the method returns the contents of the current field.

Return value

textValue$

String. The contents of the field you specified.

Usage

All values are displayed for a multi-value field. The values are separated by the multi-value separator as specified for display purposes in the field properties.

See examples
Examples: FieldGetText method

See also
CurrentField property
FieldAppendText method
FieldClear method
FieldContains method
FieldSetText method


FieldSetText method

Sets the value of a field in a document. The existing contents of the field, if any, are written over.

Defined in

NotesUIDocument

Syntax

Call notesUIDocument.FieldSetText( fieldName$, textValue$ )

Parameters

fieldName$

String. The name of the field whose value you want to set. The field must be editable. Specify an empty string ("") to set the value of the current field.

textValue$

String. The value you want to give to the field. If the fieldName$ is not of type text, this value is converted from text to the appropriate data type when you save the document.

Usage

This method is valid only when the document is in Edit mode. To enter multiple values for a multi-value field, separate the values with the input separator as specified in the field properties.

Errors

If a script attempts to call FieldSetText when a document is not in Edit mode, it raises the error: "You must be in Edit mode to change the value of a field."

See examples
Examples: FieldSetText method

See also
CurrentField property
EditMode property
FieldAppendText method
FieldClear method
FieldContains method
FieldGetText method


FindFreeTimeDialog method

Brings up the Find Free Time box to allow searches for available meeting times.

Defined in

NotesUIDocument

Syntax

flag = notesUIDocument.FindFreeTimeDialog( reqPeopleItems$, optPeopleItems$, reqRoomsItems$, optRoomsItems$, reqResourcesItems$, optResourcesItems$, removedPeopleItems$, startDateItem$, endDateItem$ )

Parameters

reqPeopleItem$

String. Name of a field (item) in the current document that contains names of people required at the meeting.

optPeopleItems$

String. Name of a field (item) in the current document that contains names of people whose attendance is optional.

reqRoomsItems$

String. Name of a field (item) in the current document that contains names of rooms required for the meeting.

optRoomsItems$

String. Name of a field (item) in the current document that contains names of optional rooms.

reqResourcesItems$

String. Name of a field (item) in the current document that contains names of resources required for the meeting.

optResourcesItems$

String. Name of a field (item) in the current document that contains names of optional resources.

removedPeopleItems$

String. Name of a Time field (item) in the current document that contains names of people to remove from the attendance list.

startDateItem$

String. Name of a Time field (item) in the current document that contains the start time for the meeting. You must specify the StartDateTime.

endDateItem$

String. Name of a field (item) in the current document that contains the end time for the meeting. You must specify the EndDateTime. The EndDate Time must be later than the StartDateTime.

Return value

flag

Boolean. Returns True if the user selects OK, False if the user selects Cancel.

Note The return value is new for Release 5. In previous releases, FindFreeTimeDialog was a sub.

Usage

If you don't need a parameter, use consecutive quotes ("") to omit it.

The meeting time should not span midnight.

The user can adjust the values specified here through the dialog box.

See examples
Example: FindFreeTimeDialog method

See also
Accessing the current document


FindFreeTimeDialogEx method

Brings up the Find Free Time box to allow searches for available meeting times.

Note This method is new with Release 5.

Defined in

NotesUIDocument

Syntax

flag = notesUIDocument.FindFreeTimeDialogEx( reqPeopleItems$, optPeopleItems$, reqRoomsItems$, optRoomsItems$, reqResourcesItems$, optResourcesItems$, removedPeopleItems$, startDateItem$, endDateItem$ )

Parameters

reqPeopleItems$

StringArray. Name of a field (item) in the current document that contains names of people required at the meeting.

optPeopleItems$

StringArray. Name of a field (item) in the current document that contains names of people whose attendance is optional.

reqRoomsItems$

StringArray. Name of a field (item) in the current document that contains names of rooms required for the meeting.

optRoomsItems$

StringArray. Name of a field (item) in the current document that contains names of optional rooms.

reqResourcesItems$

StringArray. Name of a field (item) in the current document that contains names of resources required for the meeting.

optResourcesItems$

StringArray. Name of a field (item) in the current document that contains names of optional resources.

removedPeopleItems$

StringArray. Name of a Time field (item) in the current document that contains names of people to remove from the attendance list.

startDateItem$

String. Name of a Time field (item) in the current document that contains the start time for the meeting. You must specify the StartDateTime.

endDateItem$

String. Name of a field (item) in the current document that contains the end time for the meeting. You must specify the EndDateTime. The EndDateTime must be later than the StartDateTime.

Return value

flag

Boolean. Returns True if the user selects OK, False if the user selects Cancel.

Usage

This method is the same as the FindFreeTimeDialog method, except that all the parameters in this method (except for startDateItem and endDateItem) are string arrays.

If you don't need a parameter, use consecutive quotes ("") to omit it.

The meeting time should not span midnight.

The user can adjust the values specified here through the dialog box.

See examples
Example: FindFreeTimeDialogEx method

See also
FindFreeTimeDialog method


FindString method

Finds the text in a given field.

Note This method is new with Release 5.

Defined in

NotesUIDocument

Syntax

Call notesUIDocument.FindString(text$ [, wholeword ] [, backwards ] [, caseSensitive ] [, wildCards ] [, accentSensitive ] [, searchDocument ] [, findNext ] [, wrapAround ] [, ignoreDiacritics ])

Parameters

text$

String. The text string that you want to look for.

wholeword

Boolean. Optional. Specify True to match the whole word. Default is True.

backwards

Boolean. Optional. Specify True to search backwards. Default is False.

caseSensitive

Boolean. Optional. Specify True to perform a case sensitive search. Default is False.

wildCards

Boolean. Optional. Specify True to use wild cards such as (*) in the search. Default is False.

accentSensitive

Boolean. Optional. Specify True to perform an accent sensitive search. Default is False.

searchDocument

Boolean. Optional. Specify True to search the current document. Default is True.

findNext

Boolean. Optional. Specify True to find the next match. Default is True.

wrapAround

Boolean. Optional. Specify True to perform a wrap search. Default is False.

ignoreDiacritics

Boolean. Optional. Specify True to ignore diacritics. Default is False.

Usage

Performs the equivalent of Edit - Find (Ctrl-F or Ctrl-G) that is done in the User Interface without prompting the user.

See examples
Example: FindString method


Forward method

Creates a new mail memo with the contents of a document. The user can enter recipients and mail the forwarded document like any other mail memo.

Defined in

NotesUIDocument

Syntax

Call notesUIDocument.Forward

Usage

The document can be in read or Edit mode. This method returns an error if the current document has not yet been saved.

See examples
Example: Forward method

See also
EditMode property
IsNewDoc property
Send method


GetObject method

Given a name, returns a handle to the OLE object of that name.

Note GetObject is not supported under OS/2, under UNIX, and on the Macintosh.

Defined in

NotesUIDocument

Syntax

Set handleV = notesUIDocument.GetObject( name$ )

Parameter

name$

String. The name of the object.

Return value

handleV

Variant. A handle to the OLE object. Returns Nothing if the object is not found.

See examples
Example: GetObject method

See also
CreateObject method


GetSelectedText method

Obtains the text that is highlighted in the U/I.

Note This method is new with Release 5.

Defined in

NotesUIDocument

Syntax

text$ = notesUIDocument.getSelectedText([fieldName$])

Parameters

fieldName$

String. Optional. The name of the field that contains the selected text.

Return value

text$

The selected text.

See examples
Example: GetSelectedText method


GotoBottom method

Places the cursor in the last editable field or the last button in a document.

Defined in

NotesUIDocument

Syntax

Call notesUIDocument.GotoBottom

Usage

This method is valid only when the document is in Edit mode.

See examples
Example: GotoBottom method

See also
EditMode property
GotoField method
GotoNextField method
GotoPrevField method
GotoTop method


GotoField method

Given a field name, puts the cursor in the specified field in a document.

Defined in

NotesUIDocument

Syntax

Call notesUIDocument.GotoField( fieldName$ )

Parameter

fieldName$

String. The name of the field you want to go to.

Usage

This method is valid only when the document is in Edit mode.

See examples
Example: GotoField method

See also
CurrentField property
EditMode property
GotoBottom method
GotoNextField method
GotoPrevField method
GotoTop method


GotoNextField method

Places the cursor in the next field in a document. The next field is the one below and to the right of the current field.

Defined in

NotesUIDocument

Syntax

Call notesUIDocument.GotoNextField

Usage

This method is valid only when the document is in Edit mode.

See also
EditMode property
GotoBottom method
GotoField method
GotoPrevField method
GotoTop method


GotoPrevField method

Places the cursor in the previous field in a document. The previous field is the one above and to the left of the current field.

Defined in

NotesUIDocument

Syntax

Call notesUIDocument.GotoPrevField

Usage

This method is valid only when the document is in Edit mode.

See also
EditMode property
GotoBottom method
GotoField method
GotoNextField method
GotoTop method


GotoTop method

Places the cursor in the first editable field or the first button in a document.

Defined in

NotesUIDocument

Syntax

Call notesUIDocument.GotoTop

Usage

This method is valid only when the document is in Edit mode.

See examples
Example: GotoTop method

See also
EditMode property
GotoBottom method
GotoField method
GotoNextField method
GotoPrevField method


Import method

Imports a file.

Note This method is new with Release 5.

Defined in

NotesUIDocument

Syntax

Call notesUIDocument.Import( [ filter$ ] [ filename$ ] )

Parameter

filter$

String. Optional. The type of filter you would like to use while importing the file. If you omit the parameter, the Open File dialog box appears with all the filters we currently support.

filename$

String. Optional. The name of the file that you want to import.

Usage

If you use the filter$ parameter, you must also specify the filename$ parameter.

If you use the filename$ parameter and don't specify which filter to use, the file may not be imported correctly.

See examples
Example: Import method


InsertText method

Inserts a text value at the current cursor position on a document.

Defined in

NotesUIDocument

Syntax

Call notesUIDocument.InsertText( textValue$ )

Parameter

textValue$

String. The value you want to insert.

Usage

This method is valid only when the document is in Edit mode.

See examples
Example: InsertText method

See also
EditMode property
FieldAppendText method
FieldSetText method


NavBarSetText method

Sets the text for the URL navigation bar of an Internet Explorer browser.

Note This method is new with Release 4.6.

Defined in

NotesUIDocument

Syntax

Call notesUIDocument.NavBarSetText( urltext , windowtitle )

Parameters

urltext

String. The URL text.

windowtitle

String. Optional. The window title.

See also
NavBarSpinnerStart method
NavBarSpinnerStop method


NavBarSpinnerStart method

Starts the URL navigation bar spinner for an Internet Explorer browser.

Note This method is new with Release 4.6.

Defined in

NotesUIDocument

Syntax

Call notesUIDocument.NavBarSpinnerStart( )

See also
NavBarSetText method
NavBarSpinnerStop method


NavBarSpinnerStop method

Stops the navigation bar spinner for an Internet Explorer browser.

Note This method is new with Release 4.6.

Defined in

NotesUIDocument

Syntax

Call notesUIDocument.NavBarSpinnerStop( )

See also
NavBarSetText method
NavBarSpinnerStart method


Paste method

Pastes the contents of the Clipboard at the current cursor position on a document.

Defined in

NotesUIDocument

Syntax

Call notesUIDocument.Paste

Usage

This method is valid only when the document is in Edit mode.

See examples
Example: Paste method

See also
Clear method
Copy method
CurrentField property
Cut method
EditMode property
InsertText method


Print method

Prints the current document:

  • If one or more parameters are specified, automatically prints the document.

  • If no parameters are specified, or if the first parameter is omitted, displays the File Print dialog box.

Defined in

NotesUIDocument

Syntax

Call notesUIDocument.Print

or

Call notesUIDocument.Print( [ numCopies%, [, fromPage%, [, toPage%, [,draft ]]]] )

Parameters

numCopies%

Integer. Optional. The number of copies you want to print. If you omit this parameter, the method displays the File Print dialog box. If you specify 0, the method prints one copy.

fromPage%

Integer. Optional. The page number where you want to begin printing. If you omit this parameter or specify 0, the method begins printing on the first page of the document.

toPage%

Integer. Optional. The page number where you want to stop printing. If you omit this parameter or specify 0, the method stops printing on the last page of the document.

draft

Boolean. Optional. Specify True if you want to print the document in draft mode. Otherwise, specify False or omit this parameter.

See examples
Examples: Print method


Refresh method

Refreshes a document. When you refresh a document, its computed fields are recalculated.

Defined in

NotesUIDocument

Syntax

Call notesUIDocument.Refresh( [ IncludeRichTextItems ] )

Parameters

IncludeRichTextItems

Note This parameter is new with Release 5.

Boolean. Optional. Specify True to include all rich text items in the back-end document.

Usage

This method is valid only when the document is in Edit mode.

This method is useful when the value of a computed field depends upon the contents of another field on the document.

See examples
Example: Refresh method

See also
RefreshHideFormulas method


RefreshHideFormulas method

Recalculates the hide-when formulas on the current document's form.

Defined in

NotesUIDocument

Syntax

Call notesUIDocument.RefreshHideFormulas

Usage

Use this method when you want to recalculate hide-when formulas without recalculating all the formulas on the current document's form. This method is an expensive operation, and may affect performance.

See examples
Example: RefreshHideFormulas method

See also
Refresh method


Reload method

Refreshes the current document with any changes that have been made to the corresponding back-end document. Refreshing the current document updates its representation in memory, and visually on the workspace, to reflect the changes that have been made to the back-end document.

Defined in

NotesUIDocument

Syntax

Call notesUIDocument.Reload

Usage

This method is valid only when the document is in Edit mode.

Modifications made to non-rich text items on the back-end document accessed through the Document property appear on the current document immediately. Modifications made to non-rich text items on the corresponding back-end document accessed from the front-end document but not through the Document property (for example, if you use GetDocumentByUNID) do not appear immediately unless the AutoReload property is True. To make the modifications appear when the AutoReload property is False, call Reload or close the document and reopen it.

Modifications made to rich text items on the back-end document do not appear on the current document until it is closed and reopened.

Modifications made to items on the corresponding back-end document accessed outside the front-end document (for example, by an agent or another user) do not appear unless the document is closed and reopened.

See examples
Example: Reload method

See also
AutoReload Property
Document property


Save method

Saves a document.

Defined in

NotesUIDocument

Syntax

Call notesUIDocument.Save

Usage

This method is valid only when the document is in Edit mode.

You must call Save if you want changes to the document to be written to disk.

See also
EditMode property
QuerySave event
SaveNewVersion method


SaveNewVersion method

Saves a copy of a document as a new version.

Defined in

NotesUIDocument

Syntax

Call notesUIDocument.SaveNewVersion

Usage

This method is valid only when the document is in Edit mode.

To use this method, a document's form must have one of the following versioning options:

  • New versions become responses

  • Prior versions become responses

  • New versions become siblings

The version option determines what kind of document you create when you call the SaveNewVersion method.

The document's form should be set to create versions manually, on File - Save New Version. If the form is set to create versions automatically, a new version is created automatically when you call the Save method, and there is no need to use the SaveNewVersion method.

Errors

If the form has versioning option set to None, this method raises an error: "Document command is unavailable."

See examples
Example: SaveNewVersion method

See also
EditMode property
Save method


SelectAll method

In a document in Edit mode, selects the entire contents of the current field. In a document in Read mode, selects the entire contents of the document.

Defined in

NotesUIDocument

Syntax

Call notesUIDocument.SelectAll

See examples
Example: SelectAll method

See also
Clear method
Copy method
CurrentField property
Cut method
DeselectAll method
EditMode property


Send method

Mails a document.

Defined in

NotesUIDocument

Syntax

Call notesUIDocument.Send

Usage

The document must contain a SendTo field indicating the recipients.

There are two kinds of fields that affect the mailing of the document:

  • If the document contains additional recipient items, such as CopyTo or BlindCopyTo, Notes mails the documents to these recipients, too.

  • If the document contains items to control the routing of mail, such as DeliveryPriority, DeliveryReport, or ReturnReceipt, Notes uses these when sending the document.

See examples
Example: Send method

See also
FieldGetText method
Forward method


SpellCheck method

Checks the spelling of a UI document.

Note This method is new with Release 5.

Defined in

NotesUIDocument

Syntax

Call notesUIDocument.SpellCheck()

Usage

The UI document must be in Edit mode before this method is called.

See examples
Example: SpellCheck method


PostModeChange event

Occurs after the document has changed modes (from Read to Edit mode, or from Edit to Read mode) but before the user has been given input focus.

Defined in

NotesUIDocument

Syntax

PostModeChange( Source as NotesUIDocument )

Parameters

Source

NotesUIDocument. Read-only. The current document.

Usage

When you create a script that responds to this event, Notes creates the syntax of the event for you (including the parameter). You do not need to type it in.

Use the EditMode property on Source to determine the new mode.

See examples
Example: PostModeChange event

See also
EditMode property
PostOpen event
PostRecalc event
QueryClose event
QueryModeChange event
QueryOpen event
QuerySave event


PostOpen event

Occurs after the current document has been opened, but before the user has been given input focus.

Defined in

NotesUIDocument

Syntax

PostOpen( Source as NotesUIDocument )

Parameter

Source

NotesUIDocument. Read-only. The current document.

Usage

When you create a script that responds to this event, Notes/Domino creates the syntax of the event for you (including the parameter). You do not need to type it in.

See examples
Examples: PostOpen event

See also
PostModeChange event
PostRecalc event
QueryClose event
QueryModeChange event
QueryOpen event
QuerySave event


PostRecalc event

Occurs just after the current document is recalculated (after all the formulas on the document's form have executed).

Defined in

NotesUIDocument

Syntax

PostRecalc( Source as NotesUIDocument )

Parameter

Source

NotesUIDocument. Read-only. The current document.

Usage

When you create a script that responds to this event, Notes creates the syntax of the event for you (including the parameter). You do not need to type it in.

See examples
Example: PostRecalc event

See also
PostModeChange event
PostOpen event
QueryClose event
QueryModeChange event
QueryOpen event
QuerySave event


PostSave event

Occurs just after the current document is saved.

Note This event is new with Release 5.

Defined in

NotesUIDocument

Syntax

PostSave( Source as NotesUIDocument )

Parameter

Source

NotesUIDocument. Read-only. The current document.

Usage

When you create a script that responds to this event, Notes creates the syntax of the event for you (including the parameter). You do not need to type it in.

See examples
Examples: PostSave event


QueryClose event

Occurs just before the current document is closed.

Defined in

NotesUIDocument

Syntax

QueryClose( Source as NotesUIDocument, Continue as Variant )

Parameters

Source

NotesUIDocument. Read-only. The current document.

Continue

Boolean. Read-write. Indicates whether or not the document will close. Initially set to True. Set this parameter to False if you do not want to close the document.

Usage

When you create a script that responds to this event, Notes creates the syntax of the event for you (including the parameters). You do not need to type it in.

See examples
Examples: QueryClose event

See also
PostModeChange event
PostOpen event
PostRecalc event
QueryModeChange event
QueryOpen event
QuerySave event


QueryModeChange event

Occurs just before the current document changes modes (from Read to Edit mode, or from Edit to Read mode).

Defined in

NotesUIDocument

Syntax

QueryModeChange( Source as NotesUIDocument , Continue as Variant )

Parameters

Source

NotesUIDocument. Read-only. The current document.

Continue

Boolean. Read-write. Indicates whether or not the document will change modes. Initially set to True. Set this parameter to False if you do not want the document to change modes.

Usage

When you create a script that responds to this event, Notes creates the syntax of the event for you (including the parameters). You do not need to type it in.

Use the EditMode property on Source to determine the current mode (before changing).

See examples
Examples: QueryModeChange event

See also
PostModeChange event
PostOpen event
PostRecalc event
QueryClose event
QueryOpen event
QuerySave event


QueryOpen event

Occurs just before the current document is opened.

Defined in

NotesUIDocument

Syntax

QueryOpen( Source as NotesUIDocument, Mode as Integer, IsNewDoc as Variant, Continue as Variant )

Parameters

Source

NotesUIDocument. Read-only. The current document.

Mode

Integer. Read-only. 0 indicates the user is opening the document for reading. 1 indicates the user is opening the document for editing.

IsNewDoc

Boolean. Read-only. True indicates user is creating a new document. False indicates the user is opening an existing document.

Continue

Boolean. Read-write. Indicates whether or not the document will open. Initially set to True. Set this parameter to False if you do not want the document to open.

Usage

When you create a script that responds to this event, Notes creates the syntax of the event for you (including the parameters). You do not need to type it in.

See examples
Examples: QueryOpen event

See also
PostModeChange event
PostOpen event
PostRecalc event
QueryClose event
QueryModeChange event
QuerySave event


QuerySave event

Occurs just before the current document is saved.

Defined in

NotesUIDocument

Syntax

QuerySave( Source as NotesUIDocument , Continue as Variant )

Parameters

Source

NotesUIDocument. Read-only. The current document.

Continue

Boolean. Read-write. Indicates whether or not the document will save. Initially set to True. Set this parameter to False if you do not want to save the document.

Usage

If the QuerySave event occurs during the closing of a document, setting Continue to False stops both the save and the close.

If the document contains input translation or validation formulas, execute the Refresh method for the source NotesUIDocument object at the beginning of the QueryEvent script. The QuerySave event occurs before Notes refreshes the fields during the save process, so the script works with unvalidated and untranslated data unless you explicitly refresh

When you create a script that responds to this event, Notes creates the syntax of the event for you (including the parameters). You do not need to type it in.

See examples
Examples: QuerySave event

See also
PostModeChange event
PostOpen event
PostRecalc event
QueryClose event
QueryModeChange event
QueryOpen event


NotesUIView class

Represents the current view in the Notes workspace.

Note This class is not supported in COM.

Containment

Contained by: NotesUIWorkspace

Contains: NotesDocumentCollection, NotesView

Properties

CalendarDateTime

CaretCategory

Documents

View

ViewAlias

Viewname

Methods

Print

SelectDocument

Events

PostDragDrop

PostOpen

PostPaste

QueryAddToFolder

QueryClose

QueryDragDrop

QueryOpen

QueryOpenDocument

QueryPaste

QueryRecalc

RegionDoubleClick

Access

There are three ways to access the current view:

  • Use the CurrentView property in NotesUIWorkspace.

  • Write a script that responds to a NotesUIView event. Use the source parameter of the event to access the properties and methods.

  • Through view actions.

See examples
Examples: NotesUIView class

See also
NotesUIDatabase class
Using the Domino classes


CalendarDateTime property

Read-only. The date and time of the current region in a calendar view.

Defined in

NotesUIView

Data type

Variant of type DATE

Syntax

To get: dateV = notesUIView.CalendarDateTime

Usage

This is the target date-time when the user does a copy, paste, or drag and drop operation in a calendar view.

See examples
Example: CalendarDateTime property

See also
Documents property
View property
CurrentCalendarDateTime property


CaretCategory property

Returns the current category in the view for the current document.

Note This property is new with Release 5.

Defined in

NotesUIView

Data type

Variant

Syntax

To get: variant = notesUIView.CaretCategory

Usage

This property is mainly used for categorized views.

See examples
Example: CaretCategory property


Documents property

Read-only. All the documents that the current NotesUIView event is working on.

Defined in

NotesUIView

Data type

NotesDocumentCollection

Syntax

To get: Set notesDocumentCollection = notesUIView.Documents

Usage

Events such as QueryOpen, PostOpen, QueryPaste, QueryClose, and QueryRecalc do not work on documents, so this property is always empty for these events. For events that act upon documents, this property reflects the documents selected when the user initiates the event.

See also
View property


View property

Read-only. The back-end view that corresponds to the currently open view.

Defined in

NotesUIView

Data type

NotesView

Syntax

To get: Set notesView = notesUIView.View

See examples
Examples: NotesUIView class

See also
CalendarDateTime property
Documents property


ViewAlias property

Read-only. A view alias.

Note This property is new with Release 5.0.1

Defined in

NotesUIView

Data type

String

Syntax

To get: viewalias$ = notesUIView.ViewAlias

See examples
Example: ViewAlias property


ViewName property

Read-only. The name of the view.

Note This property is new with Release 5.

Defined in

NotesUIView

Data type

String

Syntax

To get: viewname$ = notesUIView.ViewName


Print method

Implements the @Command([FilePrint]). Prints the currently open or selected document(s), or the current view.

Note This method is new with Release 5.

Defined in

NotesUIView

Syntax

Call notesUIView.Print([ numCopies%] [, fromPage%] [, toPage%] [, draft] [, pageSeparator%] [, formOverride$] [, printview] [, dateRangeBegin] [, dateRangeEnd])

Parameters

numCopies%

Integer. Optional. The number of copies you want to print. If you omit this parameter, the method displays the File Print dialog box.

fromPage%

Integer. Optional. The page of a document where you want to start printing. "0" means all.

toPage%

Integer. Optional. The page of a document where you want to stop printing. "0" means all.

draft

Boolean. Optional. Specify True if you want to print the document in draft mode.

pageSeparator%

Integer. Optional. Determines the page separator.

formOverride$

Text. Optional. The name of the form you want to use to print the document.

printView

Boolean. Optional. Specify True to indicate that you want to print the current view.

dateRangeBegin

Variant. Optional. Prints the beginning date if printing from a calendar view.

dateRangeEnd

Variant. Optional. Prints the end date if printing from a calendar view.

See examples
Example: Print method


SelectDocument method

Selects the specified document in a view.

Note This method is new with Release 4.6.

Defined in

NotesUIView

Syntax

Call notesUIView.SelectDocument( notesdocument )

Parameter

notesdocument

NotesDocument. The document to be selected.

See examples
Example: SelectDocument method


PostDragDrop event

Occurs just after a drag and drop operation in a calendar view.

Defined in

NotesUIView

Syntax

PostDragdrop(Source As Notesuiview)

Parameters

Source

NotesUIView. Read-only. The current view.

Usage

When you create a script that responds to this event, Notes creates the syntax of the event for you (including the parameters). You do not need to type it in.

See also
PostOpen event
PostPaste event
QueryAddToFolder event
QueryClose event
QueryDragDrop event
QueryOpen event
QueryOpenDocument event
QueryPaste event
QueryRecalc event
RegionDoubleClick event


PostOpen event

Occurs just after the current view is opened.

Defined in

NotesUIView

Syntax

PostOpen(Source As Notesuiview)

Parameters

Source

NotesUIView. Read-only. The current view.

Usage

When you create a script that responds to this event, Notes creates the syntax of the event for you (including the parameters). You do not need to type it in.

See examples
Example: QueryOpenDocument event

See also
PostDragDrop event
PostPaste event
QueryAddToFolder event
QueryClose event
QueryDragDrop event
QueryOpen event
QueryOpenDocument event
QueryPaste event
QueryRecalc event
RegionDoubleClick event


PostPaste event

Occurs just after a document is pasted in the view.

Defined in

NotesUIView

Syntax

PostPaste(Source As Notesuiview)

Parameters

Source

NotesUIView. Read-only. The current view.

Usage

When you create a script that responds to this event, Notes creates the syntax of the event for you (including the parameters). You do not need to type it in.

See examples
Example: PostPaste event

See also
PostDragDrop event
PostOpen event
QueryAddToFolder event
QueryClose event
QueryDragDrop event
QueryOpen event
QueryOpenDocument event
QueryPaste event
QueryRecalc event
RegionDoubleClick event


QueryAddToFolder event

Occurs just before an add to folder operation.

Defined in

NotesUIView

Parameter

Syntax

QueryAddToFolder(Source As Notesuiview, Target As Variant, Continue As Variant)

Parameters

Source

NotesUIView. Read-only. The current view.

Target

String. Read-only. The name of the folder that is the target of the dragdrop operation.

Continue

Boolean. Read-Write. Indicates whether or not the add to folder operation will proceed. Set this parameter to False to cancel the operation.

Usage

When you create a script that responds to this event, Notes creates the syntax of the event for you (including the parameters). You do not need to type it in.

See examples
Example: QueryAddToFolder event

See also
PostDragDrop event
PostOpen event
PostPaste event
QueryDragDrop event
QueryOpen event
QueryClose event
QueryOpenDocument event
QueryPaste event
QueryRecalc event
RegionDoubleClick event


QueryClose event

Occurs just before the view is closed.

Defined in

NotesUIView

Parameter

Syntax

QueryClose(Source As Notesuiview, Continue As Variant)

Parameters

Source

NotesUIView. Read-only. The current view.

Continue

Boolean. Read-Write. Indicates whether or not the view will close. Set this parameter to False if you do not want the view to close.

Usage

When you create a script that responds to this event, Notes creates the syntax of the event for you (including the parameters). You do not need to type it in.

See examples
Example: PostPaste event

See also
PostDragDrop event
PostOpen event
PostPaste event
QueryAddToFolder event
QueryDragDrop event
QueryOpen event
QueryOpenDocument event
QueryPaste event
QueryRecalc event
RegionDoubleClick event


QueryDragDrop event

Occurs just before a drag and drop operation in a calendar view.

Defined in

NotesUIView class

Parameter

Syntax

QueryDragdrop(Source As Notesuiview, Continue As Variant)

Parameters

Source

NotesUIView. Read-only. The current view.

Continue

Boolean. Read-Write. Indicates whether or not the dragdrop operation will proceed. Set this parameter to False if you do not want the operation to proceed.

Usage

When you create a script that responds to this event, Notes creates the syntax of the event for you (including the parameters). You do not need to type it in.

See examples
Examples: NotesUIView class

See also
PostDragDrop event
PostOpen event
PostPaste event
QueryAddToFolder event
QueryClose event
QueryOpen event
QueryOpenDocument event
QueryPaste event
QueryRecalc event
RegionDoubleClick event


QueryOpen event

Occurs just before the current view is opened.

Defined in

NotesUIView

Syntax

QueryOpen(Source As Notesuiview, Continue As Variant)

Parameters

Source

NotesUIView. Read-only. The current view.

Continue

Boolean. Read-Write. Indicates whether or not the view will open. Set this parameter to False if you do not want the view to open.

Usage

When you create a script that responds to this event, Notes creates the syntax of the event for you (including the parameters). You do not need to type it in.

See examples
Examples: NotesUIView class

See also
PostDragDrop event
PostOpen event
PostPaste event
QueryAddToFolder event
QueryClose event
QueryDragDrop event
QueryOpenDocument event
QueryPaste event
QueryRecalc event
RegionDoubleClick event


QueryOpenDocument event

Occurs just before a document is opened from this view.

Defined in

NotesUIView

Syntax

QueryOpenDocument(Source As Notesuiview, Continue As Variant)

Parameters

Source

NotesUIView. Read-only. The current view.

Continue

Boolean. Read-Write. Indicates whether or not the document will open. Set this parameter to False if you do not want the document to open.

Usage

The Documents property contains one document, the document the user wants to open.

When you create a script that responds to this event, Notes creates the syntax of the event for you (including the parameters). You do not need to type it in.

See examples
Example: QueryOpenDocument event

See also
PostDragDrop event
PostOpen event
PostPaste event
QueryAddToFolder event
QueryClose event
QueryDragDrop event
QueryOpen event
QueryPaste event
QueryRecalc event
RegionDoubleClick event


QueryPaste event

Occurs just before a document is pasted in the view.

Defined in

NotesUIView

Syntax

QueryPaste(Source As Notesuiview, Continue As Variant)

Parameters

Source

NotesUIView. Read-only. The current view.

Continue

Boolean. Read-Write. Indicates whether or not the document will be pasted. Set this parameter to False if you do not want the document pasted.

Usage

When you create a script that responds to this event, Notes creates the syntax of the event for you (including the parameters). You do not need to type it in.

See examples
Example: QueryPaste event

See also
PostDragDrop event
PostOpen event
PostPaste event
QueryAddToFolder event
QueryClose event
QueryDragDrop event
QueryOpen event
QueryOpenDocument event
QueryRecalc event
RegionDoubleClick event


QueryRecalc event

Occurs just before the view is recalculated.

Defined in

NotesUIView

Syntax

QueryRecalc(Source As Notesuiview, Continue As Variant)

Parameters

Source

NotesUIView. Read-only. The current view.

Continue

Boolean. Read-Write. Indicates whether or not the view will be recalculated. Set this parameter to False if you do not want the document recalculated.

Usage

When you create a script that responds to this event, Notes creates the syntax of the event for you (including the parameters). You do not need to type it in.

See examples
Example: QueryRecalc event

See also
PostDragDrop event
PostOpen event
PostPaste event
QueryAddToFolder event
QueryClose event
QueryDragDrop event
QueryOpen event
QueryOpenDocument event
QueryPaste event
RegionDoubleClick event


RegionDoubleClick event

Occurs just after the current region is double-clicked in a calendar view.

Defined in

NotesUIView

Syntax

RegionDoubleClick(Source As Notesuiview)

Parameters

Source

NotesUIView. Read-only. The current view.

Usage

The region is the blank region for a date in a calendar view.

When you create a script that responds to this event, Notes creates the syntax of the event for you (including the parameters). You do not need to type it in.

See examples
Example: CalendarDateTime property

See also
CalendarDateTime property
PostDragDrop event
PostOpen event
PostPaste event
QueryAddToFolder event
QueryClose event
QueryDragDrop event
QueryOpen event
QueryOpenDocument event
QueryPaste event
QueryRecalc event


NotesUIWorkspace class

Represents the current Notes workspace window.

Note This class is not supported in COM.

Containment

Contains: NotesUIDatabase , NotesUIDocument, NotesUIView

Properties

CurrentCalendarDateTime

CurrentDatabase

CurrentDocument

CurrentView

Methods

AddDatabase

CheckAlarms

ComposeDocument

DialogBox

EditDocument

EditProfile

EnableAlarms

Folder

GetListOfTunes

New

OpenDatabase

OpenFileDialog

OpenFrameSet

OpenPage

PickListCollection

PickListStrings

PlayTune

Prompt

RefreshParentNote

ReloadWindow

SaveFileDialog

SetCurrentLocation

SetTargetFrame

URLOpen

UseLSX

ViewRefresh

Creation

To create a new NotesUIWorkspace object, use New.

Syntax

Dim variableName As New NotesUIWorkspace

Usage

You cannot use the UI classes in a background agent, an agent called through an API, or an agent called by the NotesAgent Run method.

See examples
Example: NotesUIWorkspace class

See also
Using the Domino classes
Accessing the current document


CurrentCalendarDateTime property

Read-only. The date and time of the current (the selected) region in a calendar view.

Defined in

NotesUIWorkspace

Data type

Variant of type DATE

Syntax

To get: dateV = notesUIWorkspace.CurrentCalendarDateTime

See examples
Example: CurrentCalendarDateTime property

See also
CalendarDateTime property


CurrentDatabase property

Returns a NotesUIDatabase object representing the database that's currently open.

Note This property is new with Release 5.

Defined in

NotesUIWorkspace

Data type

NotesUIDatabase

Syntax

Set notesUIDatabase = notesUIWorkspace.CurrentDatabase

Return value

notesUIDatabase

Represents the current database.

See examples
Example: CurrentDatabase property


CurrentDocument property

Returns a NotesUIDocument object representing the document that's currently open.

Defined in

NotesUIWorkspace

Data type

NotesUIDocument

Syntax

Set notesUIDocument = notesUIWorkspace.CurrentDocument

Return value

notesUIDocument

Represents the current document. If there is no document currently open on the workspace, this method returns Nothing.

Usage

This method cannot be used to access the document that's currently highlighted in a view or folder.

This method can be used to access the current document in all NotesUIDocument events, including QueryOpen.

See examples
Example: CurrentDocument property

See also
UnprocessedDocuments property
Accessing the current document


CurrentView property

Returns a NotesUIView object representing the view that's currently open.

Note This property is new with Release 5.

Defined in

NotesUIWorkspace

Data type

NotesUIView

Syntax

Set notesUIView = notesUIWorkspace.CurrentView

Return value

notesUIView

Represents the current view.

See examples
Example: CurrentView property


AddDatabase method

Adds a database to the workspace and highlights the icon, or highlights the icon if the database is already on the workspace.

Defined in

NotesUIWorkspace

Syntax

Call notesUIWorkspace.AddDatabase( server$ , filename$ )

Parameters

server$

String. The name of the server where the database resides. If this parameter is omitted or is an empty string (""), the database is opened on the local computer.

filename$

String. Optional. The path and file name of the database.

See examples
Example: AddDatabase method


CheckAlarms method

Triggers the alarm daemon to check for new alarms in the mail file.

Defined in

NotesUIWorkspace

Syntax

Call notesUIWorkspace.CheckAlarms( )

Usage

You use this method when creating a new alarm from a template. Any time a template creates a new appoint event that contains an alarm, the template script calls CheckAlarms, causing the daemon to check for new alarms.

See also
Accessing the current document
EnableAlarms method


ComposeDocument method

Using a database and form you specify, creates a new document and displays it on the workspace.

Defined in

NotesUIWorkspace

Syntax

Set notesUIDocument = notesUIWorkspace.ComposeDocument( [ server$ [, file$ [, form$ [, windowWidth# [, windowHeight# ]]]]] )

Parameters

server$

String. Optional. The name of the server where the database resides. If this parameter is omitted or is an empty string (""), the database is opened on the local computer. If both server$ and file$ are omitted or empty strings, the current database is used.

file$

String. Optional. The file name of the database you want to compose a document in. If this parameter is omitted or is an empty string (""), a document is composed in the current database.

form$

String. Optional. The name of the form you want to use to compose the document. If this parameter is omitted or is an empty string (""), the Create Other dialog box is displayed and the user can select a form name.

windowWidth#

Double. Optional. The width in inches of the document window. If this parameter is omitted, the window is the width of the current window.

windowHeight#

Double. Optional. The height in inches of the document window. If this parameter is omitted, the window is the height of the current window.

Return value

notesUIDocument

The document that was just created and opened.

Usage

If the ComposeDocument method is used in a view action, the form formula of the view will override the form specified in the method. To avoid this problem add the following line to the form formula.

@If(@IsNewDoc; @Return(Form); "");
See examples
Examples: ComposeDocument method

See also
EditDocument method
Accessing the current document
NotesUIDocument class


DialogBox method

Brings up a dialog box that displays the current document (either open or selected in a view) or a specified document using a form you specify. The user interacts with the form and document as usual, clicking OK or Cancel when finished.

This function can be used with any form, but it's particularly useful with forms that contain a single layout region or table, because the user can interact with the layout region or table as if it were a dialog box.

Defined in

NotesUIWorkspace

Syntax

flag = notesUIWorkspace.DialogBox( form$ [, autoHorzFit [, autoVertFit [, noCancel [, noNewFields [, noFieldUpdate [, readOnly [, title$ [, notesDocument [, sizeToTable [, noOkCancel ]]]]]]]]]] )

Parameters

form$

String. The name of the form.

autoHorzFit

Boolean. Optional. Specify True if you want to scale the layout region horizontally to fit into the dialog box. If you specify False or omit this parameter, the layout region is not scaled horizontally.

autoVertFit

Boolean. Optional. Specify True if you want to scale the layout region vertically to fit into the dialog box. If you specify False or omit this parameter, the layout region is not scaled vertically.

noCancel

Boolean. Optional. Specify True if you want to display only an OK button. If you specify False or omit this parameter, both OK and Cancel buttons appear.

noNewFields

Boolean. Optional. Specify True if you don't want to add fields (that are on the dialog box form but not on the underlying form) to the underlying form. If you specify False or omit this parameter, all dialog box fields are passed to the underlying form.

noFieldUpdate

Boolean. Optional. Specify True if you don't want to pass any edits from the dialog box to the underlying form (for example, if you're passing the edits somewhere else in a Queryclose script for the dialog box form). If you specify False or omit this parameter, the edits are passed to the underlying form.

readOnly

Boolean. Optional. Specify True if you want to prohibit writing to the dialog box (for example, if you are using the dialog box to display a help screen). If you specify False or omit this parameter, the dialog box is read-write. This option makes noCancel true.

title$

String. Optional. A title for the dialog box. Defaults to "Lotus Notes."

notesDocument

NotesDocument. Optional. A document to be opened instead of the current document.

sizeToTable

Note This parameter is new with Release 5.

Boolean. Optional. Specify True if you want to scale a table to fit into the dialog box. If you specify False or omit this parameter, the table is not scaled to fit the dialog box.

noOkCancel

Note This parameter is new with Release 5.

Boolean. Optional. Specify True if you do not want to display the Ok and Cancel buttons. If you specify False or omit this parameter, both OK and Cancel buttons appear. This parameter is dependent upon the noCancel parameter. If the noCancel parameter is False, the noOkCancel parameter is ignored.

Return value

flag

Boolean. Returns True if the user clicks OK in the dialog box. Returns False if the user clicks Cancel.

Usage

autoHorzFit and autoVertFit allow you to display an entire layout region in a dialog box, without displaying the rest of the form. If there is more than one layout region on a form, only the first one is displayed. For best results:

  • Use both parameters.

  • In the layout region InfoBox, deselect Display Border and select 3D style.

Sharing of field values

This method displays the current or specified document using a different form. This means:

  • If the form has field names in common with the document, the field values of the document are displayed in the dialog box.

  • If the user changes the value of any fields in the dialog box and clicks OK, the changes are reflected in the same fields on the document.

  • If the user enters a value for a field in the dialog box, and the document does not contain a field by that name, the value is added to the document, even if it is not displayed in the form, unless noNewFields is True.

See examples
Examples: DialogBox method

See also
Accessing the current document


EditDocument method

Opens the current or a specified document in a mode you specify. The current document may be either of the following:

  • The document that's currently open.

  • The document that's currently selected in a view or folder.

Defined in

NotesUIWorkspace

Syntax

Set notesUIDocument = notesUIWorkspace.EditDocument( [editMode [, notesDocument [, notesDocumentReadOnly [, documentanchor$ ]]]] )

Parameters

editMode

Boolean. Optional. Specify True to open the document in Edit mode. Specify False to open the document in Read mode or put the document in the given Edit mode. If you omit this parameter, the document is opened in Edit mode.

notesDocument

NotesDocument. Optional. Opens the specified document instead of the currently selected document.

notesDocumentReadOnly

Boolean. Optional. If True, sets notesDocument to read-only mode, which prevents the user from later switching to read-write mode. This parameter does not open the document in Read mode; you must set editMode to False. This parameter has no effect if you do not specify notesDocument.

documentanchor$

String. Optional. Opens the document to the specified anchor/location within the document.

Return value

notesUIDocument

The document that's just been opened.

See examples
Examples: EditDocument method

See also
CurrentDocument property

EditMode property
Accessing the current document
NotesUIDocument class
PostModeChange event
PostOpen event
QueryModeChange event
QueryOpen event


EditProfile method

Opens a new or existing profile document in Edit mode.

Defined in

NotesUIWorkspace

Syntax

Set notesUIDocument = notesUIWorkspace.EditProfile( profileName$ [ , userName$] )

Parameters

profileName$

String. The name or an alias of the profile document, or the form name to use to display the profile document.

userName$

String. Optional. The user name (key) attached to the profile document.

Usage

You can efficiently store information in profile documents. You can access them quickly and use them in templates to store specific information or share variables across scripts within a database.

Only one profile of a given form or name can exist per database per person. If you create a profile without a user name associated with it, then Notes assumes it's the only profile document of that type in the database. You need at least author access to create a profile that applies to an entire database.

Documents saved with EditProfile are hidden.

See examples
Example: EditProfile method

See also
GetProfileDocument method
IsProfile property (in NotesDocument)
Key property (in NotesDocument)
NameOfProfile property (in NotesDocument)


EnableAlarms method

Starts or stops the alarm daemon.

Defined in

NotesUIWorkspace

Syntax

flag = notesUIWorkspace.EnableAlarms( enable )

Parameter

enable

Boolean. True starts the alarm daemon if it's not already running. False stops the alarm daemon if it is running.

See also
CheckAlarms method
Accessing the current document


Folder method

Displays the Move To Folder dialog and moves the current document to a folder.

Note This method is new with Release 5.

Defined in

NotesUIWorkspace

Syntax

variant = notesUIWorkspace.Folder( [foldername$] , move )

Parameters

foldername$

String. Optional. Name of the folder to which the current document should be moved. If you do not specify a foldername, this method displays the Move To Folder dialog.

move

Boolean. Specify True if the document should be moved from the current folder to the new folder.

See examples
Examples: Folder method


GetListOfTunes method

Returns the known sounds on your system.

Note This method is new with Release 5.

Defined in

NotesUIWorkspace

Syntax

variant = notesUIWorkspace.GetListOfTunes( )

Return value

variant

An array of strings that represent the sounds on the system.

See examples
Example: GetListOfTunes method


OpenDatabase method

Opens a database to a view you specify.

Defined in

NotesUIWorkspace

Syntax

Call notesUIWorkspace.OpenDatabase( server$, file$, view$, key$, newInstance, temp )

Parameters

server$

String. The name of the server where the database resides.

file$

String. The path and file name of the database.

view$

String. Optional. The name of the view you want to open. If you omit this parameter, the database opens to its default view.

key$

String. Optional. Indicates which document you want to scroll to when the view is opened. The key is a value that appears in the first sorted column of view$. If you omit this parameter, no document is selected.

newInstance

Boolean. Optional. Specify True if you want the view to open in a new window, even if there's already a window open for the database. If you specify False or omit this parameter, the new window is opened only when it's actually needed.

temp

Boolean. Optional. Specify True if you only want the database opened on a temporary basis for browsing, without adding the database to the user's workspace. If you specify False or omit this parameter, the database is added to the user's workspace.

See examples
Example: OpenDatabase method

See also
Accessing the current document


OpenFileDialog method

Displays the common FileOpen dialog.

Note This method is new with Release 5.

Defined in

NotesUIWorkspace

Syntax

stringArray = notesUIWorkspace.OpenFileDialog( multipleSelection [, title$ [, filters$ [, initialDirectory$ [, initialFile$ ]]]] )

Parameters

multipleSelection

Boolean. Specify True if you want to select multiple files.

title$

String. Optional. Title that you would use for the dialog.

filters$

String. Optional. User-defined string of filters that can limit the files displayed. For example, "Notes Databases|*.nsf|Notes Templates|*.ntf"

initialDirectory$

String. Optional. The directory that you want to use when the dialog is displayed.

initialFile$

String. Optional. The filename that you want to appear when the dialog is displayed.

Return value

variant

Could be a string array of the selected filename(s) if you click OK, or it could be Empty if you click Cancel.

See examples
Example: OpenFileDialog method


OpenFrameSet method

Opens the specified frameset within the current target frame. This method supports the @Command([OpenFrameset]) function.

Note This method is new with Release 5.

Defined in

NotesUIWorkspace

Syntax

Call notesUIWorkspace.OpenFrameSet( frameset$ )

Parameters

frameset$

String. Name of the frameset defined for the current database.

See examples
Example: OpenFrameSet method


OpenPage method

Opens the specified page within the current target frame. This method supports the @Command([OpenPage]) function.

Note This method is new with Release 5.

Defined in

NotesUIWorkspace

Syntax

Call notesUIWorkspace.OpenPage( pagename$ )

Parameters

pagename$

String. Name of the page defined for the current database.

See examples
Example: OpenPage method

See also


PickListCollection method

Displays a modal window that contains a view you specify, from which you can select one or more documents. This method supports the @Picklist function.

Note This method is new with Release 5.

Defined in

NotesUIWorkspace

Syntax

Set notesDocumentCollection = notesUIWorkspace.PickListCollection( type% [,multipleSelection ] [, server$ ] [, databaseFileName$ ] [, viewName$ ] [, title$ ] [, prompt$ ] [, Singlecategory$ ] )

Parameters

type$

Integer. The type of view you specify. This parameter is restricted to PICKLIST_CUSTOM. This value displays the specified view in a dialog.

multipleSelection

Boolean. Optional. Specify True if you want to select multiple documents.

server$

String. Optional. Name of the server where the database resides.

databaseFileName$

String. Optional. The filename of the database that contains the view.

viewName$

String. Name of the view that you want displayed in the dialog.

title$

String. Optional. Title that you would use for the dialog.

prompt$

String. Optional. The prompt you want to appear inside the dialog.

Singlecategory$

String. Optional. Displays the specified category in the view. The view should be categorized in order to use this parameter.

Return value

This method returns a NotesDocumentCollection object if you click OK, or it could return Nothing if you click Cancel.

Usage

Note If the type parameter is set to PICKLIST_CUSTOM, then all the optional parameters except Singlecategory and multipleSelection become required.

See also PickListStrings method in the NotesUIWorkspace class.

See examples
Example: PickListCollection Method


PickListStrings method

Displays a modal window that contains a view you specify, from which you can select one or more documents. This method supports the @Picklist function.

Note This method is new with Release 5.

Defined in

NotesUIWorkspace

Syntax

Set stringArray = notesUIWorkspace.PickListStrings( type%, multipleSelection [, server$ ] [, databaseFileName$ ] [, viewName$ ] [, title$ ] [, prompt$ ] [, column% ][, catetoryname$] )

Parameters

type$

Integer. The type of view you specify. The legal values for this parameter are:

PICKLIST_NAMES | Displays the names dialog
PICKLIST_ROOMS | Displays the rooms dialog
PICKLIST_RESOURCES | Displays the resources dialog
PICKLIST_CUSTOM | Displays the dialog for the view that you specify

Note The following parameters are needed only when Type takes the legal value PICKLIST_CUSTOM:

server$, databaseFileName$, viewName$, title$, prompt$, column%.

multipleSelection

Boolean. Specify True if you want to select multiple documents.

server$

String. Optional. Name of the server where the database resides.

databaseFileName$

String. Optional. The filename of the database that contains the view.

viewName$

String. Optional. Name of the view that you want displayed in the dialog.

title$

String. Optional. Title that you would use for the dialog.

prompt$

String. Optional. The prompt you want to appear inside the dialog.

column%

Integer. Optional. The column value that you want returned.

categoryname$

String. Optional. Displays the specified category in the view. The view should be categorized in order to use this parameter.

Return value

This method returns a Variant containing a stringArray if you click OK, or it could return Nothing if you click Cancel. Use the LotusScript Debugger to see what is returned in the stringArray.

Usage

See also PickListCollection method in the NotesUIWorkspace class.

See examples
Example: PickListStrings method


PlayTune method

Plays the specified tune.

Note This method is new with Release 5.

Defined in

NotesUIWorkspace

Syntax

Call notesUIWorkspace.PlayTune( tuneName$ )

Parameters

tuneName$

String. Could be the name of the sound from the GetListOfTunes method or a complete file path.

See examples
Example: PlayTune method


Prompt method

Displays a dialog box and returns a value based on your actions in the dialog box. This method is an interface to the @Prompt function.

Note This method is new with Release 5.

Defined in

NotesUIWorkspace

Syntax

variant = notesUIWorkspace.Prompt( type%, title$, prompt$, [default ] [, values ] )

Parameters

type%

Constant. Indicates the type of dialog box you want to display. May be any of the following:

PROMPT_OK

PROMPT_YESNO

PROMPT_YESNOCANCEL

PROMPT_OKCANCELEDIT

PROMPT_OKCANCELLIST

PROMPT_OKCANCELCOMBO

PROMPT_OKCANCELEDITCOMBO

PROMPT_OKCANCELLISTMULT

PROMPT_PASSWORD

title$

String. The text you want displayed in the dialog box's title bar.

prompt$

String. The text you want displayed within the dialog box.

default

The value that will be used as your default input value. The input section of the dialog box will be primed with the value; you can either accept it by selecting OK or replace it with another value.

The default value(s) for PROMPT_EDIT, PROMPT_LIST, PROMPT_COMBO, PROMPT_EDITCOMBO, and PROMPT_LISTMULT is either a string, a string array, a variant of type string, or a variant array of strings.

values

The values that you want displayed in the dialog box's list box. The user can select one of these values as the input.

The values for PROMPT_LIST, PROMPT_COMBO, PROMPT_EDITCOMBO, and PROMPT_LISTMULT is either a string array, a variant of type string, or a variant array of strings.

Return value

Variant of type integer | for PROMPT_OK, PROMPT_YESNO, PROMPT_YESNOCANCEL
Variant of type string | for PROMPT_EDIT, PROMPT_LIST, PROMPT_COMBO, PROMPT_EDITCOMBO, and PROMPT_PASSWORD
Variant Array | for PROMPT_LISTMULT

The return value is a variant containing a string array if you press OK; and Empty if you press Cancel.

See examples
Example: Prompt method


RefreshParentNote method

Updates the note with the specified value entered in the dialog box. This method supports the @Command([RefreshParentNote]) function.

Note This method is new with Release 5.

Defined in

NotesUIWorkspace

Syntax

Call notesUIWorkspace.RefreshParentNote( )

Usage

This method is used mainly to create your own buttons to dismiss a dialog box. Mostly used in the QueryClose event.


ReloadWindow method

Reloads the contents of the current window.

Note This method is new with Release 5.

Defined in

NotesUIWorkspace

Syntax

Call notesUIWorkspace.ReloadWindow( )

Usage

This method is supported by the @command([ReloadWindow]).


SaveFileDialog method

Displays the common FileSave dialog.

Note This method is new with Release 5.

Defined in

NotesUIWorkspace

Syntax

stringArray = notesUIWorkspace.SaveFileDialog( multipleSelection [, title$ ] [, filters$ ] [, initialDirectory$ ] [, initialFile$ ] )

Parameters

multipleSelection

Boolean. Specify True if you want to select multiple files.

title$

String. Optional. Title that you would use for the dialog.

filters$

String. Optional. User-defined string of filters that can limit the files displayed. For example, "Notes Databases|*.nsf|Notes Templates|*.ntf"

initialDirectory$

String. Optional. The directory that you want to use when the dialog is displayed.

initialFile$

String. Optional. The filename that you want to appear when the dialog is displayed.

Return value

Variant

Could be a string array of the selected filename(s) if you click OK, or it could be Empty if you click Cancel.


SetCurrentLocation method

Sets your current workstation location to the specified location, such as Office, Island, Home, or Travel. This method supports the @Command([SetCurrentLocation]) function.

Note This method is new with Release 5.

Defined in

NotesUIWorkspace

Syntax

Call notesUIWorkspace.SetCurrentLocation( [ location$ ] )

Parameters

location$

String. Optional. Name of location to switch to. If location$ is "" or omitted, this method brings up the Change Location dialog box.

See examples
Examples: SetCurrentLocation method


SetTargetFrame method

Allows you to specify a target frame when opening a view, page, or frameset, or when composing or editing a document. This method supports the @SetTargetFrame function.

Note This method is new with Release 5.

Defined in

NotesUIWorkspace

Syntax

Call notesUIWorkspace.SetTargetFrame( frame$ )

Parameters

frame$

String. The name of the frame that a view, page, frameset, or document should open into. You could also specify a path to the nested frame.

Usage

Use SetTargetFrame method before opening the view, page, or frameset, or before composing or editing a document. The following methods will use the frame specified in the SetTargetFrame method:

  • OpenFrameSet

  • OpenPage

  • OpenView

  • ComposeDocument

  • EditDocument

See examples
Example: SetTargetFrame method


URLOpen method

Retrieves a World Wide Web page specified by its URL.

Defined in

NotesUIWorkspace

Syntax

Call notesUIWorkspace.URLOpen( Url$, reload%, urlList%, charset$, webusername$, webpassword$, proxywebusername$, proxywebpassword$, notesRetriever )

Parameters

Url$

String. Optional. The URL for the Web page you want to open, for example, http://www.acme.com/. If you omit this parameter, you see the Open URL dialog box where the user can enter the URL for the Web page.

reload%

Integer. Optional. Enter 1 (True) to reload the page from its Internet server. Enter 0 (False) to load the page from the Internet only if it is not already in the Web Navigator database. Enter 2 to reload the page only if it has been modified on its Internet server. The default value is 0.

urlList%

Integer. Optional. Web pages can contain URL links to other Web pages. This value specifies that the Web Navigator should save the URLs in a field called URLLinksn in the document. (The Web Navigator creates a new URLLinksn field each time the field size reaches 64K. For example, the first URLLinks field would be URLLinks1, the second would be URLLinks2, and so on.)

If you save the URLs, you can use them in agents; for example, you could create an agent that opens Web pages in the Web Navigator database and then loads all the Web pages saved in each of the URLLinksn field(s).

charset$

String. Optional. Enter the MIME character set (for example, ISO-2022-JP for Japanese or ISO-8859-1 for United States) that you want the Web Navigator to use when processing the Web page. Only use this parameter when the Web Navigator misdetects the correct MIME character set of the URL contents.

webusername$

String. Optional. Some Internet servers require you to obtain a username before you can access their pages. This parameter allows you to enter the username that you previously obtained from the Internet server.

webpassword$

String. Optional. Some Internet servers require you to obtain a password before you can access their pages. This parameter allows you to enter the password that you previously obtained from the Internet server.

proxywebusername$

String. Optional. Some proxy servers require that you specify a username in order to connect through them. This parameter allows you to enter the username for the proxy server. See your administrator for the username required by the proxy.

proxywebpassword$

String. Optional. Some proxy servers require that you specify a password in order to connect through them. This parameter allows you to enter the password for the proxy server. See your administrator for the password required by the proxy.

notesRetriever

Boolean. Optional. If set to False or omitted, the default browser opens the URL. If present, or set to True, the Notes Web Navigator opens the URL.

Usage

For more information, see Working with the Internet.

See examples
Example: URLOpen method


UseLSX method

Loads a LotusScript extensions (lsx) file containing Public definitions.

Defined in

NotesUIWorkspace

Syntax

Call notesUIWorkspace.UseLSX( lsxLibraryName$ )

Parameters

lsxLibraryName$

String. The lsx file to load, either a name prepended with an asterisk or the full path name of the file. If you specify a name prepended with an asterisk (for example, "*lsxodbc"), the file is determined by searching the registry, initialization file, or preferences file, depending on the client platform. The Windows95 registry, for example, might contain an entry for HKEY_LOCAL_MACHINE, SOFTWARE, Lotus, Components, LotusScriptExtensions, 2.0, LSXODBC, whose value is "c:\notes95\nlsxodbc.dll."

Usage

LotusScript registers the Public classes defined in the lsx file for use in the module containing the UseLSX statement. Other modules that use the containing module can also access the Public classes.

See examples
Example: UseLSX method


ViewRefresh method

Refreshes the current view.

Defined in

NotesUIWorkspace

Syntax

Call notesUIWorkspace.ViewRefresh

Usage

If a view is in the active window, this method refreshes the current view.

If a document is in the active window, this method refreshes the view associated with that window, but not until the view's window is activated.

To refresh a view from within a document, you must perform both the back-end NotesView Refresh and the front-end NotesUIWorkspace ViewRefresh methods, before exiting out of the view.

See examples
Examples: ViewRefresh method


NotesView class

Represents a view or folder of a database and provides access to documents within it.

Containment

Contained by: NotesDatabase, NotesUIView

Contains: NotesDocument, NotesViewColumn, NotesViewEntry, NotesViewEntryCollection, and NotesViewNavigator

Properties

Aliases

AllEntries

AutoUpdate

BackgroundColor

ColumnCount

ColumnNames

Columns

Created

HeaderLines

HttpURL

IsCalendar

IsCategorized

IsConflict

IsDefaultView

IsFolder

IsHierarchical

IsModified

IsPrivate

LastModified

Name

NotesURL

Parent

ProtectReaders

Readers

RowLines

Spacing

TopLevelEntryCount

UniversalID

Methods

Clear

CreateViewNav

CreateViewNavFrom

CreateViewNavFromCategory

CreateViewNavFromChildren

CreateViewNavFromDescendants

CreateViewNavMaxLevel

FTSearch

GetAllDocumentsByKey

GetAllEntriesBykey

GetChild

GetColumn

GetDocumentByKey

GetEntryByKey

GetFirstDocument

GetLastDocument

GetNextDocument

GetNextSibling

GetNthDocument

GetParentDocument

GetPrevDocument

GetPrevSibling

Refresh

Remove

Access

You access a view or folder through the NotesDatabase object that contains it. There are two ways:

  • To access a view or folder when you know its name or synonym, use the GetView method.

  • To access all the views and folders in a database, use the Views property.

Both options return NotesView objects that represent public view(s) and/or folder(s) in the database. If a script runs on a workstation, the NotesView objects may also represent personal views and folders.

Usage

Both NotesDocumentCollection and NotesView objects provide access to both selected and all documents within a database. Use a NotesView object if:

  • There is a view or folder in the database that contains all the documents you want to search.

  • You need to navigate through the documents' response hierarchies.

  • You want to access documents as quickly as possible.

  • You want to find a document by its key in a view.

  • You want to access documents in sorted order.

Views are the more efficient means of accessing documents because they are already indexed by the database itself.

See examples
Examples: NotesView class

See also
Using the Domino classes
Accessing views and folders


Aliases property

Read-only. The aliases of a view.

Defined in

NotesView

Data type

Array of strings

Syntax

To get: aliases = notesView.Aliases

Usage

When you use GetView, this property returns all but the first in the list of all the view's names. The Names property returns the first name in the list.

For example, for the name "All\By review date|Review," the property returns "Review."

IsEmpty is True for this property if the view has no aliases.

See examples
Example: Aliases property

See also
Name property


AllEntries property

Read-only. All the entries in a view.

Note This property is new with Release 5.

Defined in

NotesView

Data type

NotesViewEntryCollection

Syntax

To get: notesViewEntryCollection = notesView.AllEntries

See examples
Example: AllEntries property


AutoUpdate property

Read-write. Indicates whether the front-end view is automatically updated each time a change occurs in the back-end.

Defined in

NotesView

Data type

Boolean

Syntax

To get: flag = notesView.AutoUpdate

To set: notesView.AutoUpdate = flag

Legal values

True | The front-end view is automatically updated (default)
False | The front-end view is not automatically updated

Usage

Whether the argument is True or False does not affect the physical refresh of the screen. What it affects, is the order in which the documents in the view are found. AutoUpdate affects the pointer to the next document.

See examples
Example: AutoUpdate property


BackgroundColor property

Read-only. The background color of a view.

Note This property is new with Release 5.

Defined in

NotesView

Data type

Integer

Syntax

To get: color% = notesView.BackgroundColor

Legal values

  • COLOR_BLACK (0)

  • COLOR_BLUE (4)

  • COLOR_CYAN (7)

  • COLOR_DARK_BLUE (10)

  • COLOR_DARK_CYAN (13)

  • COLOR_DARK_GREEN (9)

  • COLOR_DARK_MAGENTA (11)

  • COLOR_DARK_RED (8)

  • COLOR_DARK_YELLOW (12)

  • COLOR_GRAY (14)

  • COLOR_GREEN (3)

  • COLOR_LIGHT_GRAY (15)

  • COLOR_MAGENTA (5)

  • COLOR_RED (2)

  • COLOR_WHITE (1)

  • COLOR_YELLOW (6)

Note These values are also used with the FontColor property in the NotesViewColumn class, and NotesColor property of the NotesRichTextStyle class.

See examples
Example: BackgroundColor property


ColumnCount property

Read-only. The number of columns in a view.

Note This property is new with Release 5.

Defined in

NotesView

Data type

Integer

Syntax

To get: count% = notesView.ColumnCount

See examples
Example: ColumnCount property


ColumnNames property

Read-only. The names of the columns in a view.

Note This property is new with Release 5.0.2b.

Note This property is supported in COM only.

Defined in

NotesView

Data type

Variant

Syntax

To get: variant = notesView.ColumnNames

Usage

The order of the column names corresponds to the order of the columns in the view, from left to right.

See examples
Examples: ColumnNames property


Columns property

Read-only. All the columns in a view.

Defined in

NotesView

Data type

Array of NotesViewColumns

Syntax

To get: notesViewColumnArray = notesView.Columns

Return value

notesViewColumnArray

Array of NotesViewColumns. The order of NotesViewColumns in the array corresponds to the order of columns in the view, from left to right.

Usage

To set the value of an individual NotesViewColumn object, you need to access the array elements individually. For example, to get the first element in the array returned from the NotesView object view, you could do the following:

Dim column as NotesViewColumn

Set column = view.Columns( 0 )

See examples
Example: Columns property

See also
Accessing view or folder columns
ColumnValues property (in NotesDocument)
NotesViewColumn class


Created property

Read-only. The date that a view was created.

Defined in

NotesView

Data type

Variant of type DATE

Syntax

To get: dateV = notesView.Created

See examples
Example: Created property

See also
LastModified property


HeaderLines property

Read-only. The number of lines in the header of a view.

Note This property is new with Release 5.

Defined in

NotesView

Data type

Integer

Syntax

To get: lines% = notesView.HeaderLines

See examples
Example: HeaderLines property


HttpURL property

Read-only. The HTTP URL of a view.

Note This property is new with Release 5.0.2b.

Note This property is supported in COM only.

Defined in

NotesView

Data type

String

Syntax

To get: url$ = notesView.HttpURL


IsCalendar property

Read-only. Indicates whether a view is a calendar view.

Defined in

NotesView

Data type

Boolean

Syntax

To get: flag = notesView.IsCalendar

Return value

  • True indicates that the view is a calendar view

  • False indicates that the view is a standard outline view

See examples
Example: IsCalendar property


IsCategorized property

Read-only. Indicates whether a view is categorized.

Note This property is new with Release 5.

Defined in

NotesView

Data type

Boolean

Syntax

To get: flag = notesView.IsCategorized

Legal values

  • True indicates that the view is categorized

  • False indicates that the view is not categorized

See examples
Example: IsCategorized property


IsConflict property

Read-only. Indicates whether a view is enabled for conflict checking.

Note This property is new with Release 5.

Defined in

NotesView

Data type

Boolean

Syntax

To get: flag = notesView.IsConflict

Legal values

  • True indicates that the calendar view is enabled for conflict checking

  • False indicates that the calendar view is not enabled for conflict checking

See examples
Example: IsConflict property


IsDefaultView property

Read-only. Indicates whether a view is the default view of the database.

Defined in

NotesView

Data type

Boolean

Syntax

To get: flag = notesView.IsDefaultView

Return value

  • True indicates that the view is the default view

  • False indicates that the view is not the default view

See examples
Example: IsDefaultView property


IsFolder property

Read-only. Indicates whether a NotesView object represents a folder.

Defined in

NotesView

Data type

Boolean

Syntax

To get: flag = notesView.IsFolder

Return value

  • True indicates tha the NotesView object represents a folder

  • False indicates that the NotesView object represents a view

See examples
Example: IsFolder property


IsHierarchical property

Read-only. Indicates whether a view shows response documents in a hierarchy.

Note This property is new with Release 5.

Defined in

NotesView

Data type

Boolean

Syntax

To get: flag = notesView.IsHierarchical

Legal values

  • True indicates that a view is hierarchical

  • False indicates that a view is not hierarchical

See examples
Example: IsHierarchical property


IsModified property

Read-only. Indicates whether a view is modified.

Note This property is new with Release 5.

Defined in

NotesView

Data type

Boolean

Syntax

To get: flag = notesView.IsModified

Legal values

  • True indicates that the view is modified

  • False indicates that the view is not modified

Usage

The IsModified property can be used to determine if the current view snapshot on the Notes client corresponds to the real state of the view on the server. The view on the server can change as a result of multiple users accessing it, and this property can be used to determine if the view needs refreshing.

The IsModified property will always return True for programs accessing views remotely, and False when accessing views via agents or standalone applications.

See examples
Example: IsModified property


IsPrivate property

Read-only. Indicates if an entry is specific to an individual.

Note This property is new with Release 5.

Defined in

NotesView

Data type

Boolean

Syntax

To get: flag = notesView.IsPrivate

Legal values

  • True indicates that the view is specific to an individual

  • False indicates that the view is not specific to an individual


LastModified property

Read-only. The date that a view was last modified.

Defined in

NotesView

Data type

Variant of type DATE

Syntax

To get: dateV = notesView.LastModified

See examples
Example: LastModified property


Name property

Read-only. The name of a view.

Defined in

NotesView

Data type

String

Syntax

To get: name$ = notesView.Name

Usage

You can use GetView with any of the view's names. Notes parses through all the view's names and the Name property returns the first one on the list. You can use the Aliases property to access the rest of the names.

For example, for the name "All\By review date|Review," the property returns "All\By review date."

See examples
Example: Name property

See also
Aliases Property


NotesURL property

Read-only. The Notes URL of a view.

Note This property is new with Release 5.0.2b.

Note This property is supported in COM only.

Defined in

NotesView

Data type

String

Syntax

To get: url$ = notesView.NotesURL


Parent property

Read-only. The database to which a view belongs.

Defined in

NotesView

Data type

NotesDatabase

Syntax

To get: Set notesDatabase = notesView.Parent

See examples
Example: Parent property


ProtectReaders property

Read-write. Protects $Readers items from being overwritten by replication.

Defined in

NotesView class

Data type

Boolean

Syntax

To get: flag = notesView.ProtectReaders

To set: notesView.ProtectReaders = flag

Legal values

  • True indicates that the items are protected

  • False indicates that the items are not protected

See examples
Example: ProtectReaders property

See also
Accessing view or folder properties
Readers property


Readers property

Read-write. The contents of the $Readers field associated with the view.

Defined in

NotesView class

Data type

Array of strings

Syntax

To get: stringArray = notesView.Readers

To set: notesView.Readers = stringArray

Usage

This property accepts an array of strings or a single string. Setting this property replaces prior values.

Set the property to "" to remove all reader restrictions.

See examples
Examples: Readers property


RowLines property

Read-only. The number of lines in each row of a view.

Note This property is new with Release 5.

Defined in

NotesView

Data type

Integer

Syntax

To get: lines% = notesView.RowLines

See examples
Example: RowLines property


Spacing property

Read-only. The spacing between rows of a view.

Note This property is new with Release 5.

Defined in

NotesView

Data type

Integer

Syntax

To get: spacing% = notesView.Spacing

Legal values

  • VW_SPACING_SINGLE,

  • VW_SPACING_ONE_POINT_25,

  • VW_SPACING_ONE_POINT_50,

  • VW_SPACING_ONE_POINT_75,

  • VW_SPACING_DOUBLE

See examples
Example: Spacing property


TopLevelEntryCount property

Read-only. The number of top-level entries in a view.

Note This property is new with Release 5.

Defined in

NotesView

Data type

Integer

Syntax

To get: count% = notesView.TopLevelEntryCount

Usage

If the view is a categorized view, this property returns the number of main categories. If the view also has totals, the result will include 1 for the grand total entry.

See examples
Example: TopLevelEntryCount property


UniversalID property

Read-only. The Universal ID of a view, which is a 32-character combination of letters and numbers that uniquely identifies a view across all replicas of a database.

Defined in

NotesView

Data type

String

Syntax

To get: unid$= notesView.UniversalID

Usage

Returns empty strings for category and total entries.

See examples
Example: UniversalID property


Clear method

Clears the full-text search filtering on a view.

Defined in

NotesView

Syntax

Call notesView.Clear

See examples
Example: Clear method

See also
FTSearch method (in NotesView)
Locating documents within a view or folder


CreateViewNav method

Creates a view navigator for all entries in a view.

Note This method is new with Release 5.

Defined in

NotesView

Syntax

Set notesViewNavigator = notesView.CreateViewNav( cacheSize )

Parameter

cacheSize

Note This parameter is for COM only.

Long. Optional. The size of the navigator cache in view entries. Legal values are 0 (no cache) through 128 (default).

Return value

notesViewNavigator

The new view navigator.

Usage

The navigator contains all entries even if the view is filtered for a full-text search.

See examples
Example: CreateViewNav method


CreateViewNavFrom method

Creates a view navigator for all entries in a view starting at a specified entry.

Note This method is new with Release 5.

Defined in

NotesView

Syntax

Set notesViewNavigator = notesView.CreateViewNavFrom( navigatorObject [, cacheSize ])

Parameters

navigatorObject

Variant. A Document or ViewEntry object representing the starting entry. If you specify Nothing, this method will generate an error.

cacheSize

Note This parameter is for COM only.

Long. Optional. The size of the navigator cache in view entries. Legal values are 0 (no cache) through 128 (default).

Return value

notesViewNavigator

The new view navigator whose first entry is the specified Document or ViewEntry object; subsequent entries are all the entries in the view that follow the specified entry.

Usage

The navigator contains all entries even if the view is filtered for a full-text search.

See examples
Example: CreateViewNavFrom method


CreateViewNavFromCategory method

Creates a view navigator for all entries under a specified category.

Note This method is new with Release 5.

Defined in

NotesView

Syntax

Set notesViewNavigator = notesView.CreateViewNavFromCategory( category [, cacheSize ])

Parameters

category

String. The name of a category in the view.

cacheSize

Note This parameter is for COM only.

Long. Optional. The size of the navigator cache in view entries. Legal values are 0 (no cache) through 128 (default).

Return value

notesViewNavigator

The new view navigator.

Usage

The navigator contains all entries even if the view is filtered for a full-text search.

See examples
Example: CreateViewNavFromCategory method


CreateViewNavFromChildren method

Creates a view navigator for all the immediate children of a specified entry.

Note This method is new with Release 5.

Defined in

NotesView

Syntax

Set notesViewNavigator = notesView.CreateViewNavFromChildren( navigatorObject [, cacheSize ])

Parameters

navigatorObject

Variant. A Document or ViewEntry object representing the parent entry. If you specify Nothing, this method will generate an error.

cacheSize

Note This parameter is for COM only.

Long. Optional. The size of the navigator cache in view entries. Legal values are 0 (no cache) through 128 (default).

Return value

notesViewNavigator

The new view navigator.

Usage

The navigator contains all entries even if the view is filtered for a full-text search.

See examples
Example: CreateViewNavFromChildren method


CreateViewNavFromDescendants method

Creates a view navigator for all the descendants of a specified entry.

Note This method is new with Release 5.

Defined in

NotesView

Syntax

Set notesViewNavigator = notesView.CreateViewNavFromDescendants( navigatorObject [, cacheSize ])

Parameters

navigatorObject

Variant. A Document or ViewEntry object representing the parent entry. If you specify Nothing, this method will generate an error.

cacheSize

Note This parameter is for COM only.

Long. Optional. The size of the navigator cache in view entries. Legal values are 0 (no cache) through 128 (default).

Return value

notesViewNavigator

The new view navigator.

Usage

The navigator contains all entries even if the view is filtered for a full-text search.

See examples
Example: CreateViewNavFromDescendants method


CreateViewNavMaxLevel method

Creates a view navigator for all entries in a view down to a specified level.

Note This method is new with Release 5.0.2b.

Note This method is supported in COM only.

Defined in

NotesView

Syntax

Set notesViewNavigator = notesView.CreateViewNavMaxLevel( level& [, cacheSize& ])

Parameters

level&

Integer. The maximum level of navigation 0 (top level) through 30 (default).

cacheSize&

Integer. Optional. The size of the navigator cache in view entries. Legal values are 0 (no cache) through 128 (default).

Return value

notesViewNavigator

The new view navigator.

Usage

The entries in the navigator are all the entries in the view at levels 0 through the specified level.

An empty view results in an empty navigator. All navigation methods return null.

The cache enhances performance for iterative processing of entries using the navigation methods that do not take a parameter

See examples
Examples: CreateViewNavMaxLevel method


FTSearch method

Conducts a full-text search on all documents in a view and filters the view so it represents only those documents that match the full-text query. This method does not find word variants.

Defined in

NotesView

Syntax

numDocs& = notesView.FTSearch( query$, maxDocs% )

Parameter

query$

String. The full-text query. See below.

maxDocs%

Integer. The maximum number of documents you want returned from the search. If you want to receive all documents that match the query, specify 0.

Return value

numDocs&

Long. The number of documents in the view after the search. Each of these documents matches the query$.

Usage

If the database is not-full text indexed, this method works, but less efficiently. To test for an index, use the IsFTIndexed property. To create an index on a local database, use the UpdateFTIndex method.

After calling FTSearch, you can use the regular NotesView methods to navigate the view. The methods navigate to a subset of the documents in the view. For example, GetFirstDocument returns the first document in the view that matches the full-text query. GetLastDocument returns the last document in the view that matches the full-text query, and so on.

Use the Clear method to clear the full-text search filtering. The NotesView methods now navigate to the full set of documents in the view.

Query syntax

To search for a word or phrase, enter the word or phrase as is, except that search keywords must be enclosed in quotes. Remember to escape quotes if you are inside a literal.

Wildcards, operators, and other syntax are permitted. For the complete syntax rules, see the topic "To use operators to refine a search" in Notes 5 help.

See examples
Examples: FTSearch method

See also
Clear method
FTSearch method (in NotesDatabase)
FTSearch method (in NotesDocumentCollection)
FTSearchScore property (in NotesDocument)
IsFTIndexed property (in NotesDatabase)
LastFTIndexed property (in NotesDatabase)
Locating documents within a view or folder
UpdateFTIndex method (in NotesDatabase)


GetAllDocumentsByKey method

Finds documents based on their column values within a view. You create an array of strings (keys), where each key corresponds to a value in a sorted column in the view. The method returns all documents whose column values match each key in the array.

Defined in

NotesView

Syntax

Set notesDocumentCollection = notesView.GetAllDocumentsByKey( keyArray
[ ,exact ] )

Parameters

keyArray

String, integer, long, single or double value, or array of strings, number, DateTime, or DateRange objects. Each element in the array is compared to a sorted column in the view. The first element in the array is compared to the first sorted column in the view; the second element is compared to the second sorted column; and so on.

exact

Boolean. Optional. Specify True if you want to find an exact match. If you specify False (the default) or omit this parameter, a partial match succeeds.

Return value

notesDocumentCollection

All documents in the view whose column values match each of the strings in keyArray. If no documents match, the collection is empty and the count is zero.

Usage

For non-exact matches, returns only those documents that match the initial characters. For example, "T" matches "Tim".

For the GetAllDocumentsByKey method to work using a key, you must have at least one column sorted.

This method returns all the documents whose column values match the strings you indicate. To locate just the first document, use GetDocumentByKey.

Documents found with this method don't have a ColumnValues property. If this is a problem, use GetDocumentByKey followed by a GetNextDocument loop.

See examples
Example: GetAllDocumentsByKey method

See also
ColumnValues property (in NotesDocument)
IsCategory property (in NotesViewColumn)
IsSorted property (in NotesViewColumn)
Locating documents within a view or folder
NotesDocument class
NotesDocumentCollection class
NotesViewColumn class


GetAllEntriesByKey method

Finds view entries based on their column values within a view. The method returns all entries whose column values match the keys.

Note This method is new with Release 5.

Defined in

NotesView

Syntax

Set notesViewEntryCollection = notesView.GetAllEntriesByKey( keyArray
[ ,exactMatch%] )

Parameters

keyArray

String or array of strings, number, DateTime, or DateRange objects. Each element in the array contains a string that is compared to a sorted column in the view. The first element in the array is compared to the first sorted column in the view; the second element is compared to the second sorted column; and so on.

exactMatch

Boolean. Optional. Specify True if you want to find an exact match. If you specify False (the default) or omit this parameter, a partial match succeeds.

Return value

notesViewEntryCollection

A collection of all entries in the view whose column values match each of the strings in keyArray. If no documents match, the collection is empty and the count is zero.

Usage

For non-exact matches, returns only those entries that match the initial characters. For example, "T" matches "Tim".

To locate just the first entry, use the GetEntryByKey method.

See examples
Example: GetAllEntriesByKey method


GetChild method

Given a document in a view, returns the first response to the document.

Defined in

NotesView

Syntax

Set notesDocument = notesView.GetChild( notesDocument )

Parameter

notesDocument

Any document in the view. If you specify Nothing, this method will generate an error.

Return value

notesDocument

The first response document to the notesDocument parameter you specify. Returns Nothing if there are no responses to the document.

Usage

To find additional response documents, use GetNextSibling. The combination of GetChild and GetNextSibling lets you access a document's responses, sorted in the same order as they appear in a view. To get all of a document's immediate responses, unsorted, use the Responses property in NotesDocument.

If you've filtered the view with the FTSearch method, GetChild returns the next document in the view.

See examples
Example: GetChild method

See also
GetNextDocument method
GetNextSibling method
GetParentDocument method
Locating documents within a view or folder
NotesDocument class
Responses property (in NotesDocument)


GetColumn method

Returns a specified column in a view.

Note This method is new with Release 5.0.2b.

Note This method is supported in COM only.

Defined in

NotesView

Syntax

Set notesViewColumn = notesView.Column( columnNumber& )

Parameter

columnNumber&

Integer. A column number where 1 is the first column. Cannot be less than 1 or greater than the number of columns in the view.

Return value

notesViewColumn

The specified column.

See examples
Examples: GetColumn method


GetDocumentByKey method

Finds a document based on its column values within a view. You create an array of strings (keys), where each key corresponds to a value in a sorted column in the view. The method returns the first document whose column values match each key in the array.

Defined in

NotesView

Syntax

Set notesDocument = notesView.GetDocumentByKey( keyArray [ , exact ] )

Parameters

keyArray

String, integer, long, single or double value, or array of strings, number, DateTime, or DateRange objects. Each element in the array is compared to a sorted column in the view. The first element in the array is compared to the first sorted column in the view; the second element is compared to the second sorted column; and so on.

exact

Boolean. Optional. Specify True if you want to find an exact match. If you specify False (the default) or omit this parameter, a partial match succeeds.

Return value

notesDocument

The first document in the view whose column values match each of the strings in keyArray.

Usage

For the GetDocumentByKey method to work, you must categorize the first column to have a single-value field.

For non-exact matches, returns only those documents that match the initial characters. For example, "T" matches "Tim".

This method returns only the first document whose column values match the strings you indicate. To locate all matching documents, use GetAllDocumentsByKey, or use this method followed by a GetNextDocument loop. If you use a GetNextDocument loop, you must explicitly check to make sure the next document is a match.

See examples
Examples: GetDocumentByKey method

See also
ColumnValues property (in NotesDocument)
GetAllDocumentsByKey method
GetNextDocument method
IsCategory property (in NotesViewColumn)
IsSorted property (in NotesViewColumn)
Locating documents within a view or folder
NotesDocument class
NotesViewColumn class


GetEntryByKey method

Finds a view entry based on its column values within a view. The method returns an entry whose column values match the keys.

Note This method is new with Release 5.

Defined in

NotesView

Syntax

Set notesViewEntry = notesView.GetEntryByKey( keyArray [ ,exactMatch%] )

Parameters

keyArray

String or array of strings, number, DateTime, or DateRange objects. Each element in the array contains a string that is compared to a sorted column in the view. The first element in the array is compared to the first sorted column in the view; the second element is compared to the second sorted column; and so on.

exactMatch

Boolean. Optional. Specify True if you want to find an exact match. If you specify False (the default) or omit this parameter, a partial match succeeds.

Return value

notesViewEntry

An entry in the view whose column values match each of the strings in keyArray. If no documents match, the collection is empty and the count is zero.

Usage

This method returns only the first entry within the view. To locate all the matching documents, use the GetAllEntriesByKey method.

For non-exact matches, returns only those entries that match the initial characters. For example, "T" matches "Tim".

See examples
Example: GetEntryByKey method


GetFirstDocument method

Returns the first document in a view. This is the same document you see when you scroll to the top of the view in the Notes user interface.

Defined in

NotesView

Syntax

Set notesDocument = notesView.GetFirstDocument

Return value

notesDocument

The first document in the view.

Usage

GetFirstDocument is useful when:

  • You want to access every document in the view. Use GetNextDocument to find documents after the first one.

  • The first column in the view is sorted by date, and you want to access either the oldest or newest document in the view.

See examples
Example: GetFirstDocument method

See also
GetFirstDocument method
GetLastDocument method
GetNextDocument method
Locating documents within a view or folder
NotesDocument class


GetLastDocument method

Returns the last document in a view. This is the same document you see when you scroll to the bottom of the view in the Notes user interface.

Defined in

NotesView

Syntax

Set notesDocument = notesView.GetLastDocument

Return value

notesDocument

The last document in the view.

Usage

GetLastDocument is useful when:

  • The first column in the view is sorted by date, and you want to access either the oldest or newest document in the view.

  • You want to access every document in the view. Use GetPrevDocument to find documents before the last one.

  • You write a script that modifies items on mulitple documents, but first you want to test the script against just one document. The last document in the view is often the easiest to locate visually.

See examples
Example: GetLastDocument method

See also
GetFirstDocument method
GetPrevDocument method
GetDocumentByKey method
Locating documents within a view or folder
NotesDocument class


GetNextDocument method

Given a document in a view, returns the document immediately following it.

Defined in

NotesView

Syntax

Set notesDocument = notesView.GetNextDocument( notesDocument )

Parameter

notesDocument

Any document in the view. If you specify Nothing, this method will generate an error.

Return value

notesDocument

The document following the specified notesDocument parameter in the view. Returns Nothing if there are no more documents in the view.

Usage

GetNextDocument returns the next document in the view regardless of what type of document it is (document, response, or response-to-response). If you want the next sibling document in the view, use GetNextSibling.

See examples
Examples: GetNextDocument method

See also
GetFirstDocument method
GetNextSibling method
GetPrevDocument method
Locating documents within a view or folder
NotesDocument class


GetNextSibling method

Given a document in a view, returns the document immediately following the given document at the same level. If you send the method a main document, the next main document in the view is returned. If you send a response document, the next response document with the same parent is returned.

If the view is categorized, the next sibling must be in the same category as the original document.

Defined in

NotesView

Syntax

Set notesDocument = notesView.GetNextSibling( notesDocument )

Parameter

notesDocument

Any document in the view. If you specify Nothing, this method will generate an error.

Return value

notesDocument

The document following the specified notesDocument parameter, at the same level in the view. Returns Nothing if there are no more siblings.

Usage

You can use GetNextSibling to:

  • Move from one main document to the next, skipping any response documents in between

  • Visit the response documents of a particular parent document (use GetChild to find the first response)

  • Visit the response-to-response documents of a particular parent document (use GetChild to find the first response-to-response)

If the specified view is different from the current view, the GetNextSibling method returns the following error: "Document not found in <view>." That is, you can only navigate using the Document parameters that are from the same view in which you are navigating.

If you have filtered the view with FTSearch, GetNextSibling returns the next document in the view, regardless of level.

Siblings

Two documents are siblings if:

  • They are both main documents, or

  • They are both responses or response-to-responses and they share the same parent document

The last sibling

GetNextSibling returns Nothing when the notesDocument parameter is:

  • The last main document in a view

  • The last main document in a particular category of a view

  • The last response (or response-to-response) to a particular parent

See examples
Examples: GetNextSibling method

See also
GetNextDocument method
GetPrevSibling method
GetChild method
FTSearch method
Locating documents within a view or folder


GetNthDocument method

Given a number, returns the document at the given position in the top level of a view.

Defined in

NotesView

Syntax

Set notesDocument = notesView.GetNthDocument( index& )

Parameter

index&

Long. A number indicating the document to return. Use 1 to indicate the first document in the view, 2 to indicate the second document, and so on.

Return value

notesDocument

The document in the nth position in the view.

Usage

This method accesses only top-level (main) documents in a view; response documents are excluded.

For categorized views, this method returns the first document in each main category only.

If you do not have Reader access to a document in a view, this method returns the next document that you have reader access to.

This method is most useful when used in combination with the FTSearch method in NotesView, which returns the number of documents that remain in a view after it's been filtered with a full-text search.

See examples
Example: GetNthDocument method

See also
FTSearch method
GetDocumentByKey method
Locating documents within a view or folder
NotesDocument class


GetParentDocument method

Given a response document in a view, returns its parent document.

Defined in

NotesView

Syntax

Set notesDocument = notesView.GetParentDocument( notesDocument )

Parameter

notesDocument

Any document in the view. If you specify Nothing, this method will generate an error.

Return value

notesDocument

The parent of the specified notesDocument parameter (the document to which the notesDocument parameter is a response). If you have filtered the view using FTSearch, GetParentDocument simply returns the previous document in the view.

Usage

The document returned by GetParentDocument may be a main document, a response, or a response-to-response.

To find a document's parent outside of a view, get its ParentDocumentUNID and use the NotesDatabase method GetDocumentByUNID.

See examples
Examples: GetParentDocument method

See also
GetChild method
GetDocumentByUNID method (in NotesDatabase)
Locating documents within a view or folder
NotesDocument class
ParentDocumentUNID property (in NotesDocument)


GetPrevDocument method

Given a document in a view, returns the document immediately preceding.

Defined in

NotesView

Syntax

Set notesDocument = notesView.GetPrevDocument( notesDocument )

Parameter

notesDocument

Any document in the view. If you specify Nothing, this method will generate an error.

Return value

notesDocument

The document preceding the notesDocument parameter you specify. Returns Nothing if there is no preceding document.

See examples
Example: GetPrevDocument method

See also
GetLastDocument method
GetNextDocument method
Locating documents within a view or folder
NotesDocument class


GetPrevSibling method

Given a document in a view, returns the document immediately preceding the given document at the same level. If you send the method a main document, the preceding main document in the view is returned. If you send a response document, the preceding response document with the same parent is returned.

If the view is categorized, the previous sibling must be in the same category as the original document.

Defined in

NotesView

Syntax

Set notesDocument = notesView.GetPrevSibling( notesDocument )

Parameter

notesDocument

Any document in the view. If you specify Nothing, this method will generate an error.

Return value

notesDocument

The document preceding the notesDocument parameter you specify, at the same level. Returns Nothing if there is no previous sibling in the view.

Usage

You can use GetPrevSibling to move from one main document to the next, skipping any response documents inbetween.

If you have filtered the view using FTSearch, GetPrevSibling returns the previous document in the view, regardless of level.

Siblings

Two documents are siblings if:

  • They are both main documents, or

  • They are both responses or response-to-responses and they share the same parent document.

The first sibling

GetPrevSibling returns Nothing when the notesDocument parameter is:

  • The first main document in a view

  • The first main document in a particular category of a view

  • The first response (or response-to-response) to a particular parent

Example: GetPrevSibling method

This script finds the second-to-last main document in the Main View of a database.

  • If the Main View is categorized and lastMain is the only main document in its category, GetPrevSibling returns Nothing, even if there are more main documents in other categories in the view.

  • If the Main View is categorized and lastMain is not the only main document in its category, GetPrevSibling returns the previous main document in the same category as lastMain.

  • If the Main View is not categorized, GetPrevSibling returns the previous main document.

    • Dim db As New NotesDatabase( "Addis-Ababa", "discuss.nsf" )

    Dim view As NotesView

    Dim lastMain As NotesDocument

    Dim secondToLastMain As NotesDocument

    Set view = db.GetView( "Main View" )

    Set lastMain = view.GetLastDocument

    ' Find the last main document in the view

    While lastMain.IsResponse

      Set lastMain = view.GetParentDocument( lastMain )

    Wend

    ' Now find the second-to-last main document in the view

    Set secondToLastMain = view.GetPrevSibling( lastMain )

See examples
Example: GetPrevSibling method

See also
FTSearch method
GetChild method
GetNextSibling method
GetParentDocument method
GetPrevDocument method
Locating documents within a view or folder
NotesDocument class


Refresh method

Updates a view's contents with any changes that have occurred to the database since the NotesView object was created or since the last Refresh.

Defined in

NotesView

Syntax

Call notesView.Refresh

Usage

Navigation through a view is not normally affected by changes to the actual database, since the NotesView object is a snapshot of the view's contents at a particular time. Additions and deletions to the view that occurred since the NotesView object was created are not reflected in the NotesView object until you call Refresh.

Note The Refresh method does not rebuild the view index.

See examples
Example: Refresh method

See also
Refreshing a view or folder


Remove method

Permanently deletes a view from a database.

Defined in

NotesView

Syntax

Call notesView.Remove

Usage

When a view has been removed, all subsequent calls to any of its methods or properties will generate an error. Also, all subsequent calls to any methods or properties of any ViewNavigators created from the view will generate an error.

See examples
Example: Remove method

See also
Removing a view or folder


NotesViewColumn class

Represents a column in a view or folder.

Containment

Contained by: NotesView

Properties

Alignment

DateFmt

FontColor

FontFace

FontPointSize

FontStyle

Formula

HeaderAlignment

IsAccentSensitiveSort

IsCaseSensitiveSort

IsCategory

IsField

IsFormula

IsHidden

IsHideDetail

IsIcon

IsResize

IsResortAscending

IsResortDescending

IsResortToView

IsResponse

IsSecondaryResort

IsSecondaryResortDescending

IsShowTwistie

IsSortDescending

IsSorted

ItemName

ListSep

NumberAttrib

NumberDigits

NumberFormat

Parent

Position

TimeDateFmt

TimeFmt

TimeZoneFmt

Title

Width

Access

You access an existing NotesViewColumn object through the view or folder that contains it. Use the Columns property in NotesView.

See examples
Examples: NotesViewColumn class

See also
Using the Domino classes
Accessing view or folder columns
ColumnValues property (in NotesDocument)


Alignment property

Read-only. The alignment (justification) of data in a column.

Note This property is new with Release 5.

Defined in

NotesViewColumn

Data type

Constant of type Integer

Syntax

To get: alignment% = notesViewColumn.Alignment

Legal values

  • VC_ALIGN_CENTER (2)

  • VC_ALIGN_LEFT (0)

  • VC_ALIGN_RIGHT (1)

Note The above constants are also used with the Alignment property in the NotesRichTextParagraphStyle class, and HeaderAlignment property of the NotesViewColumn class.

See examples
Example: Alignment property


DateFmt property

Read-only. The specific format of date data in a column.

Note This property is new with Release 5.

Defined in

NotesViewColumn

Data type

Constant of type Integer

Syntax

To get: fmt% = notesViewColumn.DateFmt

Legal values

  • VC_FMT_MD (2) for month and day

  • VC_FMT_YM (3) for year and month

  • VC_FMT_YMD (0) for year, month, and day

  • VC_FMT_Y4M (6) for year (4 digit) and month

See examples
Example: DateFmt property


FontColor property

Read-only. The font color of data in a column.

Note This property is new with Release 5.

Defined in

NotesViewColumn

Data type

Constant of type Integer

Syntax

To get:color% = notesViewColumn.FontColor

Legal values

  • COLOR_BLACK (0)

  • COLOR_BLUE (4)

  • COLOR_CYAN (7)

  • COLOR_DARK_BLUE (10)

  • COLOR_DARK_CYAN (13)

  • COLOR_DARK_GREEN (9)

  • COLOR_DARK_MAGENTA (11)

  • COLOR_DARK_RED (8)

  • COLOR_DARK_YELLOW (12)

  • COLOR_GRAY (14)

  • COLOR_GREEN (3)

  • COLOR_LIGHT_GRAY (15)

  • COLOR_MAGENTA (5)

  • COLOR_RED (2)

  • COLOR_WHITE (1)

  • COLOR_YELLOW (6)

Note These values are also used with the NotesColor property in the NotesRichTextStyle class, and BackgroundColor property of the NotesView class.

See examples
Example: FontColor property


FontFace property

Read-only. The font face of data in a cloumn.

Note This property is new with Release 5.

Defined in

NotesViewColumn

Data type

String

Syntax

To get:face$ = notesViewColumn.FontFace

See examples
Example: FontFace property


FontPointSize property

Read-only. The font point size of data in a column.

Note This property is new with Release 5.

Defined in

NotesViewColumn

Data type

Integer

Syntax

To get: size% = notesViewColumn.FontPointSize

See examples
Example: FontPointSize property


FontStyle property

Read-only. The font style of data in a column.

Note This property is new with Release 5.

Defined in

NotesViewColumn

Data type

Constant of type Integer

Syntax

To get:style% = notesViewColumn.FontStyle

Legal values

  • VC_FONT_BOLD (1)

  • VC_FONT_ITALIC (2)

  • VC_FONT_UNDERLINE (4)

  • VC_FONT_STRIKEOUT (8)

See examples
Example: FontStyle property


Formula property

Read-only. The @function formula for a column, if it exists.

Defined in

NotesViewColumn

Data type

String

Syntax

To get: formula$ = notesViewColumn.Formula

Usage

If a column displays a field value, this property returns an empty string (""). If the database designer gives the column an @function formula that consists of a single field value, this property returns an empty string. You can access the field name with the ItemName property.

If a column displays a simple function, this property returns the @function formula equivalent. For example, if a column displays the simple function Creation Date, the property returns "@Created."

If a column displays an @function formula, this property returns the entire formula.

See examples
Example: Formula property


HeaderAlignment property

Read-only. The alignment (justification) of the header in a column.

Note This property is new with Release 5.

Defined in

NotesViewColumn

Data type

Constant of type Integer

Syntax

To get:alignment% = notesViewColumn.HeaderAlignment

Legal values

  • VC_ALIGN_CENTER (2)

  • VC_ALIGN_LEFT (0)

  • VC_ALIGN_RIGHT (1)

Note These values are also used with the Alignment property in the NotesRichTextParagraphStyle class, and Alignment property of the NotesViewColumn class.

See examples
Example: HeaderAlignment property


IsAccentSensitiveSort

Read-only. Indicates if a column is sorted without regard to accent.

Note This property is new with Release 5.

Defined in

NotesViewColumn

Data type

Boolean

Syntax

To get:flag = notesViewColumn.IsAccentSensitiveSort

Legal values

  • True indicates that the column is sorted without regard to accent

  • False indicates that the column is sorted with regard to accent

See examples
Example: IsAccentSensitiveSort property


IsCaseSensitiveSort property

Read-only. Indicates if a column is sorted without regard to case.

Note This property is new with Release 5.

Defined in

NotesViewColumn

Data type

Boolean

Syntax

To get:flag = notesViewColumn.IsCaseSensitiveSort

Legal values

  • True indicates that the column is sorted without regard to case

  • False indicates that the column is sorted with regard to case

See examples
Example: IsCaseSensitiveSort property


IsCategory property

Read-only. Indicates if a column is categorized.

Defined in

NotesViewColumn

Data type

Boolean

Syntax

To get: flag = notesViewColumn.IsCategory

Legal values

  • True indicates that the column is categorized

  • False indicates that the column is not categorized

Usage

If IsCategory is True, the IsSorted property is also True, since columns that are categorized must also be sorted.

See examples
Example: IsCategory property

See also
IsSorted property


IsField property

Read-only. Indicates if column values are based on field values.

Note This property is new with Release 5.

Defined in

NotesViewColumn

Data type

Boolean

Syntax

To get: flag = notesViewColumn.IsField

Legal values

  • True indicates that the column is based on field values

  • False indicates that the column is not based on field values

See examples
Example: IsField property


IsFormula property

Read-only. Indicates if column values are based on a formula.

Note This property is new with Release 5.

Defined in

NotesViewColumn

Data type

Boolean

Syntax

To get: flag = notesViewColumn.IsFormula

Legal values

  • True indicates that the column is based on a simple function or formula

  • False indicates that the column is not based on a simple function or formula

See examples
Example: IsFormula property


IsHidden property

Read-only. Indicates if a column is hidden.

Defined in

NotesViewColumn

Data type

Boolean

Syntax

To get: flag = notesViewColumn.IsHidden

Legal values

  • True indicates that the column is hidden

  • False indicates that the column is not hidden

See examples
Example: IsHidden property


IsHideDetail property

Read-only. Indicates if the details for total columns are hidden.

Note This property is new with Release 5.

Defined in

NotesViewColumn

Data type

Boolean

Syntax

To get: flag = notesViewColumn.IsHideDetail

Legal values

  • True indicates that the details for totals are hidden

  • False indicates that the details for totals are displayed

See examples
Example: IsHideDetail property


IsIcon property

Read-only. Indicates if column values are displayed as icons.

Note This property is new with Release 5.

Defined in

NotesViewColumn

Data type

Boolean

Syntax

To get: flag = notesViewColumn.IsIcon

Legal values

  • True indicates that the column values are displayed as icons

  • False indicates that the column values are not displayed as icons

See examples
Example: IsIcon property


IsResize property

Read-only. Indicates if a column is resizable.

Note This property is new with Release 5.

Defined in

NotesViewColumn

Data type

Boolean

Syntax

To get: flag = notesViewColumn.IsResize

Legal values

  • True indicates that the column is resizable

  • False indicates that the column is not resizable

See examples
Example: IsResize property


IsResortAscending property

Read-only. Indicates if a resortable column can be resorted in ascending order.

Note This property is new with Release 5.

Defined in

NotesViewColumn

Data type

Boolean

Syntax

To get: flag = notesViewColumn.IsResortAscending

Legal values

  • True indicates that the resortable column can be resorted in ascending order

  • False indicates that the resortable column cannot be resorted in ascending order

See examples
Example: IsResortAscending property


IsResortDescending property

Read-only. Indicates if a resortable column can be resorted in descending order.

Note This property is new with Release 5.

Defined in

NotesViewColumn

Data type

Boolean

Syntax

To get: flag = notesViewColumn.IsResortDescending

Legal values

  • True indicates that the resortable column can be resorted in descending order

  • False indicates that the resortable column cannot be resorted in descending order

See examples
Example: IsResortDescending property


IsResortToView property

Read-only. Indicates if a sorted column is resortable, that is, if the user can click on the column header to resort.

Note This property is new with Release 5.

Defined in

NotesViewColumn

Data type

Boolean

Syntax

To get: flag = notesViewColumn.IsResortToView

Legal values

  • True indicates that the column is resortable

  • False indicates that the column is not resortable

Usage

The IsResortToView property returns True only when you choose the "Change To View" option for "Click on column header to sort". If you select any other option, this property returns False.

See examples
Example: IsResortToView property


IsResponse property

Read-only. Indicates if a column contains only response documents.

Defined in

NotesViewColumn

Data type

Boolean

Syntax

To get: flag = notesViewColumn.IsResponse

Legal values

  • True indicates that the column contains only response documents

  • False indicates that the column contains any kind of document

See examples
Examples: IsResponse property


IsSecondaryResort property

Read-only. Indicates if a column is a secondary resortable column.

Note This property is new with Release 5.

Defined in

NotesViewColumn

Data type

Boolean

Syntax

To get: flag = notesViewColumn.IsSecondaryResort

Legal values

  • True indicates that the column is a secondary resortable column

  • False indicates that the column is not a secondary resortable column

See examples
Example: IsSecondaryResort property


IsSecondaryResortDescending property

Read-only. Indicates if a secondary resortable column is descending in sort order.

Note This property is new with Release 5.

Defined in

NotesViewColumn

Data type

Boolean

Syntax

To get: flag = notesViewColumn.IsSecondaryResortDescending

Legal values

  • True indicates that the secondary resortable column is descending

  • False indicates that the secondary resortable column is ascending

See examples
Example: IsSecondaryResortDescending property


IsShowTwistie property

Read-only. Indicates if an expandable column displays a twistie.

Note This property is new with Release 5.

Defined in

NotesViewColumn

Data type

Boolean

Syntax

To get: flag = notesViewColumn.IsShowTwistie

Legal values

  • True indicates that the expandable column displays a twistie

  • False indicates that the expandable column does not display a twistie

See examples
Example: IsShowTwistie property


IsSortDescending property

Read-only. Indicates if a sorted column is descending in sort order.

Note This property is new with Release 5.

Defined in

NotesViewColumn

Data type

Boolean

Syntax

To get: flag = notesViewColumn.IsSortDescending

Legal values

  • True indicates that the sorted column is descending

  • False indicates that the sorted column is ascending

See examples
Example: IsSortDescending property


IsSorted property

Read-only. Indicates if a column is sorted.

Defined in

NotesViewColumn

Data type

Boolean

Syntax

To get: flag = notesViewColumn.IsSorted

Legal values

  • True indicates that the column is sorted

  • False indicates that the column is not sorted

Usage

If the user can sort the column in the user interface by clicking its heading, but the column is not otherwise sorted, this property returns False.

See examples
Examples: IsSorted property

See also
IsCategory property


ItemName property

Read-only. The name of the item whose value is shown in the column. For columns whose values are simple functions or formulas, returns an automatically generated internal name.

Defined in

NotesViewColumn

Data type

String

Syntax

To get: name$ = notesViewColumn.ItemName

Usage

This property is useful with columns that display a field value. It's not so useful with columns that display the result of a simple function or formula.

See examples
Examples: ItemName property

See also
Formula property


ListSep property

Read-only. List (multi-value) separator for values in a column.

Note This property is new with Release 5.

Defined in

NotesViewColumn

Data type

Constant of type Integer

Syntax

To get: sep% = notesViewColumn.ListSep

Legal values

  • VC_SEP_COMMA (2)

  • VC_SEP_NEWLINE (4)

  • VC_SEP_SEMICOLON (3)

  • VC_SEP_SPACE (1)

See examples
Example: ListSep property


NumberAttrib property

Read-only. Attributes for numeric values in a column.

Note This property is new with Release 5.

Defined in

NotesViewColumn

Data type

Constant of type Integer

Syntax

To get: attrib% = notesViewColumn.NumberAttrib

Legal values

  • VC_ATTR_PARENS (2) for parentheses on negative numbers

  • VC_ATTR_PUNCTUATED (1) punctuated at thousands

  • VC_ATTR_PERCENT (4) percentage

See examples
Example: NumberAttrib property


NumberDigits property

Read-only. Number of decimal places for numeric values in a column.

Note This property is new with Release 5.

Defined in

NotesViewColumn

Data type

Integer

Syntax

To get: digits% = notesViewColumn.NumberDigits

See examples
Example: NumberDigits property


NumberFormat property

Read-only. Format for numeric values in a column.

Note This property is new with Release 5.

Defined in

NotesViewColumn

Data type

Constant of type Integer

Syntax

To get: format% = notesViewColumn.NumberFormat

Legal values

  • VC_FMT_CURRENCY (3)

  • VC_FMT_FIXED (1)

  • VC_FMT_GENERAL (0)

  • VC_FMT_SCIENTIFIC (2)

See examples
Example: NumberFormat property


Parent property

Read-only. The view that contains a column.

Note This property is new with Release 5.0.2b.

Note This property is supported in COM only.

Defined in

NotesViewColumn

Data type

NotesView

Syntax

To get: Set notesView = notesViewColumn.Parent

See examples
Examples: Parent property


Position property

Read-only. The position of a column in its view. Columns are numbered from left to right, starting with 1.

Defined in

NotesViewColumn

Data type

Integer

Syntax

To set: pos% = notesViewColumn.Position

Usage

The Columns property in NotesView returns an array of NotesViewColumn objects. The array is zero-based, so the first element in the array is at index 0 and contains the NotesViewColumn at Position 1. The second element in the array is at index 1 and contains the NotesViewColumn at Position 2, and so on. Remember to add one to the array index to get the correct Position value.

See examples
Examples: Position property

See also
Columns property (in NotesView)


TimeDateFmt property

Read-only. The format of time-date data in a column.

Note This property is new with Release 5.

Defined in

NotesViewColumn

Data type

Constant of type Integer

Syntax

To get: fmt% = notesViewColumn.TimeDateFmt

Legal values

  • VC_FMT_DATE (0) date only

  • VC_FMT_DATETIME (2) date and time

  • VC_FMT_TIME (1) time only

  • VC_FMT_TODAYTIME (3) date or 'Today' or 'Yesterday' and time

See examples
Example: TimeDateFmt property


TimeFmt property

Read-only. The format of time data in a column.

Note This property is new with Release 5.

Defined in

NotesViewColumn

Data type

Constant of type Integer

Syntax

To get: fmt% = notesViewColumn.TimeFmt

Legal values

  • VC_FMT_HMS (1) for hour, minute, second

  • VC_FMT_HM (0) for hour, minute

See examples
Example: TimeFmt property


TimeZoneFmt property

Read-only. The timezone format in time-date data in a column.

Note This property is new with Release 5.

Defined in

NotesViewColumn

Data type

Constant of type Integer

Syntax

To get: fmt% = notesViewColumn.TimeZoneFmt

Legal values

  • VC_FMT_ALWAYS (2) always show the timezone

  • VC_FMT_NEVER (0) adjust time to local timezone

  • VC_FMT_SOMETIMES (1) show timezone if not local

See examples
Example: TimeZoneFmt property


Title property

Read-only. The title of a column, if any.

Defined in

NotesViewColumn

Data type

String

Syntax

To get: title$ = notesViewColumn.Title

Usage

If a column does not have a title, this property returns an empty string ("").

Column titles are not necessarily unique within a view.

See examples
Example: Title property

See also
Formula property
ItemName property
Position property


Width property

Read-only. The width of a column.

Note This property is new with Release 5.

Defined in

NotesViewColumn

Data type

Integer

Syntax

To get: width% = notesViewColumn.Width

See examples
Example: Width property


NotesViewEntry class

Represents a view entry. A view entry represents a row in a view.

Note This class is new with Release 5.

Containment

Contained by: NotesView, NotesViewEntryCollection, NotesViewNavigator.

Contains: NotesDocument

Properties

ChildCount

ColumnIndentLevel

ColumnValues

DescendantCount

Document

FTSearchScore

IndentLevel

IsCategory

IsConflict

IsDocument

IsTotal

IsValid

NoteID

Parent

SiblingCount

UniversalID

Methods

GetPosition

Access

You can access a view entry through the get methods in NotesViewEntryCollection and NotesViewNavigator, and through GetEntryByKey method in NotesView.

Usage

The three types of view entries are document, category, and total. ViewEntries will return valid values for IsValid, NoteID, and Parent properties.

Documents retrieved from view entries will not have FTSearchScore, ColumnValues, or ParentView set. These values should be accessed via the ViewEntry, not the Document.

See examples
Examples: NotesViewEntry class


ChildCount property

Read-only. The number of immediate children belonging to the current view entry.

Defined in

NotesViewEntry

Data type

Integer

Syntax

To get: count% = notesViewEntry.ChildCount

See examples
Example: ChildCount property


ColumnIndentLevel property

Read-only. The column indent level of a view entry.

Defined in

NotesViewEntry

Data type

Integer

Syntax

To get: level% = notesViewEntry.ColumnIndentLevel

Usage

ColumnIndentLevel property is useful to determine the response level - ie. main topics are always at ColumnIndentLevel 0, first response at ColumnIndentLevel 1, etc. , regardless of whether or not the View is categorized.


ColumnValues property

Read-only. The value of each column in the view entry.

Defined in

NotesViewEntry

Data type

Array of variants

Syntax

To get: valuesArray = notesViewEntry.ColumnValues

See examples
Example: ColumnValues property

See also
ColumnValues property


DescendantCount property

Read-only. The number of descendants belonging to the current view entry.

Defined in

NotesViewEntry

Data type

Integer

Syntax

To get: count% = notesViewEntry.DescendantCount

See examples
Example: DescendantCount property


Document property

Read-only. The document associated with the view entry.

Defined in

NotesViewEntry

Data type

NotesDocument

Syntax

To get: Set notesDocument = notesViewEntry.Document

Usage

Returns NULL if the view entry is not a document. Returns NULL if the document is deleted after the ViewEntry object is created.

See examples
Example: Document property


FTSearchScore property

Read-only. The full-text search score of a view entry, if it was retrieved as part of a full-text search.

Defined in

NotesViewEntry

Data type

Integer

Syntax

To get: score% = notesViewEntry.FTSearchScore

Usage

The score is determined by the number of target words that are found in the entry, the term weights assigned to the target words, and any proximity operators in the search query. If the entry is not retrieved as part of a full-text search, returns 0. If the entry is retrieved using an FTSearch method on a database without a full-text index, returns an unpredictable number.

See examples
Example: FTSearchScore property

See also
FTSearchScore property


IndentLevel property

Read-only. The indent level of a view entry.

Defined in

NotesViewEntry

Data type

Integer

Syntax

To get: level% = notesViewEntry.IndentLevel

Usage

The return value for the IndentLevel property will always match the levels in the position string. For example:

Position String. | Indent Level
1 | 0
1.1 | 1
1.1.1 | 2

See examples
Example: IndentLevel property


IsCategory property

Read-only. Indicates if a view entry is a category.

Defined in

NotesViewEntry

Data type

Boolean

Syntax

To get: flag = notesViewEntry.IsCategory

Legal values

  • True indicates that the view entry is a category

  • False indicates that the view entry is not a category

See examples
Example: IsCategory property

See also
IsCategory property


IsConflict property

Read-only. Indicates if a view entry contains a document on which a replication or save conflict occurred.

Defined in

NotesViewEntry

Data type

Boolean

Syntax

To get: flag = notesViewEntry.IsConflict

Legal values

  • True indicates that the view entry is a conflict document

  • False indicates that the view entry is not a conflict document

See examples
Example: IsConflict property

See also
IsConflict property


IsDocument property

Read-only. Indicates if a view entry is a document.

Defined in

NotesViewEntry

Data type

Boolean

Syntax

To get: flag = notesViewEntry.IsDocument

Legal values

  • True indicates that the view entry is a document

  • False indicates that the view entry is not a document

See examples
Example: IsDocument property


IsTotal property

Read-only. Indicates if a view entry is a total.

Defined in

NotesViewEntry

Data type

Boolean

Syntax

To get: flag = notesViewEntry.IsTotal

Legal values

  • True indicates that the view entry is a total

  • False indicates that the view entry is not a total

See examples
Example: IsTotal property


IsValid property

Read-only. Indicates if a view entry is a valid entry.

Defined in

NotesViewEntry

Data type

Boolean

Syntax

To get: flag = notesViewEntry.IsValid

Legal values

  • True indicates that the view entry is valid

  • False indicates that the view entry is not valid

Usage

If a document is deleted after a ViewEntryCollection containing that document is created, the result of navigating to the deleted document will be a ViewEntry that can be used to navigate to the next entry, but nothing more. All of the properties or methods on this type of ViewEntry, except IsValid, will return an error. If you are sure that none of the documents in a ViewEntryCollection have been deleted, you don't need to check this property; otherwise, it should be checked.

See examples
Example: IsValid property


NoteID property

Read-only. The prefix "NT" followed by the note ID of a view entry.

Defined in

NotesViewEntry

Data type

String

Syntax

To get: note$ = notesViewEntry.NoteID

See examples
Example: NoteID property

See also
NoteID property


Parent property

Read-only. The parent ViewEntryCollection, ViewNavigator, or View object of a view entry.

Defined in

NotesViewEntry

Data type

NotesView

Syntax

To get: Set notesView = notesViewEntry.Parent

See examples
Example: Parent property

See also
Parent property
Parent property
Parent property
Parent property
Parent property
Parent property


SiblingCount property

Read-only. The number of siblings belonging to the current view entry.

Defined in

NotesViewEntry

Data type

Integer

Syntax

To get: count% = notesViewEntry.SiblingCount

Usage

The sibling count includes the current entry unless it is of type "total" because ViewEntries of type "total" are not really part of the view hierarchy.

See examples
Example: SiblingCount property


UniversalID property

Read-only. The universal ID of a document, associated with a view entry. The ID is a 32-character combination of hexadecimal digits (0-9, A-F) that uniquely identifies a document across all replicas of a database.

Defined in

NotesViewEntry

Data type

String

Syntax

To get: universalid$ = notesViewEntry.UniversalID

See examples
Example: UniversalID property


GetPosition method

Returns the position of the entry in the view hierarchy, for example, "2.3" for the third document of the second category.

Defined in

NotesViewEntry

Syntax

position$ = notesViewEntry.GetPosition( separator$ )

Parameters

separator$

The separator in the return value.

Return value

position$

String. A series of integers and separators. The integers indicate the positions of the view entry at each level, where 1 is the first position. The first integer indicates the first level and so on.

See examples
Example: GetPosition method


NotesViewEntryCollection class

Represents a collection of view entries, selected according to specific criteria. This class mainly provides you with a collection of documents in a view-sorted order.

Note This class is new with Release 5.

Containment

Contained by: NotesView

Contains: NotesViewEntry

Properties

Count

Parent

Query

Methods

AddEntry

DeleteEntry

FTSearch

GetEntry

GetFirstEntry

GetLastEntry

GetNextEntry

GetNthEntry

GetPrevEntry

PutAllInFolder

RemoveAll

RemoveAllFromFolder

StampAll

UpdateAll

Access

A ViewEntryCollection represents all or a subset of all entries in a view. The NotesView AllEntries property and GetAllEntriesByKey method return ViewEntryCollection objects.

The FTSearch method in NotesViewEntryCollection changes the content of the collection.

Usage

ViewEntryCollections never contain categories or totals, only entries that correspond to documents. The methods and properties in NotesViewEntryCollection are the same as those for NotesDocumentCollection, except for IsSorted, because this property is always True for NotesViewEntryCollection.

Current Pointer

A current pointer is maintained for view entry collections. All navigation methods set the current pointer to the retrieved entry. Add and Delete methods do not move the current pointer. The current pointer is set back to the first document after FTSearch and RemoveAll methods.

Duplicate entries

Duplicate entries exist when a document is categorized under multiple categories. Navigating over duplicate entries works except as follows:

  • GetNthEntry method returns the first ViewEntry instance for the document.

  • GetEntry method returns the first ViewEntry instance for the document if the document is not part of this collection.

  • DeleteEntry method deletes the first instance. You can delete multiple instances with multiple calls to this method.

  • AddEntry method does not allow duplicates.

See examples
Examples: NotesViewEntryCollection class


Count property

Read-only. The number of entries in a collection.

Defined in

NotesViewEntryCollection

Data type

Long

Syntax

To get: count &= notesViewEntryCollection.Count

See examples
Example: Count property

See also
Count property


Parent property

Read-only. The view that contains a view entry collection.

Defined in

NotesViewEntryCollection

Data type

NotesView

Syntax

To get: Set notesView= notesViewEntryCollection.Parent

See examples
Example: Parent property

See also
Parent property
Parent property
Parent property
Parent property
Parent property
Parent property
Parent property


Query property

Read-only. The text of the query that produced a view entry collection, if the collection results from a full-text or other search.

Defined in

NotesViewEntryCollection

Data type

String

Syntax

To get: query$= notesViewEntryCollection.Query

See examples
Example: Query property

See also
Query property
Query property


AddEntry method

Adds an entry to a view entry collection.

Defined in

NotesViewEntryCollection

Syntax

CALL notesViewEntryCollection.AddEntry(addentry [, checkDups ])

Parameters

addentry

A ViewEntry object representing the entry to be added. If the specified entry is a Category or Total entry, an error will be returned. If you specify Nothing, this method will generate an error.

checkDups

Note This parameter is for COM only. It is not currently used.

Boolean. Optional. Specify True to check for duplicate entries. The default is False.

Usage

For sorted collections, the entry will be appended. For unsorted collections, the entry will be inserted using an internal algorithm.

Sorted collections include all ViewEntryCollections and DocumentCollections created from FTSearch (including DocumentCollections modified by calling the FTSearch method on the collection). All other DocumentCollections are unsorted.

See also
AddDocument method


DeleteEntry method

Deletes an entry from a collection.

Defined in

NotesViewEntryCollection

Syntax

Call notesViewEntryCollection.DeleteEntry( deleteentry )

Parameters

deleteentry

NotesViewEntry. The view entry to be deleted. If the specified entry is a Category or Total entry, an error will be returned. If you specify Nothing, this method will generate an error.

See examples
Example: DeleteEntry method

See also
DeleteDocument method


FTSearch method

Conducts a full-text search of all the entries in a Notes database collection, and reduces the collection to those entries that match.

Defined in

NotesViewEntryCollection

Syntax

Call notesViewEntryCollection.FTsearch( query$, maxDocs% )

Parameters

query$

String. The full-text query. See below for the syntax.

maxDocs%

Integer. The maximum number of entries you want returned from the query. Set this parameter to 0 to receive all matching entries.

Usage

This method moves the current pointer to the first document in the collection.

The collection of documents that match the full-text query is sorted by relevance with highest relevance first. You can access the relevance score of each document in the collection using the FTSearchScore property in NotesDocument.

If the database is not full-text indexed, this method works, but less efficiently. To test for an index, use the IsFTIndexed property in NotesDatabase. To create an index on a local database, use the UpdateFTIndex method.

Query syntax

To search for a word or phrase, enter the word or phrase as is, except that search keywords must be enclosed in quotes. Remember to escape quotes if you are inside a literal.

Wildcards, operators, and other syntax are permitted. For the complete syntax rules, see the topic "To use operators to refine a search" in Notes 5 help.

See examples
Example: FTSearch method

See also
FTSearch method
FTSearch method
FTSearch method


GetEntry method

Gets a specified entry in a view collection.

Defined in

NotesViewEntryCollection

Syntax

Set notesViewEntry = notesViewEntryCollection.GetEntry( entry )

Parameters

entry

A ViewEntry or Document object representing the entry to be retrieved. If you specify Nothing, this method will generate an error.

Return value

notesViewEntry

The view entry to be retrieved. If the specified entry is not in the collection, returns null.

Usage

The effect of this method is to move the current pointer.

See examples
Example: GetEntry method

See also
GetEntry method


GetFirstEntry method

Gets the first entry in a view collection.

Defined in

NotesViewEntryCollection

Syntax

Set notesViewEntry = notesViewEntryCollection.GetFirstEntry( )

Return value

notesViewEntry

The first view entry in the collection. If there are no entries in the collection, returns null.

See examples
Example: GetFirstEntry method

See also
GetFirstDocument method
GetFirstEntry method


GetLastEntry method

Gets the last entry in a view collection.

Defined in

NotesViewEntryCollection

Syntax

Set notesViewEntry = notesViewEntryCollection.GetLastEntry( )

Return value

notesViewEntry

The last view entry in the collection. If there are no entries in the collection, returns null.

See examples
Example: GetLastEntry method

See also
GetLastDocument method


GetNextEntry method

Gets the entry immediately following the current or a specified entry in a view collection.

Defined in

NotesViewEntryCollection

Syntax

Set notesViewEntry = notesViewEntryCollection.GetNextEntry( currententry )

Parameters

currententry

NotesViewEntry. An entry in the view collection. If you specify Nothing, this method will generate an error.

Return value

notesViewEntry

If no parameter, the entry following the current entry. If a parameter, the entry following the specified entry. If there is no next entry, returns null.

See examples
Example: GetNextEntry method

See also
GetNextEntry method
GetNextDocument method


GetNthEntry method

Given a position number, gets the entry at that position in a view collection.

Defined in

NotesViewEntryCollection

Syntax

Set notesViewEntry = notesViewEntryCollection.GetNthEntry( index& )

Parameters

index&

Long. A number indicating the entry to return. Use 1 to indicate the first entry in the collection, 2 to indicate the second entry, and so on.

Return value

notesViewEntry

The entry in the nth position in the view collection. If there is no entry at the specified position, returns null.

Usage

View collections are renumbered when deletions occur so that the positions of entries after the deleted entry change.

See examples
Example: GetNthEntry method

See also
GetNthDocument method


GetPrevEntry method

Gets the entry immediately preceding the current or a specified entry in a view collection.

Defined in

NotesViewEntryCollection

Syntax

Set notesViewEntry = notesViewEntryCollection.GetPrevEntry( currententry )

Parameters

currententry

NotesViewEntry. An entry in the view collection. If you specify Nothing, this method will generate an error.

Return value

notesViewEntry

If no parameter, the entry preceding the current entry. If a parameter, the entry preceding the specified entry. If there is no previous entry, returns null.

See examples
Example: GetPrevEntry method

See also
GetPrevDocument method


PutAllInFolder method

Adds the documents associated with all the entries in the view collection to the specified folder. If the folder does not exist, it is created.

Defined in

NotesViewEntryCollection

Syntax

Call notesViewEntryCollection.PutAllInFolder( foldername$ [, createonfail ] )

Parameters

foldername$

String. The name of the folder in which to place the documents. The folder may be personal if the script is running on the workstation. If the folder is within another folder, specify a path to it, separating folder names with backward slashes, for example, "Vehicles\Bikes".

createonfail

Boolean. Optional. Specify True so that a folder will be created if it does not exist.

Usage

If a document is already inside the folder you specify, PutAllInFolder does nothing for that document. If you specify a path to a folder, and none of the folders exist, the method creates all of them for you.

See examples
Example: PutAllInFolder method

See also
PutAllInFolder method


RemoveAll method

Permanently removes all documents associated with the entries in a view collection from a database.

Defined in

NotesViewEntryCollection

Syntax

Call notesViewEntryCollection.RemoveAll( force )

Parameters

force

Boolean. If True, the view collection will be empty. If False, there may be entries remaining in the collection after the RemoveAll executes.

Usage

Resets current pointer to the beginning of the collection.

See examples
Example: RemoveAll method

See also
RemoveAll method


RemoveAllFromFolder method

Removes all documents associated with the entries in a view collection from the specified folder.

Defined in

NotesViewEntryCollection

Syntax

Call notesViewEntryCollection.RemoveAllFromFolder( foldername$ )

Parameters

foldername$

String. The name of the folder from which to remove the documents. The folder may be personal if the script is running on a workstation. If the folder is within another folder, specify a path to it, separating folder names with backward slashes, for example, "Vehicles\Bikes".

Usage

The method does nothing for documents not in the folder you specify. This method does nothing if the folder you specify does not exist.

See examples
Example: RemoveAllFromFolder method

See also
RemoveAllFromFolder method


StampAll method

Replaces the value of a specified item in all documents associated with the entries in a view collection.

Defined in

NotesViewEntryCollection

Syntax

Call notesViewEntryCollection.StampAll( itemname$ , value )

Parameters

itemname$

String. The name of the item.

value

A value appropriate for the item type.

Usage

If the item does not exist, it is created.

The item values are immediately written to the documents on the server. You do not have to use the Save method of NotesDocument after StampAll. However, any documents modified by your script must be saved before calling StampAll.

This method does not modify existing NotesDocument objects. Documents must be retrieved again to see the changes.

See examples
Example: StampAll method

See also
StampAll method


UpdateAll method

Marks all documents associated with the entries in a view collection as processed by an agent.

Defined in

NotesViewEntryCollection

Syntax

Call notesViewEntryCollection.UpdateAll( )

Usage

See the UpdateProcessedDoc method in NotesSession for a description of the update process.

See also
UpdateAll method


NotesViewNavigator class

Represents a view navigator. A view navigator provides access to all or a subset of the entries in a view.

Note This class is new with Release 5.

Containment

Contained by: NotesView

Contains: NotesViewEntry

Properties

CacheSize

MaxLevel

ParentView

Methods

GetChild

GetCurrent

GetEntry

GetFirst

GetFirstDocument

GetLast

GetLastDocument

GetNext

GetNextCategory

GetNextDocument

GetNextSibling

GetNth

GetParent

GetPos

GetPrev

GetPrevCategory

GetPrevDocument

GetPrevSibling

GotoChild

GotoEntry

GotoFirst

GotoFirstDocument

GotoLast

GotoLastDocument

GotoNext

GotoNextCategory

GotoNextDocument

GotoNextSibling

GotoParent

GotoPos

GotoPrev

GotoPrevCategory

GotoPrevDocument

GotoPrevSibling

Creation

You create a view navigator through the following NotesView methods:

CreateViewNav

CreateViewNavFrom

CreateViewNavFromCategory

CreateViewNavFromChildren

CreateViewNavFromDescendants

Returned is a NotesViewNavigator object that represents some or all of the entries in the view.

Usage

You can navigate through the documents in a view with the NotesView methods.

NotesViewNavigator differs from NotesView in the following ways:

  • ViewNavigator returns a ViewEntry object instead of a document (ViewEntry contains information such as SiblingCount, view position, etc.)

  • It lets you access categories and totals as well as documents.

  • Users can create navigators from subsets of views, for example, all children of an entry.

A view navigator remains associated with the parent view. A refresh of the parent view affects the view navigator.

Duplicate entries

Duplicate entries exist when a document is categorized under multiple categories. Navigating over duplicate entries works except as follows:

  • GetEntry method returns the first ViewEntry instance for the document.

  • Navigators constructed from an object that did not come from the current view return the first instance of the object.

See examples
Examples: NotesViewNavigator class


CacheSize property

Read-Write. The size of the navigator cache in view entries.

Note This property is new with Release 5.0.2b.

Note This property is supported in COM only.

Defined in

NotesViewNavigator

Data type

Long.

Syntax

To get: size& = notesViewName.CacheSize

To set: notesViewName.CacheSize = size&

Legal values

0 | minimum (no cache)
128 | maximum (default)

Note This property is not currently in use. You can get and set it but it has no effect on the cache. It is unaffected by the cache size parameter in the CreateViewNav methods of NotesView, and the legal values are ignored.

See examples
Examples: CacheSize property


MaxLevel property

Read-write. The navigator's maximum level of navigation.

Defined in

NotesViewNavigator

Data type

Long

Syntax

To get: maxlevel& = notesViewNavigator.MaxLevel

To set: notesViewNavigator.MaxLevel = maxlevel&

Legal values

0 | minimum (top level)
30 | maximum (default)

Usage

The maximum cannot be less than the minimum implied by the navigator type, for example, category, children, or descendants.

See examples
Example: MaxLevel property


ParentView property

Read-only. The parent view of a navigator.

Defined in

NotesViewNavigator

Data type

notesView

Syntax

To get: Set notesView = notesViewNavigator.ParentView

See examples
Example: ParentView property

See also
ParentView property


GetChild method

Returns the first child (response) of an entry in a view navigator.

Defined in

NotesViewNavigator

Syntax

Set notesViewEntry = notesViewNavigator.GetChild( notesViewEntry )

Parameter

notesViewEntry

An entry in the view. Defaults to the current entry. If you specify Nothing, this method will generate an error.

Return value

notesViewEntry

The first child of the current or specified entry. Returns null if there are no children.

Usage

This method moves the current pointer to the retrieved entry unless the return value is null.

To find additional response documents, use GetNextSibling. The combination of GetChild and GetNextSibling lets you access a document's responses, sorted in the same order that they appear in a view. To get all of a document's immediate responses, unsorted, use the Responses property in NotesDocument.

See examples
Example: GetChild method

See also
GetChild method


GetCurrent method

Returns the current entry in a view navigator.

Note This method is new with Release 5.0.2b.

Note This method is supported in COM only.

Defined in

NotesViewNavigator

Syntax

Set notesViewEntry = notesViewNavigator.GetCurrent()

Return value

notesViewEntry

The current entry.

Usage

If the navigator is empty, the NotesViewEntry return value is not set nor is an error raised. However, an error is raised when you attempt to use the NotesViewEntry value. You must insert your own code to handle this condition.

See examples
Examples: GetCurrent method


GetEntry method

Returns the specified entry in the navigator.

Defined in

NotesViewNavigator

Syntax

Set notesViewEntry = notesViewNavigator.GetEntry( entry )

Parameter

entry

Variant. The name of an entry in the view. Could be a Document or a ViewEntry object.

Return value

notesViewEntry

The specified entry of the navigator. Returns null if there are no entries.

Usage

This method moves the current pointer to the retrieved entry unless the return value is null.

Unlike all the other ViewNavigator methods, the entry need not come from the current navigator. For instance, you can access an entry in the navigator from a document created via a document collection navigation.

If the specified entry is a document, or came from a ViewEntryCollection, GetEntry method returns the first entry in the view for that entry. The entry may appear in multiple categories.

See examples
Example: GetEntry method

See also
GetEntry method


GetFirst method

Returns the first entry in a view navigator.

Defined in

NotesViewNavigator

Syntax

Set notesViewEntry = notesViewNavigator.GetFirst

Return value

notesViewEntry

The first entry of the navigator. Returns null if there are no entries.

Usage

This method moves the current pointer to the retrieved entry unless the return value is null.

See examples
Example: GetFirst method


GetFirstDocument method

Returns the first document entry in a view navigator, skipping any category entries.

Defined in

NotesViewNavigator

Syntax

Set notesViewEntry = notesViewNavigator.GetFirstDocument

Return value

notesViewEntry

The first document entry of the navigator. Returns null if there are no entries.

Usage

This method moves the current pointer to the retrieved entry unless the return value is null.

See examples
Example: GetFirstDocument method

See also
GetFirstDocument method
GetFirstDocument method


GetLast method

Returns the last entry in a view navigator.

Defined in

NotesViewNavigator

Syntax

Set notesViewEntry = notesViewNavigator.GetLast

Return value

notesViewEntry

The last entry of the navigator. Returns null if there are no entries.

Usage

This method moves the current pointer to the retrieved entry unless the return value is null.

See examples
Example: GetLast method


GetLastDocument method

Returns the last document entry in a view navigator, skipping any category and totals entries.

Defined in

NotesViewNavigator

Syntax

Set notesViewEntry = notesViewNavigator.GetLastDocument

Return value

notesViewEntry

The last document entry of the navigator. Returns null if there are no entries.

Usage

This method moves the current pointer to the retrieved entry unless the return value is null.

See examples
Example: GetLastDocument method

See also
GetLastDocument method
GetLastDocument method


GetNext method

Returns the next entry in a view navigator.

Defined in

NotesViewNavigator

Syntax

Set notesViewEntry = notesViewNavigator.GetNext( notesViewEntry )

Parameter

notesViewEntry

An entry in the view. Defaults to the current entry. If you specify Nothing, this method will generate an error.

Return value

notesViewEntry

The entry following the current or specified entry. Returns null if there is no next entry.

Usage

This method moves the current pointer to the retrieved entry unless the return value is null.

See examples
Example: GetNext method


GetNextCategory method

Returns the next category entry in a view navigator.

Defined in

NotesViewNavigator

Syntax

Set notesViewEntry = notesViewNavigator.GetNextCategory( notesViewEntry )

Parameter

notesViewEntry

An entry in the view. Defaults to the current entry. If you specify Nothing, this method will generate an error.

Return value

notesViewEntry

The category entry following the current or specified entry. Returns null if there is no next category entry.

Usage

This method moves the current pointer to the retrieved entry unless the return value is null.

See examples
Example: GetNextCategory method


GetNextDocument method

Returns the next document entry in a view navigator.

Defined in

NotesViewNavigator

Syntax

Set notesViewEntry = notesViewNavigator.GetNextDocument( notesViewEntry )

Parameter

notesViewEntry

An entry in the view. Defaults to the current entry. If you specify Nothing, this method will generate an error.

Return value

notesViewEntry

The document entry following the current or specified entry. Returns null if there is no next document entry.

Usage

This method moves the current pointer to the retrieved entry unless the return value is null.

See examples
Example: GetNextDocument method

See also
GetNextDocument method
GetNextDocument method


GetNextSibling method

Returns the next sibling entry in a view navigator.

Defined in

NotesViewNavigator

Syntax

Set notesViewEntry = notesViewNavigator.GetNextSibling( notesViewEntry )

Parameter

notesViewEntry

An entry in the view. Defaults to the current entry. If you specify Nothing, this method will generate an error.

Return value

notesViewEntry

The sibling entry following the current or specified entry. Returns null if there is no next sibling entry.

Usage

This method moves the current pointer to the retrieved entry unless the return value is null.

See examples
Example: GetNextSibling method

See also
GetNextSibling method


GetNth method

Returns the entry at a specified position in the top level of a view navigator.

Defined in

NotesViewNavigator

Syntax

Set notesViewEntry = notesViewNavigator.GetNth( index& )

Parameter

index&

Long. Position of the entry, where 1 is the first entry.

Return value

notesViewEntry

The nth top-level entry. Returns null if there is no nth entry.

Usage

This method moves the current pointer to the retrieved entry unless the return value is null.

If you do not have Reader access to a document in a view, this method returns the next document that you have reader access to.

See examples
Example: GetNth method


GetParent method

Returns the parent entry in a view navigator.

Defined in

NotesViewNavigator

Syntax

Set notesViewEntry = notesViewNavigator.GetParent( notesViewEntry )

Parameter

notesViewEntry

An entry in the view. Defaults to the current entry. If you specify Nothing, this method will generate an error.

Return value

notesViewEntry

The parent entry of the current or specified entry. Returns null if there is no parent entry.

Usage

This method moves the current pointer to the retrieved entry unless the return value is null.

See examples
Example: GetParent method


GetPos method

Returns the entry at a specified position in a view navigator.

Defined in

NotesViewNavigator

Syntax

Set notesViewEntry = notesViewNavigator.GetPos( position$, separator$ )

Parameters

position$

A position in decimal format, for example, "1.2.3" is the third response to the second response to the first entry, using the period as a level separator.

separator$

The separator between position levels.

Return value

notesViewEntry

The entry at the specified position. Returns null if there is no entry at that position.

Usage

This method moves the current pointer to the retrieved entry unless the return value is null.

See examples
Example: GetPos method


GetPrev method

Returns the previous entry in a view navigator.

Defined in

NotesViewNavigator

Syntax

Set notesViewEntry = notesViewNavigator.GetPrev( notesViewEntry )

Parameter

notesViewEntry

An entry in the view. Defaults to the current entry. If you specify Nothing, this method will generate an error.

Return value

notesViewEntry

The entry preceding the current or specified entry. Returns null if there is no previous entry.

Usage

This method moves the current pointer to the retrieved entry unless the return value is null.

See examples
Example: GetPrev method


GetPrevCategory method

Returns the previous category entry in a view navigator.

Defined in

NotesViewNavigator

Syntax

Set notesViewEntry = notesViewNavigator.GetPrevCategory( notesViewEntry )

Parameter

notesViewEntry

An entry in the view. Defaults to the current entry. If you specify Nothing, this method will generate an error.

Return value

notesViewEntry

The category entry preceding the current or specified entry. Returns null if there is no previous category entry.

Usage

This method moves the current pointer to the retrieved entry unless the return value is null.

See examples
Example: GetPrevCategory method


GetPrevDocument method

Returns the previous document entry in a view navigator.

Defined in

NotesViewNavigator

Syntax

Set notesViewEntry = notesViewNavigator.GetPrevDocument( notesViewEntry )

Parameter

notesViewEntry

An entry in the view. Defaults to the current entry. If you specify Nothing, this method will generate an error.

Return value

notesViewEntry

The document entry preceding the current or specified entry. Returns null if there is no previous document entry.

Usage

This method moves the current pointer to the retrieved entry unless the return value is null.

See examples
Example: GetPrevDocument method

See also
GetPrevDocument method
GetPrevDocument method


GetPrevSibling method

Returns the previous sibling entry in a view navigator.

Defined in

NotesViewNavigator

Syntax

Set notesViewEntry = notesViewNavigator.GetPrevSibling( notesViewEntry )

Parameter

notesViewEntry

An entry in the view. Defaults to the current entry. If you specify Nothing, this method will generate an error.

Return value

notesViewEntry

The sibling entry preceding the current or specified entry. Returns null if there is no previous sibling entry.

Usage

This method moves the current pointer to the retrieved entry unless the return value is null.

See examples
Example: GetPrevSibling method

See also
GetPrevSibling method


GotoChild method

Moves the current pointer to the first child of a specified entry in a view navigator.

Note This method is new with Release 5.0.2b.

Note This method is supported in COM only.

Defined in

NotesViewNavigator

Syntax

Call notesViewNavigator.GotoChild(notesViewEntry )

Parameter

notesViewEntry

An entry in the view.

Usage

If there is no child, the current pointer stays where it is. No exception is raised. You must insert your own code (for example, comparing positions) to detect this condition.

A child of a category entry can be a category or document entry.

See examples
Examples: GotoChild property


GotoEntry method

Moves the current pointer to the entry for a specified document or view entry.

Note This method is new with Release 5.0.2b.

Note This method is supported in COM only.

Defined in

NotesViewNavigator

Syntax

Call notesViewNavigator.GotoEntry( objUnknown )

Parameter

objUnknown

A NotesDocument or NotesViewEntry object.

Usage

The Document or ViewEntry object provided as the parameter does not have to come from the current view navigator. The gotoEntry method searches for the existence of the entry in the current view navigator.

If there is no entry for the document or view entry, the current pointer stays where it is. No exception is raised. You must insert your own code (for example, comparing positions) to detect this condition.

See examples
Examples: GotoEntry method


GotoFirst method

Moves the current pointer to the first entry in a view navigator.

Note This method is new with Release 5.0.2b.

Note This method is supported in COM only.

Defined in

NotesViewNavigator

Syntax

Call notesViewNavigator.GotoFirst()

See examples
Examples: GotoFirst and GotoNext methods


GotoFirstDocument method

Moves the current pointer to the first document entry in a view navigator, skipping any category entries.

Note This method is new with Release 5.0.2b.

Note This method is supported in COM only.

Defined in

NotesViewNavigator

Syntax

Call notesViewNavigator.GotoFirstDocument()

See examples
Examples: GotoFirstDocument and GotoNextDocument methods


GotoLast method

Moves the current pointer to the last entry in a view navigator.

Note This method is new with Release 5.0.2b.

Note This method is supported in COM only.

Defined in

NotesViewNavigator

Syntax

Call notesViewNavigator.GotoLast()

See examples
Examples: GotoLast and GotoPrev methods


GotoLastDocument method

Moves the current pointer to the last document entry in a view navigator, skipping any totals and category entries.

Note This method is new with Release 5.0.2b.

Note This method is supported in COM only.

Defined in

NotesViewNavigator

Syntax

Call notesViewNavigator.GotoLastDocument()

See examples
Examples: GotoLastDocument and GotoPrevDocument methods


GotoNext method

Moves the current pointer to the entry following a specified entry in a view navigator.

Note This method is new with Release 5.0.2b.

Note This method is supported in COM only.

Defined in

NotesViewNavigator

Syntax

Call notesViewNavigator.GotoNext(notesViewEntry )

Parameter

notesViewEntry

An entry in the view.

Usage

If there is no next entry, the current pointer stays where it is. No exception is raised. You must insert your own code (for example, comparing positions) to detect this condition.

See examples
Examples: GotoFirst and GotoNext methods


GotoNextCategory method

Moves the current pointer to the next category entry following a specified entry in a view navigator.

Note This method is new with Release 5.0.2b.

Note This method is supported in COM only.

Defined in

NotesViewNavigator

Syntax

Call notesViewNavigator.GotoNextCategory(notesViewEntry )

Parameter

notesViewEntry

An entry in the view.

Usage

If there is no next category entry, the current pointer stays where it is. No exception is raised. You must insert your own code (for example, comparing positions) to detect this condition.

See examples
Examples: GotoNextCategory method


GotoNextDocument method

Moves the current pointer to the next document entry following a specified entry in a view navigator.

Note This method is new with Release 5.0.2b.

Note This method is supported in COM only.

Defined in

NotesViewNavigator

Syntax

Call notesViewNavigator.GotoNextDocument(notesViewEntry )

Parameter

notesViewEntry

An entry in the view.

Usage

If there is no next document entry, the current pointer stays where it is. No exception is raised. You must insert your own code (for example, comparing positions) to detect this condition.

See examples
Examples: GotoFirstDocument and GotoNextDocument methods


GotoNextSibling method

Moves the current pointer to the next sibling entry following a specified entry in a view navigator.

Note This method is new with Release 5.0.2b.

Note This method is supported in COM only.

Defined in

NotesViewNavigator

Syntax

Call notesViewNavigator.GotoNextSibling(notesViewEntry )

Parameter

notesViewEntry

An entry in the view.

Usage

If there is no next sibling entry, the current pointer stays where it is. No exception is raised. You must insert your own code (for example, comparing positions) to detect this condition.

See examples
Examples: GotoNextSibling method


GotoParent method

Moves the current pointer to the parent entry of a specified entry in a view navigator.

Note This method is new with Release 5.0.2b.

Note This method is supported in COM only.

Defined in

NotesViewNavigator

Syntax

Call notesViewNavigator.GotoParent(notesViewEntry )

Parameter

notesViewEntry

An entry in the view.

Usage

If there is no next parent entry, the current pointer stays where it is. No exception is raised. You must insert your own code (for example, comparing positions) to detect this condition.

See examples
Examples: GotoParent method


GotoPos method

Moves the current pointer to the entry at a specified position in a view navigator.

Note This method is new with Release 5.0.2b.

Note This method is supported in COM only.

Defined in

NotesViewNavigator

Syntax

Call notesViewNavigator.GotoPos(pos$, separator$ )

Parameters

pos$

String. A position in decimal format, for example, "1.2.3" is the third child to the second child to the first entry using the period as a level separator.

separator$

String. The separator between position levels.

Usage

If there is no entry at the specified position, the current pointer stays where it is. No exception is raised. You must insert your own code (for example, comparing positions) to detect this condition.

This method raises the error ERR_NOTES_VIEWNAV_BAD_POS ("Invalid position string") if the position parameter syntax is incorrect.

See examples
Examples: GotoPos


GotoPrev method

Moves the current pointer to the entry before a specified entry in a view navigator.

Note This method is new with Release 5.0.2b.

Note This method is supported in COM only.

Defined in

NotesViewNavigator

Syntax

Call notesViewNavigator.GotoPrev(notesViewEntry )

Parameter

notesViewEntry

An entry in the view.

Usage

If there is no previous entry, the current pointer stays where it is. No exception is raised. You must insert your own code (for example, comparing positions) to detect this condition.

See examples
Examples: GotoLast and GotoPrev methods


GotoPrevCategory method

Moves the current pointer to the previous category entry before a specified entry in a view navigator.

Note This method is new with Release 5.0.2b.

Note This method is supported in COM only.

Defined in

NotesViewNavigator

Syntax

Call notesViewNavigator.GotoPrevCategory(notesViewEntry )

Parameter

notesViewEntry

An entry in the view.

Usage

If there is no previous category entry, the current pointer stays where it is. No exception is raised. You must insert your own code (for example, comparing positions) to detect this condition.

See examples
Examples: GotoPrevCategory method


GotoPrevDocument method

Moves the current pointer to the previous document entry before a specified entry in a view navigator.

Note This method is new with Release 5.0.2b.

Note This method is supported in COM only.

Defined in

NotesViewNavigator

Syntax

Call notesViewNavigator.GotoPrevDocument(notesViewEntry )

Parameter

notesViewEntry

An entry in the view.

Usage

If there is no previous document entry, the current pointer stays where it is. No exception is raised. You must insert your own code (for example, comparing positions) to detect this condition.

See examples
Examples: GotoLastDocument and GotoPrevDocument methods


GotoPrevSibling method

Moves the current pointer to the previous sibling entry before a specified entry in a view navigator.

Note This method is new with Release 5.0.2b.

Note This method is supported in COM only.

Defined in

NotesViewNavigator

Syntax

Call notesViewNavigator.GotoPrevSibling(notesViewEntry )

Parameter

notesViewEntry

An entry in the view.

Usage

If there is no previous sibling entry, the current pointer stays where it is. No exception is raised. You must insert your own code (for example, comparing positions) to detect this condition.

See examples
Examples: GotoPrevSibling method


ODBCConnection class

Represents the ODBC Data Access features for connecting to a data source.

You must put the following statement in the (Options) event of the (Global) object or the agent to access the ODBC classes:

UseLSX "*LSXODBC"

Properties

AutoCommit

CommitOnDisconnect

DataSourceName

GetLSDOMasterRevision

SilentMode

Methods

CommitTransactions

ConnectTo

Disconnect

GetError

GetErrorMessage

GetExtendedErrorMessage

IsConnected

IsSupported

ListDataSources

ListFields

ListProcedures

ListTables

RollbackTransactions

Access

To create a new ODBCConnection object, use New:

Dim variableName As New ODBCConnection

or

Set odbcConnection = New ODBCConnection

See examples
Example: ODBCConnection class


AutoCommit property

Read-Write. Indicates if auto-commit mode is in effect.

Defined in

ODBCConnection

Data type

Boolean

Syntax

To get:: flag% = odbcConnection.AutoCommit

To set: odbcConnection.AutoCommit = flag%

Legal values

  • True indicates that this database operates in auto-commit mode; default

  • False indicates that this database operates in transaction mode, allowing manual commit or rollback

Usage

When the back-end database is in auto-commit mode, all changes are automatically and permanently changed at the time of a successful UpdateRow or DeleteRow. If the database is in transaction mode, the changes may be committed at specified intervals, including at the time of disconnection.

Some data sources are auto-commit by default--changes are automatically made to the database every time you update a record, rather than at specified intervals as in transaction mode. If the database, driver, or data source does not support transaction mode, you must work in auto-commit mode; if you set AutoCommit to False in this case, it will remain set to True.

Note If you want to work in auto-commit mode, set the CommitOnDisconnect property to False.

See also
CommitOnDisconnect property
CommitTransactions method
RollbackTransactions method


CommitOnDisconnect property

Read-Write. Indicates whether pending transactions are committed or rolled back on disconnect.

Defined in

ODBCConnection

Data type

Boolean

Syntax

To get: flag% = odbcConnection.CommitOnDisconnect

To set: odbcConnection.CommitOnDisconnect = flag%

Legal values

  • True indicates that transactions will be committed on disconnect

  • False indicates that transactions will be rolled back on disconnect

Usage

When the back-end database is in auto-commit mode, all changes are automatically and permanently changed at the time of a successful UpdateRow or DeleteRow. If the database is in transaction mode, the changes may be rolled back or committed later, including at the time of disconnection.

If you want to commit updates when you disconnect from the data source, you must set CommitOnDisconnet to True; in addition, set the AutoCommit property to False.

See also
AutoCommit property
CommitTransactions method
RollbackTransactions method


DataSourceName property

Read-only. The ODBC name of the connected data source.

Defined in

ODBCConnection

Data type

String

Syntax

To get: name$ = odbcConnection. DataSourceName

Usage

The data source name identifies and distinguishes registered ODBC data sources.

Errors

Not connected (DBstsNCON)

See examples
Example: DataSourceName property

See also
ConnectTo method
ListDataSources method


GetLSDOMasterRevision property

Read-only. The revision level of the ODBC LSX.

Defined in

ODBCConnection

Data type

String

Syntax

To get: revlevel$ = odbcConnection.GetLSDOMasterRevision

Usage

Use this string as a reference when asking for help or discussing details of the LSX.

See examples
Example: GetLSDOMasterRevision property


SilentMode property

Read-write. Prevents display of a User ID and Password dialog box during program execution.

Defined in

ODBCConnection

Syntax

To get: status = odbcConnection. SilentMode

To set: odbcConnection. SilentMode = status

Legal values

  • True indicates that SilentMode is successfully set

  • False indicates that SilentMode is not set

Usage

If SilentMode is set, the connection is attempted, but may fail.

If the User ID and Password are supplied as arguments, the connection simply succeeds or fails. (If supplied to a data source that doesn't need them, the connection succeeds.) SilentMode applies to cases where the User ID and Password are not supplied as arguments, but are required.

Some ODBC drivers use several layers of software to reach the data, and an intermediate layer may prompt directly for the user ID and password, ignoring the request not to do so.

See examples
Example: SilentMode property

See also
ConnectTo method
IsSupported method


CommitTransactions method

Commits changes when transaction mode is in effect. This applies to all transactions pending through the connection, and takes no arguments.

Defined in

ODBCConnection

Syntax

status = odbcConnection.CommitTransactions

Return value

  • True indicates that the pending changes were committed successfully

  • False indicates an error

Usage

Result sets are not affected by the CommitTransactions method, only the back-end database is updated using the information in the transaction log. All updates since the last commit are entered into the back-end database.

Some data sources are auto-commit by default--changes are automatically made to the database every time you update a record, rather than at specified intervals as in transaction mode.

Errors

Not connected

Events

BeforeCommitTransactions

AfterCommitTransactions

See also
CommitOnDisconnect property
AutoCommit property
RollbackTransactions method


ConnectTo method

Connects to a data source.

Defined in

ODBCConnection

Syntax

status = odbcConnection. ConnectTo( dataSourceName$ [ , userID$ [ , password$ ]] )

Parameters

dataSourceName$

String. The ODBC name of the data source you want to connect to.

userID$

String. Optional. The name of the user ID.

password$

String. Optional. The password for the user ID.

Return value

  • True indicates that the connection to the data source was successfully achieved

  • False indicates that the connection to the data source failed

Usage

Use to establish a connection to a data source. The source must already be registered in the ODBC Driver Manager. This method does not automatically register data sources.

Errors

Cannot find named data source (DBstsCANF)

Unable to connect (DBstsCCON)

Unable to get user ID and password (DBstsACCS)

Events

BeforeConnect

AfterConnect

BeforeConnectTo

AfterConnectTo

See examples
Example: ConnectTo method

See also
Disconnect method
IsConnected method
ListDataSources method
SilentMode property


Disconnect method

Disconnects from the data source.

Defined in

ODBCConnection

Syntax

status = odbcConnection.Disconnect

Return value

  • True indicates that disconnect was successful

  • False indicates that disconnect failed

Usage

You can use a result set after disconnecting, but you cannot fetch more data or post updates to the back-end database.

Errors

Not connected to a data source (DBstsNCON)

Events

BeforeDisconnect

AfterDisconnect

See examples
Example: Disconnect method

See also
ConnectTo method
IsConnected method


GetError method

For information about this method, see GetError in the ODBCQuery class.


GetErrorMessage method

For information about this method, see GetErrorMessage in the ODBCQuery class.


GetExtendedErrorMessage method

For information about this method, see GetExtendedErrorMessage in the ODBCQuery class.


IsConnected method

Indicates whether the connection object still exists.

Defined in

ODBCConnection

Syntax

status = odbcConnection.IsConnected

Return value

  • True indicates that the connection object exists

  • False indicates that the connection no longer exists

Usage

Use IsConnected to periodically test the connection to your data source; for example, before attempting to commit a series of transactions.

See examples
Example: IsConnected method

See also
ConnectTo method
Disconnect method


IsSupported method

Indicates whether an option is supported by the data source.

Defined in

ODBCConnection

Syntax

status = odbcConnection. IsSupported( option )

Parameter

option

Constant. Must be one of the following:

DB_SUPP_CURSORS
DBMS uses cursors.

DB_SUPP_PROCEDURES
DBMS has a stored-procedure capability.

DB_SUPP_READONLY
DBMS or its driver can put the data into read-only mode. For some drivers, an incorrect value is returned. The incorrect value is usually False, indicating that the READONLY option is not supported, when in fact it is supported.

DB_SUPP_SILENTMODE
DBMS can silently deny access if the user ID or password fails.

DB_SUPP_TRANSACTIONS
DBMS supports transaction mode, allowing you to specify when updates are committed to the data source, rather than using auto-commit to commit each update immediately.

Return value

  • True indicates that the specified option is supported by the data source

  • False indicates that the option is not supported by the data source

Usage

Use IsSupported to test whether the connected data source supports a particular option before attempting to use it, thus avoiding potential errors in your script.

See examples
Example: IsSupported method

See also
DeleteRow method (in ODBCResultSet)
Execute method (in ODBCResultSet)
ListProcedures method
ReadOnly property (in ODBCResultSet)
SilentMode property
UpdateRow method (in ODBCResultSet)


ListDataSources method

Lists all registered data sources as an array.

Defined in

ODBCConnection

Syntax

sourceArray = odbcConnection. ListDataSources

Return value

sourceArray

Array of strings. Each element in the array is a string representing a registered data source.

Events

BeforeListDataSources

AfterListDataSources

See examples
Example: ListDataSources method

See also
ConnectTo method
DataSourceName property


ListFields method

Returns an array of field (column) names in a table.

Defined in

ODBCConnection

Syntax

fieldArray = odbcConnection.ListFields( [ tableName$ ] )

Parameters

tableName$

String. Optional. The name of the table. Defaults to the current table, if any.

Return value

fieldArray

Array of strings. Each element in the array is the name of a field in the referenced table. The entries are in their table order.

Errors

Not connected to a data source (DBstsNCON)

Table did not return any columns (DBstsNCOL)

Events

BeforeListFields

AfterListFields

See examples
Examples: ListFields method

See also
ListDataSources method
ListTables method


ListProcedures method

Lists the executable procedures at the connected data source.

Defined in

ODBCConnection

Syntax

procArray = odbcConnection. ListProcedures( [ dataSourceName$ [ , userID$ [ , password$ ]]] )

Parameters

dataSourceName$

String. Optional. The name of the data source.

userID$

String. Optional. The name of the user ID.

password$

String. Optional. The password for the user ID.

Return value

procArray

Array of strings. Each element in the array is the name of an executable procedure at the connected data source. The DBMS may list all stored procedures or only those that the specified user can run.

Errors

Not connected to a data source (DBstsNCON)

Unable to get user ID and password (DBstsACCS)

Events

BeforeListProcedures

AfterListProcedures

See examples
Examples: ListProcedures method

See also
IsSupported property


ListTables method

Lists the available tables in a connected data source.

Defined in

ODBCConnection

Syntax

tableArray = odbcConnection. ListTables( [ dataSourceName$ [ , userID$ [ , password$ ] ] ] )

Parameters

dataSourceName$

String. Optional. The name of the data source. Defaults to the current data source.

userID$

String. Optional. The name of the user ID.

password$

String. Optional. The password for the user ID.

Return value

tableArray

Array of strings. Each element in the array is the name of an available table in a data source.

Errors

Not connected to a data source (DBstsNCON)

Unable to get user ID and password (DBstsACCS)

Events

BeforeListTables

AfterListTables

See examples
Example: ListTables method

See also
ListFields method


RollbackTransactions method

Rolls back changes when transaction mode is in effect. This applies to all uncommitted transactions pending through the connection, and takes no arguments.

Defined in

ODBCConnection

Syntax

status = odbcConnection.RollbackTransactions

Return value

  • True indicates that the pending changes were rolled back successfully

  • False indicates an error

Usage

Result sets are not affected by the RollbackTransactions method, nor is the back-end database. Instead, all of the as-yet-uncommitted updates in the translation log are erased.

Some data sources are auto-commit by default--changes are automatically made to the database every time you update a record, rather than at specified intervals as in transaction mode. If a database is in auto-commit mode, you cannot rollback your updates. Use the AutoCommit property to determine whether a database is in auto-commit mode.

Errors

Not connected

Events

BeforeRollbackTransactions

AfterRollbackTransactions

See also
CommitOnDisconnect property
AutoCommit property
CommitTransactions method


ODBCQuery class

Represents the ODBC data access features for defining an SQL statement.

Properties

Connection

QueryExecuteTimeOut

SQL

UseRowID

Methods

GetError

GetErrorMessage

GetExtendedErrorMessage

Creation and Access

To create a new ODBCQuery object, use New:

Dim variableName As New ODBCQuery

or

Set odbcQuery = New ODBCQuery

Usage

Before using a query, use the Connection property of ODBCQuery to associate the query with an ODBCConnection object. Before using a query with a result set, use the Query property of ODBCResultSet to associate the query with the ODBCResultSet object.

See examples
Example: ODBCQuery class


Connection property

Write-only. Relates a connection object with a query.

Defined In

ODBCQuery

Data type

ODBCConnection

Syntax

Set odbcQuery.Connection = odbcConnection

Usage

You must use the connection property to link a connection object with a query. A query must pertain to a valid connection before it can be used or validated.

Errors

No valid connection object (DBstsNCOJ)

See examples
Example: Connection property


QueryExecuteTimeOut property

Read-write. Specifies a time-out value in seconds for query execution.

Defined In

ODBCQuery

Data type

Integer

Syntax

To get: time% = odbcQuery.QueryExecuteTimeOut

To set: odbcQuery.QueryExecuteTimeOut = time%

Usage

Use to optimize result set retrieval or to ensure timely results in a browsing application.

See examples
Example: QueryExecuteTimeOut property

See also
Execute method (in ODBCResultSet)
IsResultSetAvailable property (in ODBCResultSet)


SQL property

Read-write. Any SQL statement.

Defined In

ODBCQuery

Data type

String

Syntax

To get: statement$ = odbcQuery.SQL

To set: odbcQuery.SQL= statement$

Usage

When an SQL statement is stored, it is analyzed for parameters, table names, and other items, but full parsing can only be performed by the data source when the statement is executed. There is no practical limit to the length of the SQL statement written, nor is the SQL statement limited to a query (SELECT statement). The SQL statement is not executed until an ODBCResultSet object is created and Execute is performed.

When using the SQL property, be aware that Notes could stop under these circumstances:

  • The SQL statement contains the word FROM and it doesn't specify a table name.

  • While the SQL statement is being checked, memory becomes unavailable.

Statement execution depends on a user's access rights. A user may not be authorized to alter certain fields or tables, perform certain operations, or access certain tables or columns.

Events

BeforeSetSQL

AfterSetSQL

See examples
Example: SQL property

See also
Execute method (in ODBCResultSet)
ListFields method (in ODBCConnection)
ListTables method (in ODBCConnection)
SetParameter method (in ODBCResultSet)


UseRowID property

Specifies whether data in the back-end database will be accessed by row ID.

Defined in

ODBCQuery

Syntax

To get: flag% = odbcQuery.UseRowID

To set: odbcQuery.UseRowID = flag%

Data type

Boolean

Legal values

  • True indicates that "Select by row ID mode" is set

  • False indicates that "Select by row ID mode" is not set; default

Usage

UseRowID defaults to False; most databases do not support access by row ID. Set UseRowID to True when you want to use "Select by Row ID mode" (the back-end database must support this type of access). You must set this type of access before using the SQL property to define your SQL statement.

See examples
Examples: UseRowID property


GetError method

Returns the latest error code for an ODBC object.

Defined In

ODBCConnection

ODBCQuery

ODBCResultSet

Syntax

error% = odbcConnection.GetError

error% = odbcQuery.GetError

error% = odbcResultSet.GetError

Return value

error%

Integer. See GetErrorMessage for a list of error codes.

Usage

See GetErrorMessage for usage information and examples.

See also
Handling an ODBC error
GetErrorMessage method
GetExtendedErrorMessage method


GetErrorMessage method

Returns the short error message text associated with an error code.

Defined In

ODBCConnection

ODBCQuery

ODBCResultSet

Syntax

message$ = odbcConnection.GetErrorMessage( [ errorvalue ] )

message$ = odbcQuery.GetErrorMessage( [ errorvalue ] )

message$ = odbcResultSet.GetErrorMessage( [ errorvalue ] )

Parameter

errorvalue

Optional. The error number returned by the GetError method or by DB_LASTERROR to refer to the last error for an ODBC object. The following named constants identify the error numbers:

DBstsSUCCESS | Not an error, SUCCESS (cannot be trapped by ON ERROR)
DBstsACCS | Unable to get user ID and password
DBstsAHVR | The previous added row has not been updated
DBstsBADP | Bad parameter
DBstsCANF | Cannot find named data source
DBstsCARR | Cannot access requested row
DBstsCCON | Unable to connect
DBstsCNVD | String length exceeded
DBstsCNVR | Cannot convert data from native to expected or requested datatype
DBstsCOAR | Operation not allowed on AddRow workspace
DBstsCPAR | Cannot position at AddRow
DBstsCXIN | Could not execute insert or update
DBstsENTR | Entry missing
DBstsEOFD | End of data has been reached
DBstsFAIL | The operation failed for unspecified reasons
DBstsHSTMT | ODBC could not allocate a new statement handle
DBstsILLG | Unrecognized or illegal data type
DBstsINTR | Internal buffer limit reached when creating a string
DBstsINVC | Field ID is out of range
DBstsINVR | Invalid row number
DBstsMEMF | Out of memory
DBstsNAFI | Cannot insert new row before AddRow
DBstsNCOJ | No valid connection object
DBstsNCOL | Table did not return any columns
DBstsNCON | Not connected to a data source
DBstsNODA | The result contains no data
DBstsNOEX | Never executed successfully or result set closed
DBstsNQOJ | No valid query object
DBstsNUNQ | Update or Delete cannot locate a unique data row
DBstsODBC | ODBC could not complete the requested operation
DBstsPMIS | Missing parameter in query
DBstsRCHG | Original row data changed. Cannot be updated or deleted
DBstsRDON | Read Only. Data cannot be updated or deleted
DBstsROWD | The row has previously been deleted
DBstsRUNC | No changes in row
DBstsSNFD | A resource string could not be found in the resource file
DBstsUBLE | Column Not Updateable
DBstsUNIM | Unimplemented feature

Return value

message$

String. The error message that corresponds to errorvalue. The message begins with "LS:DO" to distinguish it from other LotusScript messages.

Usage

You can test for an error with one of the following techniques:

  • Check the return value of GetError immediately after a method or property is used.

  • Create an error handler and use On Error.

See examples
Examples: GetErrorMessage method

See also
Handling an ODBC error
GetError method
GetExtendedErrorMessage method


GetExtendedErrorMessage method

Returns the long, descriptive error message text associated with an error code.

Defined in

ODBCConnection

ODBCQuery

ODBCResultSet

Syntax

extendedMessage$ = odbcConnection.GetExtendedErrorMessage( errorvalue )

extendedMessage$ = odbcQuery.GetExtendedErrorMessage( errorvalue )

extendedMessage$ = odbcResultSet.GetExtendedErrorMessage( errorvalue )

Parameter

errorvalue

Optional. The error number returned by GetError. Defaults to the error number for the last method called from the object.

Return value

extendedMessage$

String. The extended error message text associated with the error number.

See also
Handling an ODBC error
GetError method
GetErrorMessage method


ODBCResultSet class

Represents the ODBC data access features for performing operations on a result set.

Properties

CacheLimit

CurrentRow

FetchBatchSize

MaxRows

Query

ReadOnly

Methods

AddRow

Close

DeleteRow

ExecProcedure

Execute

FieldExpectedDataType

FieldID

FieldInfo

FieldName

FieldNativeDataType

FieldSize

FirstRow

GetError

GetErrorMessage

GetExtendedErrorMessage

GetParameter

GetParameterName

GetRowStatus

GetValue

HasRowChanged

IsBeginOfData

IsEndOfData

IsResultSetAvailable

IsValueAltered

IsValueNull

LastRow

LocateRow

NextRow

NumColumns

NumParameters

NumRows

PrevRow

SetParameter

SetValue

UpdateRow

Creation and Access

To create a new ODBCResultSet object, use New:

Dim variableName As New ODBCResultSet

or

Set odbcResultSet = New ODBCResultSet

See examples
Example: ODBCResultSet class


CacheLimit property

Read-write. The maximum number of rows to be cached in memory.

Defined in

ODBCResultSet

Data type

Long

Syntax

To get: limit& = odbcResultSet.CacheLimit

To set: odbcResultSet.CacheLimit = limit&

Usage

The limit is DB_ALL (full set), DB_NONE (minimum set), or the number of rows to store. DB_NONE means that only a very small window, including the current row, is kept in memory.

If the FetchBatchSize property is also set, it should be less than or equal to CacheLimit unless you know that the data you're passing over is of no use.

Caching uses up memory fairly quickly, so you should only cache large numbers of rows when it's really necessary; for example, when you want to move back and forth between rows.

See examples
Example: CacheLimit property

See also
CurrentRow property
FetchBatchSize property
LastRow method
MaxRows property
NextRow method


CurrentRow property

Read-write. The number of the current row in a result set, starting from row 1.

Defined in

ODBCResultSet

Data type

Long

Syntax

row& = odbcResultSet.CurrentRow

odbcResultSet.CurrentRow = row&

Usage

The special value DB_ADDROW specifies that the current row is the AddRow workspace.

Setting the current row value is equivalent to positioning the cursor to that row and may require fetching records. Unless caching is enabled, it may not be possible to set the row at a location before the current row. Once the data has been fetched, setting the CurrentRow property to 0 raises error #545.

Errors

The result contains no data (DBstsNODA)

Cannot access requested row (DBstsCARR)

Cannot position at AddRow (DBstsCPAR)

Invalid row number (DBstsINVR)

The row has previously been deleted (DBstsROWD)

Events

AfterCurrentRow

AfterRowPositionChange

BeforeCurrentRow

BeforeRowPositionChange

See examples
Example: CurrentRow property

See also
AddRow method
Connection property (in ODBCQuery)
LastRow method
LocateRow method
NextRow method
NumRows method
PrevRow method


FetchBatchSize property

Read-write. Specifies the number of records that will be fetched at any one time. The default is 1 (get just the requested record).

Defined in

ODBCResultSet

Data type

Long

Syntax

To get: size& = odbcResultSet.FetchBatchSize

To set: odbcResultSet.FetchBatchSize = size&

Usage

Use FetchBatchSize to fine-tune performance. Fetching multiple records is faster than fetching single records. If the CacheLimit property is also set, it must be greater than or equal to FetchBatchSize, unless you know that the data you're passing over is of no use.

Fetching multiple records at once requires caching, which uses up memory fairly quickly. You should only cache large numbers of rows when it's really necessary, for example, when you want to move back and forth between rows.

See examples
Example: FetchBatchSize property

See also
CacheLimit property
MaxRows property


MaxRows property

Read-Write. Maximum number of rows fetched to the result set, or 0 to fetch all rows subject to memory limits.

Defined in

ODBCResultSet

Data type

Long

Syntax

To get: rows& = odbcResultSet.MaxRows

To set: odbcResultSet.MaxRows = rows&

Usage

This parameter defines a subset of the data. You can use MaxRows to limit the number of rows to be processed while developing a script.

See examples
Example: MaxRows property

See also
CacheLimit property
FetchBatchSize property
LastRow method
NextRow method
NumRows method


Query property

Write-only. Relates an ODBCQuery object with a result set.

Defined in

ODBCResultSet

Data type

ODBCQuery

Syntax

To set: Set odbcResultSet.Query = odbcQuery

Usage

To execute the query, you must associate the result set with a valid query object.

Errors

No valid query object (DBstsNQOJ)

See examples
Example: Query property

See also
Execute method


ReadOnly property

Read-write. Indicates if a result set is read-only. Can be set to True to prevent updates.

Defined in

ODBCResultSet

Data type

Boolean

Syntax

To get: flag% = odbcResultSet.ReadOnly

To set: odbcResultSet.ReadOnly = flag%

Legal values

  • True indicates that the result set and possibly the data source are read-only

  • False indicates that the result set and data source can be updated

Usage

Even if the data source does not support a command to place itself in read-only mode, you can set the result set to read-only .

See examples
Example: ReadOnly property

See also
DeleteRow method
IsResultSetAvailable method
IsSupported method (in ODBCConnection)
SetValue method


AddRow method

Adds a workspace for a new row.

Defined in

ODBCResultSet

Syntax

status = odbcResultSet.AddRow

Return value

status

Boolean.

Usage

The sequence of events is: use AddRow to create an empty (null data) row in the ADDROW workspace; use SetValue to populate the row with data; use UpdateRow to write the row to the data source. If the data source supports transaction model commit and roll-back, changes must be followed by a commit or roll-back. The ADDROW workspace holds exactly one row.

The added row is never actually part of a cached result set. Your current row position is either in the result set or in the added row, depending on the action you take. The initial AddRow positions you at the added row. To switch back to the result set, use CurrentRow, LocateRow, FirstRow, or LastRow. Once inside the result set, you can also use the PrevRow and NextRow methods. To switch back to the added row, use the special constant, DB_ADDROW, as in

res.CurrentRow = DB_ADDROW

The PrevRow and NextRow methods work in the result set but cannot be used in the added row.

To determine on which row and on which buffer you are currently located, test CurrentRow for the DB_ADDROW constant.

A successful UpdateRow closes the AddRow workspace and sets CurrentRow back to a row in the result set, if any. When the AddRow workspace is closed, you cannot set the CurrentRow to DB_ADDROW; you must issue another AddRow to open a new AddRow workspace. UpdateRow sends the update to the data source but does not update the result set; to see new rows, re-execute the SQL query. Execute and Close both discard an open AddRow workspace.

If you query the table with an explicit column list (for example, "SELECT Col1, Col2, Col4 FROM Table1"), that list must include all columns for which null values are disallowed; all columns not listed take a null value when the new row is inserted.

Errors

The previous added row has not been updated (DBstsAHVR)

Read only. Data cannot be updated or deleted (DBstsRDON)

Never executed successfully or result set closed (DBstsNOEX)

Events

BeforeAddRow

AfterAddRow

See examples
Example: AddRow method

See also
CurrentRow property
SetValue method
UpdateRow method


Close method

Close a result set.

Defined in

ODBCResultSet

Syntax

status = odbcResultSet.Close [ (option ) ]

Parameter

option

Constant. DB_CLOSE to close the entire result set (this is the default) or DB_CANCELADDROW to close only the AddRow workspace.

Return value

status

Boolean.

Usage

The ODBCResultSet object still exists, but the data is purged. Most methods raise the DBstsNOEX (no Execute) error on a closed result set because the data is gone. You can use the object properties, including Query, so you can "reopen" the data with Execute.

A result set can be used after disconnecting from the data source, but no additional data can be fetched and no updates can be posted. To fetch all data in one pass, set the CacheLimit property to DB_ALL, execute the query, and call the LastRow method (to force fetching and traversal of all data satisfying the query). Now you can disconnect and use the data in the result set.

Events

BeforeClose

AfterClose

See examples
Example: Close method

See also
AddRow method
Disconnect method (in ODBCConnection)


DeleteRow method

Deletes the record represented by the current row of the result set from the specified table in the external database.

Defined in

ODBCResultSet

Syntax

status = odbcResultSet.DeleteRow( tableName$ )

Parameter

tableName$

String. The name of the table in which you want to delete the record.

Return value

status

Boolean.

Usage

The DeleteRow method may not be possible if the result or database is read-only.

DeleteRow does not change the value of NumRows, so row numbers from CurrentRow do not need to be recalculated.

The tableName$ parameter is required to prevent ambiguity when forming an SQL statement for the data source.

This statement can fail when the result set includes columns with Image or Rich Text data types or when rows are not identified uniquely. To avoid these failures, see Working with data retrieved from an external database.

Errors

Invalid row number (DBstsINVR)

Update or Delete cannot locate a unique data row (DBstsNUNQ)

Read only. Data cannot be updated or deleted (DBstsRDON)

This method might raise an error about not being applicable to the AddRow workspace in some cases where another error message applies.

Events

BeforeDeleteRow

AfterDeleteRow

See examples
Example: DeleteRow method

See also
Close method
GetRowStatus method
IsSupported method (in ODBCConnection)
ReadOnly property


ExecProcedure Method

Executes a stored SQL procedure.

Defined in

ODBCResultSet

Syntax

status = odbcResultSet.ExecProcedure( procedureName$ [,arg1] [,arg2] ... [,arg30] )

or

status = odbcResultSet.ExecProcedure( procedureName$, DB_PARAM_ARRAY, argArray )

Parameters:

procedureName$

String. The name of the SQL procedure you want to execute.

arg1..30

Up to 30 arguments can be passed to a procedure. The arguments can be in any format. An argument can serve as input, output, or both. Argument data types must be consistent with the requirements of the procedure. Separate arguments with commas. Any missing arguments are treated as NULL values. The 30 argument limit is a LotusScript limitation.

To enter more than 30 arguments, you can use the alternate syntax and pass the arguments in an array. In the alternate syntax, the second argument must contain the constant DB_PARAM_ARRAY. The third argument can be an array of any size or type.

Return value

Varies, depending on the definition of the stored procedure, which may return output arguments, a result set, or an execution status.


Execute method

Executes an SQL statement.

Defined in

ODBCResultSet

Syntax

status = odbcResultSet.Execute

Return Value

status

Boolean.

Usage

Use this method to execute a query or any other valid SQL statement. Any existing data in the ODBCResultSet object is discarded. NumColumns changes to reflect the actual number of columns in the result set. NumRows is set to DB_ROWSUNKNOWN. IsResultSetAvailable, IsBeginOfData, IsEndOfData, and CurrentRow are all reset.

Errors

ODBC could not complete the requested operation (DBstsODBC)

Note GetExtendedErrorMessage contains the message, if any, returned by the data source.

Events

BeforeExecute

AfterExecute

See examples
Example: Execute method

See also
IsResultSetAvailable method
Query property
NumColumns method
NumRows method
SetParameter method


FieldExpectedDataType method

Gets or sets the data type for a column.

Defined in

ODBCResultSet

Syntax

To get: dataType = odbcResultSet.FieldExpectedDataType( column )

To set: dataType = odbcResultSet.FieldExpectedDataType( column , dataType )

Parameters

column

Integer or string. Indicates the column number or name. When using integer, use any numeric data type, except Currency.

dataType

Constant. Indicates the data type to convert to: DB_TYPE_UNDEFINED, DB_CHAR, DB_SHORT, DB_LONG, DB_DOUBLE, DB_DATE, DB_TIME, DB_BINARY, DB_BOOL, DB_DATETIME.

Return Value

dataType

Constant. The data type of the column: DB_TYPE_UNDEFINED, DB_CHAR, DB_SHORT, DB_LONG, DB_DOUBLE, DB_DATE, DB_TIME, DB_BINARY, DB_BOOL, DB_DATETIME.

Usage

All field values are returned as they appear in the database.

An application may have special field value requirements; for example, it may need field values returned as strings. Some data type conversions are not possible; for example, returning names as real numbers. The returned value indicates the type that was set, which may differ from the requested type.

To determine the database data type, use FieldNativeDataType to return the data type as stored in the database for this column. Use FieldSize to return the field size at the database. Use FieldInfo, which contains all known field information, to return other field information.

If the expected field type is DB_BINARY, LotusScript raises a type mismatch error if the target variable is not Variant or String. (You must check for this LotusScript error as well as LS:DO errors.)

Errors

Field ID is out of range (DBstsINVC)

See examples
Examples: FieldExpectedDataType method

See also
FieldNativeDataType method
FieldSize method
GetValue method
SetValue method


FieldID method

Returns the field ID of a field as an integer value, given the field name.

Defined in

ODBCResultSet

Syntax

id% = odbcResultSet.FieldID( column$ )

Parameter

column$

String. The name of the field in the result set.

Return value

id%

Integer. The field ID.

Usage

The field ID in the result set corresponds to the relative column number; that is, the first column has a field ID of 1; the second column's field ID is 2; and so on.

The field ID is required only when you know the field name, but not the column ID. If the result set changes, a field's relative position, and consequently its ID, changes. Use FieldID to determine the field ID dynamically.

Errors

Invalid column (DBstsINVC)

See examples
Example: FieldID method

See also
GetValue method
FieldName method
IsValueAltered method
NumColumns property


FieldInfo method

Returns an array of field information.

Defined in

ODBCResultSet

Syntax

infoArray = odbcResultSet.FieldInfo( column_id% )

or

infoArray = odbcResultSet.FieldInfo( column_Name$ )

Parameters

column_id%

Integer. The ID of the column. Use any numeric data type, except Currency.

column_Name$

String. The name of the column.

Return value

Array with elements as follows:

DB_INFO_AUTOINCREMENT | Boolean. Returns True if column value is automatically incremented (a serial number).
DB_INFO_CASESENSITIVE | Boolean. Returns True if column value is case sensitive. A search is performed in a case-sensitive manner.
DB_INFO_COLUMNID | String. Contains the column ID. This is an ordinal value identifying the relative position in the result set of this column. The value is also returned by FieldID.
DB_INFO_COLUMNNAME | String. Contains the column name. If the column is computed, the automatic name Computed1, Computed2, and so forth, is generated. This name is also returned by FieldName.
DB_INFO_COMPUTED | Boolean. True if the column is computed.
DB_INFO_DISPLAYSIZE | Integer. Value is maximum display size in characters, not bytes.
DB_INFO_EXPECTED_DATATYPE | Integer. The expected data type is the translation data type for this column. For actual values and additional information, see the FieldExpectedDataType method.
DB_INFO_LENGTH | Integer. Value returned in FieldSize.
DB_INFO_MONEY | Boolean. True if the column value represents money or currency.
DB_INFO_NATIVE_DATATYPE | Integer. Contains the native data type for the referenced column. The native data type is the data type of the field as stored in the database and may be any of the types described in FieldNativeDataType.
DB_INFO_NULLABLE | Integer. One of the following: DB_NO_NULLS (cannot accept null); DB_NULLABLE (can accept null); DB_NULLS_UNKNOWN (unknown null status).
DB_INFO_PRECISION | Integer. The back-end precision value.
DB_INFO_READONLY | Integer. Read-only status at the back-end; does not reflect local protection granted by the ReadOnly property. One of the following: DB_READWRITE; DB_READONLY (back-end protected or computed); DB_READONLY_UNKNOWN.
DB_INFO_SCALE | Integer. Number of places after the decimal point. Value is valid only for real or float values; zero otherwise.
DB_INFO_SEARCHABLE | Integer. One of the following: DB_UNSEARCHABLE (cannot be part of Where clause); DB_LIKE_ONLY (can be used in a Where clause only with Like); DB_ALLEXCEPT_LIKE (can be used, but without Like); DB_SEARCHABLE (can be used in a Where clause).
DB_INFO_SETTABLE | Boolean. False means that SetValue fails because the column is read-only, the database is read-only, read-only has been set by ReadOnly, or the column is computed and cannot be updated. True means that SetValue does not fail but UpdateRow may fail; for example, a unique value is required, some arguments are invalid, the original row is locked or has changed, or other reasons.
DB_INFO_SQLDATATYPE | Integer. Contains the native data type for the referenced column. The native data type is the data type of the field as stored in the database and may be any of the types described in FieldNativeDataType.
DB_INFO_TABLENAME | String. Contains the table name for the column. If the column is computed or if the column is an aggregate and is not part of any table, no table name is supplied--that is, the null string is returned.
DB_INFO_UNSIGNED | Boolean. True if the column value is unsigned. For integer and long, this means that the value has no sign.

Usage

Reports characteristics of a field. Not all data sources have all the characteristics, but the ODBC standard requires that the driver report them all.

Errors

Field id is out of range (DBstsINVC)

See also
FieldID method
FieldName method
FieldNativeDatatype method
FieldSize method
GetValue method
ReadOnly property
SetValue method


FieldName method

Returns the field name for a specified column, given its ID (column number).

Defined in

ODBCResultSet

Syntax

fieldName$ = odbcResultSet.FieldName( column_id )

Parameter

column_id

Integer. The column ID of the field in the result set. Use any numeric data type, except Currency.

Return value

fieldName$

String. The name of the field. Computed fields take names of Computed1, Computed2, and so on.

Errors

Field ID is out of range (DBstsINVC)

See examples
Example: FieldName method

See also
FieldID method


FieldNativeDataType method

Given a specific column, returns the native data type for that column.

Defined in

ODBCResultSet

Syntax

formatValue = odbcResultSet.FieldNativeDataType( column_id% )

or

formatValue = odbcResultSet.FieldNativeDataType(column_Name$ )

Parameters

column_id%

Integer. The ID of the column. Use any numeric data type, except Currency.

column_Name$

String. The name of the column

Return value

Constant. One of the following:

  • SQL_CHAR

  • SQL_NUMERIC

  • SQL_DECIMAL

  • SQL_INTEGER

  • SQL_SMALLINT

  • SQL_FLOAT

  • SQL_REAL

  • SQL_DOUBLE

  • SQL_DATE

  • SQL_TIME

  • SQL_TIMESTAMP

  • SQL_VARCHAR

  • SQL_BINARY

  • SQL_VARBINARY

  • SQL_LONGVARCHAR

  • SQL_LONGVARBINARY

  • SQL_BIGINT

  • SQL_TINYINT

  • SQL_BIT

Usage

The native data type is that of the field as stored in the database but expressed in ODBC-standard terms. The data type of the returned data value is the value set by the expected data type. If the expected type is not set, data is converted to the LotusScript data type that most closely resembles the native type.

Errors

Field ID is out of range (DBstsINVC)

See examples
Example: FieldNativeDataType method

See also
FieldExpectedDataType method
FieldInfo method


FieldSize method

Returns the maximum size of data for a field.

Defined in

ODBCResultSet

Syntax

size% = odbcResultSet. FieldSize( column_id% )

or

size% = odbcResultSet. FieldSize( column_Name$ )

Parameters

column_id%

Integer. The ID of the column. Use any numeric data type, except Currency.

column_Name$

String. The name of the column.

Return value

size%

Integer. The maximum size of data for the field.

Usage

The unit of measurement is usually a byte, but depends on the data source.

The return value may be 0 for some field types that contain large amounts of arbitrary data; for example, rich text fields.

The meaning of size% depends on the field type. For example, the size of a variable-length field is the maximum length of the field, but the stored text can be shorter.

Errors

Invalid column ID or name (DBstsINVC)

See examples
Example: FieldSize method

See also
FieldInfo method
FieldNativeDataType method


FirstRow method

Sets the current row to the first row in a result set. Equivalent to setting CurrentRow to 1.

Defined in

ODBCResultSet

Syntax

status = odbcResultSet. FirstRow

Return value

status

Boolean. Returns True if successful; otherwise, returns False, indicating an error.

Usage

FirstRow is useful to prepare for another pass through the result set, as when using LocateRow interactively.

You may not be able to move to the first row unless you enabled caching of all rows. If FirstRow fails, use GetError to examine the meaning.

"Invalid row number" can occur if the result set has 0 rows.

Errors

Cannot access requested row (DBstsCARR)

Invalid row number (DBstsINVR)

Events

BeforeFirstRow

AfterFirstRow

BeforeRowPositionChange

AfterRowPositionChange

See examples
Example: FirstRow method

See also
CurrentRow property
IsBeginOfData method
LastRow method
LocateRow method
NextRow method
NumRows method
PrevRow method


GetParameter method

Returns the last value set for the specified parameter.

Defined in

ODBCResultSet

Syntax

value = odbcResultSet.GetParameter( parameterName$ )

or

value = odbcResultSet.GetParameter( parameter_index% )

Parameters

parameterName$

String.

parameter_index%

Integer.

Return value

value

Data type varies.

Usage

Parameters are used in SQL statements. Unlike ODBC and standard SQL, parameters may appear anywhere in the SQL statement. Use SetParameter to set the replacement value for the parameter.

Events

BeforeGetParameter

AfterGetParameter

See examples
Example: GetParameter method

See also
SQL property (in ODBCQuery)
SetParameter method
GetParameterName method
NumParameters method


GetParameterName method

Retrieves a parameter name.

Defined in

ODBCResultSet

Syntax

name = odbcResultSet. GetParameterName( parameter_index% )

Parameter

parameter_index%

Integer.

Return value

name$

String. The name of the parameter.

Usage

Parameter names contained in SQL statements are retrieved using parameter_index% as an index. Each name is returned without its surrounding question marks. You can use the parameter names to prompt a user.

Events

BeforeGetParameterName

AfterGetParameterName

See examples
Example: GetParameterName method

See also
GetParameter method
SetParameter method


GetRowStatus method

Returns the alteration status of the current row.

Defined in

ODBCResultSet

Syntax

status% = odbcResultSet.GetRowStatus

Return value

Integer.

  • DB_UNCHANGED (Not changed - values are as fetched)

  • DB_ALTERED (Changed by SetValue)

  • DB_UPDATED (UpdateRow has occurred)

  • DB_DELETED (DeleteRow has occurred)

  • DB_NEWROW (AddRow has occurred, but not changed by SetValue)

Usage

HasRowChanged reflects row changes that are performed at the data source, which do not affect this status.

Once a row is deleted, SetValue or UpdateRow causes an error, but GetValue is still allowed.

Errors

The result contains no data (DBstsNODA)

See examples
Example: GetRowStatus method

See also
DeleteRow method
Execute method
SetValue method
UpdateRow method


GetValue method

Retrieves the value of the column referenced by column_id%, and copies the results to the variable field.

Defined in

ODBCResultSet

Syntax

variable = odbcResultSet.GetValue( column_id% [ , variable ] )

or

variable = odbcResultSet.GetValue( column_Name$ [ , variable ] )

or

Call odbcResultSet.GetValue( column_id% , variable )

or

Call odbcResultSet.GetValue( column_Name$ , variable )

Parameters

column_id%

Integer. The ID of a column. Use any numeric data type, except Currency.

column_Name$

String. The name of a column.

variable

Name of variable to be set. Providing the name as an argument allows the method to get its data type.

Return value

variable

Name of variable to be set.

Usage

Both the return value and the second parameter, if specified, are set to the column value.

The data type of the second parameter determines the data type of the returned data. If you omit this parameter, the data type is as set for this column by the FieldExpectedDataType property; for example, you can set the expected value to return a real value for an integer numeric field. If neither of the preceding are in effect, the data type is the closest to the native data type.

Declare the LotusScript variables used to store date-time values as data type Variant or Double. For date-only values, the data type can also Variant, Double, or String.

GetValue converts integers outside the range of -32768 to 32768 to the LotusScript Integer data type, or a short integer.

GetValue may terminate abruptly when retrieving data of the SQL_LONGVARCHAR data type from some databases (these fields are often known as "memo" or "rich text" fields); this is a problem with certain ODBC drivers. If possible, try again using a later version of the driver or contact your driver's vendor for assistance.

Null values require special consideration when using GetValue and SetValue. To test for a null value, use the IsValueNull method. If the argument data type is a variant, a null column value is returned as an empty value. Otherwise, the data returned by GetValue is converted to a LotusScript data type. For integers and reals, the returned value is 0; for strings, the returned value is a null (zero length) string; for date-time values, the returned value is "zero" time as defined in LotusScript. For image formats, GetValue treats the data as binary data.

Errors

Field ID is out of range (DBstsINVC)

The result contains no data (DBstsNODA)

Cannot convert data from native to expected or requested datatype (DBstsCNVR)

Events

BeforeGetValue

AfterGetValue

See examples
Example: GetValue method

See also
FieldExpectedDataType method
FieldID method
FieldName method
FieldNativeDatatype method
FieldSize method
IsValueAltered method
IsValueNull method


HasRowChanged method

Indicates if values in the current row have changed in the data source; that is, indicates if values differ from what was fetched into the result set.

Defined in

ODBCResultSet

Syntax

status = odbcResultSet.HasRowChanged

Return value

  • True indicates that values in the database changed since they were last fetched

  • False indicates that values are not altered

Usage

Result set values changed by SetValue are separate and do not affect this method; use GetRowStatus to find changes made within the program. HasRowChanged indicates changes made by other programs.

This statement can fail when the result set includes columns with Image or Rich Text data types or when rows are not identified uniquely. To avoid these failures, see Working with data retrieved from an external database.

Errors

Result set contains no data (DBstsNODA)

Cannot locate a unique row (DBstsNUNQ)

See examples
Example: HasRowChanged method

See also
UpdateRow method


IsBeginOfData method

Indicates whether the cursor position is at the beginning of the result set.

Defined in

ODBCResultSet

Syntax

flag% = odbcResultSet.IsBeginOfData

Return value

  • True indicates that the cursor is on the first record

  • False indicates that the cursor is not on the first record, or the result set has 0 rows

Usage

When IsBeginOfData returns False, it could mean that the result set is empty. If you do not know whether any rows were returned from your query, use the IsResultSetAvailable method to test whether data is available before using methods that assume data is present.

Errors

Not connected to a data source (DBstsNCON)

The result contains no data (DBstsNODA)

See examples
Example: IsBeginOfData method

See also
FirstRow method
IsResultSetAvailable method


IsEndOfData method

Indicates if the cursor position is at the end of the result set.

Defined in

ODBCResultSet

Syntax

flag% = odbcResultSet.IsEndOfData

Return value

  • True indicates that the cursor is on the last record, or the result set has 0 rows

  • False indicates that the cursor is not on the last record

Usage

When IsEndOfData returns True, it could mean that the result set is empty. If you do not know whether any rows were returned from your query, use the IsResultSetAvailable method to test whether data is available before using methods that assume data is present.

Use IsEndOfData in a loop structure when you want to step through rows to the end of the result set. Start the loop with NextRow and then process the row. The first NextRow after an Execute positions you on the first row.

Do

     result.NextRow

     'Process each row

Loop Until res.IsEndOfData

Tip You can tell that a memory shortage caused truncation of the result set when, on the last row, IsEndOfData is True but NumRows is still DB_ROWSUNKNOWN.

Errors

Rather than raise an error, this method returns True whenever there is no data, even before calling Execute or after calling Close.

See examples
Example: IsEndOfData method

See also
IsResultSetAvailable method
LastRow method


IsResultSetAvailable method

Indicates if the execution of a query yielded any data.

Defined in

ODBCResultSet

Syntax

flag% = odbcResultSet.IsResultSetAvailable

Return value

  • True indicates that the result set has been retrieved with at least one row of data

  • False indicates that no result set is available

Errors

Never executed successfully or result set closed (DBstsNOEX)

See examples
Example: IsResultSetAvailable method

See also
Execute method
NumRows method


IsValueAltered method

Indicates whether a column value was altered by SetValue.

Defined in

ODBCResultSet

Syntax

flag% = odbcResultSet.IsValueAltered( column_id% )

or

flag% = odbcResultSet.IsValueAltered( column_Name$ )

Parameters

column_id%

Integer. The ID of a column. Use any numeric data type, except Currency.

column_Name$

String. The name of a column.

Return value

  • True indicates that the value of this cell in the current row was set by SetValue

  • False indicates that the value was not set by SetValue, and is still as fetched (or as initiated in the AddRow workspace)

Usage

After becoming True, this flag remains True until an UpdateRow or DeleteRow operation. A Close operation deletes the entire result set.

Errors

Field ID is out of range (DBstsINVC)

See examples
Example: IsValueAltered method

See also
DeleteRow method
FieldInfo method
GetRowStatus method
SetValue method
UpdateRow method


IsValueNull method

Indicates whether a column value is a null data value.

Defined in

ODBCResultSet

Syntax

flag% = odbcResultSet.IsValueNull( column_id% )

or

flag% = odbcResultSet.IsValueNull(column_Name$ )

Parameters

column_id%

Integer. The ID of a column. Use any numeric data type, except Currency.

column_Name$

String. The name of a column.

Return value

  • True indicates that the value of this cell in the current row is null

  • False indicates that the value is not null

Errors

Field ID is out of range (DBstsINVC)

See examples
Example: IsValueNull method

See also
FieldInfo method
GetValue method
IsValueAltered method
SetValue method


LastRow method

Sets the current row position to the last row in the result set.

Defined in

ODBCResultSet

Syntax

status = odbcResultSet.LastRow

Return value

  • True indicates that the cursor position is at the last row

  • False indicates an error

Usage

To reach the last record, records must be retrieved from the result set. Therefore, locating the last row may take some time.

Events

BeforeLastRow

AfterLastRow

BeforeRowPositionChange

AfterRowPositionChange

See examples
Example: LastRow method

See also
CurrentRow property
FirstRow method
IsEndOfData method
LocateRow method
MaxRows property
NextRow method
NumRowsmethod
PrevRow method


LocateRow method

Identifies records that match a specified field value.

Defined in

ODBCResultSet

Syntax

status = odbcResultSet.LocateRow( column_id% or column_Name$ , value ,
[ column_id2% or column_Name2$ , value2 , [column_id3% or column_Name3$ , value3 ] ] )

Parameters

column_id%

Integer. The column ID. Use any numeric data type, except Currency.

column_Name$

String. The column name.

value

String. The field value.

Return value

status

Boolean. Returns True if matching records are found; otherwise returns False, indicating an error.

Usage

Specify the column_id% or the column_Name$, as well as the value you want to match. Specify up to three pairs of the two parameters. Specify the value argument as Null to search for a null value.

This method searches forward through the result set for a value in a column beginning at the current row. If the current row matches the search criteria, the row pointer stays positioned there. To make repeated locates or to locate the next occurrence beyond the current row, use the NextRow method before LocateRow. To start at the beginning of the result set, use the FirstRow method before LocateRow. Then if the first row matches the criteria, LocateRow finds it. In a loop, make sure NextRow is valid before testing LocateRow again; otherwise, you loop infinitely on the last valid row. If CacheLimit is set, the row position after a failed LocateRow is unpredictable.

The search is case- and accent- independent. You cannot use expressions to perform advanced conditional searches. Use GetError to examine errors. LocateRow does not match values in deleted rows.

Errors

Cannot access requested row (DBstsCARR)

End of data has been reached (DBstsEOFD)

The result contains no data (DBstsNODA)

Events

BeforeLocateRow

AfterLocateRow

BeforeRowPositionChange

AfterRowPositionChange

See examples
Example: LocateRow method

See also
CacheLimit property
CurrentRow property
FirstRow method
LastRow method
NextRow method
PrevRow method


NextRow method

Sets the current row position to the next row in a result set.

Defined in

ODBCResultSet

Syntax

status = odbcResultSet.NextRow

Return value

status

Boolean. Returns True if the next row in the result set is successfully retrieved; otherwise, returns False, indicating an error.

Usage

Use to read through a result set. An error is generated if there is no result set, or if the last record in a result set is reached. Use GetError to examine errors. To aid in looping over newly retrieved result sets, a NextRow operation that is the first row-positioning method invoked after Execute sets the row position to 1.

Do not use NextRow as a condition for a While or Until loop because when NextRow returns False because there are no more rows, an error is generated. Use IsEndOfData to test for the end of the table, and use NextRow within the loop.

In a Do loop, use IsEndOfData in the Until clause. Then, you can use NextRow at the top of the loop. When the loop is first called and no other procedures have been called, NextRow is set to 1 to cover all rows in the table.

Errors

Invalid row (DBstsINVR)

End of data has been reached (DBstsEOFD)

Events

BeforeNextRow

AfterNextRow

BeforeRowPositionChange

AfterRowPositionChange

See examples
Example: NextRow method

See also
CurrentRow property
FirstRow method
IsEndOfData method
LastRow method
LocateRow method
NumRows method
PrevRow method


NumColumns method

Number of columns in a result set.

Defined in

ODBCResultSet

Syntax

num% = odbcResultSet.NumColumns

Return value

num%

Number of columns in the result set.

Events

AfterNumColumns

BeforeNumColumns

See examples
Example: NumColumns method

See also
Execute method
FieldID method
IsResultSetAvailable method


NumParameters method

Returns the number of parameters in an SQL statement.

Defined in

ODBCResultSet

Syntax

num% = odbcResultSet.NumParameters

Return value

num%

Integer. Returns the number of parameters in the SQL statement associated with the ResultSet object or zero if there are no parameters.

Errors

No query object (DBstsNQOJ)

See examples
Example: NumParameters method

See also
GetParameter method
GetParameterName method
SetParameter method
SQL property (in ODBCQuery)


NumRows method

Number of rows in a result set.

Defined in

ODBCResultSet

Syntax

num% = odbcResultSet.NumRows

Return value

num%

Number of rows in the result set.

Usage

You can determine the number of rows only after the entire result set is fetched, not immediately after a query or while fetching records. You can immediately determine whether the result contains any rows at all; 0 is a valid value for this property.

This property is DB_NORESULT if there is no result set; DB_ROWSUNKNOWN if the number of rows is not known; DB_ROWSLIMITED if MaxRows limits the number of rows.

If a memory shortage causes truncation of the result set, IsEndOfData is True on the last row but NumRows is still DB_ROWSUNKNOWN.

Events

BeforeNumRows

AfterNumRows

See examples
Example: NumRows method

See also
CurrentRow property
IsEndOfData method
IsResultSetAvailable method
LastRow method
LocateRow method
MaxRows property
NextRow method


PrevRow method

Positions the current row pointer at the previous row.

Defined in

ODBCResultSet

Syntax

status = odbcResultSet.PrevRow

Return value

status

Boolean. Returns True if the pointer is successfully set to the previous row; otherwise, returns False, indicating an error.

Usage

The previous row is not accessible if the pointer is already at the first row; a result set is not cached; the current row is the AddRow workspace; or the cache is limited, and the previous row was flushed from the cache.

Errors

Invalid row number (DBstsINVR)

Cannot access requested row (DBstsCARR)

Events

BeforePrevRow

AfterPrevRow

BeforeRowPositionChange

AfterRowPositionChange

See examples
Example: PrevRow method

See also
CurrentRow property
FirstRow method
IsBeginOfData method
LastRow method
LocateRow method
NextRow method


SetParameter method

Sets the replacement value for the specified parameter.

Defined in

ODBCResultSet

Syntax

status = odbcResultSet.SetParameter( parameter_name$ , value$ )

or

status = odbcResultSet.SetParameter( parameter_index% , value$ )

Parameters

parameter_name$

String. The name of the parameter.

parameter_index%

Integer. The position of the parameter.

value$

String. A value for the parameter. Use Cstr with non-string LotusScript types.

Return value

  • True indicates that the parameter was successfully set

  • False indicates that the parameter name or index was not found

Usage

Parameters are set in SQL statements. Unlike ODBC and standard SQL, parameters may appear anywhere in the SQL statement. In LS:DO, a parameter reference is a name enclosed in question marks. Specify the value$ argument as Null to set the parameter as null, if appropriate in the SQL statement.

When you use a parameter surrounded by single quotes, specify the single quotes explicitly. Otherwise, SetParameter does not handle the value correctly. For example, specify the single quotes surrounding the city name as follows:

myquery.SQL = "SELECT * FROM DATA WHERE CITY = ?city? "

...

result1.SetParameter(city,"'Cambridge'")

Events

BeforeSetParameter

AfterSetParameter

See examples
Example: SetParameter method

See also
GetParameter method
GetParameterName method
NumParameters method
SQL property (in ODBCQuery)


SetValue method

Sets a new value to a column.

Defined in

ODBCResultSet

Syntax

status = odbcResultSet.SetValue( column_id% , value )

or

status = odbcResultSet.SetValue( column_Name$ , value )

Parameters

column_id%

Integer. The column ID. Use any numeric data type, except Currency.

column_Name$

String. The column name.

value

A value of a type consistent with the column.

Return value

  • True indicates that the current value in specified column is updated by value

  • False indicates that the value cannot be changed, as when the result set is read-only

Usage

The data is automatically converted to the required native data type.

The changes take effect when an UpdateRow operation occurs.

Specify the value argument as Null to set a null value of the correct type.

Errors

Read only. Data cannot be updated or deleted (DBstsRDON)

The row has previously been deleted (DBstsROWD)

Field ID is out of range (DBstsINVC)

Cannot convert data from native to expected or requested datatype (DBstsCNVR)

The result contains no data (DBstsNODA)

Events

BeforeSetValue

AfterSetValue

See examples
Example: SetValue method

See also
AddRow method
FieldExpectedDataType method
FieldID method
FieldName method
FieldSize method
GetRowStatus method
GetValue method
IsValueAltered method
ReadOnly property
UpdateRow method


UpdateRow method

Updates the current row, if changed, to the database.

Defined in

ODBCResultSet

Syntax

status = odbcResultSet.UpdateRow

Return value

  • True indicates that the row was updated successfully

  • False indicates that the row has been altered or locked by another user or process, or the database is read-only

Usage

Use ReadOnly to determine if the database is read-only, in which case it cannot be updated.

UpdateRow leaves you on the current row. If you perform an AddRow followed by an UpdateRow, you remain on the added row.

UpdateRow may fail when the result set includes columns with Image or Rich Text data types or when rows are not identified uniquely. To avoid these failures, see Working with data retrieved from an external database.

Errors

Read only. Data cannot be updated or deleted (DBstsRDON)

The row has previously been deleted (DBstsROWD)

Update or Delete cannot locate a unique row (DBstsNUNQ)

No changes in row (DBstsRUNC)

Events

BeforeUpdateRow

AfterUpdateRow

See examples
Example: UpdateRow method

See also
AddRow method
Close method
GetRowStatus method
HasRowChanged method
IsSupported method (in ODBCConnection)
ReadOnly property
SetValue method


Example: DateFmt property

This script displays the date format of data in a column as an integer.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim view As NotesView

Dim column As notesViewColumn

Set db = session.CurrentDatabase

Set view = db.Getview("Align")

Set column = view.Columns(0)

Messagebox(column.DateFmt)


File contents

The files lsxbeerr.lss, lsxuierr.lss, lsconst.lss, and lserr.lss are in the Domino directory. Their contents are shown in the following sections.

Contents of lsxbeerr.lss

Public Const lsERR_NOTES_ERROR =  4000

Public Const lsERR_SYS_OUT_OF_MEMORY =  4001

Public Const lsERR_SYS_LOAD_OUT_OF_MEM =  4002

Public Const lsERR_SYS_FILE_NOT_FOUND =  4003

Public Const lsERR_SYS_DICT_NOT_ON_PATH =  4004

Public Const lsERR_NOTES_ERROR2 =  4005

Public Const lsERR_SYS_RESOURCE_NOT_FOUND =  4008

Public Const lsERR_SYS_LOADING_RESOURCE =  4009

Public Const lsERR_SYS_LOCKING_RESOURCE =  4010

Public Const lsERR_SYS_FREEING_RESOURCE =  4011

Public Const lsERR_SYS_NOSUCH_RESOURCE =  4012

Public Const lsERR_SYS_WARNING_TITLE =  4016

Public Const lsERR_MAIL_COPEN_FAILED =  4026

Public Const lsERR_MAIL_PAOPEN_FAILED =  4027

Public Const lsERR_MAIL_LAOPEN_FAILED =  4028

Public Const lsERR_MAIL_VIM_MESSAGE =  4029

Public Const lsERR_MAIL_CANT_CREATE =  4030

Public Const lsERR_MAIL_UNKNOWN_PROP =  4031

Public Const lsERR_MAIL_INVALID_MSG =  4032

Public Const lsERR_MAIL_NOPUBLIC_GRP =  4033

Public Const lsERR_MAIL_NOPRIVATE_GRP =  4034

Public Const lsERR_MAIL_GRPCREATE_FAILED =  4035

Public Const lsERR_MAIL_GROUP_DELETED =  4036

Public Const lsERR_MAIL_NAME_REQUIRED =  4037

Public Const lsERR_NOTES_FAILURE =  4038

Public Const lsERR_NOTES_NOSUCH_VIEW =  4039

Public Const lsERR_NOTES_NOFTINDEX =  4040

Public Const lsERR_NOTES_DBCREATE_FAILED =  4041

Public Const lsERR_NOTES_DBDELETE_FAILED =  4042

Public Const lsERR_NOTES_DBOPEN_FAILED =  4043

Public Const lsERR_NOTES_INVALID_FORMULA =  4044

Public Const lsERR_NOTES_INVALID_DATE =  4045

Public Const lsERR_NOTES_COPY_FAILED =  4046

Public Const lsERR_NOTES_VIEWOPEN_FAILED =  4047

Public Const lsERR_NOTES_NOTEDEL_FAILED =  4048

Public Const lsERR_NOTES_NEXTITEM_FAILED =  4049

Public Const lsERR_NOTES_FINDITEM_FAILED =  4050

Public Const lsERR_NOTES_MODLOAD_FAILED =  4051

Public Const lsERR_NOTES_PROCFIND_FAILED =  4052

Public Const lsERR_NOTES_RTWRITE_FAILED =  4053

Public Const lsERR_NOTES_RTCONVERT_FAILED =  4054

Public Const lsERR_NOTES_FTSRCH_FAILED =  4055

Public Const lsERR_NOTES_QUERY_FAILED =  4056

Public Const lsERR_NOTES_DOCSEARCH_FAILED =  4057

Public Const lsERR_NOTES_ITEMCOPY_FAILED =  4058

Public Const lsERR_NOTES_CREATENOTE_FAILED =  4059

Public Const lsERR_NOTES_DBNOACCESS =  4060

Public Const lsERR_NOTES_UNAME_LOOKUP =  4061

Public Const lsERR_NOTES_SESOPEN_FAILED =  4062

Public Const lsERR_NOTES_DATABASE_NOTOPEN =  4063

Public Const lsERR_NOTES_SESSION_DATECONV =  4064

Public Const lsERR_NOTES_SESSION_VALNOTSUPP =  4065

Public Const lsERR_NOTES_CANT_GETNTH =  4066

Public Const lsERR_NOTES_ATTACH_FAILED =  4067

Public Const lsERR_NOTES_DETACH_FAILED =  4068

Public Const lsERR_NOTES_EXTRACT_FAILED =  4069

Public Const lsERR_NOTES_DIRSEARCH_FAILED =  4070

Public Const lsERR_NOTES_BAD_INDEX =  4071

Public Const lsERR_NOTES_NOSUCH_DIRECTORY =  4072

Public Const lsERR_CDTEXTCREATE_FAILED =  4073

Public Const lsERR_CDASSIM_FAILED =  4074

Public Const lsERR_NOT_RT_ITEM =  4075

Public Const lsERR_NOTES_FORMCOMP_FAILED =  4076

Public Const lsERR_NOTES_FORMEVAL_FAILED =  4077

Public Const lsERR_NOTES_ITEMCREATE_FAILED =  4078

Public Const lsERR_NOTES_DECRYPT_FAILED =  4079

Public Const lsERR_NOTES_NOTLOCAL_IDX =  4080

Public Const lsERR_NOTES_FTIDX_FAILED =  4081

Public Const lsERR_NOTES_NOTEOPEN_FAILED =  4082

Public Const lsERR_NOTES_RENDER_FAILED =  4083

Public Const lsERR_NOTES_FILENOTFOUND =  4084

Public Const lsERR_NOTES_UNKNOWN_TYPE =  4085

Public Const lsERR_NOTES_FILEOPEN_FAILED =  4086

Public Const lsERR_NOTES_FILEWRITE_FAILED =  4087

Public Const lsERR_NOTES_DATE_NOTSET =  4088

Public Const lsERR_NOTES_NODBNAME =  4089

Public Const lsERR_NOTES_TEMPLCOPY_FAILED =  4090

Public Const lsERR_NOTES_BAD_UNID =  4091

Public Const lsERR_NOTES_UNAME_REQ =  4092

Public Const lsERR_NOTES_GETACL_FAILED =  4093

Public Const lsERR_NOTES_ACLENTRY_FAILED =  4094

Public Const lsERR_NOTES_ACL_INVALID =  4095

Public Const lsERR_NOTES_QUERYACL_FAILED =  4096

Public Const lsERR_NOTES_REFRESH_FAILED =  4097

Public Const lsERR_NOTES_OLEPKG_FAILED =  4098

Public Const lsERR_NOTES_TMPFILE_FAILED =  4099

Public Const lsERR_NOTES_READFILE_FAILED =  4100

Public Const lsERR_NOTES_RTRENDER_FAILED =  4101

Public Const lsERR_NOTES_WRONG_CLASS =  4102

Public Const lsERR_NOTES_INVALID_ID =  4103

Public Const lsERR_NOTES_INVALID_AGENT =  4104

Public Const lsERR_LOG_DBOPEN_FAILED =  4135

Public Const lsERR_LOG_FOPEN_FAILED =  4136

Public Const lsERR_LOG_CDCREATE_FAILED =  4137

Public Const lsERR_LOG_MAILLOG_FAILED =  4138

Public Const lsERR_MEM_HVPOOLFULL =  4139

Public Const lsERR_NOTES_COPYACL_FAILED =  4150

Public Const lsERR_NOTES_DOC_NOTINVIEW =  4151

Public Const lsERR_NOTES_NOFTQUERY =  4152

Public Const lsERR_NOTES_NOITEMNAME =  4153

Public Const lsERR_NOTES_NOTEUPDATE_FAILED =  4154

Public Const lsERR_NOTES_NOTELOCATE_FAILED =  4155

Public Const lsERR_NOTES_VIEWDEL_FAILED =  4156

Public Const lsERR_LOG_CONSTRUCT_FAILED =  4157

Public Const lsERR_SEM_ALLOC_FAILED =  4158

Public Const lsERR_NOTES_LOOKUP_FAILED =  4159

Public Const lsERR_NOTES_SEND_FAILED =  4160

Public Const lsERR_NOTES_NCREATE_FAILED =  4161

Public Const lsERR_MACRO_IDTBL_FAILED =  4162

Public Const lsERR_MACRO_RUN_FAILED =  4163

Public Const lsERR_NOTES_DBOPEN_NOTLOCAL =  4164

Public Const lsERR_NOTES_SIGN_NOPERM =  4165

Public Const lsERR_NOTES_ENCRYPT_NOPERM =  4166

Public Const lsERR_NOTES_ENCRYPT_FAILED =  4167

Public Const lsERR_NOTES_NOSENDTO =  4168

Public Const lsERR_LOG_EVENTPUT_FAILED =  4169

Public Const lsERR_LOG_INVALID_EVTYPE =  4170

Public Const lsERR_LOG_INVALID_SEVERITY =  4171

Public Const lsERR_NOTES_NO_NEWSLETTERDOCS =  4172

Public Const lsERR_NOTES_MAILDBOPEN_FAILED =  4173

Public Const lsERR_NOTES_NEWSLETTER_FAILED =  4174

Public Const lsERR_NOTES_DFLT_VID_FAILED =  4175

Public Const lsERR_NOTES_KEYFIND_FAILED =  4176

Public Const lsERR_NOTES_RTTEXT_FAILED =  4177

Public Const lsERR_NOTES_RTDOCLINK_FAILED =  4178

Public Const lsERR_NOTES_NOPERM_DISKIO =  4179

Public Const lsERR_NOTES_NOPERM_SIGN =  4180

Public Const lsERR_NOTES_NOPERM_ENCRYPT =  4181

Public Const lsERR_NOTES_NOPERM_ENVIRON =  4182

Public Const lsERR_NOTES_NOPERM_ANY =  4183

Public Const lsERR_NOTES_NOSERV_DB =  4184

Public Const lsERR_NOTES_INVALID_DB =  4185

Public Const lsERR_NOTES_INVALID_CREDEL =  4186

Public Const lsERR_NOTES_INVALID_DOC =  4187

Public Const lsERR_NOTES_DBS_MUST_MATCH =  4188

Public Const lsERR_NOTES_RESPONSE_FAILED =  4189

Public Const lsERR_NOTES_NOLISTS =  4190

Public Const lsERR_NOTES_CONTAINS_FAILED =  4191

Public Const lsERR_NOTES_MUSTBE_STRING =  4192

Public Const lsERR_NOTES_DESVIEW_FAILED =  4193

Public Const lsERR_NOTES_ITEMARR_FAILED =  4194

Public Const lsERR_NOTES_SRVSEARCH_FAILED =  4195

Public Const lsERR_NOTES_UNKNOWN_SRCHTYPE =  4196

Public Const lsERR_NOTES_MUSTCALL_FIRSTDB =  4197

Public Const lsERR_NOTES_ALLDOCS_FAILED =  4198

Public Const lsERR_NOTES_ITYPENOT_TEXT =  4199

Public Const lsERR_NOTES_INVALID_ITYPE =  4200

Public Const lsERR_NOTES_NOSUCH_FOLDER =  4201

Public Const lsERR_NOTES_ADDRBOOK_FAILED =  4202

Public Const lsERR_NOTES_NOTCONTEXT_DB =  4203

Public Const lsERR_NOTES_LTDACCESS_FAILED =  4204

Public Const lsERR_NOTES_LTDUPDATE_FAILED =  4205

Public Const lsERR_NOTES_BADVIEW_VERSION =  4206

Public Const lsERR_NOTES_NEED_ADT =  4207

Public Const lsERR_NOTES_ACLWRITE_FAILED =  4208

Public Const lsERR_NOTES_RENAME_FAILED =  4209

Public Const lsERR_NOTES_NOSUCH_ROLENAME =  4210

Public Const lsERR_NOTES_PRIVNAME_FAILED =  4211

Public Const lsERR_NOTES_READPRIV_FAILED =  4212

Public Const lsERR_NOTES_DELPRIV_FAILED =  4213

Public Const lsERR_NOTES_DELENTRY_FAILED =  4214

Public Const lsERR_NOTES_NOSERV_EVENTS =  4215

Public Const lsERR_NOTES_INVALID_ACLENTRYNAME =  4216

Public Const lsERR_NOTES_ENTRYNAME_FAILED =  4217

Public Const lsERR_NOTES_NOTLOCAL_REPL =  4218

Public Const lsERR_NOTES_REPL_FAILED =  4219

Public Const lsERR_NOTES_NOTLOCAL_COMPACT =  4220

Public Const lsERR_NOTES_COMPACT_FAILED =  4221

Public Const lsERR_NOTES_TIMEADJUST_FAILED =  4222

Public Const lsERR_NOTES_NOSUCH_EMBED =  4223

Public Const lsERR_NOTES_NOSUCH_EOFILE =  4224

Public Const lsERR_NOTES_NOSUCH_PATH =  4225

Public Const lsERR_NOTES_EMBEDARR_FAILED =  4226

Public Const lsERR_NOTES_NOADDRS_FOUND =  4227

Public Const lsERR_NOTES_DUP_ROLENAME =  4228

Public Const lsERR_NOTES_CANTCREATE_FOLDER =  4229

Public Const lsERR_NOTERENDER_FAILED =  4230

Public Const lsERR_NOFROMFIELD =  4231

Public Const lsERR_TEXTLIST_FAILED =  4232

Public Const lsERR_NOTES_NOTA_DOCUMENT =  4233

Public Const lsERR_NOTES_VALIDATE_FAILED =  4234

Public Const lsERR_NOTES_ABSTRACT_BUFFER =  4235

Public Const lsERR_NOTES_ABSTRACTING_TEXT =  4236

Public Const lsERR_NOTES_DESAGENT_FAILED =  4237

Public Const lsERR_NOTES_MIXED_ARRAY =  4238

Public Const lsERR_NOTES_INVALID_DOCLINK =  4239

Public Const lsERR_TEXTLIST_BAD_INPUT =  4240

Public Const lsERR_NOTES_CANTREMOVE =  4241

Public Const lsERR_NOTES_CANTENCRYPT =  4242

Public Const lsERR_NOTES_CANTCLOSEDB =  4243

Public Const lsERR_NOTES_CANTRUN_OLEOBJ =  4244

Public Const lsERR_NOTES_CANTSHOW_OLEOBJ =  4245

Public Const lsERR_NOTES_NOEMBEDDED_OBJ =  4246

Public Const lsERR_NOTES_NOSUCH_EMBEDCLASS =  4247

Public Const lsERR_NOTES_CANTGET_DBSUMMARY =  4248

Public Const lsERR_NOTES_CANTCOPY_ITEMTYPE =  4249

Public Const lsERR_NOTES_NEED_DB =  4250

Public Const lsERR_NOTES_NEED_NOTE =  4251

Public Const lsERR_NOTES_CANT_LINK_OLE1 =  4252

Public Const lsERR_NOTES_ROLENAME_TOOBIG =  4253

Public Const lsERR_NOTES_EOARRAY_FAILED =  4254

Public Const lsERR_NOTES_ATTACHINFO_FAILED =  4255

Public Const lsERR_NOTES_QUOTAINFO_FAILED =  4256

Public Const lsERR_NOTES_DOCNOTSAVED =  4257

Public Const lsERR_NOTES_ACLNEXT_INVALID =  4258

Public Const lsERR_NOTES_NOTAFILE =  4259

Public Const lsERR_NOTES_CANTFIND_ATTACHMENT =  4260

Public Const lsERR_NOTES_NOSUCH_VERB =  4261

Public Const lsERR_NOTES_DOVERB_FAILED =  4262

Public Const lsERR_NOTES_INVALID_ADTTYPE =  4263

Public Const lsERR_NOTES_FTQUERY_FAILED =  4264

Public Const lsERR_NOTES_NOSUCH_DBID =  4265

Public Const lsERR_NOTES_OPENBYRID_FAILED =  4266

Public Const lsERR_NOTES_BAD_UNPROCFT =  4267

Public Const lsERR_AGENT_NO_RECURSION =  4268

Public Const lsERR_NOTES_CANTGET_MAILSERVER =  4269

Public Const lsERR_NOTES_BAD_NOTEID =  4270

Public Const lsERR_NOTES_DBSECURITY =  4271

Public Const lsERR_NOTES_DELETE_AGENT =  4272

Public Const lsERR_NOTES_RUN_AGENT =  4273

Public Const lsERR_NOTES_NOSUCH_DOCINDEX =  4274

Public Const lsERR_NOTES_BAD_SOURCE_CLASS =  4275

Public Const lsERR_NOTES_CANT_CHANGE_DEFACL =  4276

Public Const lsERR_NOTES_LINKNOCLASS =  4277

Public Const lsERR_NOTES_CANTDO_ARRAYOFARRAY =  4278

Public Const lsERR_NOTES_SESSION_CLOSED =  4279

Public Const lsERR_NOTES_CANTOPEN_URLDB =  4280

Public Const lsERR_NOTES_NEED_URL =  4281

Public Const lsERR_NOTES_INVALID_URL =  4282

Public Const lsERR_NOTES_INVALID_URLHEADER =  4283

Public Const lsERR_NOTES_NOSUCH_URLHEADER =  4284

Public Const lsERR_NOTES_NOUNPROC_DOCS =  4285

Public Const lsERR_NOTES_EMBED_FAILED =  4286

Public Const lsERR_NOTES_NODEL_CURRENTDB =  4287

Public Const lsERR_NOTES_INVALID_TIMEEXPR =  4288

Public Const lsERR_NOTES_RECURSIVE_RENDER =  4289

Public Const lsERR_NOTES_INVALID_ITEM =  4290

Public Const lsERR_NOTES_NOMOVETO_PRIV1STUSE =  4291

Public Const lsERR_NOTES_SAMESRV_REPLICA =  4292

Public Const lsERR_NOTES_CANT_SIGN =  4293

Public Const lsERR_NOTES_NO_MATCH =  4294

Public Const lsERR_NOTES_AMBIGUOUS_MATCH =  4295

Public Const lsERR_NOTES_DBALREADY_OPEN =  4296

Public Const lsERR_NOTES_OLE_NOTAVAIL =  4297

Public Const lsERR_NOTES_ARRAY_NOGOOD =  4298

Public Const lsERR_NOTES_REGARG_NOTGIVEN =  4299

Public Const lsERR_NOTES_MISSING_CERTID =  4300

Public Const lsERR_NOTES_NOCERT_CTX =  4301

Public Const lsERR_NOTES_REGFAILED =  4302

Public Const lsERR_NOTES_SRVREGFAILED =  4303

Public Const lsERR_NOTES_CERTREGFAILED =  4304

Public Const lsERR_NOTES_XCERTFAILED =  4305

Public Const lsERR_NOTES_RECERTFAILED =  4306

Public Const lsERR_NOTES_NOSUCH_BOOL =  4307

Public Const lsERR_NOTES_CANTSWITCH_ID =  4308

Public Const lsERR_NOTES_NOSUCH_MAILPATH =  4309

Public Const lsERR_NOTES_BAD_IDFILE =  4310

Public Const lsERR_NOTES_CANTADD_USER =  4311

Public Const lsERR_NOTES_CANTADD_SERV =  4312

Public Const lsERR_NOTES_CANTADD_CERT =  4313

Public Const lsERR_NOTES_NOCURRENT_AGENT =  4314

Public Const lsERR_NOTES_AGENTLOG_FAILED =  4315

Public Const lsERR_NOTES_NOSUCH_CERTIDTYPE =  4316

Public Const lsERR_NOTES_NOCURRENT_FTRESULT =  4317

Public Const lsERR_NOTES_IDTBL_FAILED =  4318

Public Const lsERR_NOTES_PROF_ARG_MISSING =  4319

Public Const lsERR_NOTES_NOSUCH_PROFILE =  4320

Public Const lsERR_NOTES_PROFUPDATE_FAILED =  4321

Public Const lsERR_NOTES_PROFDELETE_FAILED =  4322

Public Const lsERR_NOTES_NOSUCH_ARG =  4323

Public Const lsERR_NOTES_WRONG_UNID_LEN =  4324

Public Const lsERR_NOTES_DESFORM_FAILED =  4325

Public Const lsERR_NOTES_FORMDEL_FAILED =  4326

Public Const lsERR_NOTES_NOCLOSE_CURRDB =  4327

Public Const lsERR_NOTES_FREETIME_FAILED =  4328

Public Const lsERR_NOTES_UNIFORM_FAILED =  4329

Public Const lsERR_NOTES_GETOPTION_FAILED =  4330

Public Const lsERR_NOTES_MARKREAD_FAILED =  4331

Public Const lsERR_NOTES_MARKUNREAD_FAILED =  4332

Public Const lsERR_NOTES_MULTIDB_FAILED =  4333

Public Const lsERR_NOTES_ADDPROF_FAILED =  4334

Public Const lsERR_NOTES_ULOOKUP_FAILED =  4335

Public Const lsERR_NOTES_INVALID_OBJECT =  4336

Public Const lsERR_NOTES_STAMP_FAILED =  4337

Public Const lsERR_NOTES_BAD_ORGUNIT =  4338

Public Const lsERR_NOTES_BAD_FTSORT =  4339

Public Const lsERR_NOTES_NOTCONTEXT_COLLEC =  4340

Public Const lsERR_NOTES_ECLACCESS_FAILED =  4341

Public Const lsERR_NOTES_W32DOM_FAILED =  4342

Public Const lsERR_NOTES_W32DOM_NOFIRSTUSER =  4343

Public Const lsERR_NOTES_W32DOM_BADPLATFORM =  4344

Public Const lsERR_NOTES_W32DOM_BADNETAPI32 =  4345

Public Const lsERR_NOTES_W32DOM_DOMAIN_CONTROLLER =  4346

Public Const lsERR_NOTES_TOOMANY_SORT_KEYS =  4347

Public Const lsERR_NOTES_BAD_KEYTYPE =  4348

Public Const lsERR_NOTES_CANT_SELF_ASSIMILATE =  4349

Public Const lsERR_NOTES_CANT_SELF_COPY =  4350

Public Const lsERR_NOTES_POP3_FAILED =  4351

Public Const lsERR_NOTES_ARRCREATE_FAILED =  4352

Public Const lsERR_NOTES_AGSAVE_FAILED =  4353

Public Const lsERR_NOTES_CANTREMOVE_AGC =  4354

Public Const lsERR_NOTES_CANTENCRYPT_AGC =  4355

Public Const lsERR_NOTES_RTSTYLE_CREATEFAILED =  4356

Public Const lsERR_NOTES_RTSTYLE_APPENDFAILED =  4357

Public Const lsERR_NOTES_RTSTYLE_BADFONT =  4358

Public Const lsERR_NOTES_NO_CONTEXTDB =  4359

Public Const lsERR_NOTES_NULL_APPENDLIST =  4360

Public Const lsERR_NOTES_NOSUCH_JAVA_TYPE =  4361

Public Const lsERR_NOTES_INVALID_JARRAY =  4362

Public Const lsERR_NOTES_RTSTYLE_BADBOOL =  4363

Public Const lsERR_NOTES_RTSTYLE_BADFONTSIZE =  4364

Public Const lsERR_NOTES_RTSTYLE_BADCOLOR =  4365

Public Const lsERR_NOTES_RTSTYLE_BADEFFECT =  4366

Public Const lsERR_NOTES_NOTREMOTE_DB =  4367

Public Const lsERR_NOTES_RTITEM_EXISTS =  4368

Public Const lsERR_NOTES_NOFORM =  4369

Public Const lsERR_NOTES_NOTA_VECTOR =  4370

Public Const lsERR_NOTES_SERVER_SWITCH =  4371

Public Const lsERR_NOTES_DBDIR_THREAD =  4372

Public Const lsERR_NOTES_ACL_CONSTRUCTOR_FAILED =  4380

Public Const lsERR_NOTES_ACL_INVALID_TYPE =  4381

Public Const lsERR_NOTES_INVALID_TIMEZONE =  4383

Public Const lsERR_NOTES_VIEW_STATS =  4384

Public Const lsERR_NOTES_VIEW_ENTRY_READ =  4385

Public Const lsERR_NOTES_DBFOLDERREFS_NOT_SUPPORTED =  4386

Public Const lsERR_NOTES_DBFOLDERREFS_NOT_ENABLED =  4387

Public Const lsERR_NOTES_VE_NO_SEPARATOR =  4388

Public Const lsERR_NOTES_STRING_TOO_LONG =  4389

Public Const lsERR_NOTES_VIEW_FMT_READ =  4390

Public Const lsERR_NOTES_VIEW_INVALID_COLUMN =  4396

Public Const lsERR_NOTES_NO_COLLECTION =  4373

Public Const lsERR_NOTES_NOT_IN_SESSION =  4374

Public Const lsERR_NOTES_INVALID_NAME =  4375

Public Const lsERR_NOTES_DELETED =  4376

Public Const lsERR_NOTES_NOT_LOCAL =  4377

Public Const lsERR_NOTES_INVALID_RANGE =  4378

Public Const lsERR_NOTES_OBJECT_NOT_FOUND =  4379

Public Const lsERR_NOTES_ITEM_CONVERT =  4382

Public Const lsERR_NOTES_VIEW_BAD_ENTRY =  4391

Public Const lsERR_NOTES_VIEWNAV_BAD_MAX =  4392

Public Const lsERR_NOTES_VIEWNAV_BAD_POS =  4393

Public Const lsERR_NOTES_VIEWNAV_BAD_PARENT =  4394

Public Const lsERR_NOTES_NOT_IMPLEMENTED =  4395

Public Const lsERR_NOTES_RTPSTYLE_APPENDFAILED =  4397

Public Const lsERR_NOTES_RTPSTYLE_TOOMANYTABS =  4398

Public Const lsERR_NOTES_RTPSTYLE_OUTOFRANGE =  4399

Public Const lsERR_NOTES_RTPSTYLE_BADALIGN =  4400

Public Const lsERR_NOTES_RTPSTYLE_BADSPACING =  4401

Public Const lsERR_NOTES_RTPSTYLE_BADPAGINATE =  4402

Public Const lsERR_NOTES_ACL_MISSING =  4403

Public Const lsERR_NOTES_SESSION_MISSING =  4404

Public Const lsERR_NOTES_DATABASE_MISSING =  4405

Public Const lsERR_NOTES_DOCUMENT_MISSING =  4406

Public Const lsERR_NOTES_VIEW_MISSING =  4407

Public Const lsERR_NOTES_PARENT_MISSING =  4408

Public Const lsERR_NOTES_NOT_RICHTEXT =  4409

Public Const lsERR_NOTES_PSTYPE_MISSING =  4410

Public Const lsERR_NOTES_REMOVEALL_FAILED =  4411

Public Const lsERR_NOTES_ENTRY_NOT_FROM_COLLECTION =  4412

Public Const lsERR_NOTES_NOTE_NOT_FROM_COLLECTION =  4413

Public Const lsERR_NOTES_ADDENTRY_DUP =  4414

Public Const lsERR_NOTES_ADDENTRY_FAILED =  4415

Public Const lsERR_MACRO_SYNCH_ENABLE_FAILED =  4416

Public Const lsERR_NOTES_SYNCH_RUN_AGENT =  4417

Public Const lsERR_NOTES_SYNCH_NOOLE =  4418

Public Const lsERR_NOTES_RTPSTYLE_BADTABTYPE =  4419

Public Const lsERR_NOTES_GETALLENTRIES_FAILED =  4420

Public Const lsERR_NOTES_EXECUTESETUP_FAILED =  4421

Public Const lsERR_NOTES_MAXDBSIZE_EXCEEDED =  4422

Public Const lsERR_NOTES_INVALID_NAV =  4423

Public Const lsERR_NOTES_SVRACCESS_FAILED =  4425

Public Const lsERR_NOTES_NOT_IN_VIEW =  4426

Public Const lsERR_NOTES_NOT_IN_DB =  4427

Public Const lsERR_NOTES_PROP_NOT_AVAIL =  4428

Public Const lsERR_NOTES_NOT_IN_ACL =  4429

Public Const lsERR_NOTES_NO_LOGS_OPEN =  4430

Public Const lsERR_NOTES_CACHE_SZ_INVALID =  4431

Public Const lsERR_NOTES_VIEW_ENTRY_REMOVED =  4432

Public Const lsERR_NOTES_VIEW_ENTRY_DELETED =  4433

Public Const lsERR_NOTES_DOCUMENT_DELETED =  4434

Public Const lsERR_NOTES_SYNCH_INVALIDOP =  4435

Public Const lsERR_NOTES_CREATEOUTLINE_FAILED =  4436

Public Const lsERR_NOTES_HTML_GENFAILED =  4437

Public Const lsERR_NOTES_CREATE_DOCCOLL_FAILED =  4438

Public Const lsERR_NOTES_EXECUTESETUP_FAILED2 =  4439

Public Const lsERR_NOTES_CANTUPDATE_FOLDER =  4440

Public Const lsERR_NOTES_RTITEM_MISSING =  4441

Public Const lsERR_NOTES_NO_AUTHORIZATION =  4442

Public Const lsERR_NOTES_NAME_MISSING =  4443

Public Const lsERR_NOTES_ITEM_MISSING =  4444

Public Const lsERR_NOTES_DATERANGE_MISSING =  4445

Public Const lsERR_NOTES_VIEWENTRY_MISSING =  4446

Public Const lsERR_NOTES_VIEWENTRY_OR_DOC_MISSING =  4447

Public Const lsERR_NOTES_OUTLINE_MISSING =  4448

Public Const lsERR_NOTES_DATETIME_MISSING =  4449

Public Const lsERR_NOTES_VNAV_CAT_PARENT =  4450

Public Const lsERR_NOTES_VNAV_CAT_GOTO =  4451

Public Const lsERR_NOTES_INVALID_SIZE =  4452

Public Const lsERR_NOTES_REGSERVER_NOTSET =  4453

Public Const lsERR_NOTES_NOT_ATTACHMENT =  4454

Public Const lsERR_NOTES_URL_NOT_RESOLVED =  4455

Public Const lsERR_NOTES_INVALID_IOR =  4456

Public Const lsERR_NOTES_GETIOR_FAILED =  4457

Public Const lsERR_NOTES_INVALID_DATESPEC =  4458

Public Const lsERR_NOTES_INVALID_TIMESPEC =  4459

Public Const lsERR_NOTES_CANTSAVE_CURRENTAGENT =  4460

Public Const lsERR_NOTES_CANTDISABLE_MANUALAGENT =  4461

Public Const lsERR_NOTES_BAD_ENTRYDOC =  4462

Public Const lsERR_NOTES_UNINITIALIZED_THREAD =  4463

Public Const lsERR_NOTES_INVALIDATED_OBJECT =  4464

Public Const lsERR_NOTES_ACL_ROLE_INVALID =  4465

Public Const lsERR_NOTES_ARG_DELETED =  4466

Public Const lsERR_NOTES_ACLENTRY_MISSING =  4467

Public Const lsERR_NOTES_INVALID_DATE_NOARG =  4468

Public Const lsERR_NOTES_ADDDOC_DUP =  4469

Public Const lsERR_NOTES_BADDBSIZE =  4470

Public Const lsERR_NOTES_BAD_OUTLINE_ENTRY =  4471

Public Const lsERR_NOTES_CANTMODIFY_REMOTE_AGENT =  4472

Public Const lsERR_NOTES_CANT_ADD_CHILD_BEFORE_ENTRY =  4473

Public Const lsERR_NOTES_NULL_REF_ENTRY =  4474

Public Const lsERR_NOTES_REF_ENTRY_NOTINOUTLINE =  4475

Public Const lsERR_NOTES_OUTLINE_ADDENTRY_FAILED =  4476

Public Const lsERR_NOTES_OUTLINE_MOVEENTRY_FAILED =  4477

Public Const lsERR_NOTES_OUTLINE_REMOVEENTRY_FAILED =  4478

Public Const lsERR_NOTES_INVALID_PLACEHOLDER_PARENT =  4479

Public Const lsERR_NOTES_INVALID_REPLICATION_PRIORITY =  4480

Public Const lsERR_NOTES_OUTLINE_INVALID_PRIVATE_VIEW =  4481

Public Const lsERR_NOTES_NOT_SUPPORTED =  4482

Public Const lsERR_NOTES_NEED_HDRNAME =  4483

Public Const lsERR_NOTES_NEED_MIMEENT =  4484

Public Const lsERR_NOTES_ITEM_EXISTS =  4485

Public Const lsERR_NOTES_INVALID_USERNAME_PASSWD =  4486

Public Const lsERR_NOTES_INVALID_USERNAME =  4487

Public Const lsERR_NOTES_SERVER_ACCESS_DENIED =  4488

Public Const lsERR_NOTES_NO_SERVER =  4489

Public Const lsERR_NOTES_LOST_ACL =  4490

Public Const lsERR_NOTES_SESSION_NOT_INIT =  4491

Public Const lsERR_NOTES_SESSION_IS_INIT =  4492

Public Const lsERR_NOTES_AGENT_SESSION =  4493

Contents of lsxuierr.lss

Public Const lsERR_LSXUI_UNKNOWN_PROP =  4400

Public Const lsERR_LSXUI_INVALID_ARGS =  4401

Public Const lsERR_LSXUI_NO_WORKSPACE_WND =  4402

Public Const lsERR_LSXUI_NO_DATABASE_WND =  4403

Public Const lsERR_LSXUI_LSBE_DB_CREATE =  4404

Public Const lsERR_LSXUI_NO_DOCUMENT_WND =  4405

Public Const lsERR_LSXUI_LSBE_DOC_CREATE =  4406

Public Const lsERR_LSXUI_DOC_CMD_NOT_AVAILABLE =  4407

Public Const lsERR_LSXUI_FIELD_CMD_NOT_AVAILABLE =  4408

Public Const lsERR_LSXUI_CMD_NOT_AVAILABLE =  4409

Public Const lsERR_LSXUI_DOC_OBJ_NOT_VALID =  4410

Public Const lsERR_LSXUI_DOC_SAVE_CANCELLED =  4411

Public Const lsERR_LSXUI_NOTES_ERROR =  4412

Public Const lsERR_LSXUI_INVALID_LSX =  4413

Public Const lsERR_LSXUI_INVALID_STR_ARG =  4414

Public Const lsERR_LSXUI_INVALID_NULL_ARG =  4415

Public Const lsERR_LSXUI_NO_NOTE =  4416

Public Const lsERR_LSXUI_MODALEDIT_DIALOGUP =  4417

Public Const lsERR_LSXUI_QUERY_OPEN =  4418

Public Const lsERR_LSXUI_INVALID_OBJ_ARG =  4419

Public Const lsERR_LSXUI_INVALID_SHORT_ARG =  4420

Public Const lsERR_LSXUI3_FIELD_VALIDATION_FAILED =  4421

Contents of lsconst.lss

'------------------------

' Variant DataType Values

'------------------------

Public Const V_EMPTY = 0           ' Empty variant

Public Const V_NULL = 1            ' Variant containing Null

Public Const V_INTEGER = 2         ' Integer

Public Const V_LONG = 3            ' Long integer (4 bytes)

Public Const V_SINGLE = 4          ' Single

Public Const V_DOUBLE = 5          ' Double

Public Const V_CURRENCY = 6        ' Currency

Public Const V_DATE = 7            ' Date value

Public Const V_STRING = 8          ' String

Public Const V_DISPATCH = 9        ' OLE object

Public Const V_ERROR = 10          ' ERROR (from OLE only)

Public Const V_BOOLEAN = 11        ' BOOLEAN (from OLE only)

Public Const V_VARIANT = 12        ' VARIANT array or list

Public Const V_IUNKNOWN = 13       ' OLE unknown object

Public Const V_UNISTR = 14         ' OLE unicode string

Public Const V_CLIENTHDL = 32      ' LotusScript client adt handle

Public Const V_TYPEINST = 33       ' LotusScript TYPE instance

Public Const V_LSOBJ = 34          ' LotusScript object

Public Const V_PRODOBJ = 35        ' Product object

Public Const V_BYREF   = &h4000    ' By Reference

Public Const V_ARRAY   = &h2000    ' Array

Public Const V_LIST    = &h0800    ' List

Public Const V_DYNAMIC = &h0200    ' Dynamic (with V_ARRAY)

'------------------

' MsgBox parameters

'------------------

Public Const MB_OK = 0                 ' OK button only

Public Const MB_OKCANCEL = 1           ' OK and Cancel buttons

Public Const MB_ABORTRETRYIGNORE = 2   ' Abort, Retry, Ignore buttons

Public Const MB_YESNOCANCEL = 3        ' Yes, No, and Cancel buttons

Public Const MB_YESNO = 4              ' Yes and No buttons

Public Const MB_RETRYCANCEL = 5        ' Retry and Cancel buttons

Public Const MB_ICONSTOP = 16          ' Critical message

Public Const MB_ICONQUESTION = 32      ' Warning query

Public Const MB_ICONEXCLAMATION = 48   ' Warning message

Public Const MB_ICONINFORMATION = 64   ' Information message

Public Const MB_APPLMODAL = 0          ' Application Modal Message Box

Public Const MB_DEFBUTTON1 = 0         ' First button is default

Public Const MB_DEFBUTTON2 = 256       ' Second button is default

Public Const MB_DEFBUTTON3 = 512       ' Third button is default

Public Const MB_SYSTEMMODAL = 4096     ' System Modal

'---------------------

' MsgBox return values

'---------------------

Public Const IDOK = 1                  ' OK button pressed

Public Const IDCANCEL = 2              ' Cancel button pressed

Public Const IDABORT = 3               ' Abort button pressed

Public Const IDRETRY = 4               ' Retry button pressed

Public Const IDIGNORE = 5              ' Ignore button pressed

Public Const IDYES = 6                 ' Yes button pressed

Public Const IDNO = 7                  ' No button pressed

'--------------------------------

' SetAttr, Dir, GetAttr functions

'--------------------------------

Public Const ATTR_NORMAL = 0           ' Normal files

Public Const ATTR_READONLY = 1         ' Read-only files

Public Const ATTR_HIDDEN = 2           ' Hidden files

Public Const ATTR_SYSTEM = 4           ' System-attribute set

Public Const ATTR_VOLUME = 8           ' Volume label

Public Const ATTR_DIRECTORY = 16       ' Directory

Public Const ATTR_ARCHIVE = 32         ' Archive bit set

'------------------

' FileAttr function

'------------------

Public Const ATTR_MODE = 1         ' Return mode of file

Public Const ATTR_HANDLE = 2       ' Return OS handle for file

Public Const ATTR_INPUT = 1        ' Input mode

Public Const ATTR_OUTPUT = 2       ' Output mode

Public Const ATTR_RANDOM = 4       ' Random mode

Public Const ATTR_APPEND = 8       ' Append mode

Public Const ATTR_BINARY = 32      ' File opened for Binary mode

'-------------------

' Shell Window Style

'-------------------

Public Const SHELL_NORMAL_FOCUS = 1     ' Normal, with focus

Public Const SHELL_MIN_FOCUS = 2        ' Minimized, with focus (default)

Public Const SHELL_MAX_FOCUS = 3        ' Maximized, with focus

Public Const SHELL_NORMAL_NO_FOCUS = 4  ' Normal, no focus

Public Const SHELL_MIN_NO_FOCUS = 6     ' Minimized, no focus

'-----------------

' IMEStatus values

'-----------------

Public Const IME_NOT_INSTALLED	= 0		' value for all non-Asian countries

Public Const IME_ON = 1				' Asia

Public Const IME_OFF = 2				' Asia

Public Const IME_HIRAGANA	= 4			' Japan

Public Const IME_KATAKANA_DBCS	= 5		' Japan

Public Const IME_KATAKANA_SBCS = 6		' Japan

Public Const IME_HANGEUL = 4			' Korea

Public Const IME_HANJACONVERT = 5		' Korea

Public Const IME_ALPHA_DBCS = 7			' Asia

Public Const IME_ALPHA_SBCS = 8			' Asia

'---------------

' StrConv values

'---------------

Public Const SC_UPPERCASE = 1		' convert to uppercase

Public Const SC_LOWERCASE = 2		' convert to lowercase

Public Const SC_PROPERCASE	= 3		' convert to propercase

Public Const SC_WIDE = 4			' convert narrow to wide

Public Const SC_NARROW	= 8			' convert wide to narrow

Public Const SC_KATAKANA = 16		' convert Hiragana to Katakana

Public Const SC_HIRAGANA = 32		' convert Katakana to Hiragana

Public Const SC_NATIVEDIGIT = 256	' convert '0'-'9' to native digits

Public Const SC_ARABICDIGIT = 512	' convert native digits to '0'-'9'

'-------------------------------------

' Values for the builtin GETTHREADINFO

'-------------------------------------

%Include "lsprcval.lss"

Contents of lserr.lss

Public Const APISUCCESS                      = 0

Public Const APIErrRETRY                     = 1

Public Const APIErrYIELD                     = 2

Public Const APIErrBREAK                     = 3

Public Const APIErrSTOP                      = 4

Public Const APIErrUSER_BREAK                = 5

'    API Error Severity Codes

Public Const SevWARNING                      = 1

Public Const SevERROR                        = 2

Public Const SevFATAL                        = 3

'    Client Errors

Public Const APIErrEND                       = 10

Public Const APIErrUSER_ABORT                = 11

Public Const APIErrABORT                     = 12

Public Const APIErrRETURN                    = 13

Public Const APIErrMEMORY                    = 14

Public Const APIErrRESOURCE                  = 15

Public Const APIErrACCESS                    = 16

Public Const APIErrEXISTS                    = 17

Public Const APIErrUNAVAIL                   = 18

Public Const APIErrSYNTAX                    = 19

Public Const APIErrIOERR                     = 20

Public Const APIErrOVERRUN                   = 21

Public Const APIErrSYMREL                    = 22

Public Const APIErrINVALADT                  = 23

Public Const APIErrFILEINVAL                 = 24

Public Const APIErrFILEREV                   = 25

Public Const APIErrCLIENTIO                  = 26

Public Const APIErrOPENERROR                 = 27

Public Const APIErrMODEXISTS                 = 28

Public Const APIErrNOSYMBOL                  = 29

Public Const APIErrLINE                      = 30

Public Const APIErrMODINUSE                  = 31

Public Const APIErrAPIBADARG                 = 32

Public Const APIErrCURSOREND                 = 33

Public Const APIErrCURSORBAD                 = 34

Public Const APIErrCURSOROBJNOTSET           = 35

Public Const APIErrCURSORARRAYNOTDIMED       = 36

Public Const APIErrRUN_BADARG                = 37

Public Const APIErrRUN_ARGCNT                = 38

Public Const APIErrRUN_PARAMTYPE             = 39

Public Const APIErrREG_First                 = 40

Public Const APIErrREG_INVALIDPARENT         = 41

Public Const APIErrREG_FORWARDCLASS          = 42

Public Const APIErrREG_INVALIDCOLLECTION     = 43

Public Const APIErrREG_INVALIDNAME           = 44

Public Const APIErrREG_BADATTRIB             = 45

Public Const APIErrREG_CONTROLPROC           = 46

Public Const APIErrREG_RET_INVALID           = 47

Public Const APIErrREG_ARG_INVALID           = 48

Public Const APIErrREG_ARG_INVALIDFIXED      = 49

Public Const APIErrREG_ARG_INVALIDSTRING     = 50

Public Const APIErrREG_ARG_INVALIDFORWARD    = 51

Public Const APIErrREG_ARG_INVALIDCLASS      = 52

Public Const APIErrREG_ARG_INVALIDOPTIONAL   = 53

Public Const APIErrREG_ARG_INVALIDBYVALCONT  = 54

Public Const APIErrREG_ARG_INVALIDVOID       = 55

Public Const APIErrREG_Last                  = 56

Public Const APIErrENUM_DONE                 = 57

Public Const APIErrDROPPED                   = 58

Public Const APIErrNOQUEUE                   = 59

Public Const APIErrADT_VERSION               = 60

Public Const APIErrREG2_First                = 61

Public Const APIErrREG_ARG_COUNT             = 62

Public Const APIErrREG_Reserved1             = 63

Public Const APIErrREG_Reserved2             = 64

Public Const APIErrREG_Reserved3             = 65

Public Const APIErrREG_Reserved4             = 66

Public Const APIErrREG_Reserved5             = 67

Public Const APIErrREG_Reserved6             = 68

Public Const APIErrREG_Reserved7             = 69

Public Const APIErrREG_Reserved8             = 70

Public Const APIErrREG_Reserved9             = 71

Public Const APIErrREG2_Last                 = 72

Public Const APIErrLSOINCOMPAT               = 73

Public Const APIErrNOTUNLOCKED               = 74

Public Const APIErrFILEINVALV3               = 75

Public Const APIErrCRCMISMATCH               = 76

Public Const APIErrLAST                      = 76

'    Run Time LOI Errors

Public Const ErrLoiFIRST                     = 13000

Public Const ErrLoiArgOutofRange             = 13001

Public Const ErrLoiBadPropertyName           = 13002

Public Const ErrLoiBadMethodName             = 13003

Public Const ErrLoiInvalidObject             = 13004

Public Const ErrLoiTypeMismatch              = 13005

Public Const ErrLoiInvalidArgument           = 13006

Public Const ErrLoiPrintFailed               = 13007

Public Const ErrLoiCouldNotLaunch            = 13008

Public Const ErrLoiBadCoordinates            = 13009

Public Const ErrLoiFileNotCreated            = 13010

Public Const ErrLoiCouldNotSave              = 13011

Public Const ErrLoiBadExecutable             = 13012

Public Const ErrLoiClipboardEmpty            = 13013

Public Const ErrLoiDocumentReadOnly          = 13014

Public Const ErrLoiBadClipboardFormat        = 13015

Public Const ErrLoiInvocationError           = 13017

Public Const ErrLoiUnknownUnit               = 13018

Public Const ErrLoiInvalidPropertyValue      = 13019

Public Const ErrLoiLAST                      = 13019

'    Run Time Errors

Public Const ErrUSER                      = 1

Public Const ErrReturnWithoutGoSub        = 3

Public Const ErrIllegalFunctionCall       = 5

Public Const ErrOverflow                  = 6

Public Const ErrOutOfMemory               = 7

Public Const ErrSubscriptOutOfRange       = 9

Public Const ErrDivisionByZero            = 11

Public Const ErrTypeMismatch              = 13

Public Const ErrOutOfStringSpace          = 14

Public Const ErrCantContinue              = 17

Public Const ErrNoResume                  = 19

Public Const ErrResumeWithoutError        = 20

Public Const ErrOutOfStackSpace           = 28

Public Const ErrSubOrFunctionNotDefined   = 35

Public Const ErrErrorInLoadingDLL         = 48

Public Const ErrBadDLLCallingConvention   = 49

Public Const ErrInternalError             = 51

Public Const ErrBadFileNameOrNumber       = 52

Public Const ErrFileNotFound              = 53

Public Const ErrBadFileMode               = 54

Public Const ErrFileAlreadyOpen           = 55

Public Const ErrDeviceIOError             = 57

Public Const ErrFileAlreadyExists         = 58

Public Const ErrBadRecordLength           = 59

Public Const ErrDiskFull                  = 61

Public Const ErrInputPastEndOfFile        = 62

Public Const ErrBadRecordNumber           = 63

Public Const ErrBadFileName               = 64

Public Const ErrTooManyFiles              = 67

Public Const ErrDeviceUnavailable         = 68

Public Const ErrPermissionDenied          = 70

Public Const ErrDiskNotReady              = 71

Public Const ErrCantRenameWithDifferent   = 74

Public Const ErrPathFileAccessError       = 75

Public Const ErrPathNotFound              = 76

Public Const ErrObjectVariableNotSet      = 91

Public Const ErrForLoopNotInitialized     = 92

Public Const ErrInvalidPatternString      = 93

Public Const ErrInvalidUseOfNull          = 94

Public Const ErrCannotDestroyActiveInst   = 95

Public Const ErrFileNotWritable           = 96

Public Const ErrFileNotReadable           = 97

Public Const ErrBadFileNumber             = 98

Public Const ErrFileNotOpen               = 99

Public Const ErrConflictingFileModes      = 100

Public Const ErrOpenFailed                = 101

Public Const ErrIllegalOperation          = 102

Public Const ErrDataTooBig                = 103

Public Const ErrBadAttribute              = 104

Public Const ErrCouldNotSetAttribute      = 105

Public Const ErrListItemDoesNotExist      = 120

Public Const ErrLinkNoModule              = 150

Public Const ErrLinkNoSymbol              = 151

Public Const ErrLinkBadSymbol             = 152

Public Const ErrModule_Exist              = 153

Public Const ErrModule_Not_Exist          = 154

Public Const ErrModule_Bad                = 155

Public Const ErrCompile                   = 156

Public Const ErrAdtCtrlFuncNotPresent     = 158

Public Const ErrAdtNamedObjectNonExist    = 159

Public Const ErrAdtUnknownClass           = 160

Public Const ErrAdtHandleChanged          = 161

Public Const ErrCCallBadArg               = 162

Public Const ErrCCallUnsupportedArgType   = 163

Public Const ErrCCallUnsupportedRetType   = 164

Public Const ErrCCallSubUnavail           = 165

Public Const ErrEventNotHooked            = 166

Public Const ErrModuleInUse               = 167

Public Const ErrModuleOverRun             = 168

Public Const ErrNotAListTag               = 169

Public Const ErrRedimFixedArray           = 170

Public Const ErrArraySizeTooBig           = 171

Public Const ErrIllegalLikePattern        = 172

Public Const ErrArgOutOfRange             = 173

Public Const ErrCircularUse               = 174

Public Const ErrDuplicatePublic           = 175

Public Const ErrExprRange                 = 176

Public Const ErrInvalidPowerOprand        = 177

Public Const ErrLinkNoUseModule           = 178

'    Last Of V2 Error Messages ; V3 Error Mesages Start

Public Const ErrUnderflow                 = 179

Public Const ErrNoPlatSupport             = 180

Public Const ErrSuffixTypeMismatch        = 181

Public Const ErrNamedMemberNonExist       = 182

Public Const ErrNotAnObject               = 183

Public Const ErrNotAContainer             = 184

Public Const ErrWrongNumberOfArgs         = 185

Public Const ErrNotAMethod                = 186

Public Const ErrIllegalUseOfSub           = 187

Public Const ErrIllegalUseOfFunction      = 188

Public Const ErrIllegalUseOfProp          = 189

Public Const ErrReadOnlyProp              = 190

Public Const ErrInvalidListIndex          = 191

Public Const ErrInvalidIsElemArg          = 192

Public Const ErrIllegalDelete             = 193

Public Const ErrNotAProductObject         = 194

Public Const ErrNamedEventNonExist        = 195

Public Const ErrEventHandlerArgType       = 196

Public Const ErrEventHandlerArgCnt        = 197

Public Const ErrNotaPublicMember          = 198

Public Const ErrMissingArgument           = 199

Public Const ErrUninitDynArray            = 200

Public Const ErrDisallowed                = 201

Public Const ErrNeedSetAssign             = 202

Public Const ErrCollectItemError          = 203

Public Const ErrCollectionIndex           = 204

Public Const ErrNotACollection            = 205

Public Const ErrCollectionItemNotFound    = 206

Public Const ErrOLEError                  = 207

Public Const ErrOLECantCreate             = 208

Public Const ErrOLEFileName               = 209

Public Const ErrOLEMemberNotFound         = 210

Public Const ErrOLEArgumentCount          = 211

Public Const ErrOLEArgumentType           = 212

Public Const ErrOLEException              = 213

Public Const ErrForallSource              = 214

Public Const ErrOutOfSysStack             = 215

Public Const ErrIllegalRedim              = 216

Public Const ErrAdtCreateError            = 217

Public Const ErrAdtPropertyError          = 218

Public Const ErrAdtMethodError            = 219

Public Const ErrAdtError                  = 220

Public Const ErrEvaluateError             = 221

Public Const ErrEventHandlerRetType       = 222

Public Const ErrEventHandlerProcType      = 223

Public Const ErrWrongNumberOfArgsProp     = 224

Public Const ErrIllegalUseOfMember        = 225

Public Const ErrPropSetNotDefined         = 226

Public Const ErrPropGetNotDefined         = 227

Public Const ErrStringTooLarge            = 228

Public Const ErrReadOnlyVariable          = 229

Public Const ErrUnknownClassId            = 230

Public Const ErrCollectItemAssign         = 231

Public Const ErrWrongNumDims              = 232

Public Const ErrNoVersionSupport          = 233

'	234 unused

Public Const ErrUnknownLock               = 235

Public Const ErrDeadlock                  = 236

Public Const ErrLockNotOwned              = 237

Public Const ErrSemCountMaxReached        = 238

'	239-248 unused

'	LSCube Error Mesages Start

Public Const ErrServerObjectNonExist      = 249

Public Const ErrLAST                      = 249


Example: Document property

This script gets the document associated with the Cars view entry in the By Category view and puts it in the Machines folder.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim view As NotesView

Dim entry As NotesViewEntry

Dim doc As NotesDocument

Set db = session.CurrentDatabase

Set view = db.GetView("By Category")

Set entry = view.GetEntryByKey("Cars")

Set doc = entry.Document

Call doc.PutInFolder("Machines")


Example: Accessing a NotesDocument object through a view

This example displays the user name associated with the first document in the Users view.

Sub Click(Source As Button)

     Dim db As New NotesDatabase ("", "lnab.nsf")

     Dim view As NotesView

     Dim doc As NotesDocument

     Dim fname As Variant

     Set view = db.GetView("users")

     Set doc = view.GetFirstDocument

     While Not (doc Is Nothing)

          If doc.HasItem("FullName") Then

               fname = doc.GetItemValue("FullName")

               Messagebox(fname(0))

          End If

     Wend

End Sub

See also
Accessing a NotesDocument object through a view


Examples: Accessing an entry by position

This example returns the second response to the first entry in a view navigator and mails the document associated with it to Bonnie Chen.

Sub Initialize

     Dim session As New NotesSession

     Dim db As NotesDatabase

     Dim view As NotesView

     Dim nav As NotesViewNavigator

     Dim entry As NotesViewEntry

     Dim doc As NotesDocument

     Set db = session.CurrentDatabase

     Set view = db.GetView("By Category")

     Set nav = view.CreateViewNavFromCategory("Sale items")

     Set entry = nav.GetPos(1.2, ".")

     Set doc = entry.Document

     Call doc.Send(False, "Bonnie Chen")

End Sub


Example: Accessing NotesViewEntry properties

  1. This example will display several NotesViewEntry properties.

Sub Initialize

     Dim session As New NotesSession

     Dim db As NotesDatabase

     Dim view As NotesView

     Dim entry As NotesViewEntry

     Dim pv As NotesView

     Dim doc As NotesDocument

     Set db = session.CurrentDatabase

     Set view = db.GetView("By Category")

     Set entry = view.GetEntryByKey("Cars")

     Set pv = entry.parent

     Set doc = entry.Document

     Messagebox "Children: " & entry.ChildCount & Chr(10) _

     & "Descendants: " & entry.DescendantCount & Chr(10) _

     & "FTSearch score: " & entry.FTSearchScore & Chr(10) _

     & "Indent level: " & entry.IndentLevel & Chr(10) _

     & "Note ID: " & entry.NoteID & Chr(10) _

     & "Parent view UNID: " & pv.UniversalID & Chr(10) _

     & "Siblings: " & entry.SiblingCount & Chr(10) _

     & "Universal ID: " & entry.UniversalID

     If entry.IsCategory Then

          Messagebox "This view entry is a category."

     Else

          Messagebox "This view entry is not a category."

     End If

     If entry.IsConflict Then

          Messagebox "This view entry is a conflict document."

     Else

          Messagebox "Not a conflict document."

     End If

     If entry.IsDocument Then

          Messagebox "This view entry is a document."

     Else

          Messagebox "This view entry is not a document."

     End If

     If entry.IsTotal Then

          Messagebox "This view entry is a total."

     Else

          Messagebox "This view entry is not a total."

     End If

     If entry.IsValid Then

          Messagebox "This view entry is valid."

     Else

          Messagebox "This view entry is not valid."

     End If

End Sub
  1. The following script is an agent that scans the current database for conflict entries and sends a mail message if any exist.

    2. Dim session As New NotesSession

    Dim db As NotesDatabase

    Dim view As NotesView

    Dim doc As NotesDocument

    Dim entry As NotesViewEntry

    Set db = session.CurrentDatabase

    Dim Vec As  notesViewEntryCollection

    j=1

    conflictCount = 0

    Set view = db.GetView( "($All)" )

    Set vec = view.AllEntries

    Set entry = vec.GetNthEntry( j )

    Set doc = entry.Document

    If session.isonserver = True Then

       serverName = db.server

    Else

       serverName = "local"

    End If

    While Not (doc Is Nothing)

       If entry.isconflict = True Then

          conflictCount = conflictCount + 1

       End If

       j=j+1

       Set entry = vec.GetNthEntry( j )

       If entry Is Nothing Then

          If conflictCount > 0 Then

             temp = "Count Rep Conflicts Agent detected " _

             & conflictCount & " conflicts in database " _

             & db.title & " on "  & serverName

             Set doc = New NotesDocument( db )

             doc.Subject = "Replication conflict alert message"

             doc.Body = temp

             Call doc.Send( False, "John Smith" )

          End If

          Exit Sub

        End If

        Set doc = entry.Document

    Wend


Examples: Accessing rich-text paragraph style properties

  1. This example creates a rich-text item and displays its rich-text paragraph properties.

    2. Sub Initialize

         Dim session As New NotesSession

         Dim db As NotesDatabase

         Set db = session.Currentdatabase

         Dim doc As New NotesDocument(db)

         Call doc.AppendItemValue("From", session.Username)

         Call doc.AppendItemValue("Subject", _

         "Meeting agenda")

         Dim rtpStyle As NotesrichTextParagraphStyle

         Set rtpStyle = session.CreateRichTextParagraphStyle

         Dim richText As New NotesRichTextItem(doc, "Body")

         Call richText.AppendText("Where are we now?")

         Messagebox _

         "Alignment: " & rtpStyle.Alignment & Chr(10) _

         & "FirstLineLeftMargin: " & _

            rtpStyle.FirstLineLeftMargin & Chr(10) _

         & "Inter-line Spacing: " & _

            rtpStyle.InterLineSpacing & Chr(10) _

         & "Left Margin: " & rtpStyle.LeftMargin & Chr(10) _

         & "Right Margin: " & rtpStyle.RightMargin & Chr(10) _

         & "Spacing Above: " & _

            rtpStyle.SpacingAbove & Chr(10) _

         & "Spacing Below: " & _

            rtpStyle.SpacingBelow & Chr(10) _

         & "Tabs: " & rtpStyle.Tabs)

         Call doc.Save(True, False)

    End Sub
  2. This example sets the rich-text alignment property of a rich-text paragraph style object.

    3. Sub Initialize

         Dim session As New NotesSession

         Dim db As NotesDatabase

         Set db = session.Currentdatabase

         Dim doc As New NotesDocument(db)

         Call doc.AppendItemValue("From", session.Username)

         Call doc.AppendItemValue("subject", _

         "Meeting agenda")

         Dim rtpStyle As NotesRichTextParagraphStyle

         Set rtpStyle = session.CreateRichTextParagraphStyle

         Dim richText As New NotesRichTextItem(doc, "Body")

         rtpStyle.Alignment = ALIGN_CENTER

         Call richText.AppendParagraphStyle(rtpStyle)

         Call richText.AppendText("Q1 Report")

         Call doc.Save(True, False)

    End Sub
  3. This example sets the amount of space above and below a rich-text paragraph style object.

    4. Sub Initialize

         Dim session As New NotesSession

         Dim db As NotesDatabase

         Set db = session.Currentdatabase

         Dim doc As New NotesDocument(db)

         Call doc.AppendItemValue("From", session.Username)

         Call doc.AppendItemValue("subject", _

         "Meeting agenda")

         Dim rtpStyle As NotesrichTextParagraphStyle

         Set rtpStyle = session.CreateRichTextParagraphStyle

         Dim richText As New NotesRichTextItem(doc, "Body")

         rtpStyle.SpacingAbove = SPACING_DOUBLE

         rtpStyle.SpacingBelow = SPACING_ONE_POINT_50

         Call richText.AppendParagraphStyle(rtpStyle)

         Call richText.AppendText("Q1 Report: State of the company")

         Call doc.Save(True, False)

    End Sub

See also
Accessing rich-text paragraph style properties


Example: AddDocument method

This example adds a document from collectionA to collectionB, then puts collectionB into a folder called "Business documents."

Dim session As New NotesSession

Dim db As NotesDatabase

Dim collectionA As NotesDocumentCollection

Dim collectionB As NotesDocumentCollection

Dim doc As NotesDocument

Set db = session.CurrentDatabase

Set collectionA = db.FTSearch("Annual reports", 10)

Set collectionB = db.FTSearch("Business reports",10)

Set doc = collectionA.GetLastDocument

Call collectionB.AddDocument(doc)

Call collectionB.PutAllInFolder("Business documents")


Example: Adding a document

This example adds a document to the specified document collection.

Sub Initialize

     Dim session As New NotesSession

     Dim db As NotesDatabase

     Dim collection As NotesDocumentCollection

     Dim doc As NotesDocument

     Set db = session.CurrentDatabase

     Set collection = db.FTSearch("white wine", 0)

     Set doc = collection.GetFirstDocument()

     Call collection.AddDocument(doc)

End Sub

See also
Adding a document


Example: CreateEntryFrom method

This example creates a copy of the first entry in the Products outline and adds it to the outline after the second entry.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim outline As NotesOutline

Dim entryA As NotesOutlineEntry

Dim entryB As NotesOutlineEntry

Dim entryC As NotesOutlineEntry

Set db = session.CurrentDatabase

Set outline = db.GetOutline("Products")

Set entryA = outline.GetFirst()

Set entryB = outline.GetNext(entryA)

Set entryC = outline.CreateEntryFrom(entryA,entryB,1)

Call outline.save()


Examples: Creating view navigators

  1. This example creates a view navigator and displays the MaxLevel property.

    2. Sub Intialize

         Dim session As New NotesSession

         Dim db As NotesDatabase

         Dim view As NotesView

         Dim nav As NotesViewNavigator

         Set db = session.CurrentDatabase

         Set view = db.GetView("By Category")

         Set nav = view.CreateViewNav()

         Messagebox nav.MaxLevel

    End Sub
  2. This example creates a view navigator for all entries under a specified category and then retrieves the first entry.

    3. Sub Intialize

         Dim session As New NotesSession

         Dim db As NotesDatabase

         Dim view As NotesView

         Dim nav As NotesViewNavigator

         Set db = session.CurrentDatabase

         Set view = db.GetView("By Category")

         Set nav = view.CreateViewNavFromCategory("Employees")

         Call nav.GetFirst

    End Sub
  3. This example creates a view navigator for the immediate children of the specified view entry.

    4. Sub Intialize

         Dim session As New NotesSession

         Dim db As NotesDatabase

         Dim view As NotesView

         Dim entry As NotesViewEntry

         Dim nav As NotesViewNavigator

         Dim doc As NotesDocument

         Set db = session.CurrentDatabase

         Set view = db.GetView("By Category")

         Set entry = view.GetEntryByKey("Employees")

         Set doc = entry.Document

         Set nav = view.CreateViewNavFromChildren(doc)

    End Sub


Example: Database property

This example creates an outline called Products and adds an entry to it called "First Entry." The link property of the entry is then set to a database link to Test.nsf. The name of the database the entry is linked to in printed in the status bar.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim db2 As New NotesDatabase("","Test.nsf")

Dim outline As NotesOutline

Dim entry As NotesOutlineEntry

Set db = session.CurrentDatabase

Set outline = db.CreateOutline("Products")

Call outline.createEntry("First Entry")

Set entryA = outline.getFirst()

Call entryA.SetNoteLink(db2)

Call outline.save()


Example: DeleteDocument method

This example deletes the first document in the collection and puts the remaining documents in a folder called "My Favorites."

Dim session As New NotesSession

Dim db As NotesDatabase

Dim collection As NotesDocumentCollection

Dim doc As NotesDocument

Set db = session.CurrentDatabase

Set collection = db.FTSearch("Business reports", 10)

Set doc = collection.GetFirstDocument

Call collection.DeleteDocument(doc)

Call collection.PutAllinFolder("My Favorites")


Example: Deleting a document

This example deletes a document from a collection.

Sub Initialize

     Dim session As New NotesSession

     Dim db As NotesDatabase

     Dim collection As NotesDocumentCollection

     Dim doc As NotesDocument

     Dim nid As String

     Set db = session.CurrentDatabase

     Set collection = db.FTSearch("white wine", 0)

     Set doc = collection.GetFirstDocument()

     Call collection.DeleteDocument(doc)

End Sub

See also
Deleting a document


Example: GetChild method

This example retrieves the child of the first entry in the products outline and sets the value of its URL property to http://www.acme.com.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim outline As NotesOutline

Dim entryA As NotesOutlineEntry

Dim entryB As NotesOutlineEntry

Set db = session.CurrentDatabase

Set outline = db.GetOutline("products")

Set entryA = outline.GetFirst()

Set entryB = outline.GetChild(entryA)

Call entryB.SetURL("http://www.acme.com")

Call outline.save()


Example: Retrieving an entry from a view

This example retrieves an entry from a view by key and displays its universal ID.

Sub Initialize

     Dim session As New NotesSession

     Dim db As NotesDatabase

     Dim view As NotesView

     Dim entry As NotesViewEntry

     Set db = session.CurrentDatabase

     Set view = db.GetView("By Category")

     Set entry = view.Getentrybykey("Cars")

     Messagebox entry.Universalid

End Sub


Example: MoveEntry method

This example move the last entry of the Products outline after the first entry as a child.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim outline As NotesOutline

Dim entryA As NotesOutlineEntry

Dim entryB As NotesOutlineEntry

Set db = session.CurrentDatabase

Set outline = db.getOutline("Products")

Set entryA = outline.GetLast()

Set entryB = outline.GetFirst()

Call outline.MoveEntry(entryA,entryB,1,1)

Call outline.save()


Example: SelectDocument method

This example selects the first document in a collection and moves the pointer to that document.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim workspace As New NotesUIWorkspace

Dim collection As NotesDocumentCollection

Dim doc As NotesDocument

Dim uiview As NotesUIView

Set db = session.CurrentDatabase

Set uiview = workspace.Currentview

Set collection = db.AllDocuments

Set doc = collection.GetFirstDocument

Call uiview.SelectDocument(doc)

See also
SelectDocument method


Example: RemoveEntry method

This example removes the first entry and its children from the Products outline.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim outline As NotesOutline

Dim entry As NotesOutlineEntry

Set db = session.CurrentDatabase

Set outline = db.GetOutline("Products")

Set entry = outline.GetFirst()

Call outline.RemoveEntry(entry)

Call outline.save()

See also
RemoveEntry method


Example: Resetting the replication properties of a database

This example first changes, then resets the replication properties of a database after it replicates.

Sub Initialize

     Dim sesion As New NotesSession

     Dim db As NotesDatabase

     Dim rep As NotesReplication

     Set db = session.CurrentDatabase

     Set rep = db.ReplicationInfo

     If rep.IgnoreDestDeletes = True Then

          rep.IgnoreDestDeletes = False

     End If

     Call db.Replicate("Alaska")

     Call rep.Reset()

     Call rep.Save()

End Sub


Examples: Retrieving entries from a view entry collection

  1. This example finds an entry in the collection and places it in a folder.

    2. Sub Initialize

         Dim session As New NotesSession

         Dim db As NotesDatabase

         Dim view As NotesView

         Dim entryOne As NotesViewEntry

         Dim entryTwo As NotesViewEntry

         Dim vc As NotesViewEntryCollection

         Dim doc As NotesDocument

         Set db = session.CurrentDatabase

         Set view = db.GetView("By Category")

         Set vc = view.GetAllEntriesByKey("Books")

         Set entryOne = vc.GetNthEntry(2)

         Set entryTwo = vc.GetEntry(entryOne)

         Set doc = entryTwo.Document

         Call doc.PutInFolder("Shopping Cart")

    End Sub
  2. This example finds the first and last entries in a collection.

    3. Sub Initialize

         Dim session As New NotesSession

         Dim db As NotesDatabase

         Dim view As NotesView

         Dim entry As NotesViewEntry

         Dim entry2 As NotesViewEntry

         Dim vc As NotesViewEntryCollection

         Dim doc As NotesDocument

         Dim doc2 As NotesDocument

         Set db = session.CurrentDatabase

         Set view = db.GetView("By Category")

         Set vc = view.GetAllEntriesByKey("Products")

         Set entry = vc.GetFirstEntry()

         Set entry2 = vc.GetLastEntry()

         Set doc = entry.Document

         Set doc2 = entry2.Document

         Call doc.PutInFolder("First entries")

         Call doc2.PutInfolder("First entries")

    End Sub
  3. This example collects all of the entries in a view with the GetAllEntriesByKey method of NotesView, and taverses the collection by using the GetFirstEntry and GetNextEntry methods of NotesViewEntryCollection. Alternatively you can use the GetLastEntry and GetPrevEntry methods to taverse the collection backwards.

    4. Sub Initialize

         Dim session As New NotesSession

         Dim db As NotesDatabase

         Dim view As NotesView

         Dim entry As NotesViewEntry

         Dim vc As NotesViewEntryCollection

         Dim doc As NotesDocument

         Set db = session.CurrentDatabase

         Set view = db.GetView("By Category")

         Set vc = view.GetAllEntriesByKey("Products")

         Set entry = vc.GetFirstEntry()

         While Not(Entry Is Nothing)

              Set entry = vc.GetNextEntry(entry)

         Wend

    End Sub


Example: Saving database replication properties

This example changes a replication property and then saves the change.

Sub Initialize

     Dim session As New NotesSession

     Dim db As NotesDatabase

     Dim rep As NotesReplication

     Set db = session.CurrentDatabase

     Set rep = db.ReplicationInfo

     If rep.Abstract <> True Then

          rep.Abstract = True

     End If

     Call rep.Save()

End Sub


Example: Searching for entries in a view entry collection

This example searches for up to 10 user-defined view entries and places them in a folder.

Sub Initialize

     Dim session As New NotesSession

     Dim db As NotesDatabase

     Dim view As NotesView

     Dim vc As notesViewEntryCollection

     Dim entry As NotesViewEntry

     Dim doc As NotesDocument

     Set db = session.CurrentDatabase

     Set view = db.GetView("By Category")

     Set vc = View.GetAllEntriesByKey("Schools")

     Set entry = view.GetEntryByKey("Schools")

     Set doc = entry.Document

     Call vc.FTSearch(Inputbox$("Entry name?"), 10)

     Call vc.PutAllInFolder("Education")

End Sub


Example: ViewAlias property

This example displays the alias of the current view.

Dim workspace As New NotesUIWorkspace

Dim uiview As NotesUIView

Set uiview = workspace.Currentview

Messagebox uiview.ViewAlias


Example: Abstract property

This script allows large documents to be replicated in their entirety.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim rep As NotesReplication

Set db = session.CurrentDatabase

Set rep = db.ReplicationInfo

  If rep.Abstract = True Then

    rep.Abstract = False

  End If

Call rep.Save()


Example: Accessing a view entry collection

This example displays the properties of a view entry collection.

Sub Initialize

     Dim session As New NotesSession

     Dim db As NotesDatabase

     Dim view As NotesView

     Dim entry As NotesViewEntry

     Dim vc As NotesViewEntryCollection

     Dim parentV As NotesView

     Dim doc As NotesDocument

     Set db = session.CurrentDatabase

     Set view = db.GetView("By Category")

     Set entry = view.GetEntryByKey("Cars")

     Set vc = view.GetAllEntriesByKey("Cars")

     Set parentV = vc.Parent

     Set doc = entry.Document

     Call vc.FTSearch("Supra", 10)

     Messagebox "Count: " & vc.Count & Chr(10) _

     & "Parent view: " & parentV.Name & Chr(10) _

     & "Query: " & vc.query

End Sub


Example: Accessing a document

This example retrieves a document from a URL.

Sub Initialize

     Dim session As New NotesSession

     Dim db As NotesDatabase

     Dim doc As NotesDocument

     Set db = session.CurrentDatabase

     Set doc = db.GetDocumentByURL _

    ("http://www.xyz.net/profiles.nsf/f84c48e2e59

    4b4338525665e0056fba4/0f3e22f4ea8746068525666

    e005adde0?OpenDocument")

End Sub


Examples: Accessing a form

  1. This example displays the properties of a form.

    2. Sub Initialize

         Dim session As New NotesSession

         Dim db As NotesDatabase

         Dim form As NotesForm

         Set db = session.CurrentDatabase

         Set form = db.GetForm(Inputbox("Name of form?"))

         Messagebox "Name: " & form.Name

         If Not Isempty(form.Aliases) Then

              Forall aliaz In form.Aliases

                   Messagebox "Alias: " & aliaz

              End Forall

         End If

         If form.IsSubForm Then Messagebox "Is a subform"

         If form.ProtectReaders Then

              Messagebox "Readers are protected"

         Else

              Messagebox "Readers are not protected"

         End If

         If Isempty(form.Readers) Then

              Messagebox "No readers"

         Else

              Forall reader In form.Readers

                   Messagebox "Reader: " & reader

              End Forall

         End If

         If Isempty(form.FormUsers) Then

              Messagebox "No form users"

         Else

              Forall formuser In form.FormUsers

                   Messagebox "Form user: " & formuser

              End Forall

         End If

         Forall field In form.Fields

              Messagebox "Field: " & field

         End Forall

    End Sub
  2. This example checks for the existence of a form by comparing a specified name with the names of the forms in the current database.

    3. Sub Initialize

         Dim session As New NotesSession

         Dim db As NotesDatabase

         Set db = session.CurrentDatabase

         formNameIn = Lcase(Inputbox("Name of form?"))

         Forall form In db.Forms

              If Lcase(form.Name) = formNameIn Then

                   Messagebox _

                   "The form """ & formNameIn & """ exists"

                   Exit Sub

              End If

         End Forall

         Messagebox _

         "The form """ & formNameIn & """ does not exist"

    End Sub


Examples: Accessing an outline

  1. This example displays the properties of an outline.

    2. Sub Initialize

         Dim session As New NotesSession

         Dim db As NotesDatabase

         Dim outline As NotesOutline

         Set db = session.CurrentDatabase

         Set outline = db.GetOutline("MyOutline")

         Messagebox outline.Alias

         Messagebox outline.Comment

    End Sub
  2. This example displays the Label property of the first outline entry.

    3. Sub Initialize

         Dim session As New NotesSession

         Dim db As NotesDatabase

         Dim outline As NotesOutline

         Dim oe As NotesOutlineEntry

         Set db = session.CurrentDatabase

         Set outline = db.GetOutline("abba")

         Set oe = outline.GetFirst()

         Messagebox oe.Label

    End Sub
  3. This example displays the FrameText property of the last outline entry.

    4. Sub Initialize

         Dim session As New NotesSession

         Dim db As NotesDatabase

         Dim outline As NotesOutline

         Dim oe As NotesOutlineEntry

         Set db = session.CurrentDatabase

         Set outline = db.GetOutline("abba")

         Set oe = outline.GetFirst()

         Messagebox oe.FrameText

    End Sub
  4. This example creates an entry called Munchkin and adds it to the Cats outline. It will appear as the last entry at the top level of the outline.

    5. Dim session As New NotesSession

    Dim db As NotesDatabase

    Dim outline As NotesOutline

    Dim entry As NotesOutlineEntry

    Set db = session.CurrentDatabase

    Set outline = db.GetOutline("Cats")

    Set entry = outline.CreateEntry("Munchkin")

    Call outline.save()


Examples: Accessing database properties

  1. This example prints the values for the database properties that are built-in data types.

    2. Sub Initialize

         Dim session As New NotesSession

         Dim db As NotesDatabase

         Set db = session.CurrentDatabase

         Messagebox "Title: " & db.Title & Chr(10) _

         & "File name: " & db.FileName & Chr(10) _

         & "Path name: " & db.FilePath & Chr(10) _

         & "Replica ID: " & db.ReplicaID & Chr(10) _

         & "Size: " & db.Size & Chr(10) _

         & "Created: " & Chr(10) _

         & "Last modified: " & db.LastModified

         If db.IsOpen Then

              Messagebox "Database is open"

         Else

              Messagebox "Database is not open"

         End If

         Forall manager In db.Managers

              Messagebox "Manager: " & manager

         End Forall

         Messagebox "Categories: " & db.Categories

         If db.TemplateName <> "" Then

              Messagebox "Template name " _

              & db.TemplateName

         End If

         If db.DesignTemplateName <> "" Then

              Messagebox "Design template name" _

              & db.DesignTemplateName

         End If

         If db.IsFTIndexed Then

              Messagebox "Is full-text indexed " _

              & db.LastFTIndexed

         End If

         Messagebox "Current access level: " _

         & db.CurrentAccessLevel & Chr(10) _

         & "Percent used: " & db.PercentUsed & Chr(10) _

         & "Server name: " & db.Server & Chr(10) _

         & "Size limit: " & db.SizeQuota

         Messagebox "FolderReferenceEnabled: " _

         & db.FolderReferencesEnabled

         Messagebox "IsDirectoryCatalog: "_

         & db.IsDirectoryCatalog

         Messagebox "Maxsize: "_

         & db.Maxsize

    End Sub
  2. This example prints the name of each view in the database. A NotesView object is defined and set to each value in the Views property. The name is a property of the view object.

    3. Sub Initialize

         Dim session As New NotesSession

         Dim db As NotesDatabase

         Set db = session.CurrentDatabase

         REM view becomes a NotesView object

         Forall view In db.Views

              Messagebox "View name: " & view.Name

         End Forall

    End Sub


Examples: Accessing document properties

  1. This example prints properties of a document.

    2. Sub Initialize

         Dim db As New NotesDatabase _

         ("", Inputbox("Name of database file?"))

         Dim dc As NotesDocumentCollection

         Dim doc As NotesDocument

         Set dc = db.AllDocuments

         Set doc = dc.GetFirstDocument

         Forall docAuthor In doc.Authors

              Messagebox docAuthor

         End Forall

         Messagebox "Created: " & doc.Created

         If doc.IsNewNote Then

              Messagebox "Is a new note"

         End If

         If doc.IsResponse Then

              Messagebox "Parent: " _

              & doc.ParentDocumentUNID

         End If

         If doc.IsSigned Then

              Messagebox "Signed by: " & doc.Signer

              Messagebox "Verified by: " & doc.Verifier

         End If

         If doc.IsValid = True Then

              Messagebox "This document is valid."

         Else

              Messagebox "Document does not exist."

         End If

         Messagebox "Last accessed: " & doc.LastAccessed

         Messagebox "Last modified: " & doc.LastModified

         Messagebox "Note ID: " & doc.NoteID

         Messagebox "Universal ID: " & doc.UniversalID

    End Sub
  2. This example creates a new document, puts it in the folders, "view1," "view2," and "view3," and prints the folder reference and note ID for each document in the status bar.

    3. Sub Initialize

         Dim session As New NotesSession

         Dim db As NotesDatabase

         Dim doc As NotesDocument

         Set db = session.CurrentDatabase

         If(db.FolderReferencesEnabled) Then

              Messagebox ("Folder references enabled")

         Else

              Messagebox("Folder references are not enabled")

              Messagebox("Enabling folder references")

              db.FolderReferencesEnabled = True

         End If

         db.FolderReferencesEnabled = True

         Set doc = db.CreateDocument

         If Not(doc Is Nothing) Then

              Call doc.AppendItemValue("To", _

              "Test Document Name")

              Call doc.AppendItemValue("Subject", _

              "Test Document Topic")

              Call doc.Save(True, True)

              Messagebox ("Adding document to views")

              doc.PutInFolder("view1")

              doc.PutInFolder("view2")

              doc.PutInFolder("view3")

              Call doc.Save(True, True)

         End If

         Dim doccoll As NotesDocumentCollection

         Set doccoll = db.AllDocuments

         Set doc = doccoll.GetFirstDocument

         While Not(doc Is Nothing)

              i = 0

              Forall FolderReference In doc.FolderReferences

                   i = i+1

                   Print doc.noteid, "", i, "", _

                   FolderReferences

              End Forall

              Set doc = doccoll.GetNextDocument(doc)

         Wend

    End Sub


Examples: Accessing documents in a view navigator

  1. This example retrieves the first and last document entries in a view navigator and puts them in a folder called Over Stock.

    2. Sub Intialize

         Dim session As New NotesSession

         Dim db As NotesDatabase

         Dim view As NotesView

         Dim nav As NotesViewNavigator

         Dim entryA As NotesViewEntry

         Dim entryB As NotesViewEntry

         Dim docA As NotesDocument

         Dim docB As NotesDocument

         Set db = session.CurrentDatabase

         Set view = db.GetView("By Category")

         Set nav = view.CreateViewNav

         Set entryA = nav.GetFirstDocument

         Set entryB = nav.GetLastDocument

         Set docA = entryA.Document

         Set docB = entryB.Document

         Call docA.PutInfolder("Over Stock")

         Call docB.PutInfolder("Over Stock")

    End Sub
  2. This example retrieves the second document entry in a view navigator and puts it in a folder called New Releases.

    3. Sub Initialize

         Dim session As New NotesSession

         Dim db As NotesDatabase

         Dim view As NotesView

         Dim nav As NotesViewNavigator

         Dim entryA As NotesViewEntry

         Dim entryB As NotesViewEntry

         Dim doc As NotesDocument

         Set db = session.CurrentDatabase

         Set view = db.GetView("By Category")

         Set nav = view.CreateViewNav

         Set entryA = nav.GetFirstDocument

         Set entryB = nav.GetNextDocument(entryA)

         Set doc = entryB.Document

         Call doc.PutInfolder("New Releases")

    End Sub
  3. This example retrieves the next to last document in a view navigator and puts it in a folder called New Employees.

    4. Sub Initialize

         Dim session As New NotesSession

         Dim db As NotesDatabase

         Dim view As NotesView

         Dim nav As NotesViewNavigator

         Dim entryA As NotesViewEntry

         Dim entryB As NotesViewEntry

         Dim doc As NotesDocument

         Set db = session.CurrentDatabase

         Set view = db.GetView("By Category")

         Set nav = view.CreateViewNav

         Set entryA = nav.GetLastDocument

         Set entryB = nav.GetPrevDocument(entryA)

         Set doc = entryB.Document

         Call doc.PutInfolder("New Releases")

    End Sub


Examples: Accessing entries from a view navigator

  1. This example returns the specified view entry in a view navigator and places the documents associated with them in a folder called Over Stock.

    2. Sub Initialize

         Dim session As New NotesSession

         Dim db As NotesDatabase

         Dim view As NotesView

         Dim nav As NotesViewNavigator

         Dim entryA As NotesViewEntry

         Dim entryB As NotesViewEntry

         Dim doc As NotesDocument

         Set db = session.CurrentDatabase

         Set view = db.GetView("By Category")

         Set nav = view.CreateViewNavFromCategory("Stock")

         Set entryA = nav.GetFirst

         Set entryB = nav.GetEntry(entryA)

         Set doc = entryB.Document

         Call doc.PutInFolder("Over Stock")

    End Sub
  2. This example returns the first document in a Notes view navigator and displays its universal ID.

    3. Sub Intialize

         Dim session As New NotesSession

         Dim db As NotesDatabase

         Dim view As NotesView

         Dim nav As NotesViewNavigator

         Dim entry As NotesViewEntry

         Set db = session.CurrentDatabase

         Set view = db.GetView("By Category")

         Set nav = view.CreateViewNav

         Set entry = nav.GetFirstDocument

         Messagebox "Universal ID: " & entry.UniversalID

    End Sub
  3. This example returns the entry previous to the specified entry and displays the number of children for that entry.

    4. Sub Intialize

         Dim session As New NotesSession

         Dim db As NotesDatabase

         Dim view As NotesView

         Dim nav As NotesViewNavigator

         Dim entryA As NotesViewEntry

         Dim entryB As NotesViewEntry

         Set db = session.CurrentDatabase

         Set view = db.GetView("By Category")

         Set nav = view.CreateViewNav

         Set entryA = nav.GetLast

         Set entryB = nav.GetPrev(entryA)

         Messagebox entryB.ChildCount

    End Sub


Example: Accessing item properties

This example displays properties for a NotesItem object.

Sub Click(Source As Button)

     Dim workspace As New NotesUIWorkspace

     Dim uidoc As NotesUIDocument

     Dim doc As NotesDocument

     Dim item As NotesItem

     itemName = Inputbox("Which item?")

     Set uidoc = workspace.CurrentDocument

     Set doc = uidoc.Document

     Set item = doc.GetFirstItem(itemName)

     Select Case Item.Type

     Case ATTACHMENT : itemType = "File attachment"

     Case EMBEDDEDOBJECT : itemType = "Embedded object"

     Case ERRORITEM : itemType = _

     "Error occurred while accessing type"

     Case NAMES : itemType = "Names field"

     Case AUTHORS : itemType = "Authors field"

     Case READERS : itemType = "Readers field"

     Case NOTELINKS : itemType = _

     "Reference to the parent document"

     Case NOTEREFS : itemType = "DocLink"

     Case NUMBERS : itemType = "Number or range of numbers"

     Case RICHTEXT : itemType = "Rich text"

     Case SIGNATURE : itemType = "Signature"

     Case DATETIMES: itemType = _

     "Time-date value or range of values"

     Case TEXT : itemType = "Text or text list"

     Case UNAVAILABLE : itemType = "Not available"

     Case UNKNOWN : itemType = "Unknown"

     Case USERDATA : itemType = "User data"

     Case USERID : itemType = "User ID file"

     Case Else : itemType = Item.Type

     End Select

     Messagebox "Name: " & item.Name

     Messagebox "Type: " & itemType

     Messagebox "Text:" & Chr(10) & item.Text

     Messagebox "ValueLength: " & item.ValueLength

     If item.Type = RICHTEXT Then

          Messagebox "Values:" & Chr(10) & item.Values

     Elseif item.Type = DATETIMES Then

          Messagebox "Date: " & _

          item.DateTimeValue.LSLocalTime

          Elseif item.Type <> NOTELINKS _

     And item.Type <> NOTEREFS _

     And item.Type <> UNKNOWN _

     And item.Type <> UNAVAILABLE Then

          Forall itemValue In item.Values

               Messagebox "Values:" & Chr(10) & itemValue

          End Forall

     End If

     If item.IsEncrypted Then Messagebox "Is encrypted"

     If item.IsSigned Then Messagebox "Is signed"

     If item.IsSummary Then Messagebox "Is summary"

     If item.IsProtected Then Messagebox "Is protected"

     If item.IsNames Then Messagebox "Is names"

     If item.IsReaders Then Messagebox "Is readers"

     If item.IsAuthors Then Messagebox "Is authors"

End Sub


Examples: Accessing agents

  1. This example indicates whether the specified agent is a Notes agent.

    2. Sub Initialize

         Dim session As New NotesSession

         Dim db As NotesDatabase

         Dim agent As NotesAgent

         Dim nAgent As Variant

         Set db = session.CurrentDatabase

         Forall a In db.Agents

              If(a.Name = "RemoveEntry") Then

                   Set agent = a

                   nAgent = agent.IsNotesAgent

                   If nAgent = True Then

                        Messagebox "This is a Notes agent."

                   Else

                        Messagebox "This is not a Notes agent."

                   End If

              End If

         End Forall

    End Sub
  2. This example indicates whether the specified agent is a Web agent.

    3. Sub Initialize

         Dim session As New NotesSession

         Dim db As NotesDatabase

         Dim agent As NotesAgent

         Dim nAgent As Variant

         Set db = session.CurrentDatabase

         Forall a In db.Agents

              If(a.Name = "Read/Write") Then

                   Set agent = a

                   nAgent = agent.IsWebAgent

                   If nAgent = True Then

                        Messagebox nAgent

                   End If

              End If

         End Forall

    End Sub
  3. This example displays the name of the current agent.

    4. Sub Initialize

         Dim session As New NotesSession

         Dim agent As NotesAgent

         Set agent = session.CurrentAgent

         If Not Isempty(agent) Then

              Messagebox(agent.Name)

         Else

              Messagebox("Not an agent")

         End If

    End Sub
  4. This example displays the names of all the agents in the current database.

    5. Sub Initialize

         Dim session As New NotesSession

         Dim db As NotesDatabase

         Set db = session.CurrentDatabase

         agents = db.Agents

         If Not IsEmpty(agents) Then

              Forall agent In agents

                   Messagebox(agent.Name)

              End Forall

         Else

              Messagebox("No agents in database")

         End If

    End Sub
  5. This example determines if the agent "UserNameList" is triggered manually.

    6. Sub Initialize

         Dim session As New NotesSession

         Dim db As NotesDatabase

         Dim agent As NotesAgent

         Dim nAgent As Variant

         Set db = session.CurrentDatabase

         Forall a In db.Agents

              If(a.Name = "UserNameList") Then

                   Set agent = a

                   nAgent = agent.Trigger

                   If Trigger = Manual Then

                        Messagebox "Trigger is Manual"

                     End If

         End Forall

    End Sub
  6. This example saves data on the first invocation of an agent and displays it on every later invocation. If the agent is modified, the cycle restarts.

    7. Sub Initialize

         Dim session As New NotesSession

         Dim doc As NotesDocument

         Set doc = session.SavedData

         If doc.HasItem("SavedText") Then

              outText = doc.SavedText

              Messagebox("Saved text = " & outText(0))

         Else

              inText = Inputbox("Enter saved text")

              Call doc.AppendItemValue("SavedText", inText)

              Call doc.Save(True, False)

         End If

    End Sub


Example: Accessing NotesViewNavigator properties

This example displays the name of the Parent view and the maximum level of navigation in a view navigator.

Sub Intialize

     Dim session As New NotesSession

     Dim db As NotesDatabase

     Dim view As NotesView

     Dim nav As NotesViewNavigator

     Dim pv As NotesView

     Set db = session.CurrentDatabase

     Set view = db.GetView("By Category")

     Set nav = view.CreateViewNavFromCategory("Products")

     Set pv = nav.ParentView

     Messagebox "MaxLevel: " & nav.MaxLevel & Chr(10) _

     & "Parent view: " & pv.Name

End Sub


Examples: Accessing rich-text style properties

  1. This example creates several rich-text items and sets styles for them.

    2. Sub Initialize

         Dim session As New NotesSession

         Dim db As NotesDatabase

         Set db = session.CurrentDatabase

         Dim doc As New NotesDocument(db)

         Call doc.AppendItemValue("From", session.UserName)

         Call doc.AppendItemValue("Subject", _

              "Meeting time changed")

         Dim richStyle As NotesRichTextStyle

         Set richStyle = session.CreateRichTextStyle

         Dim richText As New NotesRichTextItem(doc, "Body")

         Call richText.AppendText("The meeting is at 2pm.")

         richStyle.Bold = True

         Call richText.AppendStyle(richStyle)

         Call richText.AppendText("The meeting is at 2pm.")

         richStyle.Italic = True

         Call richText.AppendStyle(richStyle)

         Call richText.AppendText("The meeting is at 2pm.")

         richStyle.FontSize = 18

         Call richText.AppendStyle(richStyle)

         Call richText.AppendText("The meeting is at 2pm.")

         richStyle.NotesColor = COLOR_CYAN

         Call richText.AppendStyle(richStyle)

         Call richText.AppendText("The meeting is at 2pm.")

         richStyle.Effects = EFFECTS_SHADOW

         Call richText.AppendStyle(richStyle)

         Call richText.AppendText("The meeting is at 2pm.")

         richStyle.Strikethrough = False

         Call richText.AppendStyle(richStyle)

         Call richText.AppendText("The meeting is at 2pm.")

         richStyle.Underline = True

         Call doc.Save(True, False)

    End Sub
  2. This example creates a rich-text item and marks it as pass-thru HTML.

    3. Sub Initialize

         Dim session As New NotesSession

         Dim db As NotesDatabase

         Set db = session.CurrentDatabase

         Dim doc As New NotesDocument(db)

         Call doc.AppendItemValue("From", session.UserName)

         Call doc.AppendItemValue("Subject", _

              "Meeting time changed")

         Dim richStyle As NotesRichTextStyle

         Set richStyle = session.CreateRichTextStyle

         Dim richText As New NotesRichTextItem(doc, "Body")

         richStyle.PassThruHTML = True

         Call richText.AppendStyle(richStyle)

         Call richText.AppendText("The meeting is at 2:00.")

         Call doc.Save(True, False)

    End Sub

See also
Accessing rich-text style properties
NotesRichTextStyle class


Examples: Accessing session properties

  1. This agent example displays the session properties.

    2. Sub Initialize

         Dim session As New NotesSession

         Dim agent As NotesAgent

         Dim db As NotesDatabase

         Dim international As NotesInternational

         Set agent = session.CurrentAgent

         Messagebox "Name of agent = " & agent.Name

         Set db = session.CurrentDatabase

         Messagebox "Title of database = " & db.Title

         Messagebox "Effective user name = " _

         & session.EffectiveUserName

         Messagebox "User name = " & session.UserName

         Messagebox "Common user name = " _

         & session.CommonUserName

         If session.IsOnServer Then

              Messagebox "Running on server"

         Else

              Messagebox "Running on workstation"

         End If

         Messagebox "Notes version = " _

         & session.NotesVersion

         Messagebox "Notes build version = " _

         & session.NotesBuildVersion

         Messagebox "Platform = " & session.Platform

         Set international = session.International

         Messagebox "Currency symbol = " _

         & international.CurrencySymbol

    End Sub
  2. This agent example displays the title and path name of each Address Book.

    3. Sub Initialize

         Dim session As New NotesSession

         Dim db As NotesDatabase

         addressBooks = session.AddressBooks

         Forall addressBook In addressBooks

              Set db = addressBook

              Call db.Open("", "")

              Messagebox db.Title & Chr(10) _

              & "(" & Ucase(db.FilePath) & ")"

              Call db.Close

         End Forall

    End Sub


Examples: Accessing the current document

  1. This example executes when the user enters a field in Edit mode. The script displays information about the field and document.

    2. Sub Entering(Source As Field)

         Dim workspace As New NotesUIWorkspace

         Dim uidoc As NotesUIDocument

         Set uidoc = workspace.CurrentDocument

         If uidoc.EditMode Then

              If uidoc.IsNewDoc Then

                   Messagebox _

                   ("This is the " & _

                   uidoc.CurrentField & " field")

              Else

                   Messagebox _

                   ("This is the " & uidoc.CurrentField & _

                   " field of " & uidoc.WindowTitle)

              End If

         End If

    End Sub
  2. This example puts the current document in Edit mode if it is not, and toggles the ruler.

    3. Sub Click(Source As Button)

         Dim workspace As New NotesUIWorkspace

         Dim uidoc As NotesUIDocument

         Set uidoc = workspace.CurrentDocument

         If Not uidoc.EditMode Then

              uidoc.EditMode = True

         End If

         If uidoc.Ruler Then

              uidoc.Ruler = False

         Else

              uidoc.Ruler = True

         End If

    End Sub
  3. This example gets the database document that corresponds to the current UI document, then gets the parent database (that is, the current database).

    4. Sub Click(Source As Button)

         Dim workspace As New NotesUIWorkspace

         Dim uidoc As NotesUIDocument

         Dim doc As NotesDocument

         Dim db As NotesDatabase

         Set uidoc = workspace.CurrentDocument

         Set doc = uidoc.Document

         Set db = doc.ParentDatabase

         Messagebox "Parent database: " & db.Title

    End Sub
  4. This example gets the selected text in the current document.

    5. Sub Click(Source As Button)

          Dim workspace As New NotesUIWorkspace

          Dim uidoc As NotesUIDocument

          Dim text As String

          Set uidoc = workspace.CurrentDocument

          text = uidoc.GetSelectedText(body$)

    End Sub
  5. This example places a value in the Categories text item using a NotesDocument object. When the NotesDocument object is saved, the workspace object is updated in real time. This code won't work for a rich-text item.

    6. Sub Click(Source As Button)

         Dim workspace As New NotesUIWorkspace

         Dim uidoc As NotesUIDocument

         Dim doc As NotesDocument

         Set uidoc = workspace.CurrentDocument

         Set doc = uidoc.Document

         If Not uidoc.EditMode Then uidoc.EditMode = True

         categories = doc.Categories

         categories(0) = "Main category"

         doc.Categories = categories

         Call doc.Save(True, False)

    End Sub
  6. This example composes a new document based on the "Person" form, and displays a dialog box based on the "Person Dialog Box" form to get information from the user. The "Person Dialog Box" form contains a layout region whose fields have names that correspond to some of the fields in the "Person" form. When the user clicks OK in the dialog box, the data in the dialog box transfers to the fields of the same name in the new document.

    7. Sub Click(Source As Button)

         Dim workspace As New NotesUIWorkspace

         Dim uidoc As NotesUIDocument

         Set uidoc = workspace.ComposeDocument("","", "Person")

         Call workspace.DialogBox _

         ("Person Dialog Box", True, True)

    End Sub
  7. This example opens the current document in a view in Edit mode and displays a dialog box based on the "Person Dialog Box" form to get information from the user. The "Person Dialog Box" form contains a layout region whose fields have names that correspond to some of the fields in the current document. When the user clicks OK in the dialog box, the data in the dialog box transfers to the fields of the same name in the document.

    8. Sub Click(Source As Button)

         Dim workspace As New NotesUIWorkspace

         Dim uidoc As NotesUIDocument

         Set uidoc = workspace.EditDocument(True)

         Call workspace.DialogBox _

         ("Person Dialog Box", True, True)

    End Sub
  8. This example is the same as the last but uses all the arguments to the DialogBox method. Argument 4 (True) displays only an OK button, argument 5 (True) refuses to add new fields to the underlying form, argument 6 (False) allows edits to be passed to the underlying form, argument 7 (False) allows the dialog box to be edited, and the last argument specifies a title for the dialog box.

    9. Sub Click(Source As Button)

         Dim workspace As New NotesUIWorkspace

         Dim uidoc As NotesUIDocument

         Set uidoc = workspace.EditDocument(True)

         Call workspace.DialogBox _

         ("Person Dialog Box", _

         True, True, True, True, False, False, _

         "Fill in this box and click Enter")

    End Sub
  9. This example finds a specified string in the current UI document.

    10. Sub Click(Source As Button)

          Dim workspace As New NotesUIWorkspace

          Dim uidoc As NotesUIDocument

          Set uidoc = workspace.CurrentDocument

          Call uidoc.FindString("Get this string.")

    End Sub
  10. This example imports a text document into the body of the current UI document.

    11. Sub Click(Source As Button)

         Dim workspace As New NotesUIWorkspace

         Dim uidoc As NotesUIDocument

         Set uidoc = workspace.CurrentDocument

         Call uidoc.Import

    End Sub
  11. This example puts the current document in Edit mode and checks it for spelling errors. The document must be in Edit mode before the SpellCheck method is called.

    12. Sub Click(Source As Button)

         Dim workspace As New NotesUIWorkspace

         Dim uidoc As NotesUIDocument

         Set uidoc = workspace.EditDocument(True)

         Call uidoc.SpellCheck

    End Sub
  12. This example brings up the Find Free Time box and searches for available meeting times for the names listed in the SendTo field. The search is restricted to the range defined in the StartDateTime and EndDateTime fields.

    13. Sub Click(Source As Button)

         Dim workspace As New NotesUIWorkspace

         Dim uidoc As NotesUIDocument

         Set uidoc = workspace.CurrentDocument

         Call uidoc.Refresh

         Call uidoc.FindFreeTimeDialogEx _

         ("SendTo", "", "", "", "", "", "", "StartDateTime", _

         "EndDateTime")

    End Sub


Examples: Accessing view or folder columns

  1. This example displays properties of all columns in all views in the current database.

    2. Sub Click(Source As Button)

         Dim session As New NotesSession

         Dim db As NotesDatabase

         Set db = session.CurrentDatabase

         REM view is a NotesView object

         Forall view In db.Views

              Messagebox "View name: " & view.Name

              REM column is a NotesViewColumn object

              Forall column In view.Columns

                   position = column.Position

                   title = column.Title

                   If title = "" Or title = " " Then _

                   title = "<no title>"

                   formu = column.Formula

                   Messagebox position & ", " _

                   & title & ", " & formu

              End Forall

         End Forall

    End Sub
  2. This example displays properties of the By Category view in a database.

    3. Sub Initialize

         Dim session As New NotesSession

         Dim db As NotesDatabase

         Dim view As NotesView

         Set db = session.CurrentDatabase

         Set view = db.GetView("By Category")

         Messagebox "Background color: " & view.BackgroundColor

         Messagebox "Column Count: " & view.ColumnCount

         Messagebox  "Header Lines: " & view.HeaderLines

         Messagebox  "Row Lines: " & view.RowLines

         Messagebox "Spacing: " & view.Spacing

         Messagebox  "Top Level Entries: " & view.TopLevelEntryCount

         If view.IsCategorized = True Then

              Messagebox "Categorized"

         Else

              Messagebox "Not Categorized"

         End If

         If view.IsConflict = True Then

              Messagebox "Conflict enabled"

         Else

              Messagebox "Not conflict enabled"

         End If

         If view.IsHierarchical = True Then

              Messagebox "Hierarchical"

         Else

              Messagebox "Not hierarchical"

         End If

         If view.IsModified = True Then

              Messagebox "Modified"

         Else

              Messagebox "Not modified"

         End If

    End Sub


Examples: Accessing view or folder properties

This example prints properties of all the views in a database.

Sub Initialize

     Dim session As New NotesSession

     Dim db As NotesDatabase

     Set db = session.CurrentDatabase

     REM view is a NotesView object

     REM cannot be Dim'd - loop reference variable

     Forall view In db.Views

          Messagebox "View name: " & view.Name & Chr(10) _

          & "Parent: " & view.Parent.Title & Chr(10) _

          & "Last modified: " & view.LastModified & Chr(10) _

          & "Created: " & view.Created & Chr(10) _

          & "Universal ID: " & view.UniversalID Chr(10) _

          & "BackgroundColor: " & _

          view.BackgroundColor Chr(10) _

          & "Number of columns: " & view.ColumnCount Chr(10) _

          & "Top level entries: " & view.TopLevelEntryCount

          If view.IsDefaultView Then _

          Messagebox "Default view"

          If view.IsFolder Then Messagebox "Folder"

          If Not Isempty(view.Aliases) Then

               Forall aliass In view.Aliases

                    Messagebox "Alias: " & aliass

               End Forall

          End If

     End Forall

End Sub


Examples: Activate method

  1. This script embeds a new object in the Body item of a document, and activates the object.

    2. Dim session As New NotesSession

    Dim doc As NotesDocument

    Dim rtitem As NotesRichTextItem

    Dim object As NotesEmbeddedObject

    Dim handle As Variant

    Set doc = New NotesDocument( session.CurrentDatabase )

    Set rtitem = New NotesRichTextItem( doc, "Body" )

    Set object = rtitem.EmbedObject _

    ( EMBED_OBJECT, "Microsoft Excel Worksheet", "", _

    "Report" )

    Set handle = object.Activate( False )

    If ( handle Is Nothing ) Then

      doc.Subject = "This object has no OLE automation interface"

    Else

      doc.Subject = "This object has an OLE automation interface"

    End If

    Call doc.Save( True, True )
  2. This script embeds a new worksheet object in a rich text item, activates it, and uses its handle to set the value of a cell in the worksheet.

    3. Dim rtitem as NotesRichTextItem

    Dim object as NotesEmbeddedObject

    Dim handle as Variant

    '...set value of rtitem...

    Set object  = rtitem.EmbedObject( EMBED_OBJECT, _

    "Microsoft Excel Worksheet", "", "Report" )

    Set handle = object.Activate ( False )

    handle.Application.Cells( 1,1 ).Value = 100

    handle.Parent.Save


Example: AddCertifierToAddressbook Method

The following script shows you how to add a certifier to your Address Book.

Dim reg As New NotesRegistration

Call reg.AddCertifierToAddressbook("c:\lotus\notes\cert.id", _

       "cpassword", "North Reading", _

       "Adding a Certifier to the Address Book")


Example: AddDatabase method

This example adds a user-specified database to the workspace.

On Error Goto errorHandler

Dim workspace As New NotesUIWorkspace

Call workspace.AddDatabase( _

Inputbox("Name of server?", "Server"), _

Inputbox("Filename of database?", "Database"))

          errorHandler:

Exit Sub


Example: AddNewLine method

This script finds the ProjectDescription item in a document. It adds a carriage return and some text to the item.

Dim doc As NotesDocument

Dim rtitem As Variant

'...set value of doc...

Set rtitem = doc.GetFirstItem( "ProjectDescription" )

If rtitem.Type = RICHTEXT Then

  Call rtitem.AddNewLine( 1 )

  Call rtitem.AppendText( "Book is 64 pages, full color." )

End If

Call doc.Save( False, True )

If the ProjectDescription item used to contain the text value "Cartoon book for children ages 9-12," it now contains the following:

Cartoon book for children ages 9-12

Book is 64 pages, full color.


Example: AddPageBreak method

This script adds a page break to the current document.

Dim workspace As New NotesUIWorkspace

Dim uidoc As NotesUIDocument

Dim doc As NotesDocument

Dim rtitem As Variant

Set uidoc = workspace.CurrentDocument

Set doc = uidoc.Document

Set rtitem = doc.GetFirstItem("Content")

If rtitem.Type <> RICHTEXT Then

     Messagebox "Content is not a rich-text item."

End If

Call rtitem.AddPageBreak

Call doc.Save(False, True)


Examples: AddressBooks property

  1. This script gets each address book, opens it, and prints its title in a dialog box.

    2. Dim session As New NotesSession

    Dim books As Variant

    books = session.AddressBooks

    Forall b In books

      Call b.Open( "", "" )

      Messagebox( b.Title )

    End Forall
  2. This action script finds an employee's phone number by looking it up in an Address Book. After the user enters the last name of the person, the script searches for the name in the People view of every available Domino Directory. If a Person document is found that matches the name, the script displays the person's phone number, from the OfficePhoneNumber item on the Person document. If a matching Person document is not found in any Domino Directory, the script displays an error message.

Sub Click(Source As Button)

  Dim session As New NotesSession

  Dim books As Variant

  Dim view As NotesView

  Dim doc As NotesDocument

  Dim done As Variant

  Dim person As String

  books = session.AddressBooks

  done = False

  person = Inputbox$ _

  ( "Enter the last name of the person: ", "Last name" )

  Forall b In books

    ' check every Domino Directory,

    ' unless we're already done

    If ( b.IsPublicAddressBook ) And ( Not done ) Then

      Call b.Open( "", "" )

      ' look up person's last name

      ' in People view of address book

      Set view = b.GetView( "People" )

      Set doc = view.GetDocumentByKey( person )

      ' if person is found, display the phone number item

      ' from the Person document

      If Not ( doc Is Nothing ) Then

        Messagebox( "Phone for " + person  _

        + " is " + doc.OfficePhoneNumber( 0 ) )

        done = True

      End If

    End If

  End Forall

  ' if done is still False, the person wasn't found

  If Not done Then

    Messagebox _

    ( "Sorry, unable to locate person's name." )

  End If

End Sub


Example: AddRole method

This script adds a Developer role to the ACL of the current database.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim acl As NotesACL

Set db = session.CurrentDatabase

Set acl = db.ACL

Call acl.AddRole( "Developer" )

Call acl.Save


Example: AddRow method

This agent adds a new row to a table.

Uselsx "*LSXODBC"

Sub Initialize

     Dim con As New ODBCConnection

     Dim qry As New ODBCQuery

     Dim result As New ODBCResultSet

     Dim firstName As String

     Dim lastName As String

     Dim msg As String

     On Error Goto errorHandler

     Set qry.Connection = con

     Set result.Query = qry

     con.ConnectTo("ATDB")

     qry.SQL = "SELECT * FROM STUDENTS"

     result.Execute

     result.AddRow

     Call result.SetValue("LASTNAME", _

     Inputbox$("Last name?", "New student", "Rodriguez"))

     Call result.SetValue("FIRSTNAME", _

     Inputbox$("First name?", "New student", "Jorges"))

     Call result.SetValue("STUDENT_NO", _

     Cint(Inputbox$("Student number?", _

                   "New student", "9999")))

     Call result.SetValue("ADDRESS", _

     Inputbox$("Address?", "New student", "11 Rogers St."))

     Call result.SetValue("CITY", _

     Inputbox$("City?", "New student", "Cambridge"))

     Call result.SetValue("STATE", _

     Inputbox$("State?", "New student", "MA"))

     Call result.SetValue("ZIP", _

     Inputbox$("Zip?", "New student", "02142"))

     Call result.SetValue("CR_TO_DATE", _

     Cint(Inputbox$("Credits to date?", "New student", "0")))

     result.UpdateRow

     result.Close(DB_CLOSE)

     con.Disconnect

     Exit Sub

errorHandler:

     Messagebox result.GetExtendedErrorMessage,, result.GetErrorMessage

     Exit Sub

End Sub


Example: AddServerToAddressbook method

The following script shows you how to add a server ID to your Address Book.

Dim reg As New NotesRegistration

reg.StoreIDInAddressBook = True

Call reg.AddServerToAddressbook( "c:\lotus\notes\server.ID", _

     "Daytona", "Notes", "spassword", "Dadmin", _

     "Administrator","Name and Address Book", _

     "Reading", "Adding Server to Address Book")


Examples: AddTab method

  1. This script adds some text, two tabs, and more text to a rich-text item called ProjectDescription.

    2. Dim doc As NotesDocument

    Dim rtitem As Variant

    '...set value of doc...

    Set rtitem = doc.GetFirstItem( "ProjectDescription" )

    If ( rtitem.Type = RICHTEXT ) Then

      Call rtitem.AppendText( "Before" )

      Call rtitem.AddTab( 2 )

      Call rtitem.AppendText( "After" )

      Call doc.Save( False, True )

    End If
    If the ProjectDescription item is empty when the script begins, it looks like this when the script finishes:

    Before After

  2. This script uses AddTab, AddNewLine, and AppendText to create a tabbed "table" of values in a new rich-text item called ProductListing. The values are retrieved from the Products view in another database, sourceDb. The first column value is a string; the second is a number, so it's converted to a string before being appended.

    3. Dim targetDoc As NotesDocument

    Dim targetRTItem As NotesRichTextItem

    '...set value of targetDoc...

    Set targetRTItem = New NotesRichTextItem _

    ( targetDoc, "ProductListing" )

    Dim sourceDb As NotesDatabase

    Dim sourceView As NotesView

    Dim sourceDoc As NotesDocument

    Set sourceDb = New NotesDatabase( "Belem", "inventry.nsf" )

    Set sourceView = sourceDb.GetView( "Products" )

    Set sourceDoc = sourceView.GetFirstDocument

    While Not ( sourceDoc Is Nothing )

      a = sourceDoc.ColumnValues( 0 )

      b = sourceDoc.ColumnValues( 1 )

      Call targetRTItem.AppendText( a )

      Call targetRTItem.AddTab( 1 )

      Call targetRTItem.AppendText( Str( b ) )

      Call targetRTItem.AddNewLine( 1 )

      Set sourceDoc = sourceView.GetNextDocument( sourceDoc )

    Wend

    Call targetDoc.Save( False, True )
    For example, if the Products view in INVENTRY.NSF has product names in the first column and quantities in the second, the result in the ProductListing item might look like this:

    Nails, common #08 989

    Nails, common #10 1000

    Nails, common #12 1000

    Nails, common #16 978

    Screws, slot, 1/4x2 1000


Example: AddUserProfile method

The following script shows you how to add a user profile to the ID file.

Dim reg As New NotesRegistration

reg.RegistrationServer = "MoonBeam"

username$ = "Jean Smith"

profilename$ = "profile1"

Call reg.AddUserProfile( "username$", "profilename$")


Example: AddUserToAddressbook method

The following script shows you how to add a user ID to your Address Book.

Dim reg As New NotesRegistration

reg.StoreIDInSAddressBook = True

Call reg.AddUserToAddressbook( "c:\lotus\notes\JSmith.ID", _

     "Joseph Smith", "Smith", "password", "Joseph", "V", _

     "MoonBeam", "JSmith.nsf", "mail\JSmith.nsf", "Reading", _

     "Adding user to Address Book")


Examples: AdjustDay method

  1. This script increments a NotesDateTime object by ten days, so that it represents 04/26/96 05:36:00 PM.

    2. Dim dateTime As New NotesDateTime( "04/16/96 05:36 PM" )

    Call dateTime.AdjustDay( 10 )
  2. This script decrements a NotesDateTime object by ten days, so that it represents 04/06/96 05:36:00 PM. If the script runs on a computer that observes daylight savings time, the date represents 04/06/96 04:36:00 PM, reflecting the fact that daylight savings time went into effect on April 6.

    3. Dim dateTime As New NotesDateTime( "04/16/96 05:36 PM" )

    Call dateTime.AdjustDay( -10 )
  3. This script decrements a NotesDateTime object by 17 days. This carries the date over to the previous month, so that it represents 03/30/96 05:36:00 PM, or 03/30/96 04:36:00 PM if the script runs on a computer that observes daylight savings time.

    4. Dim dateTime As New NotesDateTime( "04/16/96 05:36 PM" )

    Call dateTime.AdjustDay( -17 )


Examples: AdjustHour method

  1. This script increments a NotesDateTime object by two hours, so that it represents 04/16/96 07:36:00 PM.

    2. Dim dateTime As New NotesDateTime( "04/16/96 05:36 PM" )

    Call dateTime.AdjustHour( 2 )
  2. This script decrements a NotesDateTime object by two hours, so that it represents 04/16/96 03:36:00 PM.

    3. Dim dateTime As New NotesDateTime( "04/16/96 05:36 PM" )

    Call dateTime.AdjustHour( -2 )
  3. This script increments a NotesDateTime object by ten hours. This carries the date over to the next day, so that it represents 04/17/96 03:36:00 AM.

    4. Dim dateTime As New NotesDateTime( "04/16/96 05:36 PM" )

    Call dateTime.AdjustHour( 10 )
  4. This script creates a NotesDateTime object set to today's date and then attempts to increment it by 24 hours. The AdjustHour method, however, has no effect because dateTime does not have a time component.

    5. Dim dateTime As New NotesDateTime( "Today" )

    Call dateTime.AdjustHour( 24 )


Examples: AdjustMinute method

  1. This script increments a NotesDateTime object by twenty minutes, so that it represents 04/16/96 05:56:00 PM.

    2. Dim dateTime As New NotesDateTime( "04/16/96 05:36 PM" )

    Call dateTime.AdjustMinute( 20 )
  2. This script decrements a NotesDateTime object by twenty minutes, so that it represents 04/16/96 05:16:00 PM.

    3. Dim dateTime As New NotesDateTime( "04/16/96 05:36 PM" )

    Call dateTime.AdjustMinute( -20 )
  3. This script creates a NotesDateTime object set to today's date and then attempts to increment it by 50 minutes. The AdjustMinute method, however, has no effect because dateTime does not have a time component.

    4. Dim dateTime As New NotesDateTime( "Today" )

    Call dateTime.AdjustMinute( 50 )


Examples: AdjustMonth method

  1. This script increments a NotesDateTime object by three months, so that it represents 07/16/96 05:36:00 PM.

    2. Dim dateTime As New NotesDateTime( "04/16/96 05:36 PM" )

    Call dateTime.AdjustMonth( 3 )
  2. This script decrements a NotesDateTime object by three months, so that it represents 01/16/96 05:36:00 PM.

    3. Dim dateTime As New NotesDateTime( "04/16/96 05:36 PM" )

    Call dateTime.AdjustMonth( -3 )
  3. This script decrements a NotesDateTime object by four months. This carries the date over to the previous year, so that it represents 12/16/95 05:36:00 PM.

    4. Dim dateTime As New NotesDateTime( "04/16/96 05:36 PM" )

    Call dateTime.AdjustMonth( -4 )


Examples: AdjustSecond method

  1. This script increments a NotesDateTime object by twenty seconds, so that it represents 04/16/96 05:36:20 PM.

    2. Dim dateTime As New NotesDateTime( "04/16/96 05:36 PM" )

    Call dateTime.AdjustSecond( 20 )
  2. This script decrements a NotesDateTime object by twenty seconds, so that it represents 04/16/96 05:35:40 PM.

    3. Dim dateTime As New NotesDateTime( "04/16/96 05:36 PM" )

    Call dateTime.AdjustSecond( -20 )
  3. This script creates a NotesDateTime object set to today's date and then attempts to increment it by 50 seconds. The AdjustSecond method, however, has no effect because dateTime does not have a time component.

    4. Dim dateTime As New NotesDateTime( "Today" )

    Call dateTime.AdjustSecond( 50 )


Examples: AdjustYear method

  1. This script increments a NotesDateTime object by four years, so that it represents 04/16/2000 05:36:00 PM.

    2. Dim dateTime As New NotesDateTime( "04/16/96 05:36 PM" )

    Call dateTime.AdjustYear( 4 )
  2. This script decrements a NotesDateTime object by four years, so that it represents 04/16/92 05:36:00 PM.

    3. Dim dateTime As New NotesDateTime( "04/16/96 05:36 PM" )

    Call dateTime.AdjustYear( -4 )


Examples: Agents property

  1. This action script prints the name of each agent in the current database. Since the script runs on a workstation, it prints the name of public agents, as well as the names of the current user's personal agents, if any.

    2. Sub Click(Source As Button)

      Dim session As New NotesSession

      Dim db As NotesDatabase

      Set db = session.CurrentDatabase

      Forall a In db.Agents

        Messagebox( a.Name )

      End Forall

    End Sub
  2. This script finds the agent in the current database named Periodic Archive and assigns it to the agent object.

    3. Dim session As New NotesSession

    Dim db As NotesDatabase

    Dim agent As NotesAgent

    Set db = session.CurrentDatabase

    Forall a In db.Agents

      If ( a.Name = "Periodic Archive" ) Then

        Set agent = a

      End If

    End Forall


Examples: Alias property

This script displays the alias of an outline.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim outline As NotesOutline

Set db = session.CurrentDatabase

Set outline = db.GetOutline("MyOutline")

Messagebox outline.Alias


Examples: Alias property

This script displays the alias of an outline entry.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim outline As NotesOutline

Dim oe As NotesOutlineEntry

Set db = session.CurrentDatabase

Set outline = db.GetOutline("products")

Set oe = outline.GetFirst()

Messagebox "Alias: " & oe.Alias


Example: Aliases property

This script displays all the aliases for a specified form.

Dim session As New NotesSession

Dim db As NotesDatabase

Set db = session.CurrentDatabase

formNameIn = Lcase(Inputbox("Name of form?"))

Forall form In db.Forms

     If Lcase(form.Name) = formNameIn Then

          If Isempty(form.Aliases) Then

               Messagebox form.Name & " has no aliases"

          Else

               aliazCount = 0

               msgString = ""

               Forall aliaz In form.Aliases

                    aliazCount = aliazCount + 1

                    msgString = msgString & Chr(10) & _

                    "     " & aliaz

               End Forall

               Messagebox form.Name & " has " & _

               aliazCount & _

               " alias(es):" & Chr(10) & msgString

          End If

          Exit Sub

     End If

End Forall

Messagebox "The form """ & formNameIn & """ does not exist"


Example: Aliases property

This script gets all the views in the current database and displays each view's name and aliases.

Dim session As New NotesSession

Dim db As NotesDatabase

Set db = session.CurrentDatabase

Forall view In db.Views

     Messagebox "View name: " & view.Name

     If Not Isempty(view.Aliases) Then

          Forall aliass In view.Aliases

               Messagebox "Alias: " & aliass

          End Forall

     End If

End Forall


Example: Alignment property

This script displays the alignment of data in a column as an integer.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim view As NotesView

Dim column As notesViewColumn

Set db = session.CurrentDatabase

Set view = db.Getview("Align")

Set column = view.Columns(0)

Messagebox(column.Alignment)


Example: Alignment property

This example creates a new rich-text paragraph style object and centers it in the document.

Dim session As New NotesSession

Dim db As NotesDatabase

Set db = session.Currentdatabase

Dim doc As New NotesDocument(db)

Call doc.AppendItemValue("From", session.Username)

Call doc.AppendItemValue("subject", _

"Meeting agenda")

Dim rtpStyle As NotesrichTextParagraphStyle

Set rtpStyle = session.CreateRichTextParagraphStyle

Dim richText As New NotesRichTextItem(doc, "Body")

rtpStyle.Alignment = ALIGN_CENTER

Call richText.AppendParagraphStyle(rtpStyle)

Call richText.AppendText("Where are we now")

Call richText.AddNewLine(1)

Call richText.AppendText (" and where do we go from here.")

Messagebox rtpStyle.Alignment

Call doc.Save(True, False)


Examples: AllDocuments property

  1. This script gets a collection of every document in the current database. For example, if there are 56 documents in the database, AllDocuments returns a collection with a Count property of 56.

    2. Dim session As New NotesSession

    Dim db As NotesDatabase

    Dim collection As NotesDocumentCollection

    Dim n As Integer

    Set db = session.CurrentDatabase

    Set collection = db.AllDocuments

    n = collection.Count
  2. This action script removes all file attachments from the Body item of every document in the current database. The script examines each document in the collection returned by AllDocuments and, if the document's Body item contains a file attachment, calls the sub detachFiles, which detaches the file(s) to a directory on drive C.

    3. Sub Click(Source As Button)

      Dim session As New NotesSession

      Dim db As NotesDatabase

      Dim collection As NotesDocumentCollection

      Dim doc As NotesDocument

      Set db = session.CurrentDatabase

      Set collection = db.AllDocuments

      For i = 1 To collection.Count

        Set doc = collection.GetNthDocument( i )

        If doc.HasEmbedded Then

          Call detachFiles( doc )

        End If

      Next

    End Sub

    Sub detachFiles( doc As NotesDocument )

      Dim rtitem As Variant

      Set rtitem = doc.GetFirstItem( "Body" )

      Forall o In rtitem.EmbeddedObjects

        If o.Type = EMBED_ATTACHMENT Then

          Call o.ExtractFile( "c:\newfiles\" & o.Source )

          Call o.Remove

          Call doc.Save( True, True )

        End If

      End Forall

    End Sub


Example: AMString property

This example displays international time settings: 24-hour or 12-hour; for 12-hour, the AM and PM strings; the hour-minute-second separator; and the time zone.

Dim session As New NotesSession

Dim international As NotesInternational

Set international = session.International

If international.IsTime24Hour Then

     Messagebox "24-hour",, "Time format"

Else

     Messagebox "12-hour",, "Time format"

     Messagebox international.AMString & Chr(10) & _

     international.PMString,, "AM and PM notation"

End If

Messagebox international.TimeSep,, "Time separator"

Messagebox international.TimeZone,, "Time zone"


Examples: AppendDocLink method

  1. This script creates a new mail memo. In the Body item of the memo, the script places a link to the current database.

    2. Dim session As New NotesSession

    Dim db As NotesDatabase

    Dim newDoc As NotesDocument

    Dim rtitem As NotesRichTextItem

    Set db = session.CurrentDatabase

    Set newDoc = New NotesDocument( db )

    Set rtitem = New NotesRichTextItem( newDoc, "Body" )

    Call rtitem.AppendDocLink( db, db.Title )

    newDoc.Subject = "Here is a link to the database"

    newDoc.SendTo = "Lauri Nodwell"

    newDoc.Send( False )
  2. This script creates a new mail memo. In the Body item of the memo, the script places a link to the Boots folder in the current database.

    3. Dim session As New NotesSession

    Dim db As NotesDatabase

    Dim view As NotesView

    Dim newDoc As NotesDocument

    Dim rtitem As NotesRichTextItem

    Set db = session.CurrentDatabase

    Set view = db.GetView( "Boots" )

    Set newDoc = New NotesDocument( db )

    Set rtitem = New NotesRichTextItem( newDoc, "Body" )

    Call rtitem.AppendDocLink _

    ( view, view.Name & " in " & db.Title )

    newDoc.Subject = "Here is a link to the Boots folder"

    newDoc.SendTo = "Lauri Nodwell"

    Call newDoc.Send( False )
  3. This script creates a new mail memo. In the Body item of the memo, the script places a link to the first document in the Boots folder in the current database.

    4. Dim session As New NotesSession

    Dim db As NotesDatabase

    Dim view As NotesView

    Dim newDoc As NotesDocument

    Dim rtitem As NotesRichTextItem

    Dim doc As NotesDocument

    Set db = session.CurrentDatabase

    Set view = db.GetView( "Boots" )

    Set newDoc = New NotesDocument( db )

    Set rtitem = New NotesRichTextItem( newDoc, "Body" )

    Set doc = view.GetFirstDocument

    Call rtitem.AppendDocLink _

    ( doc, doc.Subject( 0 ) & " in " & view.Name )

    newDoc.Subject = _

    "Here is a link to first document in the Boots folder"

    newDoc.SendTo = "Lauri Nodwell"

    Call newDoc.Send( False )
  4. This script creates a new mail memo. In the Body item of the memo, the script places a link to each document in the Boots folder in the test.nsf database. Each link is followed by a tab, the Subject item of the document being linked to, and a carriage return.

Dim session As New NotesSession

Dim db As New NotesDatabase("", "test.nsf")

Dim view As NotesView

Dim newDoc As NotesDocument

Dim rtitem As NotesRichTextItem

Dim doc As NotesDocument

Set view = db.GetView( "Boots" )

Set newDoc = New NotesDocument( db )

Set rtitem = New NotesRichTextItem( newDoc, "Body" )

Set doc = view.GetFirstDocument

While Not ( doc Is Nothing )

  Call rtitem.AppendDocLink( doc, db.Title )

  Call rtitem.AddTab( 1 )

  Call rtitem.AppendText( doc.Subject( 0 ) )

  Call rtitem.AddNewLine( 1 )

  Set doc = view.GetNextDocument( doc )

Wend

newDoc.Subject = _

"Here are links to all docs in the Boots folder"

newDoc.SendTo = "Lauri Nodwell"

Call newDoc.Send( False )


Examples: AppendItemValue method

  1. This script adds two new items to a document: a number item called EstimatedCost with the value 89, and a text item called Region with the value "Pacific Rim."

    2. Dim doc As NotesDocument

    '...set value of doc...

    Dim itemA As NotesItem

    Dim itemB As NotesItem

    Set itemA = doc.AppendItemValue( "EstimatedCost", 89 )

    Set itemB = doc.AppendItemValue( "Region", "Pacific Rim" )

    Call doc.Save( False, True )
  2. This script achieves the same result using the extended class syntax. The difference is that if an item with the name EstimatedCost or Region already exists in the document, its value is replaced by the new value.

    3. doc.EstimatedCost = 89

    doc.Region = "Pacific Rim"

    Call doc.Save( False, True )
  3. This script creates a new text item called Contacts in a document, and adds three new values to it.

    4. Dim doc As NotesDocument

    '...set value of doc...

    Dim stringArray ( 1 To 3 ) As String

    stringArray( 1 ) = "Chrissa Ehrhardt"

    stringArray( 2 ) = "Allegra Pisarro"

    stringArray( 3 ) = "Esteban Garcia"

    Call doc.AppendItemValue( "Contacts", stringArray )

    Call doc.Save( False, True )
  4. This script achieves the same result using the extended class syntax. The difference is that if an item called Contacts already exists in the document, its value is replaced with the values Chrissa Ehrhardt, Allegra Pisarro, and Esteban Garcia.

    5. Dim stringArray ( 1 To 3 ) As String

    stringArray ( 1 ) = "Chrissa Ehrhardt"

    stringArray ( 2 ) = "Allegra Pisarro"

    stringArray ( 3 ) = "Esteban Garcia"

    doc.Contacts = stringArray

    Call doc.Save( False, True )
  5. This script creates a new time-date item called DueDate in a document. It has the value 08/15/95 12:00:00 AM.

    6. Dim doc As NotesDocument

    '...set value of doc...

    Call doc.AppendItemValue("DueDate",  _

                             Datenumber(1995, 8, 15))

    Call doc.Save( False, True )
  6. This script achieves the same result using the extended class syntax. If an item with the name DueDate already exists on the document, its value is replaced with 08/15/95 12:00:00 AM.

    7. doc.DateDue = Datenumber( 1995, 8, 15 )

    Call doc.Save( False, True )


Example: AppendParagraphStyle method

This example appends a paragraph style to a new rich-text item.

Dim session As New NotesSession

Dim db As NotesDatabase

Set db = session.Currentdatabase

Dim doc As New NotesDocument(db)

Call doc.AppendItemValue("From", session.Username)

Call doc.AppendItemValue("subject", "Meeting agenda")

Dim rtpStyle As NotesrichTextParagraphStyle

Set rtpStyle = session.CreateRichTextParagraphStyle

Dim richText As New NotesRichTextItem(doc,"Body")

rtpStyle.InterLineSpacing = SPACING_DOUBLE

Call richText.AppendParagraphStyle(rtpStyle)

Call richText.AppendText("Where are we now?")

Call richText.AppendText(" and where do we go from here.")

Messagebox rtpStyle.InterLineSpacing

Call doc.Save(True, False)


Examples: AppendRTItem method

  1. This script takes the Body item on document B and appends it to the end of the Body item on document A. The Body item on document B is deleted using the Remove method defined in NotesItem.

    2. Dim docA As NotesDocument

    Dim docB As NotesDocument

    Dim rtitemA As Variant

    Dim rtitemB As Variant

    '...set values of docA and docB...

    Set rtitemA = docA.GetFirstItem( "Body" )

    Set rtitemB = docB.GetFirstItem( "Body" )

    If ( rtitemA.Type = RICHTEXT And _

    rtitemB.Type = RICHTEXT ) Then

      Call rtitemA.AppendRTItem( rtitemB )

      Call rtitemB.Remove

      Call docA.Save( False, True )

      Call docB.Save( False, True )

    End If
  2. This script shows you how to append one RTItem to another without a prompt to save the document. This example illustrates the use of a back-end class in the UI.

    3. Sub Click(Source As Button)

    Dim w As New NotesUIWorkspace

    Dim uidoc As NotesUIDocument

    Dim docA As NotesDocument

    Dim rtitemA As Variant

    Dim rtitemB As Variant

    Set uidoc = w.CurrentDocument

    Set docA = uidoc.Document

    Call uidoc.Save

    Set rtitemA = docA.GetFirstItem( "Body" )

    Set rtitemB = docA.GetFirstItem( "Body1" )

    If ( rtitemA.Type = RICHTEXT And _

    rtitemB.Type = RICHTEXT ) Then

    Call rtitemA.AddNewLine(1)

    Call rtitemA.AppendRTItem( rtitemB )

    docA.body1 = " "

    docA.SaveOptions = "0"

    Call docA.Save(False, True)

    Call uidoc.Close

    End IF

    End Sub

Note The changes are not visible until the document (after the script has completed) is closed and reopened. Also note that the AppendRichTextItem method appends only the first 32K of a RichTextItem; the remainder is truncated.


Example: AppendText method

This script adds two lines of text, separated by a carriage return, to the end of the Body item in a document.

Dim doc As NotesDocument

Dim rtitem As Variant

'...set value of doc...

Set rtitem = doc.GetFirstItem( "Body" )

If ( rtitem.Type = RICHTEXT ) Then

  Call rtitem.AppendText( "Add text to the rich-text item" )

  Call rtitem.AddNewLine( 1 )

  Call rtitem.AppendText("Add more text to rich-text item")

  Call doc.Save( False, True )

End If


Examples: AppendToTextList method

  1. This script appends the text value "Shocks" to the Categories item in a document. For example, if the Categories item contains the values "Clocks" and "Blocks" before the script runs, it contains the values "Clocks," "Blocks," and "Shocks" after the script runs.

    2. Dim doc As NotesDocument

    Dim item As NotesItem

    ' ...set value of doc...

    Set item = doc.GetFirstItem( "Categories" )

    Call item.AppendToTextList( "Shocks" )

    Call doc.Save( False, True )
  2. This script appends three new text values to the Categories item in a document: "Girls," "Boys," and "Toys."

    3. Dim doc As NotesDocument

    Dim item As NotesItem

    Dim newVals( 1 To 3 ) As String

    '...set value of doc...

    Set item = doc.GetFirstItem( "Categories" )

    newVals( 1 ) = "Girls"

    newVals( 2 ) = "Boys"

    newVals( 3 ) = "Toys"

    Call item.AppendToTextList( newVals )

    Call doc.Save( False, True )
  3. This script copies all of the Categories values from document A onto document B. For example, if the Categories item on document A contains "Tool" and "Weapon" and the Categories item on document B contains "Technology," then after the script runs the Categories item on document B contains three values: "Tool," "Weapon," and "Technology." Document A is unchanged.

    4. Dim docA As NotesDocument

    Dim docB As NotesDocument

    Dim item As NotesItem

    '...set values of docA and docB...

    Set item = docB.GetFirstItem( "Categories" )

    Call item.AppendToTextList( docA.Categories )

    Call docB.Save( False, True )


Examples: Authors property

  1. This script prints the name of each author of a document. For example, if Ivan Ash created the document and Kate Gaston modified it, the script displays "Ivan Ash" and "Kate Gaston."

    2. Dim doc As NotesDocument

    '...set value of doc...

    Forall a In doc.Authors

      Messagebox( a )

    End Forall
  2. This script checks to see if a document has been modified within the last seven days--if not, the script mails a reminder memo to the document authors. The script sends the value of doc.Authors directly to the Send method, since the method accepts an array of strings as its second parameter.

    3. Dim session As New NotesSession

    Dim db As NotesDatabase

    Dim doc As NotesDocument

    Dim newDoc As NotesDocument

    Dim weekDateTime As NotesDateTime

    Dim modifiedDateTime As NotesDateTime

    Set db = session.CurrentDatabase

    '...set value of doc...

    Set weekDateTime = New NotesDateTime( "Today" )

    Set modifiedDateTime = New NotesDateTime( "" )

    Call weekDateTime.AdjustDay( -7 )  ' set to one week ago

    modifiedDateTime.LSLocalTime = doc.LastModified

    If weekDateTime.TimeDifference( modifiedDateTime ) > 0  Then

      Set newDoc = New NotesDocument( db )

      newDoc.Form = "Memo"

      newDoc.Subject = _

      "Reminder: please update your project plan"

      Call newDoc.Send( False, doc.Authors )

    End If
  3. You added a new role called TeamLeaders to a database and created a compose access list so that only TeamLeaders can compose Project Plan documents. You want to make sure that everyone who's been able to create and edit Project Plan documents in the past continues to be able to do so, so you write a script to enable the TeamLeader role for all authors of existing Project Plan documents.

    4. Dim session As New NotesSession

    Dim db As NotesDatabase

    Dim acl As NotesACL

    Dim entry As NotesACLEntry

    Dim collection As NotesDocumentCollection

    Dim doc As NotesDocument

    Dim dateTime As New NotesDateTime( "12/01/94" )

    Set db = session.CurrentDatabase

    Set collection = db.FTSearch("Project Plan", 20)

    Set acl = db.ACL

    Set doc = collection.GetFirstDocument()

    While Not(doc Is Nothing)

        Call enablePeople( acl, "Team Leader", doc.Authors )

        Set doc = collection.GetNextDocument( doc )

    Wend

Sub enablePeople( acl As NotesACL, role As String, _

names As Variant )

  Dim entry As NotesACLEntry

  Forall n In names

    Set entry = acl.GetEntry( n )

    If ( entry.Level = ACLLEVEL_NOACCESS ) Then

      Set entry = New NotesACLEntry( acl, n, _

      ACLLEVEL_AUTHOR )

      Call acl.Save

    End If

    Call entry.EnableRole( role )

  End Forall

  Call acl.Save

End Sub


Example: AutoReload property

This script sets the AutoReload property just after a document is opened:

Sub Postopen(Source As Notesuidocument)

  source.AutoReload = True

End Sub


Example: AutoUpdate property

This example accesses documents in a view through the front-end view. AutoUpdate is set to False so the front-end view is not repetitively updated.

Sub Queryrecalc(Source As Notesuiview, Continue As Variant)

     Dim view As NotesView

     Dim doc As NotesDocument

     Set view = Source.View

     view.AutoUpdate = False

     Set doc = view.GetFirstDocument

     Do While Not doc Is Nothing

          Call doc.ReplaceItemValue("Categories", _

          doc.Categories(0) & "0")

          Call doc.Save(True, False)

          Set doc = view.GetNextDocument(doc)

     Loop

End Sub


Example: BackgroundColor property

This script displays the integer corresponding to the background color of the "By Category" view.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim view As NotesView

Set db = session.CurrentDatabase

Set view = db.GetView("By Category")

Messagebox "View background color: " & view.BackgroundColor


Example: Bold property

This example builds a rich-text item and sets styles so that part of the text is bold.

Sub Initialize

     Dim session As New NotesSession

     Dim db As NotesDatabase

     Set db = session.CurrentDatabase

     Dim doc As New NotesDocument(db)

     Call doc.AppendItemValue("From", session.UserName)

     Call doc.AppendItemValue("Subject", _

                              "Meeting time changed")

     Dim richStyle As NotesRichTextStyle

     Set richStyle = session.CreateRichTextStyle

     Dim richText As New NotesRichTextItem(doc, "Body")

     Call richText.AppendText("The meeting is at ")

     richStyle.Bold = True

     Call richText.AppendStyle(richStyle)

     Call richText.AppendText("3:00")

     richStyle.Bold = False

     Call richText.AppendStyle(richStyle)

     Call richText.AppendText(" not 2:00")

     Call doc.Save(True, False)

End Sub


Example: CacheLimit property

This example shows an action (the Click sub) that displays the current CacheLimit and FetchBatchSize values, sets new ones according to user input, and displays the new values. The example makes sure that FetchBatchSize is not greater than CacheLimit.

Uselsx "*LSXODBC"

%INCLUDE "lsconst.lss"

Dim con As ODBCConnection

Dim qry As ODBCQuery

Dim result As ODBCResultSet

Sub Postopen(Source As Notesuidocument)

     Set con = New ODBCConnection

     Set qry = New ODBCQuery

     Set result = New ODBCResultSet

     Set qry.Connection = con

     Set result.Query = qry

     con.ConnectTo("ATDB")

     qry.SQL = "SELECT * FROM STUDENTS ORDER BY LASTNAME"

     result.Execute

     ...

End Sub

Sub Click(Source As Button)

     Dim cacheLimit As String

     Select Case result.CacheLimit

     Case DB_ALL : cacheLimit = "DB_CALL"

     Case DB_NONE : cacheLimit = "DB_NONE"

     Case Else : cacheLimit = Cstr(result.CacheLimit)

     End Select

     If Messagebox("Current settings" & Chr(10) & Chr(10) _

     & "Cache limit: " & cacheLimit & Chr(10) _

     & "Fetch batch size: " & Cstr(result.FetchBatchSize), _

     MB_YESNO, "Do you want change?") = IDYES Then

          cLimit = Inputbox _

                   ("Enter 0 for DB_NONE or size of cache", _

                    "Cache limit?")

          If cLimit = 0 Then

               result.cacheLimit = DB_NONE

          Elseif cLimit > 0 Then

               result.cacheLimit = cLimit

          Else

               Messagebox _

               "Cache limit must be 0 or positive integer"

               Exit Sub

          End If

          fbSize = Inputbox _

                   ("Enter fetch batch size", "Fetch batch size")

          If fbSize < 1 Then

               Messagebox _

               "Fetch batch size must be positive and not zero"

               result.FetchBatchSize = 1

          Elseif cLimit <> 0 And fbSize > cLimit Then

               result.FetchBatchSize = cLimit

               Messagebox _

               "Fetch batch size cannot exceed cache limit"

          Else

               result.FetchBatchSize = fbSize

          End If

          Select Case result.CacheLimit

          Case DB_ALL : cacheLimit = "DB_ALL"

          Case DB_NONE : cacheLimit = "DB_NONE"

          Case Else : cacheLimit = Cstr(result.CacheLimit)

          End Select

          Messagebox "New settings" & Chr(10) & Chr(10) _

          & "Cache limit: " & cacheLimit & Chr(10) _

          & "Fetch batch size: " &  _

          Cstr(result.FetchBatchSize), "New settings"

     End If

End Sub

Sub Queryclose(Source As Notesuidocument, Continue As Variant)

     result.Close(DB_CLOSE)

     con.Disconnect

End Sub


Examples: CacheSize property

This Visual Basic code (the CacheSize_Click Sub) increments the cache size.

Dim s As New NotesSession

Dim db As NotesDatabase

Dim v As NotesView

Dim n As NotesViewNavigator

Private Sub CacheSize_Click()

n.CacheSize = n.CacheSize + 1

MsgBox n.CacheSize, , "Cache size"

End Sub

Private Sub InitializeNav_Click()

Set s = New NotesSession

s.Initialize

Set db = s.GetDatabase("", "Web test")

Set v = db.GetView("Main View")

Set n = v.CreateViewNav

End Sub


Example: CalendarDateTime property

This example displays the date and time of the region in a calendar view that the user just double-clicked.

Sub Regiondoubleclick(Source As Notesuiview)

     Messagebox Source.CalendarDateTime,, _

                "Date and time for this region"

End Sub


Example: CanCreateLSOrJavaAgent property

This script creates an entry for Mara Smith in the ACL and gives her Reader access with LotusScript Agent or JavaScript Agent privileges.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim acl As NotesACL

Dim entry as NotesACLEntry

Set db = session.CurrentDatabase

Set acl = db.ACL

Set entry = New NotesACLEntry(acl,"Mara Smith",ACLLEVEL_READER)

entry.CanCreateLSOrJavaAgent = True

Call acl.Save


Example: CanCreateSharedFolder property

This script creates an entry for Nedra Keen in the ACLwith Editor access and allows her to create shared folders.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim acl As NotesACL

Dim entry As NotesACLEntry

Set db = session.CurrentDatabase

Set acl = db.ACL

Set entry = New NotesACLEntry(acl,"Nedra Keen",ACLLEVEL_EDITOR)

entry.CanCreateSharedFolder = True

Call acl.Save


Example: CaretCategory property

This script displays the category corresponding to the current document.

Dim workspace As New NotesUIWorkspace

Dim view As NotesUIView

Dim category As Variant

Set view = workspace.CurrentView

category = view.CaretCategory

Messagebox category


Examples: Categories property

  1. This script prints the name of each category of the current database in a dialog box.

    2. Dim session As New NotesSession

    Dim db As NotesDatabase

    Set db = session.CurrentDatabase

    Messagebox( db.Categories )
  2. This script assigns the category "Application Template" to the current database.

    3. Dim session As New NotesSession

    Dim db As NotesDatabase

    Set db = session.CurrentDatabase

    db.Categories = "Application Template"


Example: Categorize method

This form action script saves, categorizes, and closes the current document without displaying any dialog boxes to the user. The document is categorized based on the contents of its Rating field. If the rating field is empty, the script saves and closes the document, but does not categorize it. (The action is displayed only while the document is in Edit mode.)

Sub Click(Source As Button)

  Dim workspace As New NotesUIWorkspace

  Dim uidoc As NotesUIDocument

  Dim r As String

  Set uidoc = workspace.CurrentDocument

  Call uidoc.Save

  r = uidoc.FieldGetText( "Rating" )

  Select Case r

  Case "Good":

    Call uidoc.Categorize( "Successful Projects" )

  Case "Bad":

    Call uidoc.Categorize( "Unsuccessful Projects" )

  Case "Mediocre":

    Call uidoc.Categorize( "Mediocre Projects" )

  End Select

  Call uidoc.Close

End Sub


Example: ChildCount property

This script will display the number of immediate children belonging to the Cats view entry in the By Category view.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim view As NotesView

Dim entry As NotesViewEntry

Set db = session.CurrentDatabase

Set view = db.GetView("By Category")

Set entry = view.GetEntryByKey("Cats")

Messagebox entry.ChildCount


Example: Class property

This script gets the name of the application used to create the "City picture" object in the Body item of a document, and puts it into className. For example, if the object was created with Visio®, the Class property returns "Visio.Drawing"; if the object was created with WordPro, the Class property returns "WordPro.Document".

Dim doc As NotesDocument

Dim rtitem As Variant

Dim object As NotesEmbeddedObject

Dim className As String

'...set value of doc...

Set rtitem = doc.GetFirstItem( "Body" )

If ( rtitem.Type = RICHTEXT ) Then

  Set object = rtitem.GetEmbeddedObject( "City picture" )

  className = object.Class

End If


Example: Clear method

This script deletes the contents of the current field. If the current field is empty, it does nothing.

Sub Click(Source As Button)

  Dim workspace As New NotesUIWorkspace

  Dim uidoc As NotesUIDocument

  Set uidoc = workspace.CurrentDocument

  If ( uidoc.FieldGetText( uidoc.CurrentField ) <> "" ) Then

    Call uidoc.SelectAll

    Call uidoc.Clear

  End If

End Sub


Example: Clear method

This script performs a full-text search on a view. While the view is filtered with the results of the full-text search, the script puts all the documents in the view (those documents that match the search) into a folder. The script then clears the full-text search, and places all the documents in the view (including those documents that matched the search and those that did not) into another folder. The result:

  • All documents in the Transportation view that contain the word "bicycle" are placed into the Two-wheeled vehicles folder.

  • All documents in the Transportation view, including those that contain the word "bicycle," are placed into the Vehicles folder.

    • Dim folderName As String

    Dim session As New NotesSession

    Dim db As NotesDatabase

    Dim view As NotesView

    Dim doc As NotesDocument

    Set db = session.CurrentDatabase

    Set view = db.GetView( "Transportation" )

    Call view.FTSearch( "bicycle", 0 )

    ' view is filtered

    Set doc = view.GetFirstDocument

    While Not ( doc Is Nothing )

      Call doc.PutInFolder( "Two-wheeled vehicles" )

      Set doc = view.GetNextDocument( doc )

    Wend

    ' clear the full-text search

    Call view.Clear

    ' view is no longer filtered

    ' view methods now operate on all documents in view

    ' move all documents to different folder

    Set doc = view.GetFirstDocument

    While Not ( doc Is Nothing )

      Call doc.PutInFolder( "Vehicles" )

      Set doc = view.GetNextDocument( doc )

    Wend


Example: ClearAllTabs method

This script clears the tabs from a rich-text paragraph style object.

Dim session As New NotesSession

Dim db As NotesDatabase

Set db = session.CurrentDatabase

Dim doc As New NotesDocument(db)

Call doc.AppendItemValue("From", session.UserName)

Call doc.AppendItemValue("Subject", _

     "Meeting time changed")

Dim rtpStyle As NotesRichTextParagraphStyle

Dim pos As Long

Dim interval As Long

Set rtpStyle = session.CreateRichTextParagraphStyle

pos = RULER_ONE_INCH

Call rtpStyle.SetTab(pos, TAB_DECIMAL)

Call rtpStyle.ClearAllTabs()

Dim richText As New NotesRichTextItem(doc, "Body")

Call richText.AppendParagraphStyle(rtpStyle)

Call richText.AddTab(1)

Call richText.AppendText("The meeting is at 2:00 not 3:00")

Call doc.Save(True, False)


Example: ClearHistory method

This script clears the replication history of the current database.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim rep As NotesReplication

Set db = session.CurrentDatabase

Set rep = db.ReplicationInfo

Call db.Replicate("Xanadu")

Call rep.ClearHistory()

Call rep.Save()


Example: Close method

This script opens and then closes a mail log. When the Close method is called, the log gets mailed.

Dim currentLog As New NotesLog( "Log closing" )

Call currentLog.OpenMailLog( "Jimmy Ho", "Here's your log" )

'...log some errors and actions...

Call currentLog.Close   ' mail memo gets sent to Jimmy Ho now


Example: Close method

This agent adds a new row to a table, then closes the table and re-executes the query to display the entire table, including the new row.

Uselsx "*LSXODBC"

Sub Initialize

     Dim con As New ODBCConnection

     Dim qry As New ODBCQuery

     Dim result As New ODBCResultSet

     Dim firstName As String

     Dim lastName As String

     Dim msg As String

     On Error Goto errorHandler

     Set qry.Connection = con

     Set result.Query = qry

     con.ConnectTo("ATDB")

     qry.SQL = "SELECT * FROM STUDENTS"

     result.Execute

     result.AddRow

     Call result.SetValue("LASTNAME", _

     Inputbox$("Last name?", "New student", "Rodriguez"))

     Call result.SetValue("FIRSTNAME", _

     Inputbox$("First name?", "New student", "Jorges"))

     Call result.SetValue("STUDENT_NO", _

     Cint(Inputbox$("Student number?", "New student",_

                   "9999")))

     Call result.SetValue("ADDRESS", _

     Inputbox$("Address?", "New student", "11 Rogers St."))

     Call result.SetValue("CITY", _

     Inputbox$("City?", "New student", "Cambridge"))

     Call result.SetValue("STATE", _

     Inputbox$("State?", "New student", "MA"))

     Call result.SetValue("ZIP", _

     Inputbox$("Zip?", "New student", "02142"))

     Call result.SetValue("CR_TO_DATE", _

     Cint(Inputbox$("Credits to date?", "New student", "0")))

     result.UpdateRow

     result.Close(DB_CLOSE)

     result.Execute

     msg = "Student names:" & Chr(10)

     Do

          result.NextRow

          msg = msg & Chr(10)

          For i = 1 To result.NumColumns

               msg = msg & "  " & result.GetValue(i)

          Next

     Loop Until result.IsEndOfData

     Messagebox msg,, "Student data"

     result.Close(DB_CLOSE)

     con.Disconnect

     Exit Sub

errorHandler:

     Messagebox result.GetExtendedErrorMessage,, result.GetErrorMessage

     Exit Sub

End Sub


Example: Close method

This button script closes the current document.

Sub Click(Source As Button)

  Dim workspace As New NotesUIWorkspace

  Dim uidoc As NotesUIDocument

  Set uidoc = workspace.CurrentDocument

  Call uidoc.Close

End Sub


Example: CollapseAllSections method

This script checks to see if the current user has the role Lurker in the current database. If so, it collapses all the sections on the document after the user opens the document.

Sub Postopen(Source As Notesuidocument)

  Dim session As New NotesSession

  Dim db As NotesDatabase

  Dim acl As NotesACL

  Dim entry As NotesACLEntry

  Set db = session.CurrentDatabase

  Set acl = db.ACL

  Set entry = acl.GetEntry( session.CommonUserName )

  If ( entry.IsRoleEnabled( "Lurker" ) ) Then

    Call source.CollapseAllSections

  End If

End Sub


Examples: Collecting all documents and unprocessed documents

  1. This example collects all the documents in a database with the AllDocuments property of NotesDatabase, and traverses the collection by using the Count property and the GetNthDocument method of NotesDocumentCollection.

    2. Sub INITIALIZE

         Dim db As New NotesDatabase _

         ("", Inputbox("Name of database file?"))

         Dim dc As NotesDocumentCollection

         Dim doc As NotesDocument

         Set dc = db.AllDocuments

         For j =  1 To dc.Count

              Set doc = dc.GetNthDocument(j)

              Messagebox doc.Subject(0)

         Next

    End Sub
  2. This example collects all the documents in a database with the AllDocuments property of NotesDatabase, and traverses the collection by using the GetFirstDocument and GetNextDocument methods of NotesDocumentCollection. Alternatively you can use the GetLastDocument and GetPrevDocument methods to traverse the collection backwards.

    3. Sub INITIALIZE

         Dim db As New NotesDatabase _

         ("", Inputbox("Name of database file?"))

         Dim dc As NotesDocumentCollection

         Dim doc As NotesDocument

         Set dc = db.AllDocuments

         Set doc = dc.GetFirstDocument()

         While Not(Doc Is Nothing)

              Messagebox doc.Subject(0)

              Set doc = dc.GetNextDocument(doc)

         Wend

    End Sub
  3. This example collects all the documents in a database with the AllDocuments property of NotesDatabase, retrieves a document by using the GetDocument method of NotesDocumentCollection, and displays it's note ID.

    4. Sub Initialize

         Dim session As New NotesSession

         Dim db As NotesDatabase

         Dim db2 As New NotesDatabase(local, "test2.nsf")

         Dim collection As NotesDocumentCollection

         Dim docA As NotesDocument

         Dim docB As NotesDocument

         Set db = session.CurrentDatabase

         Set collection = db.AllDocuments

         Set docA = collection.GetFirstDocument

         Set docB = collection.GetDocument(docA)

         Messagebox "Note ID: " & docB.NoteID

    End Sub


Examples: Collecting documents by searching

  1. This example creates a full-text index if one does not exist, then finds all documents containing the word "alpha" or the string "string beta."

    2. Sub INITIALIZE

         Dim db As New NotesDatabase _

         ("", Inputbox("Name of database file?"))

         Dim dc As NotesDocumentCollection

         Dim doc As NotesDocument

         If db.IsFTIndexed = False Then

              Call db.UpdateFTIndex(True)

         End If

         Set dc = db.FTSearch("alpha" | "string beta""", 0)

         For J = 1 To dc.Count

              Set doc = dc.GetNthDocument(J)

              Messagebox doc.Subject(0)

         Next

    End Sub
  2. This example solicits a search token from the user and finds all documents containing the token using @Contains from the Notes formula language. The example also displays some of the properties of the NotesDocumentCollection object.

    3. Sub Click(Source As Button)

         Dim session As New NotesSession

         Dim dt As New NotesDateTime("07/03/95")

         Dim db As NotesDatabase

         Dim dc As NotesDocumentCollection

         Dim doc As NotesDocument

         Set db = session.CurrentDatabase

         token = Inputbox$("What do you want to search for?")

         notesFormula = "@Contains(Subject; " & token & ")"

         Set dc = db.Search(notesFormula, dt, 0)

         Messagebox("Count = " & dc.Count)

         Messagebox("Query = " & dc.Query)

         For j = 1 To dc.Count

              Set doc = dc.GetNthDocument(j)

              Messagebox doc.Subject(0)

         Next

    End Sub


Example: ColumnCount property

This script displays the number of columns in the By Category view of the current database.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim view As NotesView

Set db = session.CurrentDatabase

Set view = db.GetView("By Category")

Messagebox "View column count: " & view.ColumnCount


Examples: ColumnNames property

This Visual Basic displays the names of all the columns in a view.

Private Sub ViewColumnNames_Click()

Dim s As New NotesSession

s.Initialize

Dim dir As NotesDbDirectory

Dim db As NotesDatabase

Dim v As NotesView

Dim cns As String

Set dir = s.GetDbDirectory("")

Set db = dir.OpenDatabase("Web test")

Set v = db.GetView("Main View")

For Each cn In v.ColumnNames

    cns = cns + cn + Chr(10)

Next

MsgBox cns, , "Columns in Main View"

End Sub


Example: Columns property

This script prints the title of each column in a view of the WALNUT.NSF. It uses the Title property of the NotesViewColumn class.

server$ = "Montreal"

dbfile$ = "corpcomm\walnut.nsf"

Dim db As New NotesDatabase( server$, dbfile$ )

Dim view As NotesView

Set view = db.GetView( "By Date\Ascending By Main Topic" )

Forall c In view.Columns

  Messagebox ( c.Title )

End Forall


Examples: ColumnValues property

  1. You retrieve a document called currentDoc from a view that has two columns: the first shows the due date of a project (its column formula is the field DueDate), the second describes the project (its formula is "New Project: " + Description).

    2. On the currentDoc, the DueDate item contains 10/16/95 and the Description item contains "Ad Campaign for Acme." Therefore,

    currentDoc.ColumnValues(0) equals 10/16/95

    currentDoc.ColumnValues(1) equals _

            "New Project: Ad Campaign for Acme"
  2. You want to look up all the products in the Products view of an Inventory database. This script finds the view and then visits each document in the view to retrieve its first column value (which holds the product name). This is equivalent to performing an @DbColumn.

    3. server$ = "Tilburg"

    dbfile$ = "inventor.nsf"

    counter% = 1

    Dim db As New NotesDatabase( server$, dbfile$ )

    Dim view As NotesView

    Dim doc As NotesDocument

    Dim productList( 1 To 100 ) As Variant

    Dim currentProduct As Variant

    Set view = db.GetView( "Products" )

    Set doc = view.GetFirstDocument

    While Not ( doc Is Nothing )

    ' Get the value on the current document that shows up in

    ' view's first column

    ' Append this value to our productList array

      currentProduct = doc.ColumnValues( 0 )

      productList( counter% ) = currentProduct

      Set doc = view.GetNextDocument( doc )

      counter% = counter% + 1

    Wend

    ' There are now counter% - 1 items in the productList


Example: ColumnValues property

This script prints the column values of the Cars view entry in the By Category view.

Dim session As New NotesSession

Dim db As New NotesDatabase("","test.nsf")

Dim view As NotesView

Dim entry As NotesViewEntry

Set view = db.GetView("By Category")

Set entry = view.GetEntryByKey("Cars")

Messagebox entry.ColumnValues(0)

Messagebox entry.ColumnValues(1)

Messagebox entry.ColumnValues(2)

Messagebox entry.ColumnValues(3)

Messagebox entry.ColumnValues(4)


Examples: Comment property

  1. This script gets the comment for the agent that's currently running. For example, if this script were part of the "Archive" agent, the Comment property might return "This agent archives selected documents."

    2. Dim session As New NotesSession

    Dim agent As NotesAgent

    Dim c As String

    Set agent = session.CurrentAgent

    c = agent.Comment
  2. This script creates a summary of the public, enabled agents in the current database, listing each agent's name and comment. The document containing the summary is then mailed to the database's managers.

    3. Dim session As New NotesSession

    Dim db As NotesDatabase

    Dim doc As NotesDocument

    Dim rtitem As NotesRichTextItem

    Set db = session.CurrentDatabase

    Set doc = New NotesDocument( db )

    Set rtitem = New NotesRichTextItem( doc, "Body" )

    Forall a In db.Agents

      If ( a.IsPublic And a.IsEnabled ) Then

        Call rtitem.AppendText( a.Name )

        Call rtitem.AddTab( 2 )

        Call rtitem.AppendText( a.Comment )

        Call rtitem.AddNewLine( 1 )

      End If

    End Forall

    doc.Subject = "Public agent summary for " & db.Title

    Call doc.Send( False, db.Managers )
    For example, if there are three public, enabled agents in the current database, the Body of the summary document might look like this:

    Archive | This agent archives selected documents
Phone Number | Looks up an employee's phone number
Total | Calculates the total revenues for the quarter


Examples: Comment property

This script displays the text contained in the comment property of an outline.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim outline As NotesOutline

Set db = session.CurrentDatabase

Set outline = db.GetOutline("MyOutline")

Messagebox outline.Comment


Example: CommonOwner property

This script gets the common name of the person who last modified the current agent. For example, if Yukiko Kitamura/Tokyo/Production created the agent and then Mariko Ikebuchi/Tokyo/Production modified it, Mariko is considered to be the owner and the CurrentAgent property returns "Mariko Ikebuchi."

' created by Yukiko Kitamura 11/28/95

' modified by Mariko Ikebuchi 12/17/95

Dim session As New NotesSession

Dim agent As NotesAgent

Dim owner As String

Set agent = session.CurrentAgent

owner = agent.CommonOwner


Examples: CommonUserName property

  1. In this button script, the variable user gets assigned the current user's common name. Because the script runs on the workstation, the user's common name belongs to the person using Notes at the time. For example, if user Stew Malone/Editorial/Acme clicks the button, the CommonUserName property returns "Stew Malone."

    2. Sub Click(Source As Button)

      Dim session As New NotesSession

      Dim user As String

      user = session.CommonUserName

    End Sub
  2. In this agent script, the variable user gets assigned the current user's common name. For example, if the agent runs when new mail arrives on server Toronto/Editorial/Acme, the CommonUserName property returns "Toronto" because the current user is the server. If user Stew Malone/Editorial/Acme runs the agent manually from the menu, it returns "Stew Malone" because the current user is Stew Malone.

    3. Sub Initialize

      Dim session As New NotesSession

      Dim user As String

      user = session.CommonUserName

    End Sub


Examples: Compact method

  1. This script compacts WHITESPC.NSF if less than 85% of its disk space is occupied by real data.

    2. Dim db As New NotesDatabase( "", "whitespc.nsf" )

    If ( db.PercentUsed < 85 ) Then

      Call db.Compact

    End If
  2. This script compacts TOOBIG.NSF if less than 90% of its disk space is occupied by real data. It displays a message indicating the number of bytes that have been freed.

    3. Dim db As New NotesDatabase( "", "toobig.nsf" )

    Dim delta As Long

    If ( db.PercentUsed < 90 ) Then

      delta = db.Compact

      Messagebox( "You've freed " & delta & " bytes" )

    End If


Examples: ComposeDocument method

  1. This view action script composes a new Main Topic document in the current database.

    2. Sub Click(Source As Button)

      Dim workspace As New NotesUIWorkspace

      Call workspace.ComposeDocument( "", "", "Main Topic" )

    End Sub
  2. This view action script composes a new Main Topic document in the current database and moves the insertion point to the ProjectDescription field.

    3. Sub Click(Source As Button)

      Dim workspace As New NotesUIWorkspace

      Dim uidoc As NotesUIDocument

      Set uidoc = workspace.ComposeDocument _

      ( "", "", "Main Topic" )

      Call uidoc.GoToField( "ProjectDescription" )

    End Sub
  3. This form action script copies the contents of the current document's Topic field to the Clipboard. It composes a new Memo document in HERE.NSF on server Rio (changing the value of the uidoc object), and pastes the contents of the Clipboard into the new document's Subject field.

Sub Click(Source As Button)

  Dim workspace As New NotesUIWorkspace

  Dim uidoc As NotesUIDocument

  Set uidoc = workspace.CurrentDocument

  Call uidoc.GotoField( "Topic" )

  Call uidoc.SelectAll

  Call uidoc.Copy

  Set uidoc = workspace.ComposeDocument _

  ( "Rio", "here.nsf", "Memo" )

  Call uidoc.GotoField( "Subject" )

  Call uidoc.Paste

End Sub


Example: ComputeWithForm method

This script creates a new document in the current database, sets its Form item to "Notification," and sets the value of the Topic item. The Notification form has the following input validation formula for the Subject field:

@If( Subject = ""; @Failure( "You must enter a Subject" ); @Success )

Because the script has not created a Subject item on the document, validation fails, ComputeWithForm returns False, and the document is not saved.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim doc As NotesDocument

Dim success As Variant

Set db = session.CurrentDatabase

Set doc = New NotesDocument( db )

doc.Form = "Notification"

doc.Topic = "Large bodies of water"

success = doc.ComputeWithForm( False, False )

If success Then

  Call doc.Save( True, True )

End If


Examples: Connecting to an external database

  1. This agent declares a new ODBCConnection object and displays the name of the available data sources. You must include the Uselsx "*LSXODBC" statement in the (Options) script of the agent.

    2. Uselsx "*LSXODBC"

    Sub Initialize

         Dim con As New ODBCConnection

         Dim msg As String

         Dim dsnList as Variant

         dsnList = con.ListDataSources

         For n% = Lbound(dsnList) To Ubound(dsnList)

              msg = msg & dsnList(n%) & Chr(10)

         Next

         Messagebox msg,,"List of DSNs"

    End Sub
  2. This agent connects to a data source specified by the user. If the connection fails, IsConnected is False and the agent exits. (Alternatively, you can test the return value of ConnectTo, as shown in the code that is remarked out, rather than test IsConnected.) If the connection is good, the agent lists the tables for the data source by looping through the string array returned by ListTables, then disconnects before terminating.

    3. Uselsx "*LSXODBC"

    Sub Initialize

         Dim con As New ODBCConnection

         Dim dsn As String

         Dim msg As String

         dsn = Inputbox("ODBC data source name", "DSN")

         REM If Not con.ConnectTo(dsn) Then

         con.ConnectTo(dsn)

         If Not con.IsConnected Then

              Messagebox "Could not connect to " & dsn,, _

                         "Error"

              Exit Sub

         End If

         tables = con.ListTables(dsn)

         msg = dsn & " contains the following _

                       tables:" & Chr(10)

         For n% = Lbound(tables) To Ubound(tables)

              msg = msg & Chr(10) & tables(n%)

         Next

         Messagebox msg,, "Tables for " & dsn

         con.Disconnect

    End Sub
  3. This example is a form that contains two text fields named dataSource and Table, two buttons with the same names, and two actions named "List tables" and "List procedures." Notice the use of global declarations so that all the scripts on the form can access the same objects and the data. The form's Postopen script sets the objects, gets the names of the available data sources, writes the first one to the dataSource field, gets the names of the tables for the data source, and writes the first one to the Table field. The "Data source" button writes the name of the next data source to the dataSource field, gets the tables for the new data source, and writes the first one to the Table field. The "Table" button writes the name of the next table to the Table field. The "List fields" action displays the names of all the fields for the current data source and table. The "List procedures" action displays the name of all the procedures for the current data source.

    4. Uselsx "*LSXODBC"

    (Globals) (Declarations)

    Dim con As ODBCConnection

    Dim dataSources As Variant

    Dim tables As Variant

    Dim thisdsn As Integer

    Dim thistable As Integer

    Dim workspace As NotesUIWorkspace

    Dim uidoc As NotesUIDocument

    Sub Postopen(Source As Notesuidocument)

         Set workspace = New NotesUIWorkspace

         Set uidoc = workspace.CurrentDocument

         Set con = New ODBCConnection

         con.SilentMode = True

         dataSources = con.ListDataSources

         thisdsn = Lbound(dataSources)

         Call uidoc.FieldSetText("dataSource", & _

                                dataSources(thisdsn))

         tables = con.ListTables(dataSources(thisdsn))

         If Ubound(tables) <> 0 Then

              thistable = Lbound(tables)

              Call uidoc.FieldSetText("Table", & _

                                    tables(thistable))

         End If

    End Sub

    Sub Queryclose(Source As Notesuidocument, Continue As Variant)

         If con.IsConnected Then

              con.Disconnect

         End If

    End Sub

    REM "Data source" button

    Sub Click(Source As Button)

         If thisdsn = Ubound(dataSources) Then

              thisdsn = Lbound(dataSources)

         Else

              thisdsn = thisdsn + 1

         End If

         Call uidoc.FieldSetText("dataSource", & _

                                dataSources(thisdsn))

         tables = con.ListTables(dataSources(thisdsn))

         If Ubound(tables) <> 0 Then

              thistable = Lbound(tables)

              Call uidoc.FieldSetText("Table", & _

                                     tables(thistable))

         End If

    End Sub

    REM "Table" button

    Sub Click(Source As Button)

         If Ubound(tables) <> 0 Then

              If thistable = Ubound(tables) Then

                   thistable = Lbound(tables)

              Else

                   thistable = thistable + 1

              End If

              Call uidoc.FieldSetText("Table", tables(thistable))

         End If

    End Sub

    REM "List tables" action

    Sub Click(Source As Button)

         Dim msg As String

         con.ConnectTo(dataSources(thisdsn))

         If con.IsConnected Then

              fields = con.ListFields(tables(thistable))

              If Ubound(fields) <> 0 Then

                   msg = tables(thistable) & _

                 " contains the following fields:" & Chr(10)

                   For o% = Lbound(fields) To Ubound(fields)

                        msg = msg & Chr(10) & fields(o%)

                   Next

                   Messagebox msg,, con.DataSourceName

              Else

                   Messagebox "No fields in "  _

                  & tables(thistable),, _

                    con.DataSourceName

              End If

              con.Disconnect

         End If

    End Sub

    REM "List procedures" action

    Sub Click(Source As Button)

         Dim msg As String

         con.ConnectTo(dataSources(thisdsn))

         If con.IsConnected Then

              procs = con.ListProcedures

              If Ubound(procs) <> 0 Then

                   msg = con.DataSourceName & _

                   " contains the following procedures:" _

                   & Chr(10)

                   For o% = Lbound(procs) To Ubound(procs)

                        msg = msg & Chr(10) & procs(o%)

                   Next

                   Messagebox msg,, con.DataSourceName

              Else

                   Messagebox "No procedures",, _

                   con.DataSourceName

              End If

              con.Disconnect

         End If

    End Sub

See also
Connecting to an external database


Example: Connection property

The following example of form scripts sets up the necessary query connections in the Postopen script. The Connection property of ODBCQuery must specify an ODBCConnection object. The Query property of ODBCResultSet must specify the ODBCQuery object.

Uselsx "*LSXODBC"

Dim con As ODBCConnection

Dim qry As ODBCQuery

Dim result As ODBCResultSet

Sub Postopen(Source As Notesuidocument)

     Set con = New ODBCConnection

     Set qry = New ODBCQuery

     Set result = New ODBCResultSet

     Set qry.Connection = con

     Set result.Query = qry

End Sub

Sub Click(Source As Button)

     Dim firstName As String

     Dim lastName As String

     Dim msg As String

     con.ConnectTo("ATDB")

     qry.SQL = "SELECT * FROM STUDENTS"

     result.Execute

     If result.IsResultSetAvailable Then

          msg = "Student names:" & Chr(10)

          Do

               result.NextRow

               firstName = result.GetValue("FIRSTNAME",  _

                                           firstName)

               lastName = result.GetValue("LASTNAME", _

                                          lastName)

               msg = msg & Chr(10) & firstName & " " & _

                lastName

          Loop Until result.IsEndOfData

          Messagebox msg,, "Student names"

          result.Close(DB_CLOSE)

     Else

          Messagebox "Cannot get result set"

          Exit Sub

     End If

     con.Disconnect

End Sub


Example: ConnectTo method

The following form action gets the name of a data source, plus an optional user name and password, and attempts to connect to the data source.

Uselsx "*LSXODBC"

Dim con As ODBCConnection

Sub Postopen(Source As Notesuidocument)

     Set con = New ODBCConnection

End Sub

Sub Click(Source As Button)

     Dim dataSource As String

     Dim userName As String

     Dim password As String

     dataSource = Inputbox$ _

                  ("Enter name of data source",

                  "Data source?")

     userName = Inputbox$ _

                ("Enter user name, if required", "User name?")

     If userName = "" Then

       If Not con.ConnectTo(dataSource) Then

            Messagebox "Could not connect to " & dataSource

       End If

     Else

       password = Inputbox$("Enter password", "Password?")

       If Not con.ConnectTo(dataSource, _

                           userName, password) Then

            Messagebox "Could not connect to " & dataSource

          End If

     End If

End Sub

Sub Queryclose(Source As NotesUIDocument, Continue As Variant)

     con.Disconnect

End Sub


Examples: Contains method

  1. Your project on exotic orchids takes top priority next week, so you want to place all orchid-related mail in the folder "Next week." This script checks a document to see if "Exotic Orchids" is one of its categories; if so, the document is placed in the folder. The document may contain several values in its Categories item; as long as one of the values matches "Exotic Orchids," the Contains method returns True.

    2. Set category = memo.GetFirstItem( "Categories" )

    If category.Contains( "Exotic Orchids" ) Then

      Call memo.PutInFolder( "Next week" )

    End If
  2. This script shows an incorrect use Contains. It categorizes a document based on the contents of its Subject. If the memo's Subject item is "Here's my status report," the Contains method returns False because the values "Here's my status report" and "status" do not match.

    3. Dim doc As NotesDocument

    Dim item As NotesItem

    '...set value of doc...

    Set item = doc.GetFirstItem( "Subject" )

    If item.Contains( "status" ) Then

      doc.Categories = "Status reports"

      Call doc.Save( True, True )

    End If


Example: Converting between Domino Designer and LotusScript time

This example writes the DateComposed item from a Domino Designer document to the LocalTime property of a NotesDateTime object, then accesses the LSLocalTime property of that object with the Weekday LotusScript function.

Sub Click(Source As Button)

     Dim workspace As New NotesUIWorkspace

     Dim uidoc As NotesUIDocument

     Dim doc As NotesDocument

     Dim dateComposedObj As New NotesDateTime("")

     Set uidoc = workspace.CurrentDocument

     Set doc = uidoc.Document

     dateComposed = doc.DateComposed

     dateComposedObj.LSLocalTime = dateComposed(0)

     thisWeekday = Weekday(dateComposedObj.LocalTime)

     Select Case thisWeekday

     Case 1 : stringWeekday = "Sunday"

     Case 2 : stringWeekday = "Monday"

     Case 3 : stringWeekday = "Tuesday"

     Case 4 : stringWeekday = "Wednesday"

     Case 5 : stringWeekday = "Thursday"

     Case 6 : stringWeekday = "Friday"

     Case 7 : stringWeekday = "Saturday"

     End Select

     Messagebox _

     ("This document was composed on a " & stringWeekday)

End Sub


Example: ConvertToZone method

This code converts today at 6:00 AM to all the time zones using daylight savings.

Sub Initialize

  Dim dateTime As New NotesDateTime("Today 06:00")

  msg = "Zone" & Chr(9) + "Time"

  For i = -12 To 12

    Call dateTime.ConvertToZone(i, True)

    msg = msg & Chr(10) & dateTime.TimeZone & Chr(9) & dateTime.ZoneTime

  Next

  Messagebox msg,, "Today 06:00 DST"

End Sub


Example: Copy method

This button script copies the contents of the Description field to the Clipboard.

Sub Click(Source As Button)

  Dim workspace As New NotesUIWorkspace

  Dim uidoc As NotesUIDocument

  Set uidoc = workspace.CurrentDocument

  Call uidoc.GoToField( "Description" )

  Call uidoc.SelectAll

  Call uidoc.Copy

End Sub


Example: CopyAllItems method

This script copies all the items on docA into docB and then saves docB. For example, if docA has Subject, Form, and Body items, they are copied into docB. Items in docB are replaced, not addended.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim docA As NotesDocument

Dim docB As NotesDocument

Set db = session.CurrentDatabase

'...set value of docA...

Set docB = New NotesDocument( db )

Call docA.CopyAllItems( docB, True )

Call docB.Save( True, True )


Examples: Copying a document

  1. This example makes a copy of the first document in the CategoryView view in the same database.

    2. Sub Initialize

         Dim session As New NotesSession

         Dim db As NotesDatabase

         Dim view As NotesView

         Set db = session.CurrentDatabase

         Set view = db.GetView("CategoryView")

         Set doc = view.GetFirstDocument

         Call doc.CopyToDatabase(db)

    End Sub
  2. This example copies selected documents from one database to another.

    3. Sub Initialize

         Dim session As New NotesSession

         Dim db As NotesDatabase

         Dim db2 As NotesDatabase

         Dim dc As NotesDocumentCollection

         Dim doc As NotesDocument

         Set db = session.CurrentDatabase

         Set db2 = New NotesDatabase _

         ("", Inputbox("Name of database file?"))

         Call db.UpdateFTIndex(True)

         Set dc = db.FTSearch("Acme", 0)

         For j = 1 To dc.Count

              Set doc = dc.GetNthDocument(j)

              'Use the call statement because to return

              'value is needed

              Call doc.CopyToDatabase(db2)

         Next

    End Sub


Examples: Copying an item

  1. This example of a form button creates a document in the current database, creates a Subject item with the value "NEW SUBJECT," and copies the Categories and Body items to it from the current document.

    2. Sub Click(Source As Button)

         Dim session As New NotesSession

         Dim workspace As New NotesUIWorkspace

         Dim db As NotesDatabase

         Dim uidoc As NotesUIDocument

         Dim doc As NotesDocument, doc2 As NotesDocument

         Dim item As NotesItem

         Set uidoc = workspace.CurrentDocument

         Set doc = uidoc.Document

         Set db = session.CurrentDatabase

         Set doc2 = New NotesDocument(db)

         doc2.Subject = "NEW SUBJECT"

         Set item = doc.GetFirstItem("Categories")

         Call item.CopyItemToDocument(doc2, "Categories")

         Set item = doc.GetFirstItem("Body")

         Call item.CopyItemToDocument(doc2, "Body")

         Call doc2.Save(True, False)

    End Sub
  2. This example of a form button creates a document in the current database and copies to it all items from the current document.

    3. Sub Click(Source As Button)

         Dim session As New NotesSession

         Dim workspace As New NotesUIWorkspace

         Dim db As NotesDatabase

         Dim uidoc As NotesUIDocument

         Dim doc As NotesDocument, doc2 As NotesDocument

         Set uidoc = workspace.CurrentDocument

         Set doc = uidoc.Document

         Set db = session.CurrentDatabase

         Set doc2 = New NotesDocument(db)

         Call doc.CopyAllItems(doc2)

         Call doc2.Save(True, False)

    End Sub


Example: CopyItem method

This script creates a new mail memo and copies the Body item from a saved document to the memo. This example uses the Call statement.

Dim db As New NotesDatabase( "", "review.nsf" )

Dim doc As NotesDocument

Dim memo As NotesDocument

Dim item As NotesItem

'...set value of doc...

Set item = doc.GetFirstItem( "Body" )

Set memo = New NotesDocument( db )

memo.Form = "Memo"

memo.Subject = "Here's a copy of the review."

Call memo.CopyItem( item, "Body" )

Call memo.Send( False, "Viquinha Mayer" )


Example: CopyItemToDocument method

This script copies the Body and BriefDescription items from a document to a new mail memo in the current database. The Body item keeps its name; the BriefDescription item is renamed Subject.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim doc As NotesDocument

Dim memo As NotesDocument

Dim itemA As NotesItem

Dim itemB As NotesItem

Set db = session.CurrentDatabase

'...set value of doc...

Set itemA = doc.GetFirstItem( "Body" )

Set itemB = doc.GetFirstItem( "BriefDescription" )

Set memo = New NotesDocument( db )

Call itemA.CopyItemToDocument( memo, "" )

Call itemB.CopyItemToDocument( memo, "Subject" )

Call memo.Send( False, "Cynthia Brainey" )


Example: CopyToDatabase method

This script checks if a document was created before August 12, 1995. If so, it copies the document to an archive database.

Dim archiveDb As New NotesDatabase( "", "" )

Dim doc  As NotesDocument

'...set value of archiveDb...

'...set value of doc...

If ( doc.Created < Datenumber( 1995, 8, 12 ) ) Then

  Call doc.CopyToDatabase( archiveDb )

'You can use the call statement because the

'program does not need the return value

'(a handle to the new document)

End If


Examples: Count property

  1. This script displays the total number of documents in the collection.

    2. Dim session As New NotesSession

    Dim db As NotesDatabase

    Dim collection As NotesDocumentCollection

    Set db = session.CurrentDatabase

    Set collection = db.FTSearch("Business",10)

    Messagebox collection.Count
  2. This script uses Count and GetNextDocument in a For loop to put every document in a collection into a folder called "Cellar." The collection consists of documents that contain the phrase "red wine."

    3. Dim session As New NotesSession

    Dim db As NotesDatabase

    Dim collection As NotesDocumentCollection

    Dim doc As NotesDocument

    Dim j As Integer

    Set db = session.CurrentDatabase

    Set collection = db.FTSearch( "red wine", 0 )

    Set doc = collection.GetFirstDocument()

    For j = 1 To collection.Count

        Call doc.PutInFolder( "Cellar",True )

        Set doc = collection.GetNextDocument( doc )

    Next

    Messagebox collection.Count


Example: Count property

This script displays the number of entries in the Manufacturer category in the By Category view.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim view As NotesView

Dim vc As NotesViewEntryCollection

Set db = session.CurrentDatabase

Set view = db.GetView("By Category")

Set vc = view.GetAllEntriesByKey("Manufacturer")

Messagebox vc.Count


Examples: Create method

  1. This script creates a new database on the server Zagreb and sets its title to Inventory Tracking.

    2. Dim db As New NotesDatabase( "", "" )

    Call db.Create( "Zagreb", "inventry.nsf", True )

    db.Title = "Inventory Tracking"
  2. This script tests if the database QUACK.NSF exists on the current computer. If not, it uses the Create method to create a new database with the file name QUACK.NSF.

    3. Dim db As New NotesDatabase( "", "quack.nsf" )

    If db.IsOpen Then

      Messagebox( "The database quack.nsf already exists." )

    Else

      Messagebox( "Creating the database quack.nsf...")

      Call db.Create( "", "", True )

      db.Title = "Ducks of North America"

    End If


Examples: CreateCopy method

  1. This script creates an empty copy of the database PURCHASE.NSF on the server Athens.

    2. Dim db, archiveDb As NotesDatabase

    Set db = New NotesDatabase( "Athens","purchase.nsf" )

    Set archiveDb = db.CreateCopy _

    ( "Athens","archive\purchase.nsf" )
  2. This script archives all documents in the current database whose age item equals "old". It calls CreateCopy only if the archive database does not exist yet. You can use the script before or after the archive database has been created.

    3. Dim session As New NotesSession

    Dim db As NotesDatabase

    Dim archiveDb As NotesDatabase

    Dim collection As NotesDocumentCollection

    Dim doc As NotesDocument

    Dim dateTime As New NotesDateTime( "1/1/94" )

    Set db = session.CurrentDatabase

    Set archiveDb = New NotesDatabase( "", "" )

    archiveServer$ = ""

    archiveFile$ = "archive\"+db.FileName

    If (Not(archiveDb.Open(archiveServer$, archiveFile$))) Then

      Set archiveDb = db.CreateCopy( archiveServer$, _

      archiveFile$ )

    End If

    Set collection = db.Search( "age = ""old"" ", _

    dateTime, 0 )

    For i = 1 To collection.Count

      Set doc = collection.GetNthDocument( i )

      Call doc.CopyToDatabase( archiveDb )

      Call doc.Remove( False )

    Next


Examples: Created property

  1. This script gets the date that the current database was created. For example, the Created property might return 10/15/95 4:43:51 PM.

    2. Dim session As New NotesSession

    Dim db As NotesDatabase

    Dim createDate As Variant

    Set db = session.CurrentDatabase

    createDate = db.Created
  2. This script checks each database on the server Paris to see if the database was created in the last five days. If so, it sends a memo to the database managers asking them to read and follow the company rules about database maintenance.

    3. Dim directory As New NotesDbDirectory( "Paris" )

    Dim db As NotesDatabase

    Set db = directory.GetFirstDatabase( DATABASE )

    While Not ( db Is Nothing )

      Call db.Open( "", "" )

      If ( ( Today - db.Created ) <= 5 ) Then

        Set doc = New NotesDocument( db )

        doc.Form = "Memo"

        doc.Subject = "Your new database: " + db.Title

        doc.Body =

        "Please read rules for db maintenance."

        Call doc.Send( False, db.Managers )

      End If

      Call db.Close

      Set db = directory.GetNextDatabase

    Wend


Examples: Created property

  1. If the last document in the Main View of the current database was created on February 7, 1995 at 10:17:16 A.M., this script prints "2/7/95 10:17:16 AM."

    2. Dim session As New NotesSession

    Dim db As NotesDatabase

    Dim view As NotesView

    Dim doc As NotesDocument

    Dim createDate As Variant

    Set db = session.CurrentDatabase

    Set view = db.GetView( "Main View" )

    Set doc = view.GetLastDocument

    createDate = doc.Created

    Messagebox( createDate )
  2. This script uses the Created property to see if a document was created before August 12, 1995. If so, the document is copied to another database and removed from the current database.

    3. Dim doc  As NotesDocument

    Dim archiveDb As NotesDatabase

    '...set value of doc...

    '...set value of archiveDb...

    If ( doc.Created < Datenumber( 1995, 8, 12 ) ) Then

      Call doc.CopyToDatabase( archiveDb )

      Call doc.Remove( False )

    End If


Example: Created property

This script gets the date that the Main View in WALNUT.NSF was created, and displays it in a dialog box. For example, the script might display 10/22/96 09:07:22 AM.

server$ = "Communications"

dbfile$ = "corpcomm\walnut.nsf"

Dim db As New NotesDatabase( server$, dbfile$ )

Dim view As NotesView

Set view = db.GetView( "Main View" )

Messagebox( view.Created )


Examples: CreateDatabase method

This Visual Basic code creates a new database if it does not already exist.

Private Sub CreateDatabase_Click()

On Error GoTo errorHandler

Dim s As New NotesSession

s.Initialize

Dim dir As NotesDbDirectory

Dim db As NotesDatabase

Set dir = s.GetDbDirectory("")

Set db = dir.CreateDatabase("quack.nsf", True)

db.Title = "Ducks of North America"

MsgBox "Created database quack.nsf", , "Created database"

Exit Sub

errorHandler:

If Err.Number = NOTES_ERRORS.ERR_NOTES_ERROR2 Then

    MsgBox "Database quack.nsf already exists", , "Exists"

Else

    MsgBox Err.Description, , "Error " & Right(Hex(Err.Number), 4)

End If

End Sub


Example: CreateDateTime method

This script creates a new NotesDateTime object that represents August 18, 1995, at 1:36:22 P.M.

Dim session As New NotesSession

Dim dateTime As NotesDateTime

Set dateTime = session.CreateDateTime _

( "08/18/95 01:36:22 PM" )

Messagebox( dateTime.LocalTime )

Messagebox( dateTime.GMTTime )
  • The script displays the LocalTime property in a dialog box: "08/18/95 01:36:22 PM EDT," if the script runs on a computer set to Eastern Standard Time.

  • The script displays the GMTTime property in a dialog box: "08/18/95 05:36:22 PM GMT," for example, if the script runs on a computer set to Eastern Standard Time and daylight savings time is observed; or "08/18/95 06:36:22 PM GMT" if the machine is set to Central Standard Time.


Example: CreateDocument method

This script creates a new document in the current database, sets its Subject, and saves it. The document does not have a form associated with it; if a user opens the document in the user interface, Notes uses the default database form to display it.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim doc As NotesDocument

Set db = session.CurrentDatabase

Set doc = db.CreateDocument

doc.Subject = "New building"

Call doc.Save( True, True )


Examples: CreateEntry method

  1. This example creates an entry and inserts it into an empty outline.

    2. Dim session As New NotesSession

    Dim db As NotesDatabase

    Dim outline As NotesOutline

    Dim entry As NotesOutlineEntry

    Set db = session.CurrentDatabase

    'Gets the outline called emptyoutline

    Set outline = db.GetOutline("emptyoutline")

    'Creates a new outline entry called MyFirstEntry

    'and adds it to the outline

    Set entry = outline.Createentry("MyFirstEntry")

    'Saves the outline with its new entry

    Call outline.save()
  2. This example creates a new outline entry and adds it to "myoutline" as the child of the first entry in the outline.

    3. Dim session As New NotesSession

    Dim db As NotesDatabase

    Dim outline As NotesOutline

    Dim entryA As NotesOutlineEntry

    Dim entryB As NotesOutlineEntry

    Set db = session.CurrentDatabase

    Set outline = db.GetOutline("myoutline")

    Set entryA = outline.GetFirst()

    Set entryB = outline.Createentry("MyEntry",entryA,1,1)

    Call outline.save()
  3. This example creates a new outline entry and adds it to the outline as the first entry.

    4. Dim session As New NotesSession

    Dim db As NotesDatabase

    Dim outline As NotesOutline

    Dim entryA As NotesOutlineEntry

    Dim entryB As NotesOutlineEntry

    Set db = session.CurrentDatabase

    Set outline = db.GetOutline("discussion")

    Set entryA = outline.GetFirst()

    Set entryB = outline.Createentry("MyEntry",entryA)

    Call outline.save()
  4. This example creates a new outline entry and adds it to the outline after the first entry at the top level.

    5. Dim session As New NotesSession

    Dim db As NotesDatabase

    Dim outline As NotesOutline

    Dim entryA As NotesOutlineEntry

    Dim entryB As NotesOutlineEntry

    Set db = session.CurrentDatabase

    Set outline = db.GetOutline("myoutline")

    Set entryA = outline.GetFirst()

    Set entryB = outline.Createentry("MyEntry",entryA,1)

    Call outline.save()

See also
CreateEntry method


Example: CreateFromTemplate method

This script creates a new database from the discussion template.

Dim template As New NotesDatabase( "Anchorage", _

                            "discuss.ntf" )

Dim brandNewDb As NotesDatabase

Set brandNewDb = template.CreateFromTemplate _

                    ( "Juno", "suggest.nsf", True )

brandNewDb.Title = "Suggestions for Giving Campaign 1996"


Example: CreateLog method

This script opens a mail message for logging and mails it to Jimmy Ho.

Dim session As New NotesSession

Dim currentLog As NotesLog

Set currentLog = session.CreateLog( "Checkup Agent" )

Call currentLog.OpenMailLog _

( "Jimmy Ho", "Log for Checkup Agent" )

Call currentLog.Close


Example: CreateName method

This example creates a NotesName object based on the current user name.

Dim session As New NotesSession

Dim userName As NotesName

Set userName = session.CreateName(session.UserName)

If userName.IsHierarchical Then

     Messagebox userName.Canonical,, "Canonical name"

     Messagebox userName.Abbreviated,, "Abbreviated name"

End If

Messagebox userName.Common,, "Common name"

If userName.Country <> "" Then

     Messagebox userName.Country,, "Country"

End If

If userName.Organization <> "" Then

     Messagebox userName.Organization,, "Organization"

End If

If userName.OrgUnit1 <> "" Then

     Messagebox userName.OrgUnit1,, "OrgUnit1"

End If

If userName.OrgUnit2 <> "" Then

     Messagebox userName.OrgUnit2,, "OrgUnit2"

End If

If userName.OrgUnit3 <> "" Then

     Messagebox userName.OrgUnit3,, "OrgUnit3"

End If

If userName.OrgUnit4 <> "" Then

     Messagebox userName.OrgUnit4,, "OrgUnit4"

End If

If userName.Given <> "" Then

     Messagebox userName.Given,, "Given"

End If

If userName.Surname <> "" Then

     Messagebox userName.Surname,, "Surname"

End If

If userName.Initials <> "" Then

     Messagebox userName.Initials,, "Initials"

End If

If userName.Generation <> "" Then

     Messagebox userName.Generation,, "Generation"

End If

If userName.ADMD <> "" Then

     Messagebox userName.ADMD,, "ADMD"

End If

If userName.PRMD <> "" Then

     Messagebox userName.PRMD,, "PRMD"

End If

If userName.Keyword <> "" Then

     Messagebox userName.Keyword,, "Keyword"

End If


Example: CreateNewsletter method

This script performs a full-text search on the current database and creates a newsletter with a link to each matching document. The newsletter gets mailed to Sharron Karasic.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim collection As NotesDocumentCollection

Dim newsletter As NotesNewsletter

Dim doc As NotesDocument

Set db = session.CurrentDatabase

Set collection = db.FTSearch( "arachnid", 15 )

If ( collection.Count > 0 ) Then

  Set newsletter = session.CreateNewsletter( collection )

  Set doc = newsletter.FormatMsgWithDoclinks( db )

  doc.Form = "Memo"

  doc.Subject = "The Arachnid Report"

  Call doc.Send( False, "Sharron Karasic" )

End If


Example: CreateObject method

This script creates a new, blank Lotus 123 worksheet object in the Description field of the current document. Lotus123.Workbook.97 must be in the OLE registry.

Dim workspace as New NotesUIWorkspace

Dim uidoc as NotesUIDocument

Set uidoc = workspace.CurrentDocument

Call uidoc.GotoField( "Description" )

Call uidoc.CreateObject("Quarterly Reports", "Lotus123.Workbook.97")


Examples: CreateOutline method

This script creates an outline called CompanySite.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim outline As NotesOutline

Set db = session.CurrentDatabase

Set outline = db.CreateOutline("CompanySite")


Example: CanCreatePersonalAgent property

This example gives Jeffrey Kinnamon the ability to create personal agents in the current database.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim acl As NotesACL

Dim entry As NotesACLEntry

Set db = session.CurrentDatabase

Set acl = db.ACL

Set entry = acl.GetEntry( "Jeffrey Kinnamon" )

If Not ( entry Is Nothing ) Then

  entry.CanCreatePersonalAgent = True

  Call acl.Save

End If


Example: CanCreatePersonalFolder property

This example gives Jeffrey Kinnamon the ability to create personal folders in the current database.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim acl As NotesACL

Dim entry As NotesACLEntry

Set db = session.CurrentDatabase

Set acl = db.ACL

Set entry = acl.GetEntry( "Jeffrey Kinnamon" )

If Not ( entry Is Nothing ) Then

  entry.CanCreatePersonalFolder = True

  Call acl.Save

End If


Example: CreateReplica method

This script creates a replica of the current database on the server Jakarta.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim replica As NotesDatabase

Set db = session.CurrentDatabase

Set replica = db.CreateReplica( "Jakarta", "sales.nsf" )


Examples: CreateReplyMessage method

  1. This script creates a reply to a mail memo and sends it. The reply is sent only to the original sender of the memo, and contains a Body item but no Subject item.

    2. Dim memo As NotesDocument

    Dim reply As NotesDocument

    '...set value of memo...

    Set reply = memo.CreateReplyMessage( False )

    reply.Body = "This reply was generated by a script"

    Call reply.Send( False )
  2. This script checks if a mail memo was sent by an agent. If not, it creates a reply to the mail memo and sends it to all recipients of the original memo. The reply contains a Body item and a Subject item. For example, if the original memo has a Subject of "Building renovations," then the reply gets a Subject of "Re: Building renovations."

    3. Dim memo As NotesDocument

    Dim reply As NotesDocument

    '...set value of memo...

    If Not ( memo.SentByAgent ) Then

      Set reply = memo.CreateReplyMessage( True )

      reply.Subject = "Re: " & memo.Subject( 0 )

      reply.Body = "This reply was generated by a script"

      Call reply.Send( False )

    End If


Example: CreateRichTextItem method

This script creates a new rich text item called ProjectDescription and adds a text value to it.

Dim doc As NotesDocument

Dim rtitem As NotesRichTextItem

'...set value of doc...

Set rtitem = doc.CreateRichTextItem( "ProjectDescription" )

Call rtitem.AppendText( "Book for children ages 9-12" )

Call doc.Save( False, True )


Example: CreateRichTextParagraphStyle method

This script creates a new rich text paragraph style object and centers it in the document.

Dim session As New NotesSession

Dim db As NotesDatabase

Set db = session.Currentdatabase

Dim doc As New NotesDocument(db)

Call doc.AppendItemValue("From", session.Username)

Call doc.AppendItemValue("subject", _

"Meeting agenda")

Dim rtpStyle As NotesrichTextParagraphStyle

Set rtpStyle = session.CreateRichTextParagraphStyle

Dim richText As New NotesRichTextItem(doc, "Body")

rtpStyle.Alignment = ALIGN_CENTER

Call richText.AppendParagraphStyle(rtpStyle)

Call richText.AppendText("Where are we now")

Call richText.AppendText (" and where do we go from here.")

Messagebox rtpStyle.Alignment

Call doc.Save(True, False)


Examples: CreateTimer method

This example maintains and reports the elapsed time since a document is opened, unless the user disables the timer. The example has several scripts.

  1. These declarations are in the (Globals) (Declarations) script for the form. The variable elapsedTime is used by various objects on the form. The NotesTimer object elapsedTimer must be in effect during the execution of a number of scripts on the form.

    2. Dim elapsedTime As Integer

    Dim elapsedTimer As NotesTimer

    %INCLUDE "lsconst.lss"
  2. When a document based on this form opens, the NotesTimer object is created with an interval of 1 second. An event handler for the Alarm event of the object is established.

    3. Sub Postopen(Source As Notesuidocument)

         Dim session As New NotesSession

         Set elapsedTimer = session.CreateTimer()

         elapsedTimer.Interval = 1

         elapsedTimer.Comment = _

         "Elapsed time since opening document"

         elapsedTime = 0

         On Event Alarm From elapsedTimer _

         Call elapsedTimerHandler

    End Sub
  3. This user sub is the event handler specified in the On Event statement above. It simply increments the global variable by 1 each time it is called.

    4. Sub elapsedTimerHandler(Source As NotesTimer)

         elapsedTime = elapsedTime + 1

    End Sub
  4. This script is for a button on the form. The script displays the time accumulated in the global variable.

    5. Sub Click(Source As Button)

         Dim etime As Integer

         Dim minutes As Integer

         etime = elapsedTime

         If etime < 60 Then

              Messagebox etime & " second(s)",, _

              "Elapsed time since opening document"

         Else

              minutes = 0

              Do While etime > 59

                   minutes = minutes + 1

                   etime = etime - 60

              Loop

              Messagebox minutes & " minute(s), " & _

              etime & " second(s)",, _

              "Elapsed time since opening document"

         End If

    End Sub

This example queries the Enabled property of the NotesTimer object and toggles it if the user wants to.

Sub Click(Source As Button)

     If elapsedTimer.Enabled Then

          If Messagebox _

          ("Do you want to disable the timer?", _

          MB_YESNO + MB_ICONQUESTION, _

          "Elapsed timer is enabled") = IDYES Then

               elapsedTimer.Enabled = False

          End If

     Else

          If Messagebox _

          ("Do you want to enable the timer?", _

          MB_YESNO + MB_ICONQUESTION, _

          "Elapsed timer is disabled") = IDYES Then

               elapsedTimer.Enabled = True

          End If

     End If

End Sub


Example: CreateViewNav method

This script creates a view navigator for all of the entries in the By Category view and puts the second entry in a folder called My Favorites.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim view As NotesView

Dim nav As NotesViewNavigator

Dim entryA As NotesViewEntry

Dim entryB As NotesViewEntry

Dim doc As NotesDocument

Set db = session.CurrentDatabase

Set view = db.GetView("By Category")

Set nav = view.CreateViewNav()

Set entryA = nav.GetFirst

Set entryB = nav.GetNext(entryA)

Set doc = entryB.Document

Call doc.PutInFolder("My Favorites")


Example: CreateViewNavFrom method

This script creates a view navigator starting with the second document entry.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim view As NotesView

Dim docA As NotesDocument

Dim docB As NotesDocument

Set db = session.CurrentDatabase

Set view = db.GetView( "By Category" )

Set docA= view.GetFirstDocument

Set docB = view.GetNextDocument(docA)

Set nav = view.CreateViewNavFrom(docB)


Example: CreateViewNavFromCategory method

This script creates a view navigator beginning with the category Burgundy and displays the universal ID of the first document.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim view As NotesView

Dim nav As NotesViewNavigator

Dim entry As NotesViewEntry

Set db = session.CurrentDatabase

Set view = db.GetView("By Category")

Set nav = view.CreateViewNavFromCategory("Burgundy")

Set entry = nav.GetFirstDocument

Messagebox "Universal ID: " & entry.UniversalID


Example: CreateViewNavFromChildren method

This example creates a view navigator from the children of the last document entry.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim view As NotesView

Dim doc As NotesDocument

Dim nav As NotesViewNavigator

Set db = session.CurrentDatabase

Set view = db.GetView("My View")

Set doc = view.GetLastDocument

Set nav = view.CreateViewNavFromChildren(doc)


Example: CreateViewNavFromDescendants method

This example creates a view navigator for all of the decendants of the first document in a view.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim view As NotesView

Dim doc As NotesDocument

Dim nav As NotesViewNavigato

Set db = session.CurrentDatabase

Set view = db.GetView("My View")

Set doc = view.GetFirstDocument

Set nav = view.CreateViewNavFromDescendants(doc)


Examples: CreateViewNavMaxLevel method

This Visual Basic code creates a navigator that contains only the top-level entries of a view.

Private Sub ViewMaxLevel_Click()

Dim s As New NotesSession

s.Initialize

Dim dir As NotesDbDirectory

Dim db As NotesDatabase

Dim v As NotesView

Dim nav As NotesViewNavigator

Dim e As NotesViewEntry

Set dir = s.GetDbDirectory("")

Set db = dir.OpenDatabase("Web test")

Set v = db.GetView("Main View")

Set nav = v.CreateViewNavMaxLevel(0)

Set e = nav.GetFirst

MsgBox e.UniversalID, , "UNID of first entry"

End Sub


Examples: Creating a database

  1. This example creates a local database named SALES2.NSF. The database is not initialized. This database is useful for storing data programmatically but cannot be used through the Notes UI.

    2. Sub INITIALIZE

         Dim db As New NotesDatabase("", "")

         Call db.Create("", "sales2.nsf", True)

         If db.IsOpen Then Messagebox "Is Open" _

         Else Messagebox "Is Closed"

         Call db.Close

         If db.IsOpen Then Messagebox "Is Open" _

         Else Messagebox "Is Closed"

    End Sub
  2. This example creates a local database named saledisc.nsf based on the Domino template discuss4.ntf and changes the title. Discuss is the database object for the template and db is the database object for the new database. The third argument to CreateFromTemplate inherits design changes.

    3. Sub INITIALIZE

         Dim discuss As New NotesDatabase("", "DISCUSS4.NTF")

         Dim db As NotesDatabase

         Set db = discuss.CreateFromTemplate _

         ("", "SALEDISC", True)

         db.Title = "Sales Discussion Database"

    End Sub
  3. This example creates a local replica of a database on a server and initializes it.

    4. Sub INITIALIZE

         Dim names As New NotesDatabase("MARKET", "SALEDISC")

         Dim db As NotesDatabase

         Set db = names.CreateReplica("", "SALEDISC")

         Messagebox db.Title

         If db.Replicate("MARKET") Then

              Messagebox "Replication successful"

         Else

              Messagebox "Replication not successful"

         End If

    End Sub
  4. This example creates a copy of names.nsf.

    5. Sub INITIALIZE

         Dim names As New NotesDatabase("", "NAMES")

         Dim db As NotesDatabase

         Set db = names.CreateCopy("", "NAMESCPY")

    End Sub


Example: Creating a document

This example creates a new document in a database and adds four item values.

Sub Initialize

     Dim session As New NotesSession

     Dim db As NotesDatabase

     Dim doc As NotesDocument

     Set db = session.CurrentDatabase

     Set doc = New NotesDocument(db)

     doc.From = session.UserName

     doc.Subject = "Mary Lee"

     doc.Categories = "Eastern"

     doc.Body = "OK"

     Call doc.Save(True, False)

End Sub


Examples: Creating an item and assigning values

  1. This example uses the New method of the NotesItem class to add a new item named ModifiedBy to each document in a database and give it the value of the user name for the Notes session.

    2. Sub Initialize

         Dim session As New NotesSession

         Dim db As NotesDatabase

         Dim dc As NotesDocumentCollection

         Dim doc As NotesDocument

         Dim item As NotesItem

         Set db = session.CurrentDatabase

         Set dc = db.AllDocuments

         For j = 1 To dc.Count

              Set doc = dc.GetNthDocument(j)

              Set item = New NotesItem _

              (doc, "ModifiedBy", session.UserName)

              Call doc.Save(True, False)

         Next

    End Sub
  2. This example uses the AppendItemValue method of the NotesDocument class to add a new item named ModifiedBy to each document in a database and give it the value of the user name for the Notes session.

    3. Sub Initialize

         Dim session As New NotesSession

         Dim db As NotesDatabase

         Dim dc As NotesDocumentCollection

         Dim doc As NotesDocument

         Set db = session.CurrentDatabase

         Set dc = db.AllDocuments

         For j = 1 To dc.Count

              Set doc = dc.GetNthDocument(j)

              Call doc.AppendItemValue _

              ("ModifiedBy", session.UserName)

              Call doc.Save(True, False)

         Next

    End Sub
  3. This example uses the Values property of the NotesItem class to change the value of the item named ModifiedBy in each document in a database. Loops are used to access all values of all items with the name ModifiedBy.

    4. Sub Initialize

         Dim session As New NotesSession

         Dim db As NotesDatabase

         Dim dc As NotesDocumentCollection

         Dim doc As NotesDocument

         Dim item As NotesItem

         Set db = session.CurrentDatabase

         Set dc = db.AllDocuments

         For j = 1 To dc.Count

              Set doc = dc.GetNthDocument(j)

              Set item = doc.GetFirstItem("ModifiedBy")

              While Not(item Is Nothing)

                   itemValues = item.Values

                   Forall itemValue In itemValues

                   itemValue = "Anonymous"

                   End Forall

                   item.Values = itemValues

                   Set item = doc.GetNextItem(item)

              Wend

              Call doc.Save(True, False)

         Next

    End Sub
  4. This example uses the ReplaceItemValue method of the NotesDocument class to change the value of the item named ModifiedBy in each document in a database. The result in each document is a single item named ModifiedBy with a single value.

    5. Sub Initialize

         Dim session As New NotesSession

         Dim db As NotesDatabase

         Dim dc As NotesDocumentCollection

         Dim doc As NotesDocument

         Set db = session.CurrentDatabase

         Set dc = db.AllDocuments

         For j = 1 To dc.Count

              Set doc = dc.GetNthDocument(j)

              Call doc.ReplaceItemValue _

              ("ModifiedBy", "Anon2")

              Call doc.Save(True, False)

         Next

    End Sub


Example: CrossCertify method

The following script shows you how to cross certify an ID file.

Dim reg As New NotesRegistration

reg.CertifierIDFile = "c:\lotus\notes\cert.ID"

reg.Expiration = Today + 1095

Call reg.CrossCertify( "c:\lotus\notes\JSmith", "cpassword", _

     "Cross certifying Joseph's ID")


Example: CurrencySymbol property

The following example displays the currency international settings: the currency symbol; whether a space is between the currency symbol and the number; whether the currency symbol follows the number.

Dim session As New NotesSession

Dim international As NotesInternational

Set international = session.International

Messagebox international.CurrencySymbol,, "Currency symbol"

If international.IsCurrencySpace Then

     Messagebox "Yes",, _

     "Space between currency symbol and number?"

Else

     Messagebox "No",, _

     "Space between currency symbol and number?"

End If

If international.IsCurrencySuffix Then

     Messagebox "Yes",, "Currency symbol follows number?"

Else

     Messagebox "No",, "Currency symbol follows number?"

End If


Example: CurrentAccessLevel property

This script gets the current user's access level to the current database. For example:

  • If the script runs on a workstation and the current user has Author access to the current database, CurrentAccessLevel returns ACLLEVEL_AUTHOR.

  • If the script runs on a server and the script owner has Designer access to the current database, CurrentAccessLevel returns ACLLEVEL_DESIGNER.

    • Dim session As New NotesSession

    Dim db As NotesDatabase

    Dim level As Integer

    Set db = session.CurrentDatabase

    level = db.CurrentAccessLevel


Examples: CurrentAgent property

  1. This agent script gets the name of the agent that's currently running, and puts it into agentName. For example, if this script is a part of the Super Agent, the Name property returns "Super Agent."

    2. Dim session As New NotesSession

    Dim agent As NotesAgent

    Dim agentName As String

    Set agent = session.CurrentAgent

    agentName = agent.Name
  2. This agent script creates a mail log for the agent that's currently running. The log has the same name as the current agent, and gets mailed to the current agent's owner.

    3. Sub Initialize

      Dim session As New NotesSession

      Dim db As NotesDatabase

      Dim agent As NotesAgent

      Set db = session.CurrentDatabase

      Set agent = session.CurrentAgent

      Dim currentLog As NotesLog

      Set currentLog = New NotesLog( agent.Name )

      Call currentLog.OpenMailLog _

      ( agent.Owner, agent.Name & " in " & db.Title )

      '...log some actions and errors...

      Call currentLog.Close

    End Sub


Example: CurrentCalendarDateTime property

This example of an action for a calendar view displays the date and time of the region that is currently selected.

Sub Click(Source As Button)

     Dim workspace As New NotesUIWorkspace

     Messagebox workspace.CurrentCalendarDateTime,, _

     "Date and time for the current region"

End Sub


Examples: CurrentDatabase property

  1. This script gets the current database. For example, if this script runs in the database PROJECTS.NSF on server Damascus, then the db object represents PROJECTS.NSf on server Damascus.

    2. Dim session As New NotesSession

    Dim db As NotesDatabase

    Set db = session.CurrentDatabase
  2. This action script allows the user to perform a full-text search on the current database. It sends the user a newsletter with links to the top ten documents found in the search.

    3. Sub Click(Source As Button)

      Dim session As New NotesSession

      Dim db As NotesDatabase

      Dim query As String

      Dim collection As NotesDocumentCollection

      Dim newsletter As NotesNewsletter

      Dim doc As NotesDocument

      Set db = session.CurrentDatabase

      query = Inputbox$ _

      ( "What do you want to search for?", "Search" )

      Set collection = db.FTSearch( query, 10 )

      Set newsletter = New NotesNewsletter( collection )

      Set doc = newsletter.FormatMsgWithDocLinks( db )

      doc.Form = "Memo"

      Call doc.Send( False, session.UserName )

    End Sub


Example: CurrentDatabase property

This example sets the current database property and opens the By Category view.

Dim workspace As New NotesUIWorkspace

Dim db As NotesUIDatabase

Set db = workspace.CurrentDatabase

Call db.OpenView("By Category")


Example: CurrentDocument property

This script uses a NotesUIWorkspace to get the current document. It then uses the FieldGetText method to print the Subject field of the current document.

Dim workspace As New NotesUIWorkspace

Dim uidoc As NotesUIDocument

Set uidoc = workspace.CurrentDocument

Messagebox( uidoc.FieldGetText( "Subject" ) )


Examples: CurrentField property

  1. A Description field has the following script. Each time a user places the cursor inside the Description field, Notes prints "Welcome to the Description field. Describe the problem." in the status bar.

    2. Sub Entering(Source As Field)

      Dim workspace As New NotesUIWorkspace

      Dim uidoc As NotesUIDocument

      Set uidoc = workspace.CurrentDocument

      Print( "Welcome to the " + uidoc.CurrentField +  _

      " field. Describe the problem." )

    End Sub
  2. A Body field has the following script. Each time a user moves the cursor from the Body field to the Comments field, Notes prints "Thanks for visiting the Comments field" in the status bar. The CurrentField property changes as soon as the user moves the cursor to a different field.

    3. Sub Exiting(Source As Field)

      Dim workspace As New NotesUIWorkspace

      Dim uidoc As NotesUIDocument

      Set uidoc = workspace.CurrentDocument

      Print( "Thanks for visiting the " +  _

      uidoc.CurrentField + " field.")

    End Sub


Example: CurrentRow property

This agent uses a For loop, NumRows, and CurrentRow to access all the rows in a result set. The LastRow that precedes the loop is essential; otherwise, NumRows is not correct.

Uselsx "*LSXODBC"

Sub Initialize

     Dim con As New ODBCConnection

     Dim qry As New ODBCQuery

     Dim result As New ODBCResultSet

     Dim firstName As String

     Dim lastName As String

     Dim msg As String

     Set qry.Connection = con

     Set result.Query = qry

     con.ConnectTo("ATDB")

     qry.SQL = "SELECT * FROM STUDENTS ORDER BY LASTNAME"

     result.Execute

     result.LastRow

     msg = "Student names:" & Chr(10)

     For  i = 1 To result.NumRows

          result.CurrentRow = i

          firstName = result.GetValue("FIRSTNAME", firstName)

          lastName = result.GetValue("LASTNAME", lastName)

          msg = msg & Chr(10) & firstName & " " & lastName

     Next

     Messagebox msg,, "Student Names"

     con.Disconnect

End Sub


Example: CurrentView property

This script displays the name of the current view.

Dim workspace As New NotesUIWorkspace

Dim view As NotesUIView

Set view = workspace.CurrentView

Messagebox view.ViewName


Example: Cut method

This button script removes the contents of the Description field, and places them on the Clipboard.

Sub Click(Source As Button)

  Dim workspace As New NotesUIWorkspace

  Dim uidoc As NotesUIDocument

  Set uidoc = workspace.CurrentDocument

  Call uidoc.GoToField( "Description" )

  Call uidoc.SelectAll

  Call uidoc.Cut

End Sub


Example: CutoffDate property

This script displays the cut off date for documents to be included in replication.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim rep As NotesReplication

Set db = session.CurrentDatabase

Set rep = db.ReplicationInfo

Messagebox rep.CutOffDate


Example: CutoffDelete property

This script checks documents to see if they are older than the cut off date, then changes a False value to True.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim rep As NotesReplication

Set db = session.CurrentDatabase

Set rep = db.ReplicationInfo

  If rep.CutOffDelete = False Then

    rep.CutOffDelete = True

  End If

Call rep.Save()


Example: CutoffInterval property

This script checks the number of days after which documents are automatically deleted and sets the interval to 90 days.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim rep As NotesReplication

Set db = session.CurrentDatabase

Set rep = db.ReplicationInfo

  If rep.CutOffInterval <> 90 Then

    rep.CutOffInterval = 90

  End If

Call rep.Save()


Example: Database property

This example displays the title and path of a database just after it is opened.

Sub Postopen(Source As Notesuidatabase)

     Dim db As NotesDatabase

     Set db = Source.Database

     Messagebox "Title: " & db.Title & Chr(10) & _

     "Path: " & db.FilePath,, "Database opened"

End Sub


Example: DataSourceName property

The following agent uses DataSourceName to display the name of a data source once you are connected.

Uselsx "*LSXODBC"

Sub Initialize

     Dim con As New ODBCConnection

     Dim dsn As String

     Dim msg As String

     dsn = Inputbox("ODBC data source name", "DSN")

     If Not con.ConnectTo(dsn) Then

          Messagebox "Could not connect to " & dsn,, "Error"

          Exit Sub

     End If

     Messagebox "You successfully connected to " &  _

     con.DataSourceName,, _

     "Connected to " & con.DataSourceName

     con.Disconnect

End Sub


Example: DateOnly property

This script displays the current date and time on two lines.

Sub Initialize

Dim dateTime As New NotesDateTime( "" )

dateTime.LSLocalTime = Now

Messagebox _

  "Date:   " & dateTime.DateOnly & Chr(10) & _

  "Time:   " & dateTime.TimeOnly,, "Current date and time"

End Sub


Example: DateSep property

The following example displays the date international settings: whether the date format is DMY, MDY, or YMD; the month-day-year separator; the keywords for yesterday, today, and tomorrow.

Dim session As New NotesSession

Dim international As NotesInternational

Set international = session.International

If international.IsDateDMY Then

     Messagebox "DMY",, "Format of date"

Elseif international.IsDateMDY Then

     Messagebox "MDY",, "Format of date"

Elseif international.IsDateYMD Then

     Messagebox "YMD",, "Format of date"

Else

     Messagebox "Unknown",, "Format of date"

End If

Messagebox international.DateSep,, "Date separator"

Messagebox international.Yesterday & Chr(10) & _

international.Today & Chr(10) & _

international.Tomorrow ,, "Text of date keywords"


Examples: DateTimeValue property

  1. This script uses the DateTimeValue property to place the value of the DateComposed item in a document into a NotesDateTime object. For example, if the DateComposed item contains the value 03/20/96, then the dateTime object represents the date March 20, 1996.

    2. Dim item As NotesItem

    Dim dateTime As NotesDateTime

    Set item = doc.GetFirstItem( "DateComposed" )

    Set dateTime = item.DateTimeValue
  2. This script sets the value of the DateApproved item in a document to today's date. For example, if today is January 17, 1996 it sets the DateApproved item to 01/17/96.

    3. Dim doc As NotesDocument

    Dim item As NotesItem

    Dim dateTime As NotesDateTime

    '...set value of doc...

    Set item = doc.GetFirstItem( "DateApproved" )

    Set dateTime = New NotesDateTime( "Today" )

    Set item.DateTimeValue = dateTime

    Call doc.Save( False, True )


Example: DecimalSep property

This example displays the decimal international settings: the number of decimal (fraction) digits; the decimal separator (between the whole and fraction parts); the 1000s separator; and whether a zero precedes the decimal point if the number is a fraction (no whole part).

Dim session As New NotesSession

Dim international As NotesInternational

Set international = session.International

Messagebox international.CurrencyDigits,, _

"Number of decimal digits"

Messagebox international.DecimalSep,, "Decimal separator"

Messagebox international.ThousandsSep,, "1000s separator"

If international.IsCurrencyZero Then

     Messagebox "Yes",, "Leading zero?"

Else

     Messagebox "No",, "Leading zero?"

End If


Example: DelayUpdates property

This example enables delayed updates for the current database.

Dim session As New NotesSession

Dim db As NotesDatabase

Set db = session.CurrentDatabase

db.DelayUpdates = True


Examples: DeleteDocument method

  1. This script closes the current document and marks it for deletion. If the document is in Edit mode, however, the script does nothing.

    2. Sub Click(Source As Button)

      Dim workspace As New NotesUIWorkspace

      Dim uidoc As NotesUIDocument

      Set uidoc = workspace.CurrentDocument

      If Not ( uidoc.EditMode ) Then

        Call uidoc.DeleteDocument

      End If

    End Sub
  2. This script incorrectly tries to categorize the current document after calling DeleteDocument.

    3. Dim workspace As New NotesUIWorkspace

    Dim uidoc As NotesUIDocument

    Set uidoc = workspace.CurrentDocument

    If Not ( uidoc.EditMode ) Then

      Call uidoc.DeleteDocument

      Call uidoc.Categorize( "Purged" )

      'error, since uidoc object is not valid

    End If


Example: DeleteEntry method

This script displays the number of documents in the view entry collection, then deletes the first entry and displays the number of documents remaining.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim view As NotesView

Dim entry As NotesViewEntry

Dim vc As NotesViewEntryCollection

Set db = session.CurrentDatabase

Set view = db.GetView("By Category")

Set vc = view.GetAllEntriesByKey("Sale items")

Set entry = vc.GetNthEntry(1)

Messagebox "Count: " & vc.Count

Call vc.DeleteEntry(entry)

Messagebox "Count: " & vc.Count


Example: DeleteIDOnServer method

The following script shows you how to delete an ID file from the server.

Dim reg As New NotesRegistration

Dim session As New NotesSession

Dim db As NotesDatabase

Setdb = session.CurrentDatabase

reg.RegistrationServer = db.Server

username$ = "Server1/Test/RedSox"

isserverid = True

Call reg.DeleteIDOnServer(username$, isserverid)


Example: DeleteRole method

This script removes the Developer role from the ACL of the current database.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim acl As NotesACL

Set db = session.CurrentDatabase

Set acl = db.ACL

Call acl.DeleteRole( "Developer" )

Call acl.Save


Example: DeleteRow method

This agent deletes a row from a table.

Uselsx "*LSXODBC"

%INCLUDE "lsconst.lss"

Sub Initialize

     Dim con As New ODBCConnection

     Dim qry As New ODBCQuery

     Dim result As New ODBCResultSet

     Dim firstName As String

     Dim lastName As String

     Dim msg As String

     Set qry.Connection = con

     Set result.Query = qry

     con.ConnectTo("ATDB")

     qry.SQL = "SELECT * FROM STUDENTS"

     result.Execute

     studentID = Inputbox$ _

     ("ID of student to be deleted:", "Delete student")

     If studentID = "" Then

          Messagebox "No student ID entered",, _

                     "Bogus student ID"

          Exit Sub

     End If

     If Not result.LocateRow(1, Cint(studentID)) Then

          Messagebox "No such student",, "Bogus student ID"

          Exit Sub

     End If

     For i = 1 To 9 ' Get values for columns 1 - 9

          msg = msg & "  " & result.GetValue(i)

     Next

     If Messagebox _

        ("Do you really want to delete this student?" _

        & Chr(10) & Chr(10) & msg, _

        MB_YESNO + MB_ICONQUESTION, _

        "Delete student") = IDYES Then

          result.DeleteRow("STUDENTS")

     End If

     result.Close(DB_CLOSE)

     con.Disconnect

End Sub


Example: DescendantCount property

This script displays the number of descendants belonging to the Employees view entry in the By Category view.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim view As NotesView

Dim entry As NotesViewEntry

Set db = session.CurrentDatabase

Set view = db.GetView("By Category")

Set entry = view.GetEntryByKey("Employees")

Messagebox entry.DescendantCount


Example: DeselectAll method

This button script deselects the current selection before pasting the contents of the Clipboard into the current field.

Sub Click(Source As Button)

  Dim workspace As New NotesUIWorkspace

  Dim uidoc As NotesUIDocument

  Set uidoc = workspace.CurrentDocument

  Call uidoc.DeselectAll

  Call uidoc.Paste

End Sub


Examples: DesignTemplateName property

  1. This script gets the design template name of the database CBANNER.NSF. Since CBANNER.NSF is a mail file, the method returns "StdR4Mail."

    2. Dim db As New NotesDatabase( "Mecca", "mail\cbanner.nsf" )

    template$ = db.DesignTemplateName
  2. This sub notifies database managers that the design of their databases is going to change. It takes the server (such as "Caracas") and file of a template database (such as MAIL4.NTF) and sends mail to the managers of all databases on the server that inherit from that template.

    3. Sub templateNotification(server As String, file As String)

      Dim templateDb As NotesDatabase

      Dim templateName As String

      Dim db As NotesDatabase

      Dim directory As NotesDbDirectory

      Dim doc As NotesDocument

      Set templateDb = New NotesDatabase( server, file )

      templateName = templateDb.TemplateName

      Set directory = New NotesDbDirectory( server )

      Set db = directory.GetFirstDatabase( DATABASE )

      While Not ( db Is Nothing )

        If ( db.DesignTemplateName = templateName ) Then

          Call db.Open( "", "" )

          Set doc = New NotesDocument( db )

          doc.Form = "Memo"

          doc.Subject = "Template changes in " & templateName

          doc.Body = "The template " & templateName &  _

          " will be modified tomorrow."

          Call doc.Send( False, db.Managers )

        End If

        Set db = directory.GetNextDatabase

      Wend

    End Sub
    A call to this sub might look like this:

    Call templateNotification( "Caracas", "mail4.ntf" )


Examples: DialogBox method

  1. This script displays a document in a dialog box using the policy form whenever a user clicks the button. The first layout region on the policy form is sized to fit in the dialog box.

    2. Sub Click(Source As Button)

      Dim workspace As New NotesUIWorkspace

      Call workspace.DialogBox _

      ( "policy", True, True, True, True, _

      False, False, "Policy" )

    End Sub
  2. This script displays the current document using a form called DirectReports. Both the current document and the DirectReports form display a number field called HeadCount. In the dialog box, the user may edit the HeadCount, which means the field value for HeadCount changes on the current document. The script compares the HeadCount field before and after the call to DialogBox and updates the TotalHeadCount field with any changes. For example, if HeadCount increases by 5, the script increases TotalHeadCount by 5.

  3. Sub Click(Source As Button)

      Dim workspace As New NotesUIWorkspace

      Dim uidoc As NotesUIDocument

      Dim oldHeadCount, newHeadCount, _

      totalHeadCount As Integer

      Set uidoc = workspace.CurrentDocument

      oldHeadCount = Cint( uidoc.FieldGetText( "HeadCount" ) )

      totalHeadCount = Cint _

      ( uidoc.FieldGetText( "TotalHeadCount" ) )

      Call workspace.DialogBox( "DirectReports", True, True )

      ' HeadCount may have changed, so get new value

      newHeadCount = Cint( uidoc.FieldGetText( "HeadCount" ) )

      If ( oldHeadCount <> newHeadCount ) Then

        ' HeadCount has changed,

        ' so change TotalHeadCount accordingly

        Call uidoc.FieldSetText( "TotalHeadCount",  _

        Cstr( totalHeadCount + _

        ( newHeadCount - oldHeadCount ) ) )

      End If

    End Sub
  4. This script brings up a dialog with the category and subject of the first document in the "By Category" view.

    5. Sub Click(Source As Button)

         Dim db As NotesDatabase

         Dim s As New NotesSession

         Dim workspace As New NotesUIWorkspace

         Dim view As NotesView

         Dim doc As NotesDocument

         Set db = s.CurrentDatabase

         Set view = db.GetView( "By Category" )

         Set doc = view.GetFirstDocument

         Call workspace.DialogBox _

            ("Dialog Box", True, True, False, False, False,  _

         False, "Dialog Box", doc)

         Call doc.save (True, False)

    End Sub


Example: DialogBoxCanceled Property

This script tests for the DialogBoxCanceled property, then prompts users to confirm that they want to cancel the dialog. You must attach this script to the QueryClose event for the form you specified with the DialogBox method of the NotesUIWorkspace class.

(Globals)(Declarations)

%INCLUDE "lsconst.lss"

Sub Queryclose(Source As NotesUIDocument, Continue As Variant)

    If Source.DialogBoxCanceled Then

        If Messagebox ("Do you really want to Cancel", _

        MB_YESNO+MB_ICONQUESTION, "Cancel") = IDNO Then

             Continue = False

        End If

    End If

End Sub


Example: Disabled property

This script enables replication in databases where replication has been disabled.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim rep As NotesReplication

Set db = session.CurrentDatabase

Set rep = db.ReplicationInfo

  If rep.Disabled = True Then

    rep.Disabled = False

  End If

Call rep.Save()


Example: DisableRole method

This script disables the Auditor role for Bill Ehrhardt, in the database DISCUSS.NSF.

Dim db As New NotesDatabase _

( "Bucharest", "data\discuss.nsf"  )

Dim acl As NotesACL

Dim entry As NotesACLEntry

Set acl = db.ACL

Set entry = acl.GetEntry( "Bill Ehrhardt" )

Call entry.DisableRole( "Auditor" )

Call acl.Save


Example: Disconnect method

The following button disconnects from any current data source and then connects to a user-specified data source.

Uselsx "*LSXODBC"

Dim con As ODBCConnection

Sub Postopen(Source As Notesuidocument)

     Set con = New ODBCConnection

End Sub

Sub Click(Source As Button)

     Dim dataSource As String

     If con.IsConnected Then

          If Not con.Disconnect Then

               Messagebox "Disconnect failed from "  _

                          & con.DataSourceName

          End If

     End If

     dataSource = Inputbox$("Enter name of data source", _

                            "Data source?")

     If Not con.ConnectTo(dataSource) Then

          Messagebox "Could not connect to " & dataSource

     End If

End Sub

Sub Queryclose(Source As NotesUIDocument, Continue As Variant)

     If con.IsConnected Then con.Disconnect

End Sub


Example: Document Property

This form action script places the current document and its immediate responses into the Interesting folder. It uses the PutInFolder method in NotesDocument to place each document in the folder.

Sub Click(Source As Button)

  Dim workspace As New NotesUIWorkspace

  Dim uidoc As NotesUIDocument

  Dim doc As NotesDocument

  Dim collection As NotesDocumentCollection

  Set uidoc = workspace.CurrentDocument

  Set doc = uidoc.Document

  Set collection = doc.Responses

  Call doc.PutInFolder( "Interesting" )

  Set doc = collection.GetFirstDocument

  While Not ( doc Is Nothing )

    Call doc.PutInFolder( "Interesting" )

    Set doc = collection.GetNextDocument( doc )

  Wend

End Sub


Examples: DocumentContext property

  1. This agent displays the Subject item of the current document when run from a view in the Notes client.

    2. Sub Initialize

        Dim session As NotesSession

        Set session = New NotesSession

        Dim doc As NotesDocument

        Set doc = session.DocumentContext

        Messagebox doc.Subject(0),, "Subject"

    End Sub
  2. This agent displays the Subject item of the current document when run by @Command([ToolsRunMacro]) in a browser.

    3. Sub Initialize

        Dim session As NotesSession

        Set session = New NotesSession

        Dim doc As NotesDocument

        Set doc = session.DocumentContext

        Print "<H2>" + doc.Subject(0) + "</H2>"

    End Sub
  3. This agent displays the CGI variable Remote_Addr when run in a browser by the OpenAgent URL command, or by @Command([ToolsRunMacro]) if Remote_Addr is a field on the form supporting the current document.

    4. Sub Initialize

        Dim session As NotesSession

        Set session = New NotesSession

        Dim doc As NotesDocument

        Set doc = session.DocumentContext

        Print "<H2>IP address is " + doc.Remote_Addr(0) + "</H2>"

    End Sub
  4. This agent increments a counter. You can use it to track the number of times a Web page is opened by calling it from WebQueryOpen. The counter is maintained in a profile document as an item named Access_counter. An item of the name exists for display purposes only in the document being opened.

    5. Sub Initialize

        Dim session As New NotesSession

        Dim db As NotesDatabase

        Dim doc As NotesDocument

        Dim profile As NotesDocument

        Dim num As Double

        Dim numStr As String

        Set doc = session.DocumentContext

        Set db = session.CurrentDatabase

        Set profile = db.GetProfileDocument("(AccessCounterProfile)")

        numStr = profile.Access_counter(0)

        If numStr = " " Or numStr = "" Then

            num = 1

        Else

            num = Cdbl(numStr) + 1

        End If

        Call profile.ReplaceItemValue("Access_counter", Cstr(num))

        Call profile.Save(False, False)

        Call doc.ReplaceItemValue("Access_counter", Cstr(num))

    End Sub


Examples: EditDocument method

  1. This view action script opens the document that's currently highlighted in the view, in Edit mode.

    2. Sub Click(Source As Button)

      workspace As New NotesUIWorkspace

      Call workspace.EditDocument( True )

    End Sub
  2. This view action script opens the document that's currently highlighted in the view, in Edit mode, and moves the insertion point to the Body field.

    3. Sub Click(Source As Button)

      Dim workspace As New NotesUIWorkspace

      Dim uidoc As NotesUIDocument

      Set uidoc = workspace.EditDocument( True )

      Call uidoc.GotoField( "Body" )

    End Sub


Example: EditMode property

This button script puts the current document into Edit mode.

Sub Click(Source As Button)

  Dim workspace As New NotesUIWorkspace

  Dim uidoc As NotesUIDocument

  Set uidoc = workspace.CurrentDocument

  uidoc.EditMode = True

End Sub


Example: EditProfile method

This example opens an "Interest Profile" profile document for the current user. If none exists, it creates a profile document.

Dim workspace As New NotesUIWorkspace

Dim session As New NotesSession

Call workspace.EditProfile _

("Interest Profile", session.UserName)


Example: EffectiveUserName property

This script gets the current effective user name.

  • If this script runs on a server, and if Mutsumi Kitamura last edited and saved the script, the EffectiveUserName property returns "Mutsumi Nakamura."

  • If this script runs on a workstation, the EffectiveUserName property returns the name of the current user.

    • ' created 1 Jan 1996 by M. Nakamura

    ' revisions 2 Feb 1996 by M. Nakamura

    Dim session As New NotesSession

    Dim creator As String

    creator = session.E.ffectiveUserName


Example: Effects property

This example builds a rich-text item and sets styles so that part of the text is embossed.

Sub Initialize

     Dim session As New NotesSession

     Dim db As NotesDatabase

     Set db = session.CurrentDatabase

     Dim doc As New NotesDocument(db)

     Call doc.AppendItemValue("From", session.UserName)

     Call doc.AppendItemValue("Subject",  _

                              "Meeting time changed")

     Dim richStyle As NotesRichTextStyle

     Set richStyle = session.CreateRichTextStyle

     Dim richText As New NotesRichTextItem(doc, "Body")

     Call richText.AppendText("The meeting is at ")

     richStyle.Effects = EFFECTS_EMBOSS

     Call richText.AppendStyle(richStyle)

     Call richText.AppendText("3:00")

     richStyle.Effects = EFFECTS_NONE

     Call richText.AppendStyle(richStyle)

     Call richText.AppendText(" not 2:00")

     Call doc.Save(True, False)

End Sub


Examples: EmbeddedObjects property

This script uses the EmbeddedObjects property in NotesDocument. The last document in the All Documents view of HILL.NSF contains the following:

  • A Word Pro™ embedded object called "Word Pro Document" in the Body item

  • A Microsoft® Excel object link called "MS Excel Worksheet" in the Body item

  • An Ami Pro® embedded object, created in Notes Release 3, called "Ami Pro Document" in the Body item

  • A file attachment called "CASTLE.BMP" in the Body item

  • A Freelance Graphics® embedded object called "Freelance® Presentation" in the Description item

  • A 1-2-3® embedded object called "123 Worksheet" that is embedded on the form used to create the document, and has been subsequently activated and edited by a user

Dim db As NotesDatabase

Dim view As NotesView

Dim doc As NotesDocument

Set db = New NotesDatabase( "SanFrancisco", "hill.nsf" )

Set view = db.GetView( "All Documents" )

Set doc = view.GetLastDocument

Forall o In doc.EmbeddedObjects

  Messagebox( o.Name )

End Forall

This script displays the following:

  • "Word Pro Document"

  • "MS Excel Worksheet"

  • "Freelance Presentation"

  • "123 Worksheet"

EmbeddedObjects does not return the Ami Pro document because the object was created in Notes Release 3. It does not return CASTLE.BMP because CASTLE.BMP is a file attachment.


Examples: EmbeddedObjects property

This script goes through all the file attachments, object links, and embedded objects in the Body item of a document. Each time it finds a file attachment, it detaches the file to the SAMPLES directory on the C drive and removes the attachment from the document. The script has no effect on the object links or embedded objects in the Body item.

Dim doc As NotesDocument

Dim rtitem As Variant

'...set value of doc...

Set rtitem = doc.GetFirstItem( "Body" )

If ( rtitem.Type = RICHTEXT ) Then

  Forall o In rtitem.EmbeddedObjects

    If ( o.Type = EMBED_ATTACHMENT ) Then

      Call o.ExtractFile( "c:\samples\" & o.Source )

      Call o.Remove

      Call doc.Save( False, True )

    End If

  End Forall

End If


Examples: EmbedObject method

  1. This script creates a new document in the current database, creates a new rich-text item called Body on the document, and attaches the file JIM.SAM to the Body. It then sets the value of the Form and Subject items on the document and saves it.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim doc As NotesDocument

Dim rtitem As NotesRichTextItem

Dim object As NotesEmbeddedObject

Set db = session.CurrentDatabase

Set doc = New NotesDocument( db )

Set rtitem = New NotesRichTextItem( doc, "Body" )

Set object = rtitem.EmbedObject _

( EMBED_ATTACHMENT, "", "c:\jim.sam")

doc.Form = "Main Topic"

doc.Subject = "Here's Jim's document, as an attachment"

Call doc.Save( True, True )
  1. This script is identical to the one above, except that it creates an embedded object using the file JIM.SAM.

    2. Dim session As New NotesSession

    Dim db As NotesDatabase

    Dim doc As NotesDocument

    Dim rtitem As NotesRichTextItem

    Dim object As NotesEmbeddedObject

    Set db = session.CurrentDatabase

    Set doc = New NotesDocument( db )

    Set rtitem = New NotesRichTextItem( doc, "Body" )

    Set object = rtitem.EmbedObject _

    ( EMBED_OBJECT, "", "c:\jim.sam")

    doc.Form = "Main Topic"

    doc.Subject = _

    "Here's Jim's document, as an embedded object"

    Call doc.Save( True, True )
  2. This script is identical to the one above, except that it creates an object link using the file JIM.SAM.

    3. Dim session As New NotesSession

    Dim db As NotesDatabase

    Dim doc As NotesDocument

    Dim rtitem As NotesRichTextItem

    Dim object As NotesEmbeddedObject

    Set db = session.CurrentDatabase

    Set doc = New NotesDocument( db )

    Set rtitem = New NotesRichTextItem( doc, "Body" )

    Set object = rtitem.EmbedObject _

    ( EMBED_OBJECTLINK, "", "c:\jim.sam")

    doc.Form = "Main Topic"

    doc.Subject = "Here's Jim's document, as an object link"

    Call doc.Save( True, True )
  3. This script embeds a new, blank embedded object in the Body item of a document. The object is created using 1-2-3.

    4. Dim session As New NotesSession

    Dim db As NotesDatabase

    Dim doc As NotesDocument

    Dim rtitem As NotesRichTextItem

    Dim object As NotesEmbeddedObject

    Set db = session.CurrentDatabase

    Set doc = New NotesDocument( db )

    Set rtitem = New NotesRichTextItem( doc, "Body" )

    Set object = rtitem.EmbedObject _

    ( EMBED_OBJECT, "1-2-3 Worksheet", "", _

    "Quarterly Report" )

    Call doc.Save( True, True )


Examples: EnableRole method

  1. This script enables the Auditor role for Bill Ehrhardt, in the database DISCUSS.NSF.

    2. Dim db As New NotesDatabase _

    ("Reykjavik", "data\discuss.nsf")

    Dim acl As NotesACL

    Dim entry As NotesACLEntry

    Set acl = db.ACL

    Set entry = acl.GetEntry( "Bill Ehrhardt" )

    Call entry.EnableRole( "Auditor" )

    Call acl.Save
  2. This sub enables one role for multiple people in an ACL. Its parameters are a NotesACL object, the name of the role to enable, and an array of strings that represent user names.

    3. Sub enablePeople( acl As NotesACL, _

    role As String, names As Variant )

      Dim person As NotesACLEntry

      Forall n In names

        Set person = acl.GetEntry( n )

        If ( person.Level = ACLLEVEL_NOACCESS ) Then

          Set person = New NotesACLEntry _

          ( acl, n, ACLLEVEL_AUTHOR )

          Call acl.Save

        End If

        Call person.EnableRole( role )

      End Forall

      Call acl.Save

    End Sub


Examples: Encrypt method

  1. This script encrypts the Body item in a document. Other items may also be encrypted if their IsEncrypted property is True. If encryption keys have already been specified for the document, they are used to encrypt the item; otherwise, the current user's public key is used.

    2. Dim doc As NotesDocument

    Dim item As NotesItem

    '...set value of doc...

    Set item = doc.GetFirstItem( "Body" )

    item.IsEncrypted = True

    Call doc.Encrypt

    Call doc.Save( True, True )
  2. This script encrypts every item in a document. If encryption keys have already been specified for the document, they are used to encrypt the item; otherwise, the current user's public key is used.

    3. Dim doc As NotesDocument

    '...set value of doc...

    Forall i In doc.Items

      i.IsEncrypted = True

    End Forall

    Call doc.Encrypt

    Call doc.Save( True, True )
  3. This script encrypts the Subject and Body items in a document using the Top Secret encryption key.

    4. Dim doc As NotesDocument

    Dim itemA As NotesItem

    Dim itemB As NotesItem

    '...set value of doc...

    Set itemA = doc.GetFirstItem( "Subject" )

    Set itemB = doc.GetFirstItem( "Body" )

    itemA.IsEncrypted = True

    itemB.IsEncrypted = True

    doc.EncryptionKeys = "Top Secret"

    Call doc.Encrypt

    Call doc.Save( True, True )


Examples: EncryptionKeys property

  1. This script gets the encryption keys for a document. For example, if the document is encrypted with the Confidential Key and the Classified Key, keys( 0 ) equals "Confidential Key" and keys( 1 ) equals "Classified Key."

    2. Dim doc As NotesDocument

    Dim keys As Variant

    '...set value of doc...

    keys = doc.EncryptionKeys
  2. This script encrypts every item in a document with two encryption keys: Top Secret and Medium Secret.

    3. Dim doc As NotesDocument

    Dim item As NotesItem

    Dim keys( 1 To 2 ) As String

    '...set value of doc...

    Forall i In doc.Items

      i.IsEncrypted = True

    End Forall

    keys( 1 ) = "Top Secret"

    keys( 2 ) = "Medium Secret"

    doc.EncryptionKeys = keys

    Call doc.Encrypt

    Call doc.Save( True, True )


Examples: EncryptOnSend property

  1. This script sets the EncryptOnSend property for the document to True.

    2. Dim doc as NotesDocument

    '...set value of doc...

    doc.EncryptOnSend = True
  2. This script creates and sends a mail memo that is encrypted for each recipient.

    3. Dim db As New NotesDatabase( "Sao Paulo", "review.nsf" )

    Dim memo As New NotesDocument( db )

    Dim recipients ( 1 To 2 ) As String

    memo.Form = "Memo"

    memo.Subject = "Design review"

    memo.Body = "Last week's design review is posted in " _

                + db.Title

    memo.EncryptOnSend = True

    recipients( 1 ) = "Edith Sprout"

    recipients( 2 ) = "Mariko Ikebuchi"

    Call memo.Send( False, recipients )


Examples: Evaluate method

This Visual Basic code changes all the Subject items in a view to proper case.

Private Sub Evaluate_Click()

Dim s As New NotesSession

s.Initialize

Dim dir As NotesDbDirectory

Dim db As NotesDatabase

Dim v As NotesView

Dim doc As NotesDocument

Set dir = s.GetDbDirectory("")

Set db = dir.OpenDatabase("Web test")

Set v = db.GetView("Main View")

Set doc = v.GetFirstDocument

While Not (doc Is Nothing)

    eval = s.Evaluate("@ProperCase(Subject)", doc)

    Call doc.ReplaceItemValue("Subject", eval)

    Call doc.Save(True, False)

    Set doc = v.GetNextDocument(doc)

Wend

End Sub


Examples: Working with a result set

  1. This agent examines all the fields (columns) in the STUDENTS table of the ATDB data source.

    2. Uselsx "*LSXODBC"

    Sub Initialize

         Dim con As New ODBCConnection

         Dim qry As New ODBCQuery

         Dim result As New ODBCResultSet

         Dim msg As String

         Dim m2 As String

         con.ConnectTo("ATDB")

         If Not con.IsConnected Then

              Messagebox "Could not connect to ATDB",, _

                         "No connection"

              Exit Sub

         End If

         Set qry.Connection = con

         Set result.Query = qry

         qry.SQL = "SELECT * FROM STUDENTS ORDER BY LASTNAME"

         result.Execute

         If Not result.IsResultSetAvailable Then

              Messagebox "Couldn't get result set",, "No data"

              Exit Sub

         End If

         msg = "Fields in STUDENTS table:" & Chr(10)

         For i = 1 To result.NumColumns

              fieldInfo = result.FieldInfo(i)

              If fieldInfo(DB_INFO_READONLY) = DB_READONLY Then

                   m2 = "read-only"

              Else

                   m2 = "read-write"

              End If

              msg = msg & Chr(10) & _

              i & " -> " & _

              result.FieldName(i) & ", " & _

              "size " & " " & result.FieldSize(i) & ", " & _

              m2

         Next

         Messagebox msg,, "Fields"

         result.Close(DB_CLOSE)

         con.Disconnect

    End Sub
  2. This agent accesses all the rows of a result set twice starting from the first row. The first time you do not explicitly set FirstRow since the first NextRow following an Execute implicitly sets FirstRow. The second time you must explicitly set FirstRow and process the first row before entering the loop.

    3. Uselsx "*LSXODBC"

    Sub Initialize

         Dim con As New ODBCConnection

         Dim qry As New ODBCQuery

         Dim result As New ODBCResultSet

         Dim firstName As String

         Dim lastName As String

         Dim msg As String

         Set qry.Connection = con

         Set result.Query = qry

         con.ConnectTo("ATDB")

         qry.SQL = "SELECT * FROM STUDENTS ORDER BY LASTNAME"

         result.Execute

         msg = "Student names:" & Chr(10)

         Do

           result.NextRow

           firstName = result.GetValue("FIRSTNAME", firstName)

           lastName = result.GetValue("LASTNAME", lastName)

           msg = msg & Chr(10) & firstName & " " & lastName

         Loop Until result.IsEndOfData

         Messagebox msg,, "Student Names"

         msg = "Student names:" & Chr(10)

         result.FirstRow

         firstName = result.GetValue("FIRSTNAME", firstName)

         lastName = result.GetValue("LASTNAME", lastName)

         msg = msg & Chr(10) & firstName & " " & lastName

         Do

           result.NextRow

           firstName = result.GetValue("FIRSTNAME", _

                       firstName)

           lastName = result.GetValue("LASTNAME", lastName)

           msg = msg & Chr(10) & firstName & " " & lastName

         Loop Until result.IsEndOfData

         Messagebox msg,, "Student Names"

         result.Close(DB_CLOSE)

         con.Disconnect

    End Sub
  3. This agent locates all the rows in a result set with "Cambridge" in field 5 and "MA" in field 6.

    4. Uselsx "*LSXODBC"

    Sub Initialize

         Dim con As New ODBCConnection

         Dim qry As New ODBCQuery

         Dim result As New ODBCResultSet

         Dim msg As String

         Set qry.Connection = con

         Set result.Query = qry

         con.ConnectTo("ATDB")

         qry.SQL = _

         "SELECT STUDENT_NO, LASTNAME, FIRSTNAME" & _

         " FROM STUDENTS ORDER BY LASTNAME"

         result.Execute

         msg = "Students from Cambridge MA:" & Chr(10)

         result.FirstRow

         Do While result.LocateRow(5, "Cambridge", 6, "MA")

              msg = msg &Chr(10)

              For i = 1 To result.NumColumns

                   msg = msg & result.GetValue(i) & "  "

              Next

              If result.IsEndOfData Then Exit Do

              result.NextRow

         Loop

         Messagebox msg

         result.Close(DB_CLOSE)

         con.Disconnect

    End Sub
  4. This agent displays a message containing the values of the STUDENT_NO, FIRSTNAME, and LASTNAME fields for each row in the result set. The variable into which the result set value is stored is also used as the second argument to GetValue to make the data typing explicit.

    5. Sub Initialize

         Dim con As New ODBCConnection

         Dim qry As New ODBCQuery

         Dim result As New ODBCResultSet

         Dim studentNo As String

         Dim firstName As String

         Dim lastName As String

         Dim msg As String

         Set qry.Connection = con

         Set result.Query = qry

         con.ConnectTo("ATDB")

         qry.SQL = "SELECT * FROM STUDENTS ORDER BY LASTNAME"

         result.Execute

         msg = "Student names:" & Chr(10)

         If result.IsResultSetAvailable Then

              Do

                   result.NextRow

                   If result.IsValueNull("STUDENT_NO") Then

                        studentNo = "None"

                   Else

                        studentNo =  _

                        result.GetValue("STUDENT_NO", _

                                       studentNo)

                   End If

                   If result.IsValueNull("FIRSTNAME") Then

                        firstName = "None"

                   Else

                        firstName = _

                        result.GetValue("FIRSTNAME", firstName)

                   End If

                   If result.IsValueNull("FIRSTNAME") Then

                        lastName = "None"

                   Else

                        lastName = _

                        result.GetValue("LASTNAME", lastName)

                   End If

                   msg = msg & Chr(10) & _

                   studentNo & " " & firstName & " " & lastName

              Loop Until result.IsEndOfData

         Else

              Messagebox "Cannot get result set for STUDENTS"

              Exit Sub

         End If

         Messagebox msg,, "Student Names"

         con.Disconnect

    End Sub
  5. This agent examines field 1 of the first row of the STUDENTS table and reports its LotusScript Typename when the expected data type is DB_CHAR. Use the constants that are remarked out to test the field for other expected data types.

    6. Sub Initialize

         Dim con As New ODBCConnection

         Dim qry As New ODBCQuery

         Dim result As New ODBCResultSet

         Set qry.Connection = con

         Set result.Query = qry

         con.ConnectTo("ATDB")

         qry.SQL = "SELECT * FROM STUDENTS ORDER BY LASTNAME"

         result.Execute

         If result.IsResultSetAvailable Then

              result.NextRow

              REM DB_CHAR DB_SHORT DB_LONG DB_DOUBLE DB_DATE

              REM DB_TIME

              REM DB_BINARY DB_BOOL DB_DATETIME

              REM DB_TYPEUNDEFINED

              Call result.FieldExpectedDataType(1, DB_CHAR)

              Messagebox result.GetValue(1) & " " & _

              "DB_CHAR" & " " & _

              Typename(result.GetValue(1)),, _

              "Field, expected data type, type name"

         Else

              Messagebox "Cannot get result set"

              Exit Sub

         End If

         result.Close(DB_CLOSE)

         con.Disconnect

    End Sub
  6. This example is based on a form and view, both named "Phone book." The form has three fields: lastName, firstName, and phoneNumber. The view displays the three fields and has actions to create a table based on the contents of the view, add selected documents from the view to the table, delete selected documents from the table and the view, and display the table.

    7. The action for creating a table demonstrates how to create a table, delete a table, and add rows to a table. The action for adding rows demonstrates how to add rows to a table. The action for deleting rows demonstrates how to locate and delete rows from a table.

    Uselsx "*LSXODBC"

    %INCLUDE "lsconst.lss"

    Dim session As NotesSession

    Dim db As NotesDatabase

    Dim view As NotesView

    Sub Postopen(Source As Notesuiview)

         Set session = New NotesSession

         Set db = session.CurrentDatabase

         Set view = db.GetView("Phone book")

    End Sub

    Sub Click(Source As Button)

    REM Create new table

       Dim con As New ODBCConnection

       Dim qry As New ODBCQuery

       Dim result As New ODBCResultSet

       Set qry.Connection = con

       Set result.Query = qry

       con.ConnectTo("ATDB")

       qry.SQL = "CREATE TABLE Phone (LASTNAME CHAR(32), " & _

       "FIRSTNAME CHAR(32), PHONENO CHAR(16))"

       result.Execute

       If qry.GetError <> DBstsSUCCESS And _

       Mid$(qry.GetExtendedErrorMessage, 31, 19) = _

       "File already exists" Then

              If Messagebox _

              ("Do you want to delete the existing table?", _

              MB_YESNO, "Table already exists") = IDYES Then

                   result.Close(DB_CLOSE)

                   qry.SQL = "DROP TABLE Phone"

                   If Not result.Execute() Then

                        Messagebox "Couldn't drop",, "Error"

                        con.Disconnect

                        Exit Sub

                   End If

                   result.Close(DB_CLOSE)

                   qry.SQL = _

                  "CREATE TABLE Phone (LASTNAME CHAR(32), " & _

                   "FIRSTNAME CHAR(32), PHONENO CHAR(16))"

                   result.Execute

              Else

                   result.Close(DB_CLOSE)

                   con.Disconnect

                   Exit Sub

              End If

              End If

         If qry.GetError <> DBstsSUCCESS Then

              result.Close(DB_CLOSE)

              con.Disconnect

              Messagebox qry.GetExtendedErrorMessage,, _

              qry.GetErrorMessage

              Exit Sub

         End If

         result.Close(DB_CLOSE)

         qry.SQL = "SELECT * FROM Phone"

         result.Execute

         Set doc = view.GetFirstDocument

         While Not(doc Is Nothing)

              result.AddRow

              Call result.SetValue("LASTNAME", doc.lastName(0))

              Call result.SetValue("FIRSTNAME", _

                                  doc.firstName(0))

              Call result.SetValue("PHONENO", _

                                doc.phoneNumber(0))

              result.UpdateRow

              Set doc = view.GetNextDocument(doc)

         Wend

         result.Close(DB_CLOSE)

         con.Disconnect

    End Sub

    Sub Click(Source As Button)

    REM Add new row(s)

         Dim con As New ODBCConnection

         Dim qry As New ODBCQuery

         Dim result As New ODBCResultSet

         Set qry.Connection = con

         Set result.Query = qry

         con.ConnectTo("ATDB")

         qry.SQL = "SELECT * FROM Phone"

         result.Execute

         Set dc = db.UnprocessedDocuments

         If dc.Count = 0 Then

              result.Close(DB_CLOSE)

              con.Disconnect

              Exit Sub

         End If

         For i = 1 To dc.Count

              Set doc = dc.GetNthDocument(i)

              result.AddRow

              Call result.SetValue("LASTNAME", doc.lastName(0))

              Call result.SetValue("FIRSTNAME", _

                                  doc.firstName(0))

              Call result.SetValue("PHONENO", _

                                  doc.phoneNumber(0))

              result.UpdateRow

         Next

         result.Close(DB_CLOSE)

         con.Disconnect

    End Sub

    Sub Click(Source As Button)

    REM Delete row(s)

         Dim con As New ODBCConnection

         Dim qry As New ODBCQuery

         Dim result As New ODBCResultSet

         Set qry.Connection = con

         Set result.Query = qry

         con.ConnectTo("ATDB")

         qry.SQL = "SELECT * FROM Phone"

         result.Execute

         Set dc = db.UnprocessedDocuments

         If dc.Count = 0 Then

              result.Close(DB_CLOSE)

              con.Disconnect

              Exit Sub

         End If

         For i = 1 To dc.Count

              Set doc = dc.GetNthDocument(i)

              If result.LocateRow(1, doc.lastName(0), _

                                 2, doc.firstName(0)) Then

                   result.DeleteRow("Phone")

              End If

              Call doc.Remove(True)

         Next

         view.Refresh

         result.Close(DB_CLOSE)

         con.Disconnect

    End Sub

    Sub Click(Source As Button)

    REM Display table

         Dim con As New ODBCConnection

         Dim qry As New ODBCQuery

         Dim result As New ODBCResultSet

         Set qry.Connection = con

         Set result.Query = qry

         con.ConnectTo("ATDB")

         qry.SQL = "SELECT * FROM Phone ORDER BY LASTNAME"

         result.Execute

         msg = "Phone entries:" & Chr(10)

         Do

              result.NextRow

              firstName = result.GetValue("FIRSTNAME", _

                                         firstName)

              lastName = result.GetValue("LASTNAME", lastName)

              phoneNo = result.GetValue("PHONENO", phoneNo)

              msg = msg & Chr(10) & firstName & " " _

              & lastName & " " & phoneNo

         Loop Until result.IsEndOfData

         Messagebox msg,, "Phone numbers"

         result.Close(DB_CLOSE)

         con.Disconnect

    End Sub

See also
Working with data retrieved from an external database


Examples: Examining and adjusting an access control list

  1. This example displays whether uniform access is enforced, then accesses each entry in the ACL of a local database and displays its name.

    2. Sub Initialize

         Dim db As New NotesDatabase _

         ("", Inputbox("Name of database"))

         Dim dbACL As NotesACL

         Dim dbACLEntry As NotesACLEntry

         Set dbACL = db.ACL

         Set dbACLEntry = dbACL.GetFirstEntry()

         If dbACL.UniformAccess Then

              Messagebox "Uniform access in effect"

         Else

              Messagebox "Uniform access not in effect"

         End If

         While Not(dbACLEntry Is Nothing)

              Messagebox dbACLEntry.Name

              Set dbACLEntry = dbACL.GetNextEntry(dbACLEntry)

         Wend

    End Sub
  2. This example indicates the maximum Internet access level for a database.

    3. Sub Initialize

         Dim session As New NotesSession

         Dim db As NotesDatabase

         Dim acl As NotesACL

         Set db = session.CurrentDatabase

         Messagebox acl.InternetLevel

         If acl.InternetLevel = ACLLEVEL_READER Then

              acl.InternetLevel = ACLLEVEL_EDITOR

         End If

         Call acl.Save

    End Sub
  3. This example finds an entry in the ACL of a local database and displays some of its properties.

    4. Sub Initialize

         Dim db As New NotesDatabase _

         ("", Inputbox("Name of database"))

         Dim dbACL As NotesACL

         Dim dbACLEntry As NotesACLEntry

         Set dbACL = db.ACL

         Set dbACLEntry = dbACL.GetEntry _

         (Inputbox("Name of ACL entry?"))

         Messagebox "Name: " & dbACLEntry.Name

         Select Case dbACLEntry.Level

         Case ACLLEVEL_NOACCESS : level = "No access"

         Case ACLLEVEL_DEPOSITOR : level = "Depositor"

         Case ACLLEVEL_READER : level = "Reader"

         Case ACLLEVEL_AUTHOR : level = "Author"

         Case ACLLEVEL_EDITOR : level = "Editor"

         Case ACLLEVEL_DESIGNER : level = "Designer"

         Case ACLLEVEL_MANAGER : level = "Manager"

         End Select

         Messagebox "Access level is " & level

         If dbACLEntry.CanCreateDocuments Then

              Messagebox "Can create documents"

         Else

              Messagebox "Cannot create documents"

         End If

         If dbACLEntry.CanDeleteDocuments Then

              Messagebox "Can delete documents"

         Else

              Messagebox "Cannot delete documents"

         End If

         dbRoles = dbACLEntry.Roles

         If Not(Isempty(dbRoles)) Then

              Forall dbRole In dbRoles

                   Messagebox "Role: " & dbRole

              End Forall

         Else

              Messagebox "No roles for this ACL entry"

         End If

         If dbACLEntry.IsAdminServer <> True Then

              Messagebox "Entry does not have server

              adminstration access."

         Else

              Messagebox "Entry may administer server."

         End If

         If dbACLEntry.IsAdminReaderAuthor <> True Then

              Messagebox "AdminReaderAuthor access denied."

         Else

              Messagebox "AdminReaderAuthor access allowed."

         End If

         If dbACLEntry.CanCreateSharedFolder = True Then

              Messagebox "Can create shared folders."

         Else

              Messagebox "Cannot create shared folders."

         End If

    End Sub
  4. This example creates a new ACL entry in a database.

    5. Sub Initialize

         Dim db As New NotesDatabase _

         ("", Inputbox("Name of database"))

         Dim dbACL As NotesACL

         Dim dbACLEntry As NotesACLEntry

         Set dbACL = db.ACL

         ename = Inputbox("Name of new ACL entry?")

         Set dbACLEntry = New NotesACLEntry _

         (dbACL, ename, ACLLEVEL_DESIGNER)

         Messagebox dbACLEntry.Name & " " &dbACLEntry.Level

         Call dbACL.Save

    End Sub
  5. This example removes an ACL entry from a database.

    6. Sub Initialize

         Dim db As New NotesDatabase _

         ("", Inputbox("Name of database"))

         Dim dbACL As NotesACL

         Dim dbACLEntry As NotesACLEntry

         Set dbACL = db.ACL

         ename = Inputbox("Name of ACL entry to be removed?")

         Set dbACLEntry = dbACL.GetEntry(ename)

         Messagebox dbACLEntry.Name & " " & dbACLEntry.Level

         Call dbACLEntry.Remove

         Call dbACL.save

    End Sub
  6. This example adds a role to a database ACL and enables it for an ACL entry.

    7. Sub Initialize

         Dim db As New NotesDatabase _

         ("", Inputbox("Name of database"))

         Dim dbACL As NotesACL

         Dim dbACLEntry As NotesACLEntry

         Set dbACL = db.ACL

         ename = Inputbox("Name of ACL entry?")

         Set dbACLEntry = dbACL.GetEntry(ename)

         Call dbACL.AddRole("Role 3")

         Call dbACLEntry.EnableRole("Role 3")

         dbRoles = dbACLEntry.Roles

         If Not(Isempty(dbRoles)) Then

              Forall dbRole In dbRoles

                   Messagebox "Role " & dbRole

              End Forall

         Else

              Messagebox "No roles for this ACL entry"

         End If

         Call dbACL.save

    End Sub
  7. This example displays and then changes the user type of an ACL entry in a database.

    8. Sub Initialize

         Dim session As New NotesSession

         Dim db As NotesDatabase

         Dim acl As NotesACL

         Dim entry As NotesACLEntry

         Set db = session.CurrentDatabase

         Set acl = db.ACL

         Set entry = acl.GetEntry("Lloyd Johnson")

         If entry.IsGroup <> True Then

              Messagebox entry.Name & " is not a group."

              entry.IsGroup = True

         Else

              Messagebox entry.Name & " is a group."

         End If

         Call acl.Save

    End Sub


Examples: Examining and adjusting database replication settings

  1. This example displays several replication properties of a database.

    2. Sub Intialize

         Dim session As New NotesSession

         Dim db As NotesDatabase

         Dim rep As NotesReplication

         Set db = session.CurrentDatabase

         Set rep = db.ReplicationInfo

         Messagebox "Cut off date: " & rep.CutOffDate & _

         Chr(10)_

         & "Cut off interval: " & rep.CutOffInterval & _

         Chr(10)_

         If rep.Abstract = True Then

           Messagebox "Truncate large documents" & Chr(10)_

                       & "and remove attachments."

         Else

           Messagebox "Do not Truncate large" & Chr(10)_

                       & "documents and remove attachments."

         End If

         If rep.CutOffDelete = True Then

           Messagebox "Automatically delete old documents."

         Else

           Messagebox "Do not delete old documents"

         End If

         If rep.Disabled = True Then

           Messagebox "Replication is disabled."

         Else

           Messagebox "Replication is enabled."

         End If

         If rep.DoNotBrowse = True Then

           Messagebox "Not in Open Database dialog."

         Else

           Messagebox "In Open Database dialog."

         End If

         If rep.DoNotCatalog = True Then

           Messagebox "Not in database catalog."

         Else

           Messagebox "In database catalog."

         End If

         If rep.HideDesign = True Then

           Messagebox "Database design is hidden."

         Else

           Messagebox "Database design is visible."

         End If

         If rep.IgnoreDeletes = True Then

           Messagebox "Deletions will not be replicated."

         Else

           Messagebox "Deletions will be replicated."

         End If

         If rep.IgnoreDestDeletes = True Then

           Messagebox _

           ("Deletions will not replicate to destination database.")

         Else

           Messagebox _

           ("Deletions will replicate to destination database.")

         End If

         If rep.MultiDBIndex = True Then

           Messagebox _

           ("Included in multi-database indexing.")

         Else

           Messagebox _

           ("Not included in multi-database indexing.")

         End If

         If rep.NeverReplicate = True Then

           Messagebox "Replication disabled."

         Else

           Messagebox "Replication enabled."

         End If

         If rep.NoChronos = True Then

           Messagebox "Background agents disabled."

         Else

           Messagebox "Background agents enabled."

         End If

         If rep.Priority = DB_REPLICATION_PRIORITY_LOW Then

           Messagebox "Replication priority: Low"

         Else

         If rep.Priority = DB_REPLICATION_PRIORITY_MED Then

           Messagebox "Replication priority: Medium"

         Else

         If rep.Priority = DB_REPLICATION_PRIORITY_HIGH Then

           Messagebox "Replication priority: High"

         Else

         If rep.Priority = DB_REPLICATION_PRIORITY_NOTSET Then

           Messagebox "Replication priority: Not set"

         End If

         End If

         End If

         End If

    End Sub
  2. This example sets the replication priority to high and keeps deletions from replicating.

    3. Sub Intialize

         Dim session As New NotesSession

         Dim db As NotesDatabase

         Dim rep As NotesReplication

         Set db = session.CurrentDatabase

         Set rep = db.ReplicationInfo

         If rep.Priority <> DB_REPLICATION_PRIORITY_HIGH Then

              rep.Priority = DB_REPLICATION_PRIORITY_HIGH

         End If

         If rep.IgnoreDeletes <> True Then

              rep.IgnoreDeletes = True

         End If

         Call rep.Save()

    End Sub
  3. This example disables replication by selecting Temporarily Disable Replication in the UI.

    4. Sub Initialize

         Dim session As New NotesSession

         Dim db As NotesDatabase

         Dim rep As NotesReplication

         Set db = session.CurrentDatabase

         Set rep = db.ReplicationInfo

         If rep.Disabled <> True Then

              rep.Disabled = True

         End If

         Call rep.Save()

    End Sub
  4. This example disables replication, but does not affect the UI.

    5. Sub Intialize

         Dim session As New NotesSession

         Dim db As NotesDatabase

         Dim rep As NotesReplication

         Set db = session.CurrentDatabase

         Set rep = db.ReplicationInfo

         If rep.NeverReplicate <> True Then

              rep.NeverReplicate = True

         End If

         Call rep.Save()

    End Sub
  5. This example disables background agents.

    6. Sub Intialize

         Dim session As New NotesSession

         Dim db As NotesDatabase

         Dim rep As NotesReplication

         Set db = session.CurrentDatabase

         Set rep = db.ReplicationInfo

         If rep.NoChronos <> True Then

              rep.NoChronos = True

         End If

         Call rep.Save()

    End Sub


Example: Execute method

This agent executes an SQL query. The agent also displays some of the ODBCResultSet properties after the Execute method and after all the rows in the result set are accessed.

Uselsx "*LSXODBC"

Dim con As ODBCConnection

Dim qry As ODBCQuery

Dim result As ODBCResultSet

Dim firstName As String

Dim lastName As String

Dim msg As String

Sub Initialize

     Set con = New ODBCConnection

     Set qry = New ODBCQuery

     Set result = New ODBCResultSet

     Set qry.Connection = con

     Set result.Query = qry

     con.ConnectTo("ATDB")

     qry.SQL = "SELECT * FROM STUDENTS"

     If Not result.Execute Then

          Messagebox _

          result.GetExtendedErrorMessage,, result.GetErrorMessage

          Exit Sub

     End If

     REM Display result set properties after Execute

     Call DisplayResultSetProperties

     msg = "Student names:" & Chr(10)

     Do

          result.NextRow

          firstName = result.GetValue("FIRSTNAME", firstName)

          lastName = result.GetValue("LASTNAME", lastName)

          msg = msg & Chr(10) & firstName & " " & lastName

     Loop Until result.IsEndOfData

     Messagebox msg,, "Student Names"

     REM Display result set properties after  _

     REM processing result set

     Call DisplayResultSetProperties

     result.Close(DB_CLOSE)

     con.Disconnect

End Sub

Sub DisplayResultSetProperties

     If result.IsResultSetAvailable Then

          If result.NumRows = DB_ROWSUNKNOWN Then

               rows$ = "Not determined yet"

          Else

               rows$ = Cstr(result.NumRows)

          End If

          Messagebox _

          "NumColumns = " & result.NumColumns & Chr(10) & _

          "NumRows = " & rows$ & Chr(10) &  _

          "IsBeginOfData = " & result.IsBeginOfData & _

          Chr(10) & _

          "IsEndOfData = " & result.IsEndOfData & Chr(10) _

          & "CurrentRow = " & result.CurrentRow,,  _

          "Result set properties"

     Else

          Messagebox "Result set not available",, _

          "No result set"

     End If

End Sub


Example: ExpandAllSections method

This script expands the sections in a document if the user switches to Edit mode, and collapses them if the user switches to Read mode.

Sub Postmodechange(Source As Notesuidocument)

  If source.EditMode Then

    Call source.ExpandAllSections

  Else

    Call source.CollapseAllSections

  End If

End Sub


Example: ExtractFile method

This script detaches and removes all the file attachments in a document's Body item that are larger than 100,000 bytes. The first file attachment that's found gets detached to c:\reports\newfile1, the second attachment that's found gets detached to c:\reports\newfile2, and so on.

Dim doc As NotesDocument

Dim rtitem As Variant

Dim fileCount As Integer

Const MAX = 100000

fileCount = 0

'...set value of doc...

Set rtitem = doc.GetFirstItem( "Body" )

If ( rtitem.Type = RICHTEXT ) Then

  Forall o In rtitem.EmbeddedObjects

    If ( o.Type = EMBED_ATTACHMENT ) _

    And ( o.FileSize > MAX ) Then

      fileCount = fileCount + 1

      Call o.ExtractFile _

      ( "c:\reports\newfile" & Cstr(fileCount) )

      Call o.Remove

      Call doc.Save( True, True )

    End If

  End Forall

End If


Example: FetchBatchSize property

This example shows an action (the Click sub) that displays the current CacheLimit and FetchBatchSize values, sets new ones according to user input, and displays the new values. The example makes sure that FetchBatchSize is not greater than CacheLimit.

Uselsx "*LSXODBC"

%INCLUDE "lsconst.lss"

Dim con As ODBCConnection

Dim qry As ODBCQuery

Dim result As ODBCResultSet

Sub Postopen(Source As Notesuidocument)

     Set con = New ODBCConnection

     Set qry = New ODBCQuery

     Set result = New ODBCResultSet

     Set qry.Connection = con

     Set result.Query = qry

     con.ConnectTo("ATDB")

     qry.SQL = "SELECT * FROM STUDENTS ORDER BY LASTNAME"

     result.Execute

     ...

End Sub

Sub Click(Source As Button)

     If Messagebox("Current settings" & Chr(10) & Chr(10) _

     & "Cache limit: " & result.CacheLimit & Chr(10) _

     & "Fetch batch size: " & result.FetchBatchSize, _

     MB_YESNO, "Do you want change?") = IDYES Then

          cLimit = Inputbox _

          ("Enter 0 for DB_NONE or size of cache", _

          "Cache limit?")

          If cLimit = 0 Then

               result.cacheLimit = DB_NONE

          Elseif cLimit > 0 Then

               result.cacheLimit = cLimit

          Else

               Messagebox  _

               "Cache limit must be 0 or positive integer"

               Exit Sub

          End If

          fbSize = Inputbox("Enter fetch batch size", _

                            "Fetch batch size")

          If fbSize < 1 Then

            Messagebox _

            "Fetch batch size must be positive integer

            and not zero"

            result.FetchBatchSize = 1

          Elseif cLimit <> 0 And fbSize > cLimit Then

               result.FetchBatchSize = cLimit

               Messagebox "Fetch batch size reduced to" _

               & result.CacheLimit,, _

               "Fetch batch size cannot exceed cache limit"

          Else

               result.FetchBatchSize = fbSize

          End If

          Messagebox "New settings" & Chr(10) & Chr(10) _

          & "Cache limit: " & result.CacheLimit & Chr(10) _

          & "Fetch batch size: " & result.FetchBatchSize, , _

          "New settings"

     End If

End Sub

Sub Queryclose(Source As Notesuidocument, Continue As Variant)

     result.Close(DB_CLOSE)

     con.Disconnect

End Sub


Examples: FieldAppendText method

  1. This form action script appends the phrase "Over here, balloon man!" to the Body field of the current document.

    2. Sub Click(Source As Button)

      Dim workspace As New NotesUIWorkspace

      Dim uidoc As NotesUIDocument

      Set uidoc = workspace.CurrentDocument

      Call uidoc.FieldAppendText _

      ( "Body", "Over here, balloon man!" )

    End Sub
  2. This script appends today's date, the current user's name, and the contents of the Event field (each separated by spaces) to the Log field, when the user saves the document. The Event field is cleared.

Sub Querysave(Source As Notesuidocument, Continue As Variant)

  Dim session As New NotesSession

  Call source.FieldAppendText( "Log", Cstr( Date ) )

  Call source.FieldAppendText( "Log", " " )

  Call source.FieldAppendText _

  ( "Log", session.CommonUserName )

  Call source.FieldAppendText( "Log", " " )

  Call source.FieldAppendText _

  ( "Log", source.FieldGetText( "Event" ) )

  Call source.FieldClear( "Event" )

End Sub

  1. This button script appends a new value to a text list. The script prompts the user for a string value. If the choices field is empty, the script adds the new string to the choices field. If the choices field already contains values, the script appends the new string to the choices field, preceded by a semicolon, which is the designated multi-value separator for the field.

    2. Sub Click(Source As Button)

      Dim workspace As New NotesUIWorkspace

      Dim uidoc As NotesUIDocument

      Dim currentChoices As String

      Dim newChoice As String

      Set uidoc = workspace.CurrentDocument

      currentChoices = uidoc.FieldGetText( "choices" )

      newChoice = Inputbox$( "Please enter a new choice: " )

      If ( currentChoices = "" ) Then

        Call uidoc.FieldSetText( "choices", newChoice )

      Else

        Call uidoc.FieldAppendText("choices", ";" & newChoice)

      End If

    End Sub


Example: FieldClear method

This script appends the contents of the LatestEvent field, preceded by three dashes, to the History field, before the document is saved. The LatestEvent field is cleared so that another event can be entered into it.

Sub Querysave(Source As Notesuidocument, Continue As Variant)

  Dim lastEvent As String

  lastEvent = source.FieldGetText( "LatestEvent" )

  Call source.FieldAppendText( "History", "---" )

  Call source.FieldAppendText( "History", lastEvent )

  Call source.FieldClear( "LatestEvent" )

End Sub

After the document has been edited and saved three times, the History field might look like this:

---Aerial photographs of deforestation published---Government reacts---Public protests began today


Example: FieldContains method

This script checks the contents of the Conclusion field when the user exits the field. If Conclusion contains the word "disaster," as in "This project was a complete disaster," the script displays a message to comfort the user.

Sub Exiting(Source As Field)

  Dim workspace As New NotesUIWorkspace

  Dim uidoc As NotesUIDocument

  Set uidoc = workspace.CurrentDocument

  If uidoc.FieldContains( "Conclusion", "disaster" ) Then

    Messagebox( "Sorry to hear it." )

  End If

End Sub


Examples: FieldExpectedDataType method

  1. This agent sets the expected data type for fields 2, 3, and 4 to DB_LONG and checks the return value to make sure that the field is convertible to that data type.

    2. Uselsx "*LSXODBC"

    Sub Initialize

         Dim con As New ODBCConnection

         Dim qry As New ODBCQuery

         Dim result As New ODBCResultSet

         Dim firstName As String

         Dim lastName As String

         Dim msg As String

         Set qry.Connection = con

         Set result.Query = qry

         con.ConnectTo("ATDB")

         qry.SQL = "SELECT * FROM GETSCALE"

         result.Execute

         If result.FieldExpectedDataType(2, _

         DB_LONG) <> DB_LONG Then

              Messagebox _

              "Data type wrong for field 2",, "Bad data type"

              Exit Sub

         End If

         If result.FieldExpectedDataType(3, DB_LONG) <> DB_LONG Then

              Messagebox "Data type wrong for field 2",, _

                         "Bad data type"

              Exit Sub

         End If

         If result.FieldExpectedDataType(4, DB_LONG) <> DB_LONG Then

              Messagebox "Data type wrong for field 2",, _

                         "Bad data type"

              Exit Sub

         End If

         msg = "Getscale data:" & Chr(10)

         Do

              result.NextRow

              msg = msg & Chr(10)

              For i = 1 To result.NumColumns

                   msg = msg & "  " & result.GetValue(i)

              Next

         Loop Until result.IsEndOfData

         Messagebox msg,, "Getscale Data"

         con.Disconnect

    End Sub
  2. This agent executes an SQL query; sets the expected data type of each field in the result set; and displays the field ID, field name, and expected data type. The expected data type is set by interpolating from the native data type.

Uselsx "*LSXODBC"

Sub Initialize

     Dim con As New ODBCConnection

     Dim qry As New ODBCQuery

     Dim result As New ODBCResultSet

     Dim msg As String

     Set qry.Connection = con

     Set result.Query = qry

     con.ConnectTo("ATDB")

     qry.SQL = "SELECT * FROM STUDENTS"

     result.Execute

     msg = "Fields in STUDENTS table:" & Chr(10)

     For i = 1 To result.NumColumns

          Call result.FieldExpectedDataType(i, _

          SetDataType(result.FieldNativeDataType(i)))

          msg = msg & Chr(10) & i & " " & _

          result.FieldName(i) _

          & " " & _

          GetDataType(result.FieldExpectedDataType(i))

     Next

     Messagebox msg,, "Field names and expected data types"

     result.Close(DB_CLOSE)

     con.Disconnect

End Sub

Function GetDataType(typeConst As Integer) As String

     Select Case typeConst

     Case DB_TYPE_UNDEFINED : GetDataType = "UNDEFINED"

     Case DB_CHAR : GetDataType = "CHAR"

     Case DB_SHORT : GetDataType = "DECIMAL"

     Case DB_LONG : GetDataType = "SHORT"

     Case DB_DOUBLE : GetDataType = "DOUBLE"

     Case DB_DATE : GetDataType = "DATE"

     Case DB_TIME : GetDataType = "TIME"

     Case DB_BINARY : GetDataType = "BINARY"

     Case DB_BOOL : GetDataType = "BOOL"

     Case DB_DATETIME : GetDataType = "DATETIME"

     End Select

End Function

Function SetDataType(typeConst As Integer) As Integer

     Select Case typeConst

     Case SQL_CHAR : SetDataType = DB_CHAR

     Case SQL_NUMERIC : SetDataType = DB_TYPE_UNDEFINED

     Case SQL_DECIMAL : SetDataType = DB_TYPE_UNDEFINED

     Case SQL_INTEGER : SetDataType = DB_SHORT

     Case SQL_SMALLINT : SetDataType = DB_SHORT

     Case SQL_FLOAT : SetDataType = DB_DOUBLE

     Case SQL_REAL : SetDataType = DB_DOUBLE

     Case SQL_DOUBLE : SetDataType = DB_DOUBLE

     Case SQL_DATE : SetDataType = DB_DATE

     Case SQL_TIME : SetDataType = DB_TIME

     Case SQL_TIMESTAMP : SetDataType = DB_DATETIME

     Case SQL_VARCHAR : SetDataType = DB_CHAR

     Case SQL_BINARY : SetDataType = DB_BINARY

     Case SQL_VARBINARY : SetDataType = DB_BINARY

     Case SQL_LONGVARCHAR : SetDataType = DB_CHAR

     Case SQL_LONGVARBINARY : SetDataType = DB_BINARY

     Case SQL_BIGINT : SetDataType = DB_LONG

     Case SQL_TINYINT : SetDataType = DB_SHORT

     Case SQL_BIT : SetDataType = DB_BINARY

     End Select

End Function


Examples: FieldGetText method

  1. This script puts the string "02:32 PM Today" into the variable composed, if the DateComposed field holds the date-time value 02:32 PM Today.

    2. Sub Click(Source As Button)

      Dim workspace As New NotesUIWorkspace

      Dim uidoc As NotesUIDocument

      Dim composed As String

      Set uidoc = workspace.CurrentDocument

      composed = uidoc.FieldGetText( "DateComposed" )

    End Sub
  2. This script uses FieldGetText to send a mail memo to the author of a document. It assumes that the author is stored in the From field. For example, if the current document's author is Stephanie Mavis and its subject is "Suit and tie," this script sends a memo to Stephanie Mavis with a subject "Re: Suit and tie."

    3. Sub Click(Source As Button)

      Dim workspace As New NotesUIWorkspace

      Dim session As New NotesSession

      Dim db As NotesDatabase

      Dim uidoc As NotesUIDocument

      Dim doc As NotesDocument

      Set db = session.CurrentDatabase

      Set uidoc = workspace.CurrentDocument

      Set doc = New NotesDocument( db )

      doc.Form = "Memo"

      doc.Subject = "Re: " + uidoc.FieldGetText( "Subject" )

      doc.Body = _

      "Please send me some more information on this topic."

      Call doc.Send( False, uidoc.FieldGetText( "From" ) )

    End Sub


Example: FieldHelp property

This script turns field help on.

Sub Click(Source As Button)

  Dim workspace As New NotesUIWorkspace

  Dim uidoc As NotesUIDocument

  Set uidoc = workspace.CurrentDocument

  uidoc.FieldHelp = True

End Sub


Example: FieldID method

This agent executes an SQL query, gets a field name from the user, and displays its field ID.

Uselsx "*LSXODBC"

Sub Initialize

     Dim con As New ODBCConnection

     Dim qry As New ODBCQuery

     Dim result As New ODBCResultSet

     Dim fieldName As String

     Set qry.Connection = con

     Set result.Query = qry

     con.ConnectTo("ATDB")

     qry.SQL = "SELECT * FROM STUDENTS"

     result.Execute

     fieldName = Inputbox$("Field name?", "STUDENTS table")

     If result.FieldID(fieldName) Then

          Messagebox result.FieldID(fieldName),, fieldName

     Else

          Messagebox "No such field",, fieldName

     End If

     result.Close(DB_CLOSE)

     con.Disconnect

End Sub


Example: FieldName method

This agent executes an SQL query and displays the column number and the name of each field in the result set.

Uselsx "*LSXODBC"

Sub Initialize

     Dim con As New ODBCConnection

     Dim qry As New ODBCQuery

     Dim result As New ODBCResultSet

     Dim msg As String

     Set qry.Connection = con

     Set result.Query = qry

     con.ConnectTo("ATDB")

     qry.SQL = "SELECT * FROM STUDENTS"

     result.Execute

     msg = "Fields in STUDENTS table:" & Chr(10)

     For i = 1 To result.NumColumns

          msg = msg & Chr(10) & i & " " & result.FieldName(i)

     Next

     Messagebox msg,, "Field names"

     result.Close(DB_CLOSE)

     con.Disconnect

End Sub


Example: FieldNativeDataType method

This agent executes an SQL query and displays the column number, name, and data type of each field in the result set. The text for the data type is obtained by examining all possible return values to FieldNativeDataType.

Uselsx "*LSXODBC"

Sub Initialize

     Dim con As New ODBCConnection

     Dim qry As New ODBCQuery

     Dim result As New ODBCResultSet

     Dim msg As String

     Set qry.Connection = con

     Set result.Query = qry

     con.ConnectTo("ATDB")

     qry.SQL = "SELECT * FROM STUDENTS"

     result.Execute

     msg = "Fields in STUDENTS table:" & Chr(10)

     For i = 1 To result.NumColumns

          msg = msg & Chr(10) & i & " " & result.FieldName(i) _

          & " " & GetDataType(result.FieldNativeDataType(i))

     Next

     Messagebox msg,, "Field names"

     result.Close(DB_CLOSE)

     con.Disconnect

End Sub

Function GetDataType(typeConst As Integer) As String

     Select Case typeConst

     Case SQL_CHAR : GetDataType = "CHAR"

     Case SQL_NUMERIC : GetDataType = "NUMERIC"

     Case SQL_DECIMAL : GetDataType = "DECIMAL"

     Case SQL_INTEGER : GetDataType = "INTEGER"

     Case SQL_SMALLINT : GetDataType = "SMALLINT"

     Case SQL_FLOAT : GetDataType = "FLOAT"

     Case SQL_REAL : GetDataType = "REAL"

     Case SQL_DOUBLE : GetDataType = "DOUBLE"

     Case SQL_DATE : GetDataType = "DATE"

     Case SQL_TIME : GetDataType = "TIME"

     Case SQL_TIMESTAMP : GetDataType = "TIMESTAMP"

     Case SQL_VARCHAR : GetDataType = "VARCHAR"

     Case SQL_BINARY : GetDataType = "BINARY"

     Case SQL_VARBINARY : GetDataType = "VARBINARY"

     Case SQL_LONGVARCHAR : GetDataType = "LONGVARCHAR"

     Case SQL_LONGVARBINARY : GetDataType = "LONGVARBINARY"

     Case SQL_BIGINT : GetDataType = "BIGINT"

     Case SQL_TINYINT : GetDataType = "TINYINT"

     Case SQL_BIT : GetDataType = "BIT"

     End Select

End Function


Example: Fields property

This script displays the names of all the fields on a form.

Dim session As New NotesSession

Dim db As NotesDatabase

Set db = session.CurrentDatabase

formNameIn = Lcase(Inputbox("Name of form?"))

Forall form In db.Forms

     If Lcase(form.Name) = formNameIn Then

          If Isempty(form.Fields) Then

               Messagebox form.Name & " has no fields"

          Else

               fieldCount = 0

               msgString = ""

               Forall field In form.Fields

                    fieldCount = fieldCount + 1

                    msgString = msgString & Chr(10) & _

                    "     " & field

               End Forall

               Messagebox form.Name & " has " & _

               fieldCount & _

               " field(s):" & Chr(10) & msgString

          End If

          Exit Sub

     End If

End Forall

Messagebox "The form """ & formNameIn & """ does not exist"


Examples: FieldSetText method

  1. This script sets the value of the Creator field to the user's name after a document is opened in Edit mode. For example, if Brian Flokka creates a new document, the string "Brian Flokka" is placed in the Creator field.

Sub Postopen(Source As Notesuidocument)

  Dim session As New NotesSession

  If source.EditMode Then

    Call source.FieldSetText _

    ( "Creator", session.CommonUserName )

  End If

End Sub
  1. This script gets the value of four number fields: Q1, Q2, Q3, and Q4, and converts them to integers using Cint(). It adds the four values together and sets the value of the Total field, using Cstr() to convert the result to a string.

Sub Querysave(Source As Notesuidocument, Continue As Variant)

  a% = Cint( source.FieldGetText( "Q1" ) )

  b% = Cint( source.FieldGetText( "Q2" ) )

  c% = Cint( source.FieldGetText( "Q3" ) )

  d% = Cint( source.FieldGetText( "Q4" ) )

  Call source.FieldSetText _

  ( "Total", Cstr( a% + b% + c% + d% ) )

End Sub


Example: FieldSize method

This agent executes an SQL query and displays the column number, name, and size of each field in the result set.

Uselsx "*LSXODBC"

Sub Initialize

     Dim con As New ODBCConnection

     Dim qry As New ODBCQuery

     Dim result As New ODBCResultSet

     Dim msg As String

     Set qry.Connection = con

     Set result.Query = qry

     con.ConnectTo("ATDB")

     qry.SQL = "SELECT * FROM STUDENTS"

     result.Execute

     msg = "Fields in STUDENTS table:" & Chr(10)

     For i = 1 To result.NumColumns

          msg = msg & Chr(10) & i & " " & _

          result.FieldName(i)

          & " " & result.FieldSize(i)

     Next

     Messagebox msg,, "Field names and sizes"

     result.Close(DB_CLOSE)

     con.Disconnect

End Sub


Examples: FileName property

  1. This script gets the file name of the database cbanner.nsf. The property returns "cbanner.nsf."

    2. Dim db As New NotesDatabase( "Sofia", "cbanner.nsf" )

    Dim file As String

    file = db.FileName
  2. This script gets the file name of the database cs_doc.nsf. The property returns "cs_doc.nsf."

    3. Dim db As New NotesDatabase( "Sofia", "cserv\cs_doc.nsf" )

    Dim file As String

    file = db.FileName


Examples: FilePath property

  1. This script gets the path of the database cbanner.nsf. The property returns "cbanner.nsf."

    2. Dim db As New NotesDatabase( "Sofia", "cbanner.nsf" )

    Dim path As String

    path = db.FilePath
  2. This script gets the path of the database cserv\cs_doc.nsf. The property returns "c:\notes\cserv\cs_doc.nsf."

    3. Dim db As New NotesDatabase( "", "c:\notes\cserv\cs_doc.nsf" )

    Dim path As String

    path = db.FilePath


Example: FileSize property

This script gets the size of the "City picture" embedded object in the Body item of a document, and puts it into sizeInBytes. For example, FileSize might return 582.

Dim doc As NotesDocument

Dim rtitem As Variant

Dim object As NotesEmbeddedObject

Dim sizeInBytes As Long

'...set value of doc...

Set rtitem = doc.GetFirstItem( "Body" )

If ( rtitem.Type = RICHTEXT ) Then

  Set object = rtitem.GetEmbeddedObject( "City picture" )

  sizeInBytes = object.FileSize

End If


Example: FindFreeTimeDialog method

This script opens the Free Time dialog box using the names that are in the SendTo field of the current UI document, and the dates that are in the StartDateTime and EndDateTime fields.

Sub Click(Source As Button)

     Dim workspace As New NotesUIWorkspace

     Dim uidoc As NotesUIDocument

     Set uidoc = workspace.CurrentDocument

     Call uidoc.Refresh

     Call uidoc.FindFreeTimeDialog _

     ("SendTo", "", "", "", "", "", "", _

        "StartDateTime","EndDateTime")

End Sub


Example: FindFreeTimeDialogEx method

This script opens the Free Time dialog box using the names that are in the SendTo field of the current UI document and tells you who is free for a meeting during the time period listed in the StartDateTime and EndDateTime fields.

Sub Click(Source As Button)

     Dim workspace As New NotesUIWorkspace

     Dim uidoc As NotesUIDocument

     Set uidoc = workspace.CurrentDocument

     Call uidoc.Refresh

     Call uidoc.FindFreeTimeDialogEx _

     ("SendTo", "", "", "", "", "", "", _

         "StartDateTime", "EndDateTime")

End Sub


Example: FindString method

This script finds a user defined string in the current UI document.

Sub Click(Source As Button)

     Dim workspace As New NotesUIWorkspace

     Dim uidoc As NotesUIDocument

     Set uidoc = workspace.CurrentDocument

     Call uidoc.FindString(Inputbox$( _

             "Word or phrase to look for:"))

End Sub


Example: FirstLineLeftMargin property

This example changes the FirstLineLeftMargin attribute and displays the change.

Dim session As New NotesSession

Dim db As NotesDatabase

Set db = session.Currentdatabase

Dim doc As New NotesDocument(db)

Call doc.AppendItemValue("From", session.Username)

Call doc.AppendItemValue("subject", _

"Meeting agenda")

Dim rtpStyle As NotesrichTextParagraphStyle

Set rtpStyle = session.CreateRichTextParagraphStyle

Dim richText As New NotesRichTextItem(doc, "Body")

If rtpStyle.FirstLineLeftMargin <> RULER_ONE_INCH Then

rtpStyle.FirstLineLeftMargin = RULER_ONE_INCH

Call richText.AppendText("Where are we now?")

Call richText.AppendParagraphStyle(rtpStyle)

Messagebox "First Line Left Margin: " &

rtpStyle.FirstLineLeftMargin

Call doc.Save(True, False)

End If


Example: FirstRow method

This agent accesses all rows of a result set twice starting from the first row. The first time you do not explicitly set FirstRow -- the first NextRow following an Execute implicitly sets FirstRow. The second time, you must explicitly set FirstRow and process the first row outside the loop that follows.

Uselsx "*LSXODBC"

Sub Initialize

     Dim con As New ODBCConnection

     Dim qry As New ODBCQuery

     Dim result As New ODBCResultSet

     Dim firstName As String

     Dim lastName As String

     Dim msg As String

     Set qry.Connection = con

     Set result.Query = qry

     con.ConnectTo("ATDB")

     qry.SQL = "SELECT * FROM STUDENTS ORDER BY LASTNAME"

     result.Execute

     msg = "Student names:" & Chr(10)

     Do

          result.NextRow

          firstName = result.GetValue("FIRSTNAME", firstName)

          lastName = result.GetValue("LASTNAME", lastName)

          msg = msg & Chr(10) & firstName & " " & lastName

     Loop Until result.IsEndOfData

     Messagebox msg,, "Student Names"

     msg = "Student names:" & Chr(10)

     result.FirstRow

     firstName = result.GetValue("FIRSTNAME", firstName)

     lastName = result.GetValue("LASTNAME", lastName)

     msg = msg & Chr(10) & firstName & " " & lastName

     Do

          result.NextRow

          firstName = result.GetValue("FIRSTNAME", firstName)

          lastName = result.GetValue("LASTNAME", lastName)

          msg = msg & Chr(10) & firstName & " " & lastName

     Loop Until result.IsEndOfData

     Messagebox msg,, "Student Names"

     result.Close(DB_CLOSE)

     con.Disconnect

End Sub


Examples: Folder method

  1. The following agent puts the current selected or open document in the folder named "test." This is the name of the folder you want to move the current document into.

    2. Dim ws As New NotesUIWorkspace

    Dim temp As Variant

    temp = ws.folder("test",True)
  2. The following agent brings up the move to folder dialog box when a document is selected or open.

    3. Dim ws As New NotesUIWorkspace

    Dim temp As Variant

    temp = ws.folder("",False)


Example: FolderReferences property

The following script creates a new document in the database, puts it into "view1", "view2", and "view3" folders, then prints out all folder references and a count for each document.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim doc As NotesDocument

Set db = session.CurrentDatabase

If(db.FolderReferencesEnabled) Then

   Messagebox ("Folder references enabled")

Else

   Messagebox("Folder references are not enabled")

   Messagebox("Enabling folder references")

   db.FolderReferencesEnabled = True

End If

db.FolderReferencesEnabled = True

Set doc = db.CreateDocument

If Not(doc Is Nothing) Then

   Call doc.AppendItemValue("To", "Test Document Name")

   Call doc.AppendItemValue("Subject", "Test Document Topic")

   Call doc.Save(True, True)

   Messagebox ("Adding document to views")

   doc.PutInFolder("view1")

   doc.PutInFolder("view2")

   doc.PutInFolder("view3")

   Call doc.Save(True, True)

End If

Dim doccoll As NotesDocumentCollection

Set doccoll = db.AllDocuments

Set doc = doccoll.GetFirstDocument

While Not(doc Is Nothing)

    i = 0

    Forall FolderReference In doc.FolderReferences

    i = i+1

    Print doc.noteid, "", i, "", FolderReferences

    End Forall

    Set doc = doccoll.GetNextDocument(doc)

 Wend


Example: FontColor property

This script displays the font color of data in a column as an integer.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim view As NotesView

Dim column As notesViewColumn

Set db = session.CurrentDatabase

Set view = db.Getview("Align")

Set column = view.Columns(0)

Messagebox(column.FontColor)


Example: FontFace property

This script displays the type face of data in a column as a string value.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim view As NotesView

Dim column As notesViewColumn

Set db = session.CurrentDatabase

Set view = db.Getview("Align")

Set column = view.Columns(0)

Messagebox(column.FontFace)


Example: FontPointSize property

This script displays the point size of the font in a column.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim view As NotesView

Dim column As notesViewColumn

Set db = session.CurrentDatabase

Set view = db.Getview("Align")

Set column = view.Columns(0)

Messagebox (column.FontPointSize)


Example: FontSize property

This example builds a rich-text item and sets styles so that part of the text is 12-point and part 16-point.

Sub Initialize

     Dim session As New NotesSession

     Dim db As NotesDatabase

     Set db = session.CurrentDatabase

     Dim doc As New NotesDocument(db)

     Call doc.AppendItemValue("From", session.UserName)

     Call doc.AppendItemValue("Subject",  _

                              "Meeting time changed")

     Dim richStyle As NotesRichTextStyle

     Set richStyle = session.CreateRichTextStyle

     Dim richText As New NotesRichTextItem(doc, "Body")

     richStyle.FontSize = 12

     Call richText.AppendStyle(richStyle)

     Call richText.AppendText("The meeting is at ")

     richStyle.FontSize = 16

     Call richText.AppendStyle(richStyle)

     Call richText.AppendText("3:00")

     richStyle.FontSize = 12

     Call richText.AppendStyle(richStyle)

     Call richText.AppendText(" not 2:00")

     Call doc.Save(True, False)

End Sub


Example: FontStyle property

This script dispays a constant integer for the font style of data in a column.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim view As NotesView

Dim column As notesViewColumn

Set db = session.CurrentDatabase

Set view = db.Getview("Align"

Set column = view.Columns(0)

Messagebox (column.FontStyle)


Examples: FormatDocument method

  1. This script performs a full-text search on the current database, creates a rendering of the first document in the resulting collection, and mails the rendered document to Susanna Tallan.

    2. Dim session As New NotesSession

    Dim db As NotesDatabase

    Dim collection As NotesDocumentCollection

    Dim newsletter As NotesNewsletter

    Dim doc As NotesDocument

    Set db = session.CurrentDatabase

    Set collection = db.FTSearch( "botany", 0 )

    Set newsletter = New NotesNewsletter( collection )

    Set doc = newsletter.FormatDocument( db, 1 )

    Call doc.Send( False, "Susanna Tallan" )
  2. This script performs a full-text search on the current database. For each document in the resulting collection (which contains a maximum of three documents), the script creates a rendering of the document, copies the Subject item of the original document into the rendering, and sends the rendering to Susanna Tallan.

    3. Dim session As New NotesSession

    Dim db As NotesDatabase

    Dim collection As NotesDocumentCollection

    Dim newsletter As NotesNewsletter

    Dim doc As NotesDocument

    Dim j As Integer

    Set db = session.CurrentDatabase

    Set collection = db.FTSearch( "botany", 3 )

    Set newsletter = New NotesNewsletter( collection )

    ' for every document in the newsletter's collection

    For j = 1 To collection.Count

      ' create a rendering of the original document

      Set doc = newsletter.FormatDocument( db, j )

      ' copy subject of original document into new document

      doc.Subject = collection.GetNthDocument(j).Subject(0)

      ' send the new document

      Call doc.Send( False, "Susanna Tallan" )

    Next


Examples: FormatMsgWithDoclinks method

  1. This view action script gets a collection of the documents currently selected in the view. It creates a newsletter containing links to each document in the collection, and saves it in the current database.

    2. Sub Click( Source As Button )

      Dim session As New NotesSession

      Dim db As NotesDatabase

      Dim collection As NotesDocumentCollection

      Dim newsletter As NotesNewsletter

      Dim doc As NotesDocument

      Set db = session.CurrentDatabase

      Set collection = db.UnprocessedDocuments

      Set newsletter = New NotesNewsletter( collection )

      Set doc = newsletter.FormatMsgWithDoclinks( db )

      doc.Form = "Summary"

      Call doc.Save( True, True )

    End Sub
  2. This script performs a full-text search on the current database, creates a newsletter containing links to each document in the resulting collection, and saves the newsletter to SCIENCE.NSF on the current computer. The documents containing the most instances of the word "botany" are sorted at the top of the collection, so their links appear at the top of the newsletter. Each document's full-text relevance score is listed next to its link.

    3. Dim session As New NotesSession

    Dim db As NotesDatabase

    Dim summaryDb As NotesDatabase

    Dim collection As NotesDocumentCollection

    Dim newsletter As NotesNewsletter

    Dim doc As NotesDocument

    Set db = session.CurrentDatabase

    Set summaryDb = New NotesDatabase _

    ( "", "summary\science.nsf" )

    Set collection = db.FTSearch( "botany", 0 )

    Set newsletter = New NotesNewsletter( collection )

    newsletter.DoScore = True

    Set doc = newsletter.FormatMsgWithDoclinks( summaryDb )

    doc.Subject = "Garden of Botanical documents"

    doc.Form = "Summary"

    Call doc.Save( True, True )
  3. This agent script runs on all new and modified documents. It performs a full-text search on the unprocessed documents in the current database, creates a newsletter containing links to each document in the resulting collection, and mails the newsletter to Susanna Tallan. Each document's relevance score and Topic item are listed in the newsletter next to the document's link.

    4. The script then marks each document as processed so that the UnprocessedFTSearch method does not search for these documents the next time the agent runs.

    Sub Initialize

      Dim session As New NotesSession

      Dim db As NotesDatabase

      Dim collection As NotesDocumentCollection

      Dim newsletter As NotesNewsletter

      Dim doc As NotesDocument

      Dim j As Integer

      Dim originalDoc As NotesDocument

      Set db = session.CurrentDatabase

      Set collection = db.UnprocessedFTSearch( "botany", 0 )

      Set newsletter = New NotesNewsletter( collection )

      newsletter.DoScore = True

      newsletter.DoSubject = True

      newsletter.SubjectItemName = "Topic"

      Set doc = newsletter.FormatMsgWithDoclinks( db )

      doc.Subject = "New botany documents from this week"

      doc.Form = "Memo"

      Call doc.Send( False, "Susanna Tallan" )

      ' mark all documents in newsletter's collection as

      ' processed, so that they aren't included in the

      ' newsletter next time

      For j = 1 To collection.Count

        Set originalDoc = collection.GetNthDocument( j )

        Call session.UpdateProcessedDoc( originalDoc )

      Next

    End Sub


Example: Forms property

This example displays the names of all the forms in the current database

Dim session As New NotesSession

Dim db As New NotesSession

Dim db as NotesDatabase

Set db = session.CurrentDatabase

Forall form In db.Forms

     Messagebox form.Name

End Forall


Example: Formula property

This script gets the formula for the third column in the By Author view of YAHOO.NSF.

  • If the column displays the result of the formula @Name([CN]; From), the Formula property returns "@Name([CN]; From)."

  • If the column displays the simple function Size, the Formula property returns "@DocLength."

  • If the column displays the simple function Creation Date, the Formula property returns "@Created."

    • Dim db As New NotesDatabase( "", "yahoo.nsf" )

    Dim view As NotesView

    Dim column As NotesViewColumn

    Dim f As String

    Set view = db.GetView( "By Author" )

    Set column = view.Columns( 2 )

    f = column.Formula


Examples: Formula property

This script displays the formula of an action outline.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim outline As NotesOutline

Dim oe As NotesOutlineEntry

Set db = session.CurrentDatabase

Set outline = db.GetOutline("products")

Set oe = outline.GetFirst()

Messagebox "Formula: " & oe.Formula


Examples: FormUsers property

  1. This example adds names to the form users field.

    2. Dim session As New NotesSession

    Dim db As NotesDatabase

    Dim form As NotesForm

    Dim newFormUsers(0 To 63) As String

    Dim formUser As String

    Set db = session.CurrentDatabase

    Set form = db.GetForm(Inputbox("Name of form?"))

    If Isempty(form.FormUsers) Then

         n = 0

    Else

         For j = 0 To Ubound(form.FormUsers)

              newFormUsers(j) = form.FormUsers(j)

              Messagebox "Current form user: " & _

                         newFormUsers(j)

         Next

         n = Ubound(form.FormUsers) + 1

    End If

    formUser = Inputbox("Name of form user?")

    Do While formUser <> ""

         newFormUsers(n) = formUser

         formUser = Inputbox("Name of form user?")

         n = n + 1

    Loop

    form.FormUsers = newFormUsers
  2. This example replaces the contents of the form users field.

    3. REM Replaces $FORMUSERS in total with what the user specifies here

    Dim session As New NotesSession

    Dim db As NotesDatabase

    Dim form As NotesForm

    Dim newFormUsers(0 To 63) As String

    Dim formUser As String

    Dim emptyFormUsers As Variant

    Set db = session.CurrentDatabase

    Set form = db.GetForm(Inputbox("Name of form?"))

    n = 0

    formUser = Inputbox("Name of form user?")

    Do While formUser <> ""

         newFormUsers(n) = formUser

         formUser = Inputbox("Name of formUser?")

         n = n + 1

    Loop

    form.FormUsers = newFormUsers


Example: Forward method

This script forwards the current document. If the document is new, it displays an error message.

Sub Click(Source As Button)

  Dim workspace As New NotesUIWorkspace

  Dim uidoc As NotesUIDocument

  Set uidoc = workspace.CurrentDocument

  If uidoc.IsNewDoc Then

    Messagebox _

    ( "Please save the document before forwarding it.")

  Else

    Call uidoc.Forward

  End If

End Sub


Examples: FrameText property

This example displays the name of the target frame in which the entry will appear.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim outline As NotesOutline

Dim oe As NotesOutlineEntry

Set db = session.CurrentDatabase

Set outline = db.GetOutline("products")

Set oe = outline.GetFirst()

Messagebox "Frame: " & oe.FrameText


Example: FreeTimeSearch method

This example finds the first 60-minute time slot available for three people.

Dim session As New NotesSession

Dim window As NotesDateRange

Dim startDateTime As New NotesDateTime("Today")

Dim endDateTime As New NotesDateTime("Tomorrow")

Dim names(1 To 3) As String

Dim freeTime As Variant

Set window = session.CreateDateRange()

Set window.StartDateTime = startDateTime

Set window.EndDateTime = endDateTime

names(1) = "Robert Erronpay"

names(2) = "Marybeth Enakermay"

names(3) = "Kerry Oodwardway"

freeTime = session.FreeTimeSearch _

(window, 60, names, False)

Messagebox Error$

If (freeTime(0) Is Nothing) Then

Messagebox "No Match Found"

Else

  Forall x In freeTime

  Messagebox x.Text

  End Forall

EndIf


Example: FTSearch method

This script does a full-text search of all the entries in the view entry collection and places the results in a folder called Search Results.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim view As NotesView

Dim vc As NotesViewEntryCollection

Dim entry As NotesViewEntry

Dim doc As NotesDocument

Set db = session.CurrentDatabase

Set view = db.GetView("By Category")

Set entry = view.GetEntryByKey("Books")

Set doc = entry.Document

Call vc.FTSearch("Best Sellers", 10)

Call vc.PutAllInFolder("Search Results")


Example: FTSearch method

This script collects all of the documents in the Business category of a database that contain the word "Presentations" and mails the document links to Minnie Brew.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim collection As NotesDocumentCollection

Dim newsletter As NotesNewsletter

Dim doc As NotesDocument

Set db = session.CurrentDatabase

Set collection = db.FTSearch("Business", 10)

Call collection.FTSearch("Presentations",10)

Set newsletter = New NotesNewsletter( collection )

Set doc = newsletter.FormatMsgWithDoclinks( db )

doc.Form = "Memo"

doc.Subject = "Here's the newsletter you requested."

Call doc.Send( False, "Minnie Brew/CHI/ACME" )


Examples: FTSearch method

  1. This script searches the current database for the phrase "printing press." Every document containing the phrase is placed into the collection.

    2. Dim session As New NotesSession

    Dim db As NotesDatabase

    Dim collection As NotesDocumentCollection

    Set db = session.CurrentDatabase

    Set collection = db.FTSearch( """printing press""", 0 _

    FT_SCORES, FT_STEMS)
  2. This script creates a newsletter of the top ten documents in the INVNTION.NSF database that contain the word "vaccine," and mails it to Joann Smera. If the database isn't full-text indexed, the script does nothing.

    3. Dim db As New NotesDatabase( "Berlin", "invntion.nsf" )

    Dim collection As NotesDocumentCollection

    Dim newsletter As NotesNewsletter

    Dim doc As NotesDocument

    If db.IsFTIndexed Then

      Set collection = db.FTSearch( "vaccine", 10 )

      Set newsletter = New NotesNewsletter( collection )

      Set doc = newsletter.FormatMsgWithDoclinks( db )

      doc.Form = "Memo"

      doc.Subject = "Here's the newsletter you requested."

      Call doc.Send( False, """Joann Smera""" )

    End If


Examples: FTSearch method

  1. This script performs a full-text search for the word "benchmark" in a view in WALNUT.NSF. The variable j contains the number of documents that contain "benchmark"; for example, 22.

    2. Dim db As New NotesDatabase( "Montreal", "walnut.nsf" )

    Dim view As NotesView

    Dim j As Integer

    Set view = db.GetView( "By Date\Ascending By Main Topic" )

    j = view.FTSearch( "benchmark", 0 )
  2. This script opens the same view as the example above and performs a full-text search for "benchmark*." Using a wildcard lets you search for word variants (such as "benchmarks," "benchmarked," and "benchmarking"), even though the FTSearch method does not automatically search for variants.

    3. Dim db As New NotesDatabase( "Montreal", "walnut.nsf" )

    Dim view As NotesView

    Dim doc As NotesDocument

    Dim j As Integer

    Set view = db.GetView( "By Date\Ascending By Main Topic" )

    j = view.FTSearch( "benchmark*", 0 )
  3. This script finds all documents in a view that contain both "server" and "protocol" and places them into the For Review folder. If the folder does not exist, one will be created. When done, the script clears the search.

    4. Dim session As New NotesSession

    Dim db As NotesDatabase

    Dim view As NotesView

    Dim doc As NotesDocument

    Dim j As Integer

    Set db = session.CurrentDatabase

    Set view = db.GetView( "All Documents" )

    j = view.FTSearch( "server AND protocol", 0 )

    Set doc = view.GetFirstDocument

    For i = 1 To j

        Call doc.PutInFolder( "For Review", True )

        Set doc = view.GetNextDocument(doc)

    Next

    Call view.Clear


Examples: FTSearchScore property

  1. This script performs a full-text search to filter the By Category view of the current database. It then gets the full-text search score of the first document in the view and puts it into the variable score. For example, FTSearchScore returns 80.

    2. Dim session As New NotesSession

    Dim db As NotesDatabase

    Dim view As NotesView

    Dim doc As NotesDocument

    Dim score As Integer

    Set db = session.CurrentDatabase

    Set view = db.GetView( "By Category" )

    Call view.FTSearch( "blue", 0 )

    Set doc = view.GetFirstDocument

    score = doc.FTSearchScore
  2. This script performs a full-text search on the current database and places any document whose full-text search score is greater than 90 into a folder.

    3. Dim session As New NotesSession

    Dim db As NotesDatabase

    Dim collection As NotesDocumentCollection

    Dim doc As NotesDocument

    Set db = session.CurrentDatabase

    Set collection = db.FTSearch( "blue", 0 )

    Set doc = collection.GetFirstDocument()

    While Not(doc Is Nothing)

        If ( doc.FTSearchScore > 90 ) Then

            Call doc.PutInFolder( "Blue documents" )

            Set doc = collection.GetNextDocument(doc)

        End If

    Wend


Example: FTSearchScore property

This script displays the full-text search score of Breed view entry in the By Category view.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim view As NotesView

Dim entry As NotesViewEntry

Set db = session.CurrentDatabase

Set view = db.GetView("By Category")

Set entry = view.GetEntryByKey("Breed")

Messagebox entry.FTSearchScore


Example: GetAgent method

This example displays all the agents in the current database, then runs a user-specified agent.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim theAgent As NotesAgent

Dim agentString As String

Set db = session.CurrentDatabase

Forall agent In db.Agents

     agentString = agentString & Chr(10) & agent.Name

End Forall

Messagebox agentString,, "Agents"

Set theAgent = db.GetAgent(Inputbox( _

"Which agent do you want to run?"))

If Not(theAgent Is Nothing) Then

     Call theAgent.Run

Else

     Messagebox "No existing agent selected"

End If


Example: GetAllDocumentsByKey method

This example gets all the documents in the category "Spanish leather" in the By Category view of the current database, and puts them in the Boots folder.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim view As NotesView

Dim dc As NotesDocumentCollection

Set db = session.CurrentDatabase

Set view = db.GetView( "By Category" )

Set dc = view.GetAllDocumentsByKey("Spanish leather", False)

Call dc.PutAllInFolder("Boots")


Example: AllEntries property

This script will get all the entries in the By Category view of the current database and put them in the Cat2 folder.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim view As NotesView

Dim vc As NotesViewEntryCollection

Set db = session.CurrentDatabase

Set view = db.GetView("By Category")

Set vc = view.AllEntries

Call vc.PutAllInFolder("Cat2")


Example: Retrieving multiple entries from a view

This example retrieves all of the entries under the Spanish leather category from the Stock view.

Sub Initialize

     Dim session As New NotesSession

     Dim view As NotesView

     Dim vc As NotesViewEntryCollection

     Set db = session.CurrentDatabase

     Set view = db.GetView("Stock")

     Set vc = view.GetAllEntriesByKey("Spanish leather", False)

     Call vc.PutAllInFolder("Boots")

End Sub


Example: GetAllEntriesByKey method

This script gets all the entries in the category "Spanish leather" in the By Category view of the current database, and puts them in the Boots folder.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim view As NotesView

Dim vc As NotesViewEntryCollection

Set db = session.CurrentDatabase

Set view = db.GetView("By Category")

Set vc = view.GetAllEntriesByKey("Spanish leather", False)

Call vc.PutAllInfolder("Boots")


Examples: GetAttachment method

  1. This script gets an attachment called JIM.SAM from a document.

    2. Dim doc As NotesDocument

    Dim object As NotesEmbeddedObject

    '...set value of doc...

    Set object = doc.GetAttachment( "jim.sam" )
  2. This script checks the Body item of a document to see if it contains an attachment called jill.sam. If not, the script uses GetAttachment to search the entire document for the attachment.

    3. Dim doc As NotesDocument

    Dim rtitem As Variant

    Dim object As NotesEmbeddedObject

    '...set value of doc...

    Set rtitem = doc.GetFirstItem( "Body" )

    If ( rtitem.Type = RICHTEXT ) Then

      ' check for attachment in Body item

      Set object = rtitem.GetEmbeddedObject( "jill.sam" )

      If ( object Is Nothing ) Then

        ' check for attachment in rest of document

        Set object = doc.GetAttachment( "jill.sam" )

      End If

    End If


Example: GetChild method

This script gets the first response to the first document in the view, if there is one.

Dim db As New NotesDatabase( "Troy", "gonotes.nsf" )

Dim view As NotesView

Dim doc As NotesDocument

Dim response As NotesDocument

Set view = db.GetView( "Main View" )

Set doc = view.GetFirstDocument

Set response = view.GetChild( doc )


Example: GetChild method

This script retrieves the child of the first entry in the Products category and places it in a folder.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim view As NotesView

Dim entryA As NotesViewEntry

Dim entryB As NotesViewEntry

Dim nav As NotesViewNavigator

Dim doc As NotesDocument

Set db = session.CurrentDatabase

Set view = db.GetView("By Category")

Set nav = view.CreateViewNavFromCategory("Stock")

Set entryA = nav.GetFirst

Set entryB = nav.GetChild(entryA)

Set doc = entryB.Document

Call doc.PutInFolder("My Favorites")


Examples: GetColumn method

This Visual Basic code displays the title of the first column of a view.

Private Sub ViewGetColumn_Click()

Dim s As New NotesSession

s.Initialize

Dim dir As NotesDbDirectory

Dim db As NotesDatabase

Dim v As NotesView

Dim vc As NotesViewColumn

Set dir = s.GetDbDirectory("")

Set db = dir.OpenDatabase("Web test")

Set v = db.GetView("Main View")

Set vc = v.GetColumn(1)

MsgBox vc.Title, , "Title of column 1"

End Sub


Examples: GetCurrent method

This Visual Basic code (GetCurrent_Click Sub) gets the current entry.

Dim s As New NotesSession

Dim db As NotesDatabase

Dim v As NotesView

Dim n As NotesViewNavigator

Private Sub GetCurrent_Click()

On Error GoTo errorHandler

Set e = n.GetCurrent

If e.IsCategory Then

    MsgBox e.ColumnValues(0), , "Category"

ElseIf e.IsTotal Then

    MsgBox "Is a total", , "Total"

ElseIf e.IsDocument Then

    MsgBox e.Document.GetItemValue("Subject")(0), , "Document"

End If

Exit Sub

errorHandler:

MsgBox "Nothing in view or folder", , "No entries"

End Sub

Private Sub InitializeNav_Click()

Set s = New NotesSession

s.Initialize

Set db = s.GetDatabase("", "Web test")

Set v = db.GetView("Main View")

Set n = v.CreateViewNav

End Sub


Example: GetDatabase method

This script creates a NotesDatabase object called db and uses GetDatabase to assign a database to it. The database is located at the top level of the Domino data directory on the server Barcelona. If the database exists, GetDatabase automatically opens the database, so you can access the database's properties and methods immediately.

Dim session As New NotesSession

Dim db As NotesDatabase

Set db = session.GetDatabase( "Barcelona", "plan.nsf" )

Messagebox( db.Title )


Example: GetDbDirectory method

This script opens the directory on the Somerville server, finds the first template database on the server, and opens the template.

Dim session As New NotesSession

Dim directory As NotesDbDirectory

Dim db As NotesDatabase

Set directory = session.GetDbDirectory( "Somerville" )

Set db = directory.GetFirstDatabase( TEMPLATE )

Call db.Open( "", "" )


Examples: GetDocument method

This script gets the first document in a database and displays its Universal and Notes IDs.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim collection As NotesDocumentCollection

Dim docA As NotesDocument

Dim docB As NotesDocument

Set db = session.CurrentDatabase

Set collection = db.FTSearch("Business", 10)

Set docA = collection.GetFirstDocument

Set docB = collection.GetDocument(docA)

Messagebox "Unid: " & docB.Universalid & Chr(10) _

& "NoteID: " & docB.Noteid


Examples: GetDocumentByID method

  1. This script gets the document in the current database whose NoteID is 000021CA, if such a document exists.

    2. Dim session As New NotesSession

    Dim db As NotesDatabase

    Dim doc As NotesDocument

    Set db = session.CurrentDatabase

    Set doc = db.GetDocumentByID( "000021CA" )
  2. This sub takes two string arrays and a NotesDatabase as parameters. The elements of each array contain valid NoteIDs representing documents in the NotesDatabase. The sub finds the NoteIDs that are present in both arrays, uses GetDocumentByID to find the corresponding documents in the database, and places a link to each document into a rich text field of a new document called resultDoc.

    3. Sub mergeSearch( arrayA As Variant, arrayB As Variant,  _

    db As NotesDatabase )

      Dim doc As NotesDocument

      Dim resultDoc As NotesDocument

      Dim rtitem As NotesRichTextItem

      Set resultDoc = New NotesDocument( db )

      Set rtitem = New NotesRichTextItem( resultDoc, "Body" )

      Forall noteIDa In arrayA

        Forall noteIDb In arrayB

          If ( noteIDa = noteIDb ) And ( noteIDa <> "" ) Then

            Set doc = db.GetDocumentByID( noteIDa )

            Call rtitem.AppendDoclink( doc, doc.Subject( 0 ) )

          End If

        End Forall

      End Forall

      resultDoc.Subject = "Here's the results of two searches"

      Call resultDoc.Send( False, "Anne Mackinnon" )

    End Sub
    You could use the sub above to create a "newsletter" document that contains links to documents that match two separate searches.

    For example, when the following script calls the mergeSearch sub, Anne Mackinnon receives an e-mail memo containing links to documents in the current database that contain the word "wheels," have "bicycle" in the Subject item, and were created after January 20, 1995. The script performs two searches, constructs an array of NoteIDs representing the documents of the two resulting collections, and calls mergeSearch to do the rest.

    Dim session As New NotesSession

    Dim db As NotesDatabase

    Dim dateTime As NotesDateTime

    Dim collectionA As NotesDocumentCollection

    Dim collectionB As NotesDocumentCollection

    Dim arrayA( 1 To 10 ) As String

    Dim arrayB( 1 To 10 ) As String

    Set db = session.CurrentDatabase

    Set dateTime = New NotesDateTime( "01/20/95" )

    Set collectionA = db.FTSearch( "wheels", 10 )

    Set collectionB = db.Search _

    ( "@Contains( Subject; ""bicycle"" )", dateTime, 10 )

    For i = 1 To collectionA.Count

      Set doc = collectionA.GetNthDocument( i )

      arrayA( i ) = doc.NoteID

    Next

    For j = 1 To collectionB.Count

      Set doc = collectionB.GetNthDocument( j )

      arrayB( j ) = doc.NoteID

    Next

    Call mergeSearch( arrayA, arrayB, db )


Examples: GetDocumentByKey method

  1. This script gets the first document in the first category that begins with "Spanish" in the By Category view of the current database.

    2. Dim session As New NotesSession

    Dim db As NotesDatabase

    Dim view As NotesView

    Dim doc As NotesDocument

    Set db = session.CurrentDatabase

    Set view = db.GetView( "By Category" )

    Set doc = view.GetDocumentByKey( "Spanish" )
  2. This script gets the first document in the category "Spanish leather" in the By Category view of the current database. The name of the category must be exactly "Spanish leather" except for case.

    3. Dim session As New NotesSession

    Dim db As NotesDatabase

    Dim view As NotesView

    Dim doc As NotesDocument

    Set db = session.CurrentDatabase

    Set view = db.GetView( "By Category" )

    Set doc = view.GetDocumentByKey( "Spanish leather", True )
  3. This script examines the By Category and Author view of the current database, which categorizes documents by category and, within each category, by author. The script gets the first document in the Expense Report category whose author is Robson Da Silva.

    4. Dim session As New NotesSession

    Dim db As NotesDatabase

    Dim view As NotesView

    Dim keys( 1 To 2 ) As String

    Dim doc As NotesDocument

    Set db = session.CurrentDatabase

    Set view = db.GetView( "By Category and Author" )

    keys( 1 ) = "Expense Report"

    keys( 2 ) = "Robson Da Silva"

    Set doc = view.GetDocumentByKey( keys )
  4. This field script gets a user's full name from a field on the current document, parses the full name to find the last name, and then uses GetDocumentByKey to find the user's office phone number in the People view of the Address Book on the current machine. It places the phone number into the Phone field on the current document.

    5. Sub Exiting(Source As Field)

      Dim workspace As New NotesUIWorkspace

      Dim uidoc As NotesUIDocument

      Dim fullName As String

      Dim lastName As String

      Dim db As NotesDatabase

      Dim view As NotesView

      Dim doc As NotesDocument

      ' first parse the full name to find the last name

      Set uidoc = workspace.CurrentDocument

      fullName = uidoc.FieldGetText( "Name" )

      lastName = Mid$( fullName, (Instr( fullName, " ") + 1 ))

      ' now use the last name as the key

      Set db = New NotesDatabase( "", "names.nsf" )

      Set view = db.GetView( "People" )

      Set doc = view.GetDocumentByKey( lastName )

      Call uidoc.FieldSetText _

      ( "Phone", doc.OfficePhoneNumber( 0 ) )

    End Sub
  5. (See GetAllDocumentsByKey for an easier way to do this. The only advantage to this technique is that it correctly sets the ColumnValues property in the retrieved documents while GetAllDocumentsByKey does not.) This script gets all of the documents in the category "Spanish leather" in the By Category view of the current database, and puts them in the Boots folder. The script finds the first document in the category using GetDocumentByKey, and the remaining documents in the category using GetNextDocument. The script uses the ColumnValues property in NotesDocument to check each document's column values: as long as a document's value for the first sorted column in the view equals "Spanish leather," the script places the document in the Boots folder. If the document's value for the first sorted column does not equal "Spanish leather," or if there are no more documents in the view, the script ends.

    6. Dim session As New NotesSession

    Dim db As NotesDatabase

    Dim view As NotesView

    Dim column As NotesViewColumn

    Dim doc As NotesDocument

    Set db = session.CurrentDatabase

    Set view = db.GetView( "By Category" )

    ' get the first sorted and categorized column in the view

    Forall c In view.Columns

      If ( c.IsSorted And c.IsCategory ) Then

        Set column = c

        Exit Forall

      End If

    End Forall

    ' get the first document that matches the key

    Set doc = view.GetDocumentByKey( "Spanish leather" )

    ' get the remaining documents that match the key

    ' since ColumnValues array starts at 0 for position 1,

    ' subtract 1 from the column position

    Do While Not ( doc Is Nothing )

      If ( doc.ColumnValues( column.Position - 1 ) =  _

      "Spanish leather" ) Then

        Call doc.PutInFolder( "Boots" )

      Else

        Exit Do

      End If

      Set doc = view.GetNextDocument( doc )

    Loop


Examples: GetDocumentByUNID method

  1. This script gets the parent of a response document. It gets the value of the $REF item on the response, which is a valid UNID representing the response document's parent.

    2. Dim response As NotesDocument

    Dim parent As NotesDocument

    '...set value of response...

    Set parent = db.GetDocumentByUNID _

    ( response.GetItemValue( "$REF" )( 0 ) )
  2. This script gets the parent of a response document. The ParentDocumentUNID property in NotesDocument returns a valid UNID representing the response document's parent.

    3. Dim response As NotesDocument

    Dim parent As NotesDocument

    '...set value of response...

    Set parent = db.GetDocumentByUNID _

    ( response.ParentDocumentUNID )


Example: GetDocumentByURL Method

This script creates a copy of the page at the specified URL and stores it in the Personal Web Navigator database, myURLdb.nsf.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim webDb As NotesDatabase

Dim doc As NotesDocument

Set db = session.CurrentDatabase

Set webDB = session.getDatabase("","myURLdb.nsf")

Set doc = webDB.GetDocumentByURL("http://www.notes.net/

notesua.nsf/f84c48e2e594b4338525665e0056fba4/

0f3e22f4ea8746068525666e005adde0?OpenDocument")


Examples: GetEmbeddedObject method

  1. This script finds a rich-text item called Body in a document and uses GetEmbeddedObject to check if the Body item contains an embedded object called "Jim." It displays a message stating whether or not Jim was found.

Dim doc As NotesDocument

Dim rtitem As Variant

Dim object As NotesEmbeddedObject

'...set value of doc...

Set rtitem = doc.GetFirstItem( "Body" )

If ( rtitem.Type = RICHTEXT ) Then

  Set object = rtitem.GetEmbeddedObject( "Jim" )

  If ( object Is Nothing ) Then

    Messagebox( "Unable to find an object named Jim" )

  Else

    Messagebox( "Found an object named Jim" )

  End If

End If
  1. This action script is similar to the one above, but it gets an embedded object named Eben using the Activate method in NotesEmbeddedObject to launch the application in which Eben was created. Since the script runs on a workstation, the script can bring up the application's user interface.

    2. Sub Click(Source As Button)

      Dim rtitem As Variant

      Dim object As NotesEmbeddedObject

      Dim handle As Variant

      '...set value of doc...

      Set rtitem = doc.GetFirstItem( "Body" )

      If ( rtitem.Type = RICHTEXT ) Then

        Set object = rtitem.GetEmbeddedObject( "Eben" )

        If Not ( object Is Nothing ) Then

          Set handle = object.Activate( True )

        End If

      End If

    End Sub


Examples: GetEntry method

  1. This script gets the entry for Kendra Bauer, from the ACL of JUDGE.NSF.

    2. Dim db As New NotesDatabase( "Kabul", "ubthe\judge.nsf" )

    Dim acl As NotesACL

    Dim entry As NotesACLEntry

    Set acl = db.ACL

    Set entry = acl.GetEntry( "Kendra Bauer" )
  2. This script gets the entry for the "Destroyers" group in the current database. It modifies the ACL so that Destroyers cannot delete documents in the database.

    3. Dim session As New NotesSession

    Dim db As NotesDatabase

    Dim acl As NotesACL

    Dim entry As NotesACLEntry

    Set db = session.CurrentDatabase

    Set acl = db.ACL

    Set entry = acl.GetEntry( "Destroyers" )

    If Not ( entry Is Nothing ) Then

      entry.CanDeleteDocuments = False

      Call acl.Save

    End If


Example: GetEntry method

This script retrieves the second entry in the Household Appliances category of the By Category view and puts it in the Sale Items folder.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim view As NotesView

Dim entryOne As NotesViewEntry

Dim entryTwo As NotesViewEntry

Dim vc As NotesViewEntryCollection

Dim doc As NotesDocument

Set db = session.CurrentDatabase

Set view = db.GetView("By Category")

Set vc = view.GetAllEntriesByKey("Household Appliances")

Set entryOne = vc.GetNthEntry(2)

Set entryTwo = vc.GetEntry(entryOne)

Set doc = entryTwo.Document

Call doc.PutInFolder("Sale Items"))


Example: GetEntry method

This script retrieves the specified entry in a view navigator.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim view As NotesView

Dim entryA As NotesViewEntry

Dim entryB As NotesViewEntry

Dim nav As NotesViewNavigator

Dim doc As NotesDocument

Set db = session.CurrentDatabase

Set view = db.GetView("By Category")

Set nav = view.CreateViewNavFromCategory("Stock")

Set entryA = nav.GetFirst

Set entryB = nav.GetEntry(entryA)

Set doc = entryB.Document

Call doc.PutInFolder("Inventory items")


Example: GetEntryByKey method

This script finds an entry in the By Category view with a column value that matches the specified key, Dogs, and puts it in the Puppies folder.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim view As NotesView

Dim entry As NotesViewEntry

Set db = session.CurrentDatabase

Set view = db.GetView("By Category")

Set entry = view.GetEntryByKey("Dogs")

Call entry.PutAllInFolder("Puppies")


Examples: GetEnvironmentString method

  1. This script gets the value of the ENVLoc environment variable and puts it into the variable location. For example, GetEnvironmentString returns "15 Rogers Street" if the user's NOTES.INI (or Notes Preferences) file contains the line $ENVLoc=15 Rogers Street.

    2. Dim session As New NotesSession

    Dim location As String

    location = session.GetEnvironmentString( "ENVLoc" )
  2. These two form scripts work together to get and set the environment variable ENVLoc. When a user composes a new document with the form, the value of ENVLoc gets placed into the Location field. When a user saves a document with the form, the contents of the Location field get saved to the environment variable ENVLoc. This means the user can compose several new documents without having to fill in the Location field each time.

    3. Sub Postopen(Source As Notesuidocument)

      Dim session As New NotesSession

      If source.IsNewDoc Then

        Call source.FieldSetText( "Location",  _

        session.GetEnvironmentString( "ENVLoc" ) )

      End If

    End Sub

    Sub Querysave(Source As Notesuidocument, Continue As Variant)

      Dim session As New NotesSession

      Call session.SetEnvironmentVar("ENVLoc", _

      source.FieldGetText("Location"))

    End Sub
  3. This script gets the value of the system environment variable MailServer. For example, GetEnvironmentString returns "London" if the NOTES.INI (or Notes Preferences) file contains the line MailServer = London.

    4. Dim session As New NotesSession

    Dim server As String

    server = session.GetEnvironmentString("MailServer", True)


Examples: GetEnvironmentValue method

  1. This script gets the value of a numeric environment variable called ENVNum and puts it into latestNumber. For example, GetEnvironmentValue returns 75.

    2. Dim session As New NotesSession

    Dim latestNumber As Integer

    latestNumber = session.GetEnvironmentValue( "ENVNum" )
  2. This script gets the value of the system environment variable Timezone. For example, GetEnvironmentValue returns 5 if the NOTES.INI(or Notes Preferences) file contains the line Timezone = 5.

    3. Dim session As New NotesSession

    Dim zoneNumber As Integer

    zoneNumber = session.GetEnvironmentValue("Timezone", True)


Examples: GetErrorMessage method

  1. This agent checks for an error in the ODBCConnection object after calling the ListTables method. If the name of the data source is wrong, an error occurs.

    2. Uselsx "*LSXODBC"

    Sub Initialize

         Dim con As New ODBCConnection

         Dim msg As String

         tables = con.ListTables("ATDC")

         If con.GetError <> DBstsSuccess Then

              Messagebox con.GetExtendedErrorMessage,, con.GetErrorMessage

              Exit Sub

         End If

         msg = "ATDB contains the following tables:" & Chr(10)

         For n% = Lbound(tables) To Ubound(tables)

              msg = msg & Chr(10) & tables(n%)

         Next

         Messagebox msg,, "Tables for ATDB"

         con.Disconnect

    End Sub
  2. This agent enables an error handler, which is called if any ODBC error occurs. The error handler displays the error message associated with the ODBCConnection object.

    3. Sub Initialize

         On Error Goto errorHandler

         Dim con As New ODBCConnection

         Dim msg As String

         tables = con.ListTables("ATDC")

         msg = "ATDB contains the following tables:" & Chr(10)

         For n% = Lbound(tables) To Ubound(tables)

              msg = msg & Chr(10) & tables(n%)

         Next

         Messagebox msg,, "Tables for ATDB"

         con.Disconnect

         Exit Sub

    errorHandler:

         Messagebox con.GetExtendedErrorMessage,, con.GetErrorMessage

         con.Disconnect

         Exit Sub

    End Sub
  3. This agent enables an error handler. The error handler searches for an ODBC object that returns an error status (not success) and displays its error message.

    4. Sub Initialize

         Dim con As New ODBCConnection

         Dim qry As New ODBCQuery

         Dim result As New ODBCResultSet

         On Error Goto errorHandler

         Set qry.Connection = con

         Set result.Query = qry

         con.ConnectTo("ATDB")

         REM This causes an error during result.Execute

         qry.SQL =  _

          "SELECT * FROM STUDENTS WHERE ?STUDENT_ID? = ?1234?"

         result.Execute

         result.Close(DB_CLOSE)

         con.Disconnect

         Exit Sub

    errorHandler:

         If con.GetError <> DBstsSuccess Then

              con.Disconnect

              Messagebox con.GetErrorMessage,, "Connect"

         Elseif qry.GetError <> DBstsSuccess Then

              con.Disconnect

              Messagebox qry.GetErrorMessage,, "Query"

         Elseif result.GetError <> DBstsSuccess Then

              result.Close(DB_CLOSE)

              con.Disconnect

              Messagebox result.GetErrorMessage,, "Result"

         End If

         Exit Sub

    End Sub
  4. This agent tests for DBstsODBC on a connection error. If DBstsODBC is the error, the agent tries to establish the connection again. Otherwise, the agent exits.

    5. Uselsx "*LSXODBC"

    Sub Initialize

         Dim con As New ODBCConnection

         Dim dsn As String

         Dim msg As String

         On Error Goto errorHandler

    getDsn:

         dsn = Inputbox("ODBC data source name", "DSN")

         If dsn = "" Then Exit Sub

         con.ConnectTo(dsn)

         tables = con.ListTables(dsn)

         msg = dsn & " contains the following tables: _

               & Chr(10)

         For n% = Lbound(tables) To Ubound(tables)

              msg = msg & Chr(10) & tables(n%)

         Next

         Messagebox msg,, "Tables for " & dsn

         con.Disconnect

         Exit Sub

    errorHandler:

         If con.GetError = DBstsODBC Then

              Messagebox "Enter correct DSN or nothing",, _

                         "Bad data source name"

              Resume getDsn

         Else

              Messagebox con.GetExtendedErrorMessage,, _

                         con.GetErrorMessage

              Exit Sub

         End If

    End Sub
  5. This agent contains a function that returns the name of an error number, given the number.

    6. Uselsx "*LSXODBC"

    Sub Initialize

         Dim con As New ODBCConnection

         Dim qry As New ODBCQuery

         Dim result As New ODBCResultSet

         On Error Goto errorHandler

         Set qry.Connection = con

         Set result.Query = qry

         con.ConnectTo("ATDB")

         REM This causes an error during result.Execute

         qry.SQL =  _

           ("SELECT * FROM STUDENTS WHERE ?STUDENT_ID? =

            ?1234?")

         result.Execute

         Exit Sub

    errorHandler:

         If con.GetError <> DBstsSuccess Then

              Messagebox con.GetErrorMessage,, WhatIsError(con.Error)

         Elseif qry.GetError <> DBstsSuccess Then

              Messagebox qry.GetErrorMessage,, WhatIsError(qry.Error)

         Elseif result.GetError <> DBstsSuccess Then

              Messagebox result.GetErrorMessage,, WhatIsError(result.Error)

         End If

         Exit Sub

    End Sub

    Function WhatIsError(number As Integer) As String

         Select Case number

         Case DBSTSACCS : WhatIsError = "DBSTSACCS"

         Case DBSTSAHVR : WhatIsError = "DBSTSAHVR"

         Case DBSTSBADP : WhatIsError = "DBSTSBADP"

         Case DBSTSCANF : WhatIsError = "DBSTSCANF"

         Case DBSTSCARR : WhatIsError = "DBSTSCARR"

         Case DBSTSCCON : WhatIsError = "DBSTSCCON"

         Case DBSTSCNVD : WhatIsError = "DBSTSCNVD"

         Case DBSTSCNVR : WhatIsError = "DBSTSCNVR"

         Case DBSTSCOAR : WhatIsError = "DBSTSCOAR"

         Case DBSTSCPAR : WhatIsError = "DBSTSCPAR"

         Case DBSTSCXIN : WhatIsError = "DBSTSCXIN"

         Case DBSTSENTR : WhatIsError = "DBSTSENTR"

         Case DBSTSEOFD : WhatIsError = "DBSTSEOFD"

         Case DBSTSFAIL : WhatIsError = "DBSTSFAIL"

         Case DBSTSHSTMT : WhatIsError = "DBSTSHSTMT"

         Case DBSTSILLG : WhatIsError = "DBSTSILLG"

         Case DBSTSINTR : WhatIsError = "DBSTSINTR"

         Case DBSTSINVC : WhatIsError = "DBSTSINVC"

         Case DBSTSINVR : WhatIsError = "DBSTSINVR"

         Case DBSTSMEMF : WhatIsError = "DBSTSMEMF"

         Case DBSTSNAFI : WhatIsError = "DBSTSNAFI"

         Case DBSTSNCOJ : WhatIsError = "DBSTSNCOJ"

         Case DBSTSNCOL : WhatIsError = "DBSTSNCOL"

         Case DBSTSNCON : WhatIsError = "DBSTSNCON"

         Case DBSTSNODA : WhatIsError = "DBSTSNODA"

         Case DBSTSNOEX : WhatIsError = "DBSTSNOEX"

         Case DBSTSNQOJ : WhatIsError = "DBSTSNQOJ"

         Case DBSTSNUNQ : WhatIsError = "DBSTSNUNQ"

         Case DBSTSODBC : WhatIsError = "DBSTSODBC"

         Case DBSTSPMIS : WhatIsError = "DBSTSPMIS"

         Case DBSTSRCHG : WhatIsError = "DBSTSRCHG"

         Case DBSTSRDON : WhatIsError = "DBSTSRDON"

         Case DBSTSROWD : WhatIsError = "DBSTSROWD"

         Case DBSTSRUNC : WhatIsError = "DBSTSRUNC"

         Case DBSTSSNFD : WhatIsError = "DBSTSSNFD"

         Case DBSTSUBLE : WhatIsError = "DBSTSUBLE"

         Case DBSTSUNIM : WhatIsError = "DBSTSUNIM"

         End Select

         Mid(WhatIsError, 3, 5) = "sts"

    End Function


Examples: GetFirst method

This script retrieves the first outline entry in the "products" outline and displays its label.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim outline As NotesOutline

Dim oe As NotesOutlineEntry

Set db = session.CurrentDatabase

Set outline = db.GetOutline("products")

Set oe = outline.GetFirst()

Messagebox oe.Label


Example: GetFirst method

This script returns the first entry in a view navigator.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim view As NotesView

Dim entry As NotesViewEntry

Dim nav As NotesViewNavigator

Set db = session.CurrentDatabase

Set view = db.GetView("By Category")

Set nav = view.CreateViewNav

Set entry = nav.GetFirst

Messagebox entry.UniversalID


Example: GetFirstDatabase method

This LotusScript agent gets the first database on the server Snapper.

Sub Initialize

    Dim dbdir As New NotesDbDirectory("Snapper")

    Dim db As NotesDatabase

    Set db = dbdir.GetFirstDatabase(DATABASE)

    Msgbox db.Title, , db.FileName

End Sub

This Visual Basic code using COM gets the first database on the server Snapper.

Private Sub GetFirst_Click()

Dim s As New NotesSession

s.Initialize

Dim dir As NotesDbDirectory

Dim db As NotesDatabase

Set dir = s.GetDbDirectory("Snapper")

Set db = dir.GetFirstDatabase(NOTES_DATABASE)

MsgBox db.Title, , db.FileName

End Sub


Example: GetFirstDocument method

This script gets the first document in a collection and copies it to another database.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim db2 As New NotesDatabase("","Project.nsf")

Dim collection As NotesDocumentCollection

Dim doc As NotesDocument

Set db = session.CurrentDatabase

Set collection = db.FTSearch("Business", 10)

Set doc = collection.GetFirstDocument

Call doc.Copytodatabase(db2)


Example: GetFirstDocument method

This script gets the first document entry in a view navigator.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim view As NotesView

Dim entry As NotesViewEntry

Dim nav As NotesViewNavigator

Set db = session.CurrentDatabase

Set view = db.GetView("By Category")

Set nav = view.CreateViewNav

Set entry = nav.GetFirstDocument

Messagebox entry.UniversalID


Example: GetFirstDocument method

This script gets the first document in the Open\By Project & Priority view of a database.

Dim db As New NotesDatabase( "Gaborone", "todo.nsf" )

Dim view As NotesView

Dim doc As NotesDocument

Set view = db.GetView( "Open\By Project & Priority" )

Set doc = view.GetFirstDocument

If doc.HasItem("Subject") Then

   While Not(doc Is Nothing)

   Forall subject In doc.GetItemValue("Subject")

   Messagebox subject

   End Forall

   Set doc = view.GetNextDocument(doc)

   Wend

End If


Example: GetFirstEntry method

This script gets the first entry from the ACL of a database called HELLO.NSF.

Dim db As New NotesDatabase( "Kampala", "hello.nsf" )

Dim acl As NotesACL

Dim firstEntry As NotesACLEntry

Set acl = db.ACL

Set firstEntry = acl.GetFirstEntry


Example: GetFirstEntry method

This script retrieves the first entry in the Student category in the By Category view and puts it in the Honors folder.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim view As NotesView

Dim entry As NotesViewEntry

Dim vc As NotesViewEntryCollection

Dim doc As NotesDocument

Set db = session.CurrentDatabase

Set view = db.getView("By Category")

Set vc = view.GetAllEntriesByKey("Student")

Set entry = vc.GetFirstEntry()

Set doc = entry.Document

Call doc.PutInFolder("Honors")


Examples: GetFirstItem method

  1. This script prints a message about the Subject item in a document.

    2. Dim doc As NotesDocument

    '...set value of doc...

    Dim item As NotesItem

    Set item = doc.GetFirstItem( "Subject" )

    If ( item Is Nothing ) Then

      Messagebox( "No Subject item on the document." )

    Else

      Messagebox(  _

      "The Subject item on the document has the value: " _

      + item.Text )

    End If
  2. This example demonstrates an attempt to get the value of the DateComposed item in a document. If there is no such item (possibly because DateComposed is only a field that's computed for display), it uses the Created property instead.

    3. Dim doc As NotesDocument

    Dim item As NotesItem

    Dim dateTime As New NotesDateTime( "" )

    '...set value of doc...

    Set item = doc.GetFirstItem( "DateComposed" )

    ' An item called DateComposed doesn't exist on the document

    If ( item Is Nothing ) Then

      dateTime.LSLocalTime = doc.Created

    ' an item called DateComposed exists

    ' on the document

    Else

      Set dateTime = item.DateTimeValue

    End If
  3. This script gets a rich text item from a document and adds some text to it.

    4. Dim doc As NotesDocument

    Dim rtitem As Variant

    '...set value of doc...

    Set rtitem = doc.GetFirstItem( "Body" )

    If ( rtitem.Type = RICHTEXT ) Then

      Call rtitem.AppendText( "One line of text" )

      Call rtitem.AddNewLine( 2 )

      Call rtitem.AppendText( "Another line of text" )

      Call doc.Save( False, True )

    End If


Example: GetForm method

This script checks for the existence of a form by trying to access it with GetForm.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim form As NotesForm

On Error Goto processError

Set db = session.CurrentDatabase

formNameIn = Inputbox("Name of form?")

Set form = db.GetForm(formNameIn)

Messagebox "The form """ & form.Name & """ exists"

Exit Sub

processError:

REM     If Err() = ErrObjectVariableNotSet Then

If Err() = 91 Then

     Messagebox  _

     "The form """ & formNameIn & """ does not exist"

Else

     Messagebox "Error " & Err() & ": " & Error()

End If

Exit Sub


Examples: GetFormattedText method

  1. This script gets the Body item in a document, and writes its contents to a plain text file called PLANE.TXT. Any existing text in the file is written over. The text keeps its tabs and the default line wrapping is used.

    2.

    Dim doc As NotesDocument

    Dim rtitem As Variant

    Dim plainText As String

    Dim fileNum As Integer

    '...set value of doc...

    Set rtitem = doc.GetFirstItem( "Body" )

    If ( rtitem.Type = RICHTEXT ) Then

      plainText = rtitem.GetFormattedText( False, 0 )

    End If

    ' get a file number for the file

    fileNum = Freefile

    ' open the file for writing

    Open "c:\plane.txt" For Output As fileNum

    ' write the formatted text to the file

    Print #fileNum, plainText

    ' close the file

    Close #fileNum
  2. This script gets the Body item in a document, and appends its contents to a plain text file called PLANE.TXT. Any existing text in the file remains. The appended text is stripped of tabs and wraps every 15 characters.

Dim doc As NotesDocument

Dim rtitem As Variant

Dim plainText As String

Dim fileNum As Integer

'...set value of doc...

Set rtitem = doc.GetFirstItem( "Body" )

If ( rtitem.Type = RICHTEXT ) Then

  plainText = rtitem.GetFormattedText( True, 15 )

End If

' get a file number for the file

fileNum = Freefile

' open the file for appending

Open "c:\plane.txt" For Append As fileNum

' write the formatted text to the file

Print #fileNum, plainText

' close the file

Close #fileNum


Example: GetIDFromServer method

The following script shows you how to get an ID file from the server.

Dim reg As New NotesRegistration

Dim session As New NotesSession

Dim db As NotesDatabase

Setdb = session.CurrentDatabase

reg.RegistrationServer = db.Server

username$ = "Server2/Test/RedSox"

filepath$ = "c:\notes\data\newfile.id"

isserverid = True

Call reg.GetIDFromServer( username$, filepath$, isserverid))


Examples: GetItemValue method

In the following examples, doc is a NotesDocument whose value has been set.

  1. This script prints the contents of the Subject item in a document in a dialog box. In this case, GetItemValue returns an array of one element, so the code uses subj( 0 ) to access the first element.

    2. Dim subj As Variant

    subj = doc.GetItemValue( "Subject" )

    Messagebox( subj( 0 ) )
  2. This script achieves the same result using the extended class syntax.

    3. Dim subj As Variant

    subj = doc.Subject

    Messagebox( subj( 0 ) )
  3. This script sums every value in the quarterlyRevenue item on doc and places the result into the totalRevenue item. The quarterlyRevenue item is a number list, and the totalRevenue item is a number. For example, if quarterlyRevenue contains 50; 60; 70; 80, then totalRevenue gets assigned a value of 260.

    4. Dim total As Integer

    Dim money As Variant

    total = 0

    money = doc.GetItemValue( "quarterlyRevenue" )

    Forall m In money

      total = total + m

    End Forall

    Call doc.ReplaceItemValue( "totalRevenue", total )

    Call doc.Save( False, True )
  4. This script achieves the same result using the extended class syntax.

    5. Dim total As Integer

    Dim money As Variant

    total = 0

    money = doc.quarterlyRevenue

    Forall m In money

      total = total + m

    End Forall

    doc.totalRevenue = total

    Call doc.Save( False, True )
  5. This script gets the contents of the rich text item Body, which is returned as a single string, and places it into the Body field of a new mail memo.

    6. Dim memo As NotesDocument

    Set memo = New NotesDocument( db )

    Dim bodytext As String

    bodytext = doc.GetItemValue( "Body" )

    Call memo.ReplaceItemValue( "Body", bodytext )

    Call memo.ReplaceItemValue( "Subject", _

    "Here's some plain text" )

    Call memo.ReplaceItemValue( "Form", "Memo" )

    Call memo.Send( False, _

    "dbattersly @ purple.peopleeater.org @ internet" )

    3a. This script achieves the same result using the extended class syntax.

    Dim memo As NotesDocument

    Set memo = New NotesDocument( db )

    memo.Body = doc.Body

    memo.Subject = "Here's some plain text"

    memo.Form = "Memo"

    Call memo.Send( False, _

    "dbattersly @ purple.peopleeater.org @ internet" )


Examples: GetLast method

This script retrieves the last entry in the "products" outline and displays its label.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim outline As NotesOutline

Dim oe As NotesOutlineEntry

Set db = session.CurrentDatabase

Set outline = db.GetOutline("products")

Set oe = outline.GetLast()

Messagebox oe.Label


Example: GetLast method

This script returns the last entry in a view navigator.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim view As NotesView

Dim entry As NotesViewEntry

Dim nav As NotesViewNavigator

Set db = session.CurrentDatabase

Set view = db.GetView("By Category")

Set nav = view.CreateViewNav

Set entry = nav.GetLast

Set doc = entry.Document

Call doc.PutInFolder("My Favorites")


Example: GetLastDocument method

This script gets the last document in a collection, and copies it to another database.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim db2 As New NotesDatabase("","Ankara.nsf")

Dim collection As NotesDocumentCollection

Dim doc As NotesDocument

Set db = session.CurrentDatabase

Set collection = db.FTSearch("Business", 10)

Set doc = collection.GetLastDocument

Call doc.Copytodatabase(db2)


Example: GetLastDocument method

This script returns the universal ID of the last document entry in a view navigator.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim view As NotesView

Dim entry As NotesViewEntry

Dim nav As NotesViewNavigator

Set db = session.CurrentDatabase

Set view = db.GetView("By Category")

Set nav = view.CreateViewNav

Set entry = nav.GetLastDocument

Messagebox entry.UniversalID


Example: GetLastDocument method

This script gets the last document in the Main View of a discussion database. The first column in the Main View is sorted by date, in ascending order; therefore, the last document is the newest document in the view.

Dim db As New NotesDatabase( "France", "foodwine.nsf" )

Dim view As NotesView

Dim doc As NotesDocument

Set view = db.GetView( "Main View")

Set doc = view.GetLastDocument


Example: GetLastEntry method

This script retrieves the last entry in the Student category in the By Category view and puts it in the Honors folder.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim view As NotesView

Dim entry As NotesViewEntry

Dim vc As NotesViewEntryCollection

Dim doc As NotesDocument

Set db = session.CurrentDatabase

Set view = db.getView("By Category")

Set vc = view.GetAllEntriesByKey("Student")

Set entry = vc.GetLastEntry()

Set doc = entry.Document

Call doc.PutInFolder("Honors")


Example: GetListOfTunes method

This script displays a list of sounds available on your system.

Dim workspace As New NotesUIWorkspace

Dim tunes As Variant

tunes = workspace.GetListOfTunes()

Dim messagestring As String

Forall tunelist In tunes

     messagestring = messagestring & tunelist & Chr(10)

End Forall

Messagebox messagestring

For another example, please refer to the Alarms Dialog subform and the Calendar Profile form of the Mail template.


Examples: GetNext method

This script uses the GetNext method to retrieve the second entry in the "products" outline and displays its label.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim outline As NotesOutline

Dim oeA As NotesOutlineEntry

Dim oeB As NotesOutlineEntry

Set db = session.CurrentDatabase

Set outline = db.GetOutline("products")

Set oeA = outline.GetFirst()

Set oeB = outline.GetNext(oeA)

Messagebox oeB.Label


Example: GetNext method

This script returns the next entry after the specified entry in the view navigator.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim view As NotesView

Dim entryA As NotesViewEntry

Dim entryB As NotesViewEntry

Dim nav As NotesViewNavigator

Dim doc As NotesDocument

Set db = session.CurrentDatabase

Set view = db.GetView("By Category")

Set nav = view.CreateViewNavFromCategory("Sale items")

Set entryA = nav.GetNth(1.2)

Set entryB = nav.GetNext(entryA)

Set doc = entryB.Document

Call doc.PutInFolder("Midnight Madness")


Example: GetNextCategory method

This script returns the next category entry in a view navigator.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim view As NotesView

Dim entryA As NotesViewEntry

Dim entryB As NotesViewEntry

Dim nav As NotesViewNavigator

Dim doc As NotesDocument

Set db = session.CurrentDatabase

Set view = db.GetView("By Category")

Set nav = view.CreateViewNav

Set entryA = nav.GetFirst

Set entryB = nav.GetNextCategory(entryA)

Messagebox entryB.ChildCount


Example: GetNextDatabase method

This LotusScript agent gets all the databases on the server Snapper.

Sub Initialize

    Dim dbdir As New NotesDbDirectory("Snapper")

    Dim db As NotesDatabase

    Set db = dbdir.GetFirstDatabase(DATABASE)

    While Not(db Is Nothing)

        Msgbox db.Title, , db.FileName

        Set db = dbdir.GetNextDatabase

    Wend

End Sub

This Visual Basic code using COM gets all the databases on the server Snapper.

Private Sub GetNext_Click()

Dim s As New NotesSession

s.Initialize

Dim dir As NotesDbDirectory

Dim db As NotesDatabase

Set dir = s.GetDbDirectory("Snapper")

Set db = dir.GetFirstDatabase(NOTES_DATABASE)

While Not (db Is Nothing)

    MsgBox db.Title, , db.FileName

    Set db = dir.GetNextDatabase

Wend

End Sub


Example: GetNextDocument method

This script displays the authors of the second document in a collection.

Dim s As New NotesSession

Dim db As NotesDatabase

Dim dc As NotesDocumentCollection

Dim docA As NotesDocument

Dim docB As NotesDocument

Set db = s.CurrentDatabase

Set dc = db.FTSearch("Business",10)

Set docA = dc.GetFirstDocument

Set docB = dc.GetNextDocument(docA)

Forall a In docB.Authors

    Messagebox( a )

End Forall


Example: GetNextDocument method

This script returns the next document entry in a view navigator.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim view As NotesView

Dim entryA As NotesViewEntry

Dim entryB As NotesViewEntry

Dim nav As NotesViewNavigator

Dim doc As NotesDocument

Set db = session.CurrentDatabase

Set view = db.GetView("By Category")

Set nav = view.CreateViewNavFromCategory("Zircon")

Set entryA = nav.GetFirstDocument

Set entryB = nav.GetNextDocument(entryA)

Set doc = entryB.Document

Call doc.PutInFolder("Midnight Madness")


Examples: GetNextDocument method

  1. This script gets the second document in a view.

    2. Dim db As New NotesDatabase( "Istanbul", "contacts.nsf" )

    Dim view As NotesView

    Dim firstDoc As NotesDocument

    Dim secondDoc As NotesDocument

    Set view = db.GetView( "Main View" )

    Set firstDoc = view.GetFirstDocument

    Set secondDoc = view.GetNextDocument( firstDoc )
  2. This script shows how you can use a While loop and GetNextDocument to access every document in a view. The While loop exits when GetNextDocument returns Nothing, which means there are no more documents in the view. This construct is useful for a variety of cases; for example, this script checks to see that every document in the Open\By Due Date view is updated daily; if it isn't, the script sends mail to the document's authors.

    3. Dim db As New NotesDatabase _

    ( "Ankara", "current\projects.nsf" )

    Dim view As NotesView

    Dim doc As NotesDocument

    Set view = db.GetView( "Open\By Due Date" )

    Set doc = view.GetFirstDocument

    While Not ( doc Is Nothing )

      If doc.LastModified < Today Then

        Call doc.Send( True, doc.Authors )

      End If

      Set doc = view.GetNextDocument( doc )

    Wend


Example: GetNextEntry method

This script gets the second entry from the ACL of HELLO.NSF.

Dim db As New NotesDatabase( "Kampala", "hello.nsf" )

Dim acl As NotesACL

Dim firstEntry As NotesACLEntry

Dim secondEntry As NotesACLEntry

Set acl = db.ACL

Set firstEntry = acl.GetFirstEntry

Set secondEntry = acl.GetNextEntry( firstEntry )


Example: GetNextEntry method

This script retrieves the second entry in the Student category in the By Category view and puts it in the Honors folder.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim view As NotesView

Dim entryOne As NotesViewEntry

Dim entryTwo As NotesViewEntry

Dim vc As NotesViewEntryCollection

Dim doc As NotesDocument

Set db = session.CurrentDatabase

Set view = db.getView("By Category")

Set vc = view.GetAllEntriesByKey("Student")

Set entryOne = vc.GetFirstEntry()

Set entryTwo = vc.GetNextEntry(entryOne)

Set doc = entryTwo.Document

Call doc.PutInFolder("Honors")


Examples: GetNextSibling method

  1. This script gets the second main document in the Main View of a database, skipping over any responses to the first main document.

    • If the Main View is categorized and firstMainDoc is the only main document in its category, GetNextSibling returns Nothing, even if there are more main documents in other categories in the view.

    • If the Main View is categorized and firstMainDoc is not the only main document in its category, GetNextSibling returns the next main document in the same category as currentDoc.

    • If the Main View is not categorized, GetNextSibling returns the next main document.

      Dim db As New NotesDatabase( "Providence", "buddy.nsf" )

      Dim view As NotesView

      Dim firstMainDoc As NotesDocument

      Dim secondMainDoc As NotesDocument

      Set view = db.GetView( "Main View" )

      Set firstMainDoc = view.GetFirstDocument

      Set secondMainDoc = view.GetNextSibling( firstMainDoc )
  2. The script calculates an item value in a main document based on item values in its response documents. Here, the total item in a main document is calculated to be the sum of all the total items of its responses. The script moves from one main document to the next and from one response document to the next. The Main View is not categorized.

    3. Dim db As New NotesDatabase( "Cape-Town", "richardj.nsf" )

    Dim view As NotesView

    Dim parentDoc As NotesDocument

    Dim responseDoc As NotesDocument

    Set view = db.GetView( "Main View" )

    Set parentDoc = view.GetFirstDocument

    '   Visit each main document in the view

    While Not ( parentDoc Is Nothing )

      newTotal% = 0

      Set responseDoc = view.GetChild( parentDoc )

      '   Visit each of the parent's response documents

      While Not ( responseDoc Is Nothing )

        subtotal = responseDoc.GetItemValue( "total" )

        newTotal% = newTotal% + Cint( subtotal( 0 ) )

        Set responseDoc = view.GetNextSibling( responseDoc )

      Wend

      '   Put the new total onto the parent document

      Call parentDoc.ReplaceItemValue( "total", newTotal% )

      Call parentDoc.Save( True, False )

      Set parentDoc = view.GetNextSibling( parentDoc )

    Wend


Examples: GetNextSibling method

This script uses the GetNextSibling method to retrieve the second sibling of the first entry in the "products" outline and displays its label.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim outline As NotesOutline

Dim oeA As NotesOutlineEntry

Dim oeB As NotesOutlineEntry

Dim oeC As NotesOutlineEntry

Set db = session.CurrentDatabase

Set outline = db.GetOutline("products")

Set oeA = outline.GetFirst()

Set oeB = outline.GetNextSibling(oeA)

Set oeC = outline.GetNextSibling(oeB)

Messagebox oeC.Label


Example: GetNextSibling method

This script returns the next sibling entry in a view navigator and places in a folder.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim view As NotesView

Dim entryA As NotesViewEntry

Dim entryB As NotesViewEntry

Dim entryC As NotesViewEntry

Dim nav As NotesViewNavigator

Dim doc As NotesDocument

Set db = session.CurrentDatabase

Set view = db.GetView("By Category")

Set nav = view.CreateViewNavFromCategory("Sale items")

Set entryA = nav.GetFirst

Set entryB = nav.GetChild(entryA)

Set entryC = nav.GetNexSibling(entryB)

Set doc = entryC.Document

Call doc.PutInFolder("Midnight Madness")


Example: GetNth method

This script returns the nth entry in a view navigator.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim view As NotesView

Dim entry As NotesViewEntry

Dim nav As NotesViewNavigator

Set db = session.CurrentDatabase

Set view = db.GetView("By Category")

Set nav = view.CreateViewNav

Set entry = nav.GetNth(2)

Messagebox entry.NoteID


Examples: GetNthDocument method

  1. This script gets the third document in a collection and sends it to Jen Smith.

    2. Dim session As New NotesSession

    Dim db As NotesDatabase

    Dim collection As NotesDocumentCollection

    Dim doc As NotesDocument

    Set db = session.CurrentDatabase

    Set collection = db.FTSearch("Business",10)

    Set doc =  collection.GetNthDocument(3)

    Call doc.Send(False,"Jen Smith/BOS/ACME")


Example: GetNthDocument method

This script performs a full-text search on the Botanist's Delight folder in the current database. It then removes the second document in the collection from the folder.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim folderName As String

Dim view As NotesView

Dim count As Integer

Dim doc As NotesDocument

Set db = session.CurrentDatabase

folderName = "Botanist's Delight"

Set view = db.GetView( folderName )

Call view.FTSearch( "pollution", 0 )

Set doc = view.GetNthDocument(2)

Call doc.RemoveFromFolder( folderName )

Call view.Clear


Example: GetNthEntry method

This script retrieves the third entry in the Student category of the By Category view and puts it in the Honors folder.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim view As NotesView

Dim entry As NotesViewEntry

Dim vc As NotesViewEntryCollection

Dim doc As NotesDocument

Set db = session.CurrentDatabase

Set view = db.getView("By Category")

Set vc = view.GetAllEntriesByKey("Student")

Set entry = vc.GetNthEntry(3)

Set doc = entry.Document

Call doc.PutInFolder("Honors")


Example: GetObject method

This script gets a handle to an object on the current document called Quarterly Reports.

Dim workspace as New NotesUIWorkspace

Dim uidoc as NotesUIDocument

Dim handle as Variant

Set uidoc = workspace.CurrentDocument

Set handle = uidoc.GetObject( "Quarterly Reports" )


Example: GetParameter method

This example shows a form action (the second Click sub) that gets the parameters for the SQL query in the Postopen sub. Although the query in the Postopen sub contains exactly two parameters, the action works for a variable number of parameters.

Uselsx "*LSXODBC"

Dim con As ODBCConnection

Dim qry As ODBCQuery

Dim result As ODBCResultSet

Sub Postopen(Source As Notesuidocument)

     Set con = New ODBCConnection

     Set qry = New ODBCQuery

     Set result = New ODBCResultSet

     Set qry.Connection = con

     Set result.Query = qry

     con.ConnectTo("ATDB")

     qry.SQL = "SELECT * FROM STUDENTS WHERE " & _

     "LASTNAME = ?lastName? AND FIRSTNAME = ?firstName?"

End Sub

Sub Click(Source As Button)

     Dim inputParameter As String

     For i = 1 To result.NumParameters

          inputParameter = Inputbox$(result.GetParameterName(i), _

          "Parameter " & i)

          Call result.SetParameter _

          (i, "'" & inputParameter & "'")

     Next

End Sub

Sub Click(Source As Button)

     Dim msg As String

     msg = "Parameter name = parameter value" & Chr(10)

     For i = 1 To result.NumParameters

          msg = msg & Chr(10) & result.GetParameterName(i) _

          & " = " & result.GetParameter(i)

     Next

     Messagebox msg,, "Parameters"

End Sub

Sub Queryclose(Source As Notesuidocument, Continue As Variant)

     result.Close(DB_CLOSE)

     con.Disconnect

End Sub


Example: GetParameterName method

This example shows a form action (the Click sub) that sets the parameters for the SQL query in the Postopen sub. Although the query in the Postopen sub contains exactly two string parameters, the action works for a variable number of string parameters. The Click sub uses the GetParameterName method to prompt the user for a value for each parameter value.

Uselsx "*LSXODBC"

Dim con As ODBCConnection

Dim qry As ODBCQuery

Dim result As ODBCResultSet

Sub Postopen(Source As Notesuidocument)

     Set con = New ODBCConnection

     Set qry = New ODBCQuery

     Set result = New ODBCResultSet

     Set qry.Connection = con

     Set result.Query = qry

     con.ConnectTo("ATDB")

     qry.SQL = "SELECT * FROM STUDENTS WHERE " & _

     "LASTNAME = ?lastName? AND FIRSTNAME = ?firstName?"

End Sub

Sub Click(Source As Button)

     Dim inputParameter As String

     For i = 1 To result.NumParameters

          inputParameter = Inputbox$(result.GetParameterName(i), _

          "Parameter " & i)

          Call result.SetParameter(i, "'"  _

          & inputParameter & "'")

     Next

End Sub

Sub Queryclose(Source As Notesuidocument, Continue As Variant)

     result.Close(DB_CLOSE)

     con.Disconnect

End Sub


Examples: GetParent method

This script displays the label of the parent of the last entry in the "products" outline.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim outline As NotesOutline

Dim oeA As NotesOutlineEntry

Dim oeB As NotesOutlineEntry

Set db = session.CurrentDatabase

Set outline = db.GetOutline("products")

Set oeA = outline.GetLast()

Set oeB = outline.GetParent(oeA)

Messagebox oeB.Label


Example: GetParent method

This script returns the parent entry in a view navigator.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim view As NotesView

Dim entryA As NotesViewEntry

Dim entryB As NotesViewEntry

Dim nav As NotesViewNavigator

Set db = session.CurrentDatabase

Set view = db.GetView("By Category")

Set nav = view.CreateViewNav

Set entryA = nav.GetFirstDocument

Set entryB = nav.GetParent(entryA)

Messagebox entryB.SiblingCount


Examples: GetParentDocument method

  1. This script finds the parent of the last document in the By Category view of a discussion database and displays its universal id.

    2. Dim db As New NotesDatabase( "Byzantium", "discuss.nsf" )

    Dim view As NotesView

    Dim doc As NotesDocument

    Dim parentDoc As NotesDocument

    Set view = db.GetView( "By Category" )

    Set doc = view.GetLastDocument

    If doc.IsResponse Then

        Set parentDoc = view.GetParentDocument( doc )

        Messagebox parentDoc.Universalid

    End If
  2. This function takes a document and returns its ancestor--that is, the original main document that began a response hierarchy. This is useful for discussion databases in which response-to-response documents often nest many levels deep.

Function getAncestor ( doc As NotesDocument ) _

As NotesDocument

  Dim view As NotesView

  Set view = doc.ParentView

  If Not(Doc Is Nothing)

    While doc.IsResponse

    Set doc = view.GetParentDocument( doc )

    Wend

  End If

  Set getAncestor = doc

End Function


Example: GetPos method

This script returns the entry at the user-specified position in a view navigator.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim view As NotesView

Dim entryB As NotesViewEntry

Dim nav As NotesViewNavigator

Dim doc As NotesDocument

Set db = session.CurrentDatabase

Set view = db.GetView("By Category")

Set nav = view.CreateViewNav

Set entryB = nav.GetPos(Inputbox$("Entry position: "), ".")

Set doc = entryB.Document

Call doc.PutInFolder("My Favorites")


Example: GetPosition method

This script returns the position of the view entry Scirocco in the hierarchy of the By Category view and displays it as a message.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim view As NotesView

Dim entry As NotesViewEntry

Set db = session.CurrentDatabase

Set view = db.GetView("By Category")

Set entry = view.GetEntryByKey("Cars")

Messagebox entry.GetPosition("Scirocco")


Examples: GetPrev method

This script returns the label of the entry previous to the last entry in the "products" outline.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim outline As NotesOutline

Dim oeA As NotesOutlineEntry

Dim oeB As NotesOutlineEntry

Set db = session.CurrentDatabase

Set outline = db.GetOutline("products")

Set oeA = outline.GetLast()

Set oeB = outline.GetPrev(oeA)

Messagebox oeB.Label


Example: GetPrev method

This script displays the note ID of the previous entry in a view navigator.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim view As NotesView

Dim entryA As NotesViewEntry

Dim entryB As NotesViewEntry

Dim nav As NotesViewNavigator

Set db = session.CurrentDatabase

Set view = db.GetView("By Category")

Set entryA = nav.GetLastDocument

Set entryB = nav.GetPrev(entryA)

Messagebox entryB.NoteID


Example: GetPrevCategory method

This example displays the number of children under the first category in the view navigator.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim view As NotesView

Dim entryA As NotesViewEntry

Dim entryB As NotesViewEntry

Dim entryC As NotesViewEntry

Dim nav As NotesViewNavigator

Dim doc As NotesDocument

Set db = session.CurrentDatabase

Set view = db.GetView("By Category")

Set nav = view.CreateViewNav

Set entryA = nav.GetFirst

Set entryB = nav.GetNextCategory(entryA)

Set entryC = nav.GetPrevCategory(entryB)

Messagebox entryC.ChildCount


Example: GetPrevDocument method

This script gets the second-to-last document in a collection, and assigns it to the secondToLastDoc object.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim collection As NotesDocumentCollection

Dim lastDoc As NotesDocument

Dim secondToLastDoc As NotesDocument

Set db = session.CurrentDatabase

Set collection = db.FTSearch("Annual reports", 10)

Set lastDoc = collection.GetLastDocument

Set secondToLastDoc = collection.GetPrevDocument( lastDoc )


Example: GetPrevDocument method

This script returns the previous document entry in a view navigator and places it in a folder.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim view As NotesView

Dim entryA As NotesViewEntry

Dim entryB As NotesViewEntry

Dim nav As NotesViewNavigator

Set db = session.CurrentDatabase

Set view = db.GetView("By Category")

Set nav = view.CreateViewNav

Set entryA = nav.GetLastDocument

Set entryB = nav.GetPrevDocument(entryA)

Messagebox entryB.UniversalID


Example: GetPrevDocument method

This script gets the second-to-last document in the All by Status & Project view of a database.

Dim db As New NotesDatabase( "Constantinople", "todo.nsf" )

Dim view As NotesView

Dim lastDoc As NotesDocument

Dim secondToLastDoc As NotesDocument

Set view = db.GetView( "All by Status & Project" )

Set lastDoc = view.GetLastDocument

Set secondToLastDoc = view.GetPrevDocument( lastDoc )


Example: GetPrevEntry method

This script retrieves the second entry in the Student Category in the By Category view and places it in the Honors folder.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim view As NotesView

Dim entryOne As NotesViewEntry

Dim entryTwo As NotesViewEntry

Dim vc As Dim doc As NotesDocument

Set db = session.CurrentDatabase

Set view = db.getView("By Category")

Set vc = view.GetAllEntriesByKey("Student")

Set entryOne = vc.GetNthEntry(3)

Set entryTwo = vc.GetPrevEntry(entryOne)

Set doc = entryTwo.Document

Call doc.PutInFolder("Honors")


Examples: GetPrevSibling method

This script displays the label of the sibling preceding the last entry in the "products" outline.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim outline As NotesOutline

Dim oeA As NotesOutlineEntry

Dim oeB As NotesOutlineEntry

Set db = session.CurrentDatabase

Set outline = db.GetOutline("products")

Set oeA = outline.GetLast()

Set oeB = outline.GetPrevSibling(oeA)

Messagebox oeB.Label


Example: GetPrevSibling method

This script returns the previous sibling in a view navigator.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim view As NotesView

Dim entryA As NotesViewEntry

Dim entryB As NotesViewEntry

Dim nav As NotesViewNavigator

Dim doc As NotesDocument

Set db = session.CurrentDatabase

Set view = db.GetView("By Category")

Set nav = view.CreateViewNavFrom("Stock")

Set entryA = nav.GetLastDocument

Set entryB = nav.GetPrevSibling(entryA)

Set doc = entryB.Document

Call doc.PutInFolder("My Favorites")


Examples: GetProfileDocument method

This example gets the "Interest Profile" profile document based on the current user and displays items from it.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim doc As NotesDocument

Dim profileAuthors As NotesItem

Dim profileStrings As NotesItem

Dim stringAuthors As String

Dim stringStrings As String

Set db = session.CurrentDatabase

Set doc = db.GetProfileDocument("Interest Profile", _

session.UserName)

Set profileAuthors = doc.GetFirstItem("ProfileAuthors")

Set profileStrings = doc.GetFirstItem("ProfileStrings")

stringAuthors = ""

stringStrings = ""

Forall profileAuthor In profileAuthors.Values

     stringAuthors = stringAuthors & Chr(10) &profileAuthor

End Forall

Forall profileString In profileStrings.Values

     stringStrings = stringStrings & Chr(10) &profileString

End Forall

If stringAuthors = "" Then

     stringAuthors = "None"

Else

     stringAuthors = Right _

     (stringAuthors, Len(stringAuthors) - 1)

End If

If stringStrings = "" Then

     stringAuthors = "None"

Else

     stringStrings = Right _

     (stringStrings, Len(stringStrings) - 1)

End If

Messagebox stringAuthors,, "Profile authors"

Messagebox stringStrings,, "Profile strings"


Example: GetRowStatus method

This button example displays the status of the current row. The form that contains the button contains other scripts that declare global variables, load the result set, and process the result set. The global declarations and a portion of the Postopen script are shown.

Uselsx "*LSXODBC"

Dim con As ODBCConnection

Dim qry As ODBCQuery

Dim result As ODBCResultSet

Sub Postopen(Source As Notesuidocument)

     Set con = New ODBCConnection

     Set qry = New ODBCQuery

     Set result = New ODBCResultSet

     Set qry.Connection = con

     Set result.Query = qry

     con.ConnectTo("ATDB")

     qry.SQL = "SELECT * FROM STUDENTS ORDER BY LASTNAME"

     result.Execute

     ...

End Sub

Sub Click(Source As Button)

     Dim msg As String

     Select Case result.GetRowStatus

     Case DB_UNCHANGED : msg =  _

                        "No change - same as on database"

     Case DB_ALTERED : msg = "Changed by SetValue"

     Case DB_UPDATED : msg = "UpdateRow has occurred"

     Case DB_DELETED : msg = "Deleted by DeleteRow"

     Case DB_NEWROW : msg = "New row awaiting SetValue"

     End Select

     Messagebox msg,, "Current row status"

End Sub


Example: GetSelectedText method

This script obtains the selected text in the current UI document and copies it to the clipboard.

Sub Click(Source As Button)

     Dim workspace As New NotesUIWorkspace

     Dim uidoc As NotesUIDocument

     Dim text As String

     Set uidoc = workspace.CurrentDocument

     text = uidoc.GetSelectedText(body$)

     uidoc.copy

End Sub


Examples: Getting an item and its values

  1. This example uses the Items property of NotesDocument to get each item in each document in a database view, and displays its name and text representation.

    2. Sub Initialize

         Dim session As New NotesSession

         Dim db As NotesDatabase

         Dim view As NotesView

         Dim doc As NotesDocument

         Set db = session.CurrentDatabase

         Set view = db.GetView("By Category")

         Set doc = view.GetFirstDocument

         While Not(doc Is Nothing)

              Forall item In doc.Items

                   Messagebox item.Name & " = " & item.Text

              End Forall

              Set doc = view.GetNextDocument(doc)

         Wend

    End Sub
  2. This example uses the GetFirstItem method of NotesDocument to get the Subject item in each document in a database view, and displays its name and text value.

    3. Sub Initialize

         Dim session As New NotesSession

         Dim db As NotesDatabase

         Dim view As NotesView

         Dim doc As NotesDocument

         Dim item As NotesItem

         Set db = session.CurrentDatabase

         Set view = db.GetView("By Category")

         Set doc = view.GetFirstDocument

         If doc.HasItem("Subject") Then

              While Not(doc Is Nothing)

                   Set item = doc.GetFirstItem("Subject")

                   Messagebox item.Name & " = " & item.Text

                   Set doc = view.GetNextDocument(doc)

              Wend

         End If

    End Sub
  3. This example uses the item name as a document property to get the value of the Categories item in each document in a database.

    4. Sub Initialize

         Dim session As New NotesSession

         Dim db As NotesDatabase

         Dim view As NotesView

         Dim doc As NotesDocument

         Set db = session.CurrentDatabase

         Set view = db.GetView("By Category")

         Set doc = view.GetFirstDocument

         If doc.HasItem("Categories") Then

              While Not(doc Is Nothing)

                   Forall category In doc.Categories

                        Messagebox category

                   End Forall

                   Set doc = view.GetNextDocument(doc)

              Wend

         End If

    End Sub
  4. This example uses the GetItemValue method of NotesDocument to get the value of the Subject item in each document in a database.

    5. Sub Initialize

         Dim session As New NotesSession

         Dim db As NotesDatabase

         Dim view As NotesView

         Dim doc As NotesDocument

         Set db = session.CurrentDatabase

         Set view = db.GetView("By Category")

         Set doc = view.GetFirstDocument

         If doc.HasItem("Subject") Then

              While Not(doc Is Nothing)

                   Forall subject In _

                   doc.GetItemValue("Subject")

                        Messagebox subject

                   End Forall

                   Set doc = view.GetNextDocument(doc)

              Wend

         End If

    End Sub
  5. This example tests for the presence of a specified item in each document in a view.

    6. Sub Initialize

         Dim session As New NotesSession

         Dim db As NotesDatabase

         Dim view As NotesView

         Dim doc As NotesDocument

         Set db = session.CurrentDatabase

         Set view = db.GetView("By Category")

         itemName = Inputbox("Name of item?")

         Set doc = view.GetFirstDocument

         While Not(doc Is Nothing)

              If doc.HasItem(itemName) Then

                   Messagebox "Item present in document"

              Else

                   Messagebox "Item not present in document"

              End If

              Set doc = view.GetNextDocument(doc)

         Wend

    End Sub


Example: Getting the position of a view entry

This example will display the position of the view entry in the view hierarchy.

Sub Initialize

     Dim  NotesSession

     Dim db As NotesDatabase

     Dim view As NotesView

     Dim entry As NotesViewEntry

     Set db = session.CurrentDatabase

     Set view = db.GetView("By Category")

     Set entry = view.GetEntryByKey("Employees")

     Messagebox entry.GetPosition("1988")

End Sub


Example: GetURLHeaderInfo method

The following script tests to make sure that the dash in the header string will get converted to an underscore within the call to the GetURLHeaderInfo method.

Sub Initialize

Dim session As New NotesSession

Dim db As NotesDatabase

Dim urlinfo As string

Set db = session.CurrentDatabase

urlinfo = db.GetURLHeaderInfo("http://www.cnn.com", _

        "Content-Type")

Print "URL Info: ", urlinfo

End Sub


Example: GetUserInfo method

The following script shows you how to get the user information from the server.

Dim reg As New NotesRegistration

reg.RegistrationServer = "MoonBeam"

Call reg.GetUserInfo( "JSmith", retmailserver$, _

      retmailfile$, retmaildomain$, _

      retmailsystem%, retprofile$)


Example: GetValue method

This agent gets the value of each column in each row of a result set.

Uselsx "*LSXODBC"

Sub Initialize

     Dim con As New ODBCConnection

     Dim qry As New ODBCQuery

     Dim result As New ODBCResultSet

     Dim msg As String

     Set qry.Connection = con

     Set result.Query = qry

     con.ConnectTo("ATDB")

     qry.SQL = "SELECT * FROM STUDENTS ORDER BY LASTNAME"

     result.Execute

     msg = "Student names:" & Chr(10)

     Do

          result.NextRow

          msg = msg & Chr(10)

          For i = 1 To result.NumColumns

               msg = msg & "  " & result.GetValue(i)

          Next

     Loop Until result.IsEndOfData

     Messagebox msg,, "Student data"

     result.Close(DB_CLOSE)

     con.Disconnect

End Sub


Examples: GetView method

  1. This script gets the Main View of the current database and prints its title.

    2. Dim session As New NotesSession

    Dim db As NotesDatabase

    Dim view As NotesView

    Set db = session.CurrentDatabase

    Set view = db.GetView( "Main View" )

    Messagebox( view.Name )
  2. This script gets the By Projects\By Author view of the current database, but uses its alias to access it.

    3. Dim session As New NotesSession

    Dim db As NotesDatabase

    Dim view As NotesView

    Set db = session.CurrentDatabase

    Set view = db.GetView( "Authors" )


Examples: GMTTime property

  1. This script displays the value of the GMTTime property.

    2. Dim dateTime As New NotesDateTime( "04/16/96 05:36 PM" )

    Messagebox( dateTime.GMTTime )
    • If the script runs on a computer set to Eastern Standard Time and daylight savings time is observed, the dateTime object has a TimeZone property equal to 5, so the GMTTime property returns the string "04/16/96 09:36:00 PM GMT."

    • If the script runs on a computer set to Bering Standard Time, the dateTime object has a TimeZone property equal to 11, so the GMTTime property returns the string "04/17/96 03:36:00 AM GMT."

  2. This script creates a Branch Office Report document using a collection of documents created by users from several different time zones. The PostedDate item on each document indicates when it was posted and in what time zone; the Event item indicates what event is being reported. You want the Body of the Branch Office Report to show the PostedDate of each document in a single time zone, so you use the GMTTime property to convert each date-time to Greenwich Mean Time.

    3. Dim session As New NotesSession

    Dim db As NotesDatabase

    Dim collection As NotesDocumentCollection

    Dim doc As NotesDocument

    Dim report As NotesDocument

    Dim reportBody As NotesRichTextItem

    Dim item As NotesItem

    Dim dateTime As NotesDateTime

    Dim j As Integer

    Set db = session.CurrentDatabase

    '...set value of collection...

    Set report = New NotesDocument( db )

    Set reportBody = New NotesRichTextItem( report, "Body" )

    report.Form = "Branch Office Report"

    For j = 1 To collection.Count

      Set doc = collection.GetNthDocument( j )

      Set item = doc.GetFirstItem( "PostedDate" )

      Set dateTime = item.DateTimeValue

      Call reportBody.AppendText( dateTime.GMTTime )

      Call reportBody.AppendText( " " )

      Call reportBody.AppendText( doc.Event( 0 ) )

      Call reportBody.AddNewLine( 1 )

    Next

    Call report.Save( True, True )
    For example, if there are three documents in the collection, created in Greenwich Mean Time, Pacific Standard Time, and Central Standard Time, respectively, the body of the Report might look like this:

    08/06/95 06:12:14 PM GMT London office posts results

    08/06/95 06:17:11 PM GMT San Francisco office obtains proposal

    08/06/95 08:50:58 PM GMT Chicago office receives sketches


Example: GotoBottom method

This script moves the cursor to the last field on the document when the user creates a new document.

Sub Postopen(Source As Notesuidocument)

  If source.IsNewDoc Then

    Call source.GotoBottom

  End If

End Sub


Examples: GotoChild property

This Visual Basic code (GotoChild_Click Sub) goes to the child of the current entry. It displays a message if the child entry is the same as the last entry.

Dim s As New NotesSession

Dim db As NotesDatabase

Dim v As NotesView

Dim n As NotesViewNavigator

Dim e As NotesViewEntry

Dim lastPosition As String

Private Sub GotoChild_Click()

Call n.GotoChild(e)

Set e = n.GetCurrent

If e.GetPosition(".") = lastPosition Then

    MsgBox "No more children", , "END"

Else

    lastPosition = e.GetPosition(".")

End If

End Sub

Private Sub InitializeNav_Click()

Set s = New NotesSession

s.Initialize

Set db = s.GetDatabase("", "Web test")

Set v = db.GetView("By Category")

Set n = v.CreateViewNav

End Sub


Examples: GotoEntry method

This Visual Basic code (GotoFirstNext_Click Sub) gets all the entries in a view from first to last.

Dim s As New NotesSession

Dim db As NotesDatabase

Dim v As NotesView

Dim n As NotesViewNavigator

Dim e As NotesViewEntry

Dim lastPosition As String

Private Sub GotoEntry_Click()

On Error GoTo errorHandler

Dim dc As NotesDocumentCollection

Dim doc As NotesDocument

Set e = n.GetCurrent

Set dc = db.Search("SUBJECT = """ + Text1 + """", Nothing, 1)

If dc.Count = 0 Then

    MsgBox Text1, , "No Subject with this content"

    Exit Sub

Else

    Set doc = dc.GetFirstDocument

    Call n.GotoEntry(doc)

    Set e = n.GetCurrent

    If e.Document.GetItemValue("Subject")(0) <> Text1 Then

        MsgBox "This document not in this view", , "Not in view"

    Else

        p = e.GetPosition(".")

        MsgBox "Position of entry in view", , p

    End If

End If

Exit Sub

errorHandler:

MsgBox "This document not in this view", , "Not in view"

End Sub

Private Sub InitializeNav_Click()

Set s = New NotesSession

s.Initialize

Set db = s.GetDatabase("", "Web test")

Set v = db.GetView("By Category")

Set n = v.CreateViewNav

End Sub


Example: GotoField method

This script checks to make sure the user entered something in the Conclusion field before allowing the user to save the document. If the Conclusion field is empty, it displays a message and then uses GotoField to place the cursor in the Conclusion field.

Sub Querysave(Source As Notesuidocument, Continue As Variant)

  If ( source.FieldGetText( "Conclusion" ) = "" ) Then

    Messagebox( "Please enter a Conclusion" )

    Call source.GotoField( "Conclusion" )

    Continue = False

  End If

End Sub


Examples: GotoFirst and GotoNext methods

This Visual Basic code (GotoFirstNext_Click Sub) gets all the entries in a view from first to last.

Dim s As New NotesSession

Dim db As NotesDatabase

Dim v As NotesView

Dim n As NotesViewNavigator

Dim e As NotesViewEntry

Dim lastPosition As String

Private Sub GotoFirstNext_Click()

InitializeNav_Click

lastPosition = ""

Call n.GotoFirst

Set e = n.GetCurrent

While e.GetPosition(".") <> lastPosition

    If e.IsCategory Then

        MsgBox e.ColumnValues(0), , "Category"

    ElseIf e.IsDocument Then

        MsgBox e.Document.GetItemValue("Subject")(0), , "Document"

    End If

    lastPosition = e.GetPosition(".")

    Call n.GotoNext(e)

    Set e = n.GetCurrent

Wend

End Sub

Private Sub InitializeNav_Click()

Set s = New NotesSession

s.Initialize

Set db = s.GetDatabase("", "Web test")

Set v = db.GetView("By Category")

Set n = v.CreateViewNav

End Sub


Examples: GotoFirstDocument and GotoNextDocument methods

This Visual Basic code (GotoFirstNextDocument_Click Sub) gets all the document entries in a view from first to last.

Dim s As New NotesSession

Dim db As NotesDatabase

Dim v As NotesView

Dim n As NotesViewNavigator

Dim e As NotesViewEntry

Dim lastPosition As String

Private Sub GotoFirstNextDocument_Click()

InitializeNav_Click

lastPosition = ""

Call n.GotoFirstDocument

Set e = n.GetCurrent

While e.GetPosition(".") <> lastPosition

    MsgBox e.Document.GetItemValue("Subject")(0), , "Document"

    lastPosition = e.GetPosition(".")

    Call n.GotoNextDocument(e)

    Set e = n.GetCurrent

Wend

End Sub

Private Sub InitializeNav_Click()

Set s = New NotesSession

s.Initialize

Set db = s.GetDatabase("", "Web test")

Set v = db.GetView("By Category")

Set n = v.CreateViewNav

End Sub


Examples: GotoLast and GotoPrev methods

This Visual Basic code (GotoLastPrev_Click Sub) gets all the entries in a view from last to first.

Dim s As New NotesSession

Dim db As NotesDatabase

Dim v As NotesView

Dim n As NotesViewNavigator

Dim e As NotesViewEntry

Dim lastPosition As String

Private Sub GotoLastPrev_Click()

InitializeNav_Click

lastPosition = ""

Call n.GotoLast

Set e = n.GetCurrent

While e.GetPosition(".") <> lastPosition

    If e.IsCategory Then

        MsgBox e.ColumnValues(0), , "Category"

    ElseIf e.IsTotal Then

        MsgBox "Is a total", , "Total"

    ElseIf e.IsDocument Then

        MsgBox e.Document.GetItemValue("Subject")(0), , "Document"

    End If

    lastPosition = e.GetPosition(".")

    Call n.GotoPrev(e)

    Set e = n.GetCurrent

Wend

End Sub

Private Sub InitializeNav_Click()

Set s = New NotesSession

s.Initialize

Set db = s.GetDatabase("", "Web test")

Set v = db.GetView("By Category")

Set n = v.CreateViewNav

End Sub


Examples: GotoLastDocument and GotoPrevDocument methods

This Visual Basic code (GotoLastPrevDocument_Click Sub) gets all the document entries in a view from last to first.

Dim s As New NotesSession

Dim db As NotesDatabase

Dim v As NotesView

Dim n As NotesViewNavigator

Dim e As NotesViewEntry

Dim lastPosition As String

Private Sub GotoLastPrevDocument_Click()

InitializeNav_Click

lastPosition = ""

Call n.GotoLastDocument

Set e = n.GetCurrent

While e.GetPosition(".") <> lastPosition

    MsgBox e.Document.GetItemValue("Subject")(0), , "Document"

    lastPosition = e.GetPosition(".")

    Call n.GotoPrevDocument(e)

    Set e = n.GetCurrent

Wend

End Sub

Private Sub InitializeNav_Click()

Set s = New NotesSession

s.Initialize

Set db = s.GetDatabase("", "Web test")

Set v = db.GetView("By Category")

Set n = v.CreateViewNav

End Sub


Examples: GotoNextCategory method

This Visual Basic code (GotoNextCategory_Click Sub) gets all the category entries in a view from first to last.

Dim s As New NotesSession

Dim db As NotesDatabase

Dim v As NotesView

Dim n As NotesViewNavigator

Dim e As NotesViewEntry

Dim lastPosition As String

Private Sub GotoNextCategory_Click()

InitializeNav_Click

lastPosition = ""

Call n.GotoFirst

Set e = n.GetCurrent

If Not e.IsCategory Then Exit Sub

While e.GetPosition(".") <> lastPosition

    If e.ColumnValues(0) = "" Then

        MsgBox "Uncategorized", , "Category"

    Else

        MsgBox e.ColumnValues(0), , "Category"

    End If

    lastPosition = e.GetPosition(".")

    Call n.GotoNextCategory(e)

    Set e = n.GetCurrent

Wend

End Sub

Private Sub InitializeNav_Click()

Set s = New NotesSession

s.Initialize

Set db = s.GetDatabase("", "Web test")

Set v = db.GetView("By Category")

Set n = v.CreateViewNav

End Sub


Examples: GotoNextSibling method

This Visual Basic code (GotoNextSibling_Click Sub) gets the next sibling entry in a view navigator.

Dim s As New NotesSession

Dim db As NotesDatabase

Dim v As NotesView

Dim n As NotesViewNavigator

Dim e As NotesViewEntry

Dim lastPosition As String

Private Sub GotoNextSibling_Click()

Call n.GotoNextSibling(e)

Set e = n.GetCurrent

If e.GetPosition(".") = lastPosition Then

    MsgBox "No more siblings", , "END"

Else

    lastPosition = e.GetPosition(".")

End If

End Sub

Private Sub InitializeNav_Click()

Set s = New NotesSession

s.Initialize

Set db = s.GetDatabase("", "Web test")

Set v = db.GetView("By Category")

Set n = v.CreateViewNav

End Sub


Examples: GotoParent method

This Visual Basic code (GotoParent_Click Sub) gets the parent entry in a view navigator.

Dim s As New NotesSession

Dim db As NotesDatabase

Dim v As NotesView

Dim n As NotesViewNavigator

Dim e As NotesViewEntry

Dim lastPosition As String

Private Sub GotoParent_Click()

Call n.GotoParent(e)

Set e = n.GetCurrent

If e.GetPosition(".") = lastPosition Then

    MsgBox "No parent", , "END"

Else

    lastPosition = e.GetPosition(".")

End If

End Sub

Private Sub InitializeNav_Click()

Set s = New NotesSession

s.Initialize

Set db = s.GetDatabase("", "Web test")

Set v = db.GetView("By Category")

Set n = v.CreateViewNav

End Sub


Examples: GotoPos

This Visual Basic code (GotoPos_Click Sub) gets the entry at the position specified by a text box on the form.

Dim s As New NotesSession

Dim db As NotesDatabase

Dim v As NotesView

Dim n As NotesViewNavigator

Dim e As NotesViewEntry

Dim lastPosition As String

Private Sub GotoPos_Click()

On Error GoTo errorHandler

Call n.GotoPos(NavigatorForm.Position, ".")

Set e = n.GetCurrent

If e.GetPosition(".") <> NavigatorForm.Position Then

    MsgBox "Nothing at that position", , "Nothing"

    Exit Sub

End If

If e.IsCategory Then

    MsgBox e.ColumnValues(0), , "Category"

ElseIf e.IsDocument Then

    MsgBox e.Document.GetItemValue("Subject")(0), , "Document"

End If

Exit Sub

errorHandler:

MsgBox Err.Description, , "Error"

End Sub

Private Sub InitializeNav_Click()

Set s = New NotesSession

s.Initialize

Set db = s.GetDatabase("", "Web test")

Set v = db.GetView("By Category")

Set n = v.CreateViewNav

End Sub


Examples: GotoPrevCategory method

This Visual Basic code (GotoPrevCategory_Click Sub) gets all the category entries in a view from last to first.

Dim s As New NotesSession

Dim db As NotesDatabase

Dim v As NotesView

Dim n As NotesViewNavigator

Dim e As NotesViewEntry

Dim lastPosition As String

Private Sub GotoPrevCategory_Click()

InitializeNav_Click

Call n.GotoLast

Set e = n.GetCurrent

lastPosition = e.GetPosition(".")

Call n.GotoPrevCategory(e)

Set e = n.GetCurrent

While e.GetPosition(".") <> lastPosition

    If e.ColumnValues(0) = "" Then

        MsgBox "Uncategorized", , "Category"

    Else

        MsgBox e.ColumnValues(0), , "Category"

    End If

    lastPosition = e.GetPosition(".")

    Call n.GotoPrevCategory(e)

    Set e = n.GetCurrent

Wend

End Sub

Private Sub InitializeNav_Click()

Set s = New NotesSession

s.Initialize

Set db = s.GetDatabase("", "Web test")

Set v = db.GetView("By Category")

Set n = v.CreateViewNav

End Sub


Examples: GotoPrevSibling method

This Visual Basic code (GotoPrevSibling_Click Sub) goes to the previous sibling entry in a view navigator.

Dim s As New NotesSession

Dim db As NotesDatabase

Dim v As NotesView

Dim n As NotesViewNavigator

Dim e As NotesViewEntry

Dim lastPosition As String

Private Sub GotoPrevSibling_Click()

Call n.GotoPrevSibling(e)

Set e = n.GetCurrent

If e.GetPosition(".") = lastPosition Then

    MsgBox "No more siblings", , "END"

Else

    lastPosition = e.GetPosition(".")

End If

End Sub

Private Sub InitializeNav_Click()

Set s = New NotesSession

s.Initialize

Set db = s.GetDatabase("", "Web test")

Set v = db.GetView("By Category")

Set n = v.CreateViewNav

End Sub


Example: GotoTop method

This button script prompts the user for a location. The script then inserts the resulting string in the first editable field in the current document.

Sub Click(Source As Button)

  Dim workspace As New NotesUIWorkspace

  Dim uidoc As NotesUIDocument

  Dim location As String

  Set uidoc = workspace.CurrentDocument

  location = Inputbox$ _

  ( "Please enter your location", "Location" )

  Call uidoc.GotoTop

  Call uidoc.InsertText( location )

End Subf


Examples: GrantAccess method

  1. This script gives Author access to the PROFITS.NSF database for everyone in the group Sales Supervisors.

    2. Dim db As New NotesDatabase( "Sydney", "profits.nsf")

    Call db.GrantAccess("Sales Supervisors", ACLLEVEL_AUTHOR)
  2. This script provides Designer access to the current database for all servers in the local domain and Reader access for all servers from other domains.

    3. Dim session As New NotesSession

    Dim db As NotesDatabase

    Set db = session.CurrentDatabase

    Call db.GrantAccess( "LocalDomainServers", _

                       ACLLEVEL_DESIGNER )

    Call db.GrantAccess( "OtherDomainServers", _

                      ACLLEVEL_READER )
  3. This script prevents Will Kates from accessing the database. If the default for the database is No Access, it revokes Will's access by making him a member of the default group; otherwise (if the default is Reader, for example), it specifically provides No Access to Will.

    4. Dim db As New NotesDatabase( "Sydney","profits.nsf")

    If (db.QueryAccess("-Default-")=ACLLEVEL_NOACCESS) _

    Then

      Call db.RevokeAccess("Will Kates")

    Else

      Call db.GrantAccess("Will Kates",ACLLEVEL_NOACCESS )

    End If


Example: Handling an ODBC event

In this example, the values of a row in an ODBC table are displayed as fields on a form. The user can use actions to get the next and previous rows. The event handler AfterPositionChange displays the number of the current row in another field on the form.

Uselsx "*LSXODBC"

Dim con As ODBCConnection

Dim qry As ODBCQuery

Dim result As ODBCResultSet

Sub Postopen(Source As Notesuidocument)

     Set con = New ODBCConnection

     Set qry = New ODBCQuery

     Set result = New ODBCResultSet

     Set qry.Connection = con

     Set result.Query = qry

     On Event AfterFirstRow From result Call

     AfterPositionChange

     On Event AfterLastRow From result Call AfterPositionChange

     On Event AfterNextRow From result Call AfterPositionChange

     On Event AfterPrevRow From result Call AfterPositionChange

     con.ConnectTo("ATDB")

     qry.SQL = "SELECT * FROM STUDENTS ORDER BY LASTNAME"

     result.Execute

     If Not source.EditMode Then

          source.EditMode = True

     End If

     result.FirstRow

     Call source.FieldSetText("Student_No", _

     Cstr(result.GetValue("STUDENT_NO")))

     Call source.FieldSetText("FirstName", _

     result.GetValue("FIRSTNAME"))

     Call source.FieldSetText("LastName", _

     result.GetValue("LASTNAME"))

     Call source.FieldSetText("Address", _

     result.GetValue("ADDRESS"))

     Call source.FieldSetText("City", _

     result.GetValue("CITY"))

     Call source.FieldSetText("State", _

     result.GetValue("STATE"))

     Call source.FieldSetText("Zip", _

     result.GetValue("ZIP"))

     Call source.FieldSetText("Phone", _

     result.GetValue("PHONE"))

     Call source.FieldSetText("Cr_to_date", _

     Cstr(result.GetValue("CR_TO_DATE")))

End Sub

Sub Click(Source As Button)

REM Action to get the next row

     Dim workspace As New NotesUIWorkspace

     Dim uidoc As NotesUIDocument

     Set uidoc = workspace.CurrentDocument

     If Not result.IsEndOfData Then result.NextRow

     Call uidoc.FieldSetText("Student_No", _

     Cstr(result.GetValue("STUDENT_NO")))

     Call uidoc.FieldSetText("FirstName", _

          result.GetValue("FIRSTNAME"))

     Call uidoc.FieldSetText("LastName", _

          result.GetValue("LASTNAME"))

     Call uidoc.FieldSetText("Address", _

          result.GetValue("ADDRESS"))

     Call uidoc.FieldSetText("City", result.GetValue("CITY"))

     Call uidoc.FieldSetText("State", result.GetValue("STATE"))

     Call uidoc.FieldSetText("Zip", result.GetValue("ZIP"))

     Call uidoc.FieldSetText("Phone", result.GetValue("PHONE"))

     Call uidoc.FieldSetText("Cr_to_date", _

     Cstr(result.GetValue("CR_TO_DATE")))

End Sub

Sub Click(Source As Button)

REM Action to get the previous row

     Dim workspace As New NotesUIWorkspace

     Dim uidoc As NotesUIDocument

     Set uidoc = workspace.CurrentDocument

     If Not result.IsBeginOfData Then result.PrevRow

     Call uidoc.FieldSetText("Student_No", _

     Cstr(result.GetValue("STUDENT_NO")))

     Call uidoc.FieldSetText("FirstName", _

          result.GetValue("FIRSTNAME"))

     Call uidoc.FieldSetText("LastName", _

          result.GetValue("LASTNAME"))

     Call uidoc.FieldSetText("Address", _

          result.GetValue("ADDRESS"))

     Call uidoc.FieldSetText("City", result.GetValue("CITY"))

     Call uidoc.FieldSetText("State", result.GetValue("STATE"))

     Call uidoc.FieldSetText("Zip", result.GetValue("ZIP"))

     Call uidoc.FieldSetText("Phone", result.GetValue("PHONE"))

     Call uidoc.FieldSetText("Cr_to_date", _

     Cstr(result.GetValue("CR_TO_DATE")))

End Sub

Sub Queryclose(Source As Notesuidocument, Continue As Variant)

     result.Close(DB_CLOSE)

     con.Disconnect

End Sub

Sub AfterPositionChange(res As ODBCResultSet)

     Dim ws As New NotesUIWorkspace

     Dim source As NotesUIDocument

     Set source = ws.CurrentDocument

     Call source.FieldSetText("RowNumber", Cstr(res.CurrentRow))

End Sub


Examples: Handling run-time errors

  1. This example shows the simplest case of an error handler. The first statement establishes a handler for all errors. The handler prints the error number and message, and exits. If the user enters the name of a non-existent file, an error is raised on "Set dc = db.AllDocuments."

    2. Sub Initialize

         On Error Goto processError

         Dim dc As NotesDocumentCollection

         Dim db As New NotesDatabase("", _

         Inputbox("Database?"))

         Set dc = db.AllDocuments

         Exit Sub

    processError:

         Messagebox "Error " & Err() & ": " & Error()

         Exit Sub

    End Sub
  2. This example traps the error that occurs when you later try to use a NotesDatabase object that did not open because of a bad file name specification. In addition, the example handles other errors. If the user enters a bad name, the error handler allows the user to retry or cancel. For a retry, the error handler calls the Open method then resumes execution in the mainline code.

    3. (Declarations)

    %INCLUDE "lsconst.lss"

    %INCLUDE "lsxbeerr.lss"

    Sub Initialize

         On Error Goto processError

         On Error ERR_NOTES_DATABASE_NOTOPEN _

         Goto processNotOpen

         Dim dc As NotesDocumentCollection

         Dim db As New NotesDatabase("", Inputbox("Database?"))

         Set dc = db.AllDocuments

         Exit Sub

    processNotOpen:

         reply = Messagebox _

         ("Database name is wrong", MB_RETRYCANCEL)

         If reply = IDRETRY Then

              Call db.Open("", Inputbox("Database?"))

              Resume

         Else

              Messagebox "Error " & Err() & ": " & Error()

              Exit Sub

         End If

    processError:

         Messagebox "Error " & Err() & ": " & Error()

         Exit Sub

    End Sub
  3. This example tests the effect of the New method with the IsOpen property.

    4. (Declarations)

    %INCLUDE "lsconst.lss"

    Sub Initialize

         Dim dc As NotesDocumentCollection

         Dim db As New NotesDatabase("", _

         Inputbox("Database?"))

         Do While Not db.IsOpen

              reply = Messagebox _

              ("Database name is wrong", MB_RETRYCANCEL)

              If reply = IDRETRY Then

                   Call db.Open("", Inputbox("Database?"))

              Else

                   Messagebox "Database can't be opened"

                   Exit Sub

              End If

         Loop

         Set dc = db.AllDocuments

    End Sub
  4. This example tests the effect of the Open method by examining its return value

    5. (Declarations)

    %INCLUDE "lsconst.lss"

    Sub Initialize

         Dim dc As NotesDocumentCollection

         Dim db As New NotesDatabase("", "")

         Do While Not db.Open("", Inputbox("Database?"))

              reply = Messagebox _

              ("Database name is wrong", MB_RETRYCANCEL)

              If reply <> IDRETRY Then

                   Messagebox "Database can't be opened"

                   Exit Sub

              End If

         Loop

         Set dc = db.AllDocuments

    End Sub


Examples: HasChildren property

This script indicates whether an entry has children.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim outline As NotesOutline

Dim oe As NotesOutlineEntry

Set db = session.CurrentDatabase

Set outline = db.GetOutline("products")

Set oe = outline.GetFirst()

If oe.HasChildren = True Then

     Messagebox "This entry has children."

Else

     Messagebox "This entry has no children."

End If


Examples: HasEmbedded property

  1. This script prints a message.

    2. Dim doc As NotesDocument

    '...set value of doc...

    If doc.HasEmbedded Then

      Messagebox _

      ( "Doc contains an object, link, or attachment" )

    Else

      Messagebox _

      ( "Doc has no objects, links, or attachments" )

    End If
  2. This script goes through each document in the current database and checks to see if it contains an object, link, or file attachment. If so, it places the document in the folder called "Sally's Object Store - Open 9 to 5."

    3. Dim session As New NotesSession

    Dim db As NotesDatabase

    Dim doc As NotesDocument

    Dim collection As NotesDocumentCollection

    Set db = session.CurrentDatabase

    Set collection = db.AllDocuments

    Set doc = collection.GetFirstDocument()

    While Not(doc Is Nothing)

        If doc.HasEmbedded Then

            Call doc.PutInFolder _

            ( "Sally's Object Store - Open 9 to 5" )

        End If

        Set doc = collection.GetNextDocument(doc)

    Wend


Examples: HasItem method

  1. This script displays a message about a document.

    2. Dim doc As NotesDocument

    '...set value of doc...

    If doc.HasItem( "Subject" ) Then

      Messagebox _

      ( "There is a Subject item on this document." )

    Else

      Messagebox _

      ( "There is no Subject item on this document." )

    End If
  2. This example shows how you can use HasItem and AppendItemValue together. Suppose you have a discussion database with Main Topics and Responses. After users have created and saved several documents, you decide that the Response documents should store the original Subject from the Main Topic, as well as their own Subject.

    3. You create an OriginalSubject field on the Response form that inherits its value from the Subject field of the Main Topic. This works nicely, but you still have several Response documents with no value for Original Subject. You write this script to remedy the situation. It uses HasItem to check every Response in the main view of the current database for an item called OriginalSubject. If HasItem returns False, it uses AppendItemValue to create an item called OriginalSubject.

    Dim session As New NotesSession

    Dim db As NotesDatabase

    Dim view As NotesView

    Dim mainDoc As NotesDocument

    Dim responseDoc As NotesDocument

    Set db = session.CurrentDatabase

    Set view = db.GetView( "Main View" )

    ' get the first document in the view, which is a Main Topic

    Set mainDoc = view.GetFirstDocument

    ' visit every Main Topic in the view

    While Not ( mainDoc Is Nothing )

      ' get the first response to the Main Topic

      Set responseDoc = view.GetChild( mainDoc )

      ' visit every response to the Main Topic

      While Not ( responseDoc Is Nothing )

        If Not (responseDoc.HasItem("OriginalSubject")) Then

          ' copy the Main Topic's Subject item into the

          ' Response's OriginalSubject item

          Call responseDoc.AppendItemValue _

          ( "OriginalSubject", _

          mainDoc.GetItemValue( "Subject" ) )

          Call responseDoc.Save( True, False )

        End If

        ' get the next response to the Main Topic

        Set responseDoc = view.GetNextSibling( responseDoc )

      Wend

      ' get the next Main Topic

      Set mainDoc = view.GetNextSibling( mainDoc )

    Wend


Example: HasRowChanged method

This example contains an action (the Click sub) that updates a row. Before the update occurs, a check is made to see if another program updated the row since this program fetched it.

Uselsx "*LSXODBC"

Dim con As ODBCConnection

Dim qry As ODBCQuery

Dim result As ODBCResultSet

Sub Postopen(Source As Notesuidocument)

     Set con = New ODBCConnection

     Set qry = New ODBCQuery

     Set result = New ODBCResultSet

     Set qry.Connection = con

     Set result.Query = qry

     con.ConnectTo("ATDB")

     qry.SQL = "SELECT * FROM STUDENTS ORDER BY LASTNAME"

     result.Execute

     ...

End Sub

Sub Click(Source As Button)

     Dim workspace As New NotesUIWorkspace

     Dim uidoc As NotesUIDocument

     Set uidoc = workspace.CurrentDocument

     Call result.SetValue("STUDENT_NO", _

     Cint(uidoc.FieldGetText("Student_No")))

     Call result.SetValue("FIRSTNAME", _

     uidoc.FieldGetText("FirstName"))

     Call result.SetValue("LASTNAME", _

     uidoc.FieldGetText("LastName"))

     Call result.SetValue("ADDRESS", _

     uidoc.FieldGetText("Address"))

     Call result.SetValue("CITY", _

     uidoc.FieldGetText("City"))

     Call result.SetValue("STATE", _

     uidoc.FieldGetText("State"))

     Call result.SetValue("ZIP", _

     uidoc.FieldGetText("Zip"))

     Call result.SetValue("PHONE", _

     uidoc.FieldGetText("Phone"))

     Call result.SetValue("CR_TO_DATE", _

     uidoc.FieldGetText("Cr_to_date"))

     If result.HasRowChanged Then

          If Messagebox("Someone else changed this row " & _

          "after you fetched it. " & _

          "Do you want to proceed?", MB_YESNO, _

          "Row was changed!") <> IDYES Then

               Exit Sub

          End If

     End If

     result.UpdateRow

End Sub

Sub Queryclose(Source As Notesuidocument, Continue As Variant)

     result.Close(DB_CLOSE)

     con.Disconnect

End Sub


Example: HeaderAlignment property

This script displays the alignment (justification) of the header in a coumn.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim view As NotesView

Dim column As notesViewColumn

Set db = session.CurrentDatabase

Set view = db.Getview("Align")

Set column = view.Columns(0)

Messagebox (column.HeaderAlignment)


Example: HeaderLines property

This script will display the number of lines in the header of the By Category view in the current database.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim view As NotesView

Set db = session.CurrentDatabase

Set view = db.GetView("By Category")

Messagebox "Number of header lines: " & view.HeaderLines


Examples: HiddenChars property

  1. This action script turns hidden characters on.

    2. Sub Click(Source As Button)

      Dim workspace As New NotesUIWorkspace

      Dim uidoc As NotesUIDocument

      Set uidoc = workspace.CurrentDocument

      uidoc.HiddenChars = True

    End Sub
  2. This action script toggles hidden characters: if hidden characters are off, the script turns them on; if hidden characters are on, the script turns them off.

    3. Sub Click(Source As Button)

      Dim workspace As New NotesUIWorkspace

      Dim uidoc As NotesUIDocument

      Set uidoc = workspace.CurrentDocument

      If ( uidoc.HiddenChars = False ) Then

        uidoc.HiddenChars = True

      Else

        uidoc.HiddenChars = False

      End If

    End Sub


Example: HorzScrollBar property

This script hides the horizontal scroll bar when the user leaves a particular field.

Sub Exiting(Source As Field)

  Dim workspace As New NotesUIWorkspace

  Dim uidoc As NotesUIDocument

  Set uidoc = workspace.CurrentDocument

  uidoc.HorzScrollBar = False

End Sub


Example: IgnoreDeletes property

This script sets the IgnoreDeletes property so that deletions will not be replicated.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim rep As NotesReplication

Set db = session.CurrentDatabase

Set rep = db.ReplicationInfo

  If rep.IgnoreDeletes = False Then

    rep.IgnoreDeletes = True

  End If

Call rep.Save()


Example: IgnoreDestDeletes property

This script keeps deletions from being replicated to the destination database.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim rep As NotesReplication

Set db = session.CurrentDatabase

Set rep = db.ReplicationInfo

  If rep.IgnoreDestDeletes = False Then

    rep.IgnoreDestDeletes = True

  End If

Call rep.Save()


Examples: ImagesText property

This script displays the name of the image file used to add an icon to the entry.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim outline As NotesOutline

Dim oe As NotesOutlineEntry

Set db = session.CurrentDatabase

Set outline = db.GetOutline("products")

Set oe = outline.GetFirst()

Messagebox "Image: " & oe.ImagesText


Example: Import method

  1. This script imports a text file into the body of the current UI document. The cursor must be in the body field when you click the button.

    2. Sub Click(Source As Button)

         Dim workspace As New NotesUIWorkspace

         Dim uidoc As NotesUIDocument

         Set uidoc = workspace.CurrentDocument

         Call uidoc.Import

    End Sub
  2. This script imports a specific file using the Lotus Word Pro filter.

    3. Sub Click(Source As Button)

         Dim workspace As New NotesUIWorkspace

         Dim uidoc As NotesUIDocument

         Set uidoc = workspace.CurrentDocument

         Call uidoc.Import("Lotus Word Pro","c:\windows\desktop\QRept.lwp")

    End Sub


Example: IndentLevel property

This script displays the indent level of the Breed view entry in the By Category view.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim view As NotesView

Dim entry As NotesViewEntry

Set db = session.CurrentDatabase

Set view = db.GetView("By Category")

Set entry = view.GetEntryByKey("Breed")

Messagebox entry.IndentLevel


Examples: Initialize method

  1. This Visual Basic code initializes a Domino session based on the current user ID without supplying a password. The user is prompted as necessary.

    2. Private Sub InitializeDomino_Click()

    Dim s As New NotesSession

    Call s.Initialize

    MsgBox s.CommonUserName, , "Common user name"

    End Sub
  2. This Visual Basic code initializes a Domino session based on the current ID and supplies a password.

    3. Private Sub InitializeDomino_Click()

    Dim session As NotesSession

    Set session = CreateObject("Lotus.NotesSession")

    Call session.Initialize("secretPassword")

    TextUsername = session.UserName

    End Sub


Examples: InitializeUsingNotesUserName method

  1. This Visual Basic code initializes a Domino session based on a lookup in the current Domino Directory without supplying a password. The user is prompted as necessary.

    2. Private Sub InitializeDomino_Click()

    Dim s As New NotesSession

    Call s.InitializeUsingNotesUserName("Marie LeBlanc")

    MsgBox s.CommonUserName, , "Common user name"

    End Sub
  2. This Visual Basic code initializes a Domino session based on a lookup in the current Domino Directory and supplies a password.

    3. Private Sub InitializeDomino_Click()

    Dim session As NotesSession

    Set session = CreateObject("Lotus.NotesSession")

    Call session.InitializeUsingNotesUserName _

    ("Marie LeBlanc", "secretPassword")

    TextUsername = session.UserName

    End Sub
  3. This Visual Basic code initializes a Domino session based on Anonymous access.

    4. Private Sub InitializeDomino_Click()

    Dim s As New NotesSession

    Call s.InitializeUsingNotesUserName("")

    MsgBox s.CommonUserName, , "Common user name"

    End Sub


Example: InPreviewPane property

This script puts the document in Edit mode if it is not being accessed from the preview pane.

Sub Postopen(Source As Notesuidocument)

     If Not source.InPreviewPane Then

          source.EditMode = True

     End If

End Sub


Example: InsertText method

This script flatters the user by inserting the user's name into the current field whenever a button is clicked.

Sub Click(Source As Button)

  Dim session As New NotesSession

  Dim workspace As New NotesUIWorkspace

  Dim uidoc As NotesUIDocument

  Set uidoc = workspace.CurrentDocument

  Call uidoc.InsertText( session.CommonUserName )

End Sub


Example: InterLineSpacing property

This example creates a new rich-text paragraph style object and sets the InterLineSpacing property.

Dim session As New NotesSession

Dim db As NotesDatabase

Set db = session.Currentdatabase

Dim doc As New NotesDocument(db)

Call doc.AppendItemValue("From", session.Username)

Call doc.AppendItemValue("subject", _

"Meeting agenda")

Dim rtpStyle As NotesrichTextParagraphStyle

Set rtpStyle = session.CreateRichTextParagraphStyle

Dim richText As New NotesRichTextItem(doc,"Body")

rtpStyle.InterLineSpacing = SPACING_DOUBLE

Call richText.AppendParagraphStyle(rtpStyle)

Call richText.AppendText("Where are we now?")

Call richText.AddNewLine(1)

Call richText.AppendText (" Where do we go from here.")

Messagebox rtpStyle.InterLineSpacing

Call doc.Save(True, False)


Example: InternetLevel property

This script obtains the maximum Internet access level for the current database and displays it in a message. If the access level is Manager, the script changes it to Designer.

Dim session As New NotesSession

Dim db As NotesACL

Dim acl As NotesACL

Set db = session.CurrentDatabase

Set acl = db.ACL

Messagebox acl.InternetLevel

  If acl.InternetLevel = ACLLEVEL_MANAGER Then

    acl.InternetLevel = ACLLEVEL_DESIGNER

End If

Call acl.Save


Example: IsAccentSensitiveSort property

This script indicates if a column is sorted without regard to accent.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim view As NotesView

Dim column As notesViewColumn

Set db = session.CurrentDatabase

Set view = db.Getview("Align")

Set column = view.Columns(0)

Messagebox (column.IsAccentSensitiveSort)


Example: IsAdminServer and IsAdminReaderAuthor properties

This agent sets an ACL entry as an administration server that can modify reader and author fields.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim acl As NotesACL

Dim entry As NotesACLEntry

Set db = session.CurrentDatabase

Set acl = db.ACL

Set entry = acl.CreateACLEntry("tornado", ACLLEVEL_MANAGER)

entry.IsAdminServer = True

entry.IsAdminReaderAuthor = True

Call acl.Save


Example: CanCreateDocuments property

This script creates an entry for Eben Klemm in the current database and gives him Author access. It gives him the right to create documents in the database and denies him the right to delete documents.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim acl As NotesACL

Dim entry As NotesACLEntry

Set db = session.CurrentDatabase

Set acl = db.ACL

Set entry = New NotesACLEntry _

( acl, "Eben Klemm", ACLLEVEL_AUTHOR )

entry.CanCreateDocuments = True

entry.CanDeleteDocuments = False

Call acl.Save


Example: IsAuthors property

This script checks if the From item in a document is of type Authors. If so, it adds Jeffrey Kinnamon to the item.

Dim doc As NotesDocument

Dim item As NotesItem

' ...set value of doc...

Set item =  doc.GetFirstItem( "From" )

If ( item.IsAuthors = True ) Then

  Call item.AppendToTextList( "Jeffrey Kinnamon" )

  Call doc.Save( False, True )

End If


Example: IsBeginOfData method

This agent accesses all rows of a result set starting from the last row. You must explicitly set LastRow and process it outside the loop. In the loop, each PrevRow gets the previous row in the data set. IsBeginOfData detects that the first row was processed.

Uselsx "*LSXODBC"

Sub Initialize

     Dim con As New ODBCConnection

     Dim qry As New ODBCQuery

     Dim result As New ODBCResultSet

     Dim firstName As String

     Dim lastName As String

     Dim msg As String

     Set qry.Connection = con

     Set result.Query = qry

     con.ConnectTo("ATDB")

     qry.SQL = "SELECT * FROM STUDENTS ORDER BY LASTNAME"

     result.Execute

     msg = "Student names:" & Chr(10)

     result.LastRow

     firstName = result.GetValue("FIRSTNAME", firstName)

     lastName = result.GetValue("LASTNAME", lastName)

     msg = msg & Chr(10) & firstName & " " & lastName

     Do

          result.PrevRow

          firstName = result.GetValue("FIRSTNAME", firstName)

          lastName = result.GetValue("LASTNAME", lastName)

          msg = msg & Chr(10) & firstName & " " & lastName

     Loop Until result.IsBeginOfData

     Messagebox msg,, "Student Names"

     result.Close(DB_CLOSE)

     con.Disconnect

End Sub


Example: IsCalendar property

This example displays whether each view in the current database is a calendar view or a standard outline view.

Dim session As New NotesSession

Dim db As NotesDatabase

Set db = session.CurrentDatabase

Forall view In db.Views

  If view.IsCalendar Then

    Messagebox "Calendar view",, view.Name

  Else

    Messagebox "Standard outline view",, view.Name

  End If

End Forall


Example: IsCategorized property

This script displays whether or not the Employees view in the current database is categorized.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim view As NotesView

Set db = session.CurrentDatabase

Set view = db.GetView("Employees")

If view.IsCategorized Then

  Messagebox "The Employees view is categorized."

Else

  Messagebox "The Employees view is not categorized."

End If


Example: IsCategory property

This script checks if the first column in the By Category view of the DENMARK.NSF database is categorized.

Dim db As New NotesDatabase( "", "denmark.nsf" )

Dim view As NotesView

Dim column As NotesViewColumn

Set view = db.GetView( "By Category" )

Set column = view.Columns( 0 )

If column.IsCategory Then

  Messagebox( "First column is categorized." )

Else

  Messagebox( "First column isn't categorized." )

End If


Example: IsCategory property

This script checks to see if the Breed view entry is a category in the By Category view.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim view As NotesView

Dim entry As NotesViewEntry

Set db = session.CurrentDatabase

Set view = db.GetView("By Category")

Set entry = view.GetEntryByKey("Breed")

If entry.IsCategory Then

  Messagebox "This view entry is a category."

Else

  Messagebox "This view entry is not a category."

End If


Example: IsConflict property

This script indicates whether or not the Work Schedule calendar view in the current database is enabled for conflict checking.

Dim session As New NoteSession

Dim db As NotesDatabase

Dim view As NotesView

Set db = session.CurrentDatabase

Set view = db.GetView("Work Schedule")

If view.IsConflict Then

  Messagebox "Conflict checking is in effect."

Else

  Messagebox "Conflict checking is not in effect."

End If


Example: IsConflict property

  1. This script checks to see if the Books view entry in the Discussion view is a conflict document.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim view As NotesView

Dim entry As NotesViewEntry

Set db = session.CurrentDatabase

Set view = db.GetView("Discussion")

Set entry = view.GetEntryByKey("Books")

If entry.IsConflict Then

  Messagebox ("This view entry is a conflict document.")

Else

  Messagebox ("This view entry is not a conflict document.")

End If


Example: IsConnected method

The following button checks first to see if a connection already exists, and then connects to a user-specified data source:

Uselsx "*LSXODBC"

Dim con As ODBCConnection

Sub Postopen(Source As Notesuidocument)

      Set con = New ODBCConnection

End Sub

Sub Click(Source As Button)

     Dim dataSource As String

     If con.IsConnected Then

          Messagebox "Already connected to " &  _

                     con.DataSourceName

          Exit Sub

     End If

     dataSource = Inputbox$("Enter name of data source", _

                            "Data source?")

     If Not con.ConnectTo(dataSource) Then

          Messagebox "Could not connect to " & dataSource

     End If

End Sub

Sub Queryclose(Source As NotesUIDocument, Continue As Variant)

     con.Disconnect

End Sub


Example: IsDefaultView property

This script finds the default view in the current database and prints the view's name in the status bar. For example, if the default view's name is "Main View", the script displays "Main View" in the status bar.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim view As NotesView

Set db = session.CurrentDatabase

Forall v In db.Views

  If v.IsDefaultView Then

    Set view = v

    Exit Forall

  End If

End Forall

Print( view.Name )


Examples: IsDeleted property

The following script indicates whether a document is deleted or not.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim doc As NotesDocument

Set db = session.CurrentDatabase

Set doc = db.CreateDocument

If (doc.IsDeleted) Then

  Messagebox ("Doc is Deleted")

   Else

  Messagebox ("Doc is not Deleted")

End If


Example: IsDirectoryCatalog property

The following script determines if the current database is a Directory Catalog and if it is on Local or on a server.

Dim session As New NotesSession

Dim books As Variant

books = session.addressbooks

Forall b In books

  If b.IsPrivateAddressBook = True Then

      Call b.open("","")

      If b.IsDirectoryCatalog = True Then

           Messagebox "Directory Catalog on Local"

      Else

           Messagebox "NAB on Local"

      End If

      Else

           Call b.open("", "")

           If b.IsDirectoryCatalog = True Then

                Messagebox "Directory Catalog on Server"

        Else

                Messagebox "NAB on Server"

           End If

      End If

  End Forall

End Sub


Example: IsDocument property

This script indicates if the Cars view entry in the By Category view is a document.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim view As NotesView

Dim entry As NotesViewEntry

Set db = session.CurrentDatabase

Set view = db.GetView("By Category")

Set entry = view.GetEntryByKey("Cars")

If entry.IsDocument Then

  Messagebox "This entry is a document."

Else

  Messagebox "This entry is not a document."

End If


Example: IsDST property

This script creates a NotesDateTime object, sets it to today's date and time, and checks whether Daylight-Saving Time is currently in effect or not.

Dim dateTime As New NotesDateTime( "" )

Call dateTime.SetNow

If dateTime.IsDST Then

  Messagebox( "Enjoy the long days." )

Else

  Messagebox( "Endure the darkness." )

End If


Example: IsEnabled property

This script finds the "Sort incoming mail" agent in the current database and checks to see if it's enabled. If it is, IsEnabled returns True; otherwise it returns False.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim agent As NotesAgent

Dim enabled As Variant

Set db = session.CurrentDatabase

Forall a In db.Agents

  If ( a.Name = "Sort incoming mail" ) Then

    Set agent = a

    enabled = agent.IsEnabled

  End If

End Forall

This script finds the "Sort incoming mail" agent in the current database and enables it.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim agent As NotesAgent

Dim enabled As Variant

Set db = session.CurrentDatabase

Forall a In db.Agents

  If ( a.Name = "Sort incoming mail" ) Then

    Set agent = a

    agent.IsEnabled = True

    Call agent.Save

  End If

End Forall


Example: IsEncrypted property

This script encrypts the Body item in a document. Any other items on the document remain unencrypted.

Dim doc As NotesDocument

Dim item As NotesItem

'...set value of doc...

Set item = doc.GetFirstItem( "Body" )

item.IsEncrypted = True

Call doc.Encrypt

Call doc.Save( False, True )


Example: IsEndOfData method

This agent accesses all rows of a result set starting from the first row. Each NextRow gets the next row in the data set. IsEndOfData detects that the last row was processed.

Uselsx "*LSXODBC"

Sub Initialize

     Dim con As New ODBCConnection

     Dim qry As New ODBCQuery

     Dim result As New ODBCResultSet

     Dim firstName As String

     Dim lastName As String

     Dim msg As String

     Set qry.Connection = con

     Set result.Query = qry

     con.ConnectTo("ATDB")

     qry.SQL = "SELECT * FROM STUDENTS ORDER BY LASTNAME"

     result.Execute

     msg = "Student names:" & Chr(10)

     Do

          result.NextRow

          firstName = result.GetValue("FIRSTNAME", firstName)

          lastName = result.GetValue("LASTNAME", lastName)

          msg = msg & Chr(10) & firstName & " " & lastName

     Loop Until result.IsEndOfData

     Messagebox msg,, "Student Names"

     result.Close(DB_CLOSE)

     con.Disconnect

End Sub


Example: IsField property

This script indicates whether or not column values are based on filed values.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim view As NotesView

Dim column As notesViewColumn

Set db = session.CurrentDatabase

Set view = db.Getview("Align")

Set column = view.Columns(0)

Messagebox (column.IsField)


Example: IsFolder property

This script performs a full-text search on a database and puts the matching documents into a folder. It prompts the user for a word to search for, and for the name of a folder. The script uses IsFolder to make sure the user enters a folder name, and not a view name.

Dim query As String

Dim folderName As String

Dim session As New NotesSession

Dim db As NotesDatabase

Dim view As NotesView

Dim collection As NotesDocumentCollection

Dim doc As NotesDocument

query = Inputbox$( "What string do you want to search for?" )

folderName = Inputbox$ _

( "Which folder do you want the documents in?" )

Set db = session.CurrentDatabase

Set view = db.GetView( folderName )

If ( view Is Nothing ) Then

  Messagebox _

  ( folderName & " does not exist in this database." )

Elseif Not ( view.IsFolder ) Then

  Messagebox( folderName & _

  " is a view, not a folder. Please enter a folder." )

Else

  Set collection = db.FTSearch( query, 0 )

  Set doc = collection.GetFirstDocument

  While Not ( doc Is Nothing )

    Call doc.PutInFolder( folderName )

    Set doc = collection.GetNextDocument( doc )

  Wend

End If


Example: IsFormula property

Indicates whether or not column values are based on a formula.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim view As NotesView

Dim column As notesViewColumn

Set db = session.CurrentDatabase

Set view = db.Getview("Align")

Set column = view.Columns(0)

Messagebox (column.IsFormula)


Examples: IsFTIndexed property

  1. This script checks if the current database has a full-text index before calling the FTSearch method.

    2. Dim session As New NotesSession

    Dim db As NotesDatabase

    Dim collection As NotesDocumentCollection

    Set db = session.CurrentDatabase

    If db.IsFTIndexed Then

      Set collection = db.FTSearch( "Clay tablets", 0 )

    End If
  2. This script uses IsFTIndexed to determine which method to use to create and save a newsletter. The newsletter contains links to ten documents that have to do with "press" in the database SALES.NSF. If the database is full-text indexed, it uses FTSearch to search the database. Otherwise, it uses Search to select documents whose Body field contains "press." The newsletter is saved in the database with the form name "Search Summary."

    3. Dim db As New NotesDatabase( "", "sales.nsf" )

    Dim collection As NotesDocumentCollection

    Dim newsletter As NotesNewsletter

    Dim doc As NotesDocument

    Dim dateTime As NotesDateTime

    Dim maxDocs As Integer

    maxDocs = 10

    If db.IsFTIndexed Then

      Set collection = db.FTSearch( "press", maxDocs )

    Else

      Set dateTime = New NotesDateTime( "" )

      Set collection = db.Search _

      ( "@Contains( Body; ""press"" )", dateTime, maxDocs )

    End If

    Set newsletter = New NotesNewsletter( collection )

    Set doc = newsletter.FormatMsgWithDoclinks( db )

    doc.Form = "Search Summary"

    Call doc.Save( True, True )


Example: IsGroup property

This script checks to see if the entry is a group.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim acl As NotesACL

Dim entry As NotesACLEntry

Set db = session.CurrentDatabase

Set acl = db.ACL

Set entry = acl.GetEntry("Luscious Bao")

If entry.IsGroup Then

Messagebox entry.Name & " is a group."

Else

Messagebox entry.Name & " is not a group."

End If

Call acl.Save


Example: IsHidden property

This script checks if there are any hidden columns in the By Author view of the current database.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim view As NotesView

Dim hiddenColumn As Variant

Set db = session.CurrentDatabase

Set view = db.GetView( "By Author" )

hiddenColumn = False

Forall c In view.Columns

  If c.IsHidden Then

    hiddenColumn = True

    Exit Forall

  End If

End Forall

If hiddenColumn Then

  Messagebox _

  ( "There's at least one hidden column in view" )

Else

  Messagebox( "There are no hidden columns in view" )

End If


Examples: IsHidden, IsHiddenFromNotes, IsHiddenFromWeb, HideFormula, and UseHideFormula properties

This script displays the hide characteristics of the entries in an outline.

Sub Initialize

  Dim s As New NotesSession

  Dim db As NotesDatabase

  Dim outline As NotesOutline

  Dim entry As NotesOutlineEntry

  Set db = s.CurrentDatabase

  Set outline = db.getOutline("DiscOutline")

  Set entry = outline.GetFirst

  While Not(entry Is Nothing)

    msg = ""

    If entry.IsHidden Then

      msg = msg & Chr(10) & "Is hidden in this context"

    Else

      msg = msg & Chr(10) & "Is not hidden in this context"

    End If

    If entry.IsHiddenFromNotes Then

      msg = msg & Chr(10) & "Is hidden in the Notes client"

    Else

      msg = msg & Chr(10) & "Is not hidden in the Notes client"

    End If

    If entry.IsHiddenFromWeb Then

      msg = msg & Chr(10) & "Is hidden in the Web client"

    Else

      msg = msg & Chr(10) & "Is not hidden in the Web client"

    End If

    If entry.UseHideFormula Then

      msg = msg & Chr(10) & "Hide formula is in effect"

      If (entry.HideFormula = "") Then

        msg = msg & Chr(10) & "Hide formula is blank"

      Else

        msg = msg & Chr(10) & "Hide formula: " & entry.HideFormula

      End If

    Else

      msg = msg & Chr(10) & "Hide formula is not in effect"

    End If

    Messagebox msg,, entry.Alias

    Set entry = outline.GetNext(entry)

  Wend

End Sub


Example: IsHideDetail property

This script indicates whether or not the details for total columns are hidden.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim view As NotesView

Dim column As notesViewColumn

Set db = session.CurrentDatabase

Set view = db.Getview("Align")

Set column = view.Columns(0)

Messagebox (column.IsHideDetail)


Example: IsHierarchical property

This script indicates whether or not the By Category view in the current database shows response documents in a hierarchy.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim view As NotesView

Set db = session.CurrentDatabase

Set view = db.GetView("By Category")

If view.IsHierarchical Then

  Messagebox "This is a hierarchical view."

Else

  Messagebox "This is not a hierarchical view."

End If


Example: IsIcon property

This script indicates whether or not column values are dispayed as icons.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim view As NotesView

Dim column As notesViewColumn

Set db = session.CurrentDatabase

Set view = db.Getview("Align")

Set column = view.Columns(0)

Messagebox (column.IsIcon)


Examples: IsInThisDB property

This example indicates whether an entry is in the current database.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim outline As NotesOutline

Dim oe As NotesOutlineEntry

Set db = session.CurrentDatabase

Set outline = db.GetOutline("products")

Set oe = outline.GetFirst()

If oe.IsInThisDB = True Then

     Messagebox "This entry is in the current database."

Else

     Messagebox "This entry is not in the current database."

End If


Example: IsModified property

This view indicates whether or not a view is modified.

Dim session As New NotesDatabase

Dim db As NotesDatabase

Dim view As NotesView

Set db = session.CurrentDatabase

Set view = db.GetView(By Category)

If view.IsModified Then

  Messagebox "This view is modified."

Else

  Messagebox "This view is not modified."

End If


Example: IsMultiDbSearch property

This example displays the status of IsMultiDbSearch.

Dim session As New NotesSession

Dim db As NotesDatabase

Set db = session.CurrentDatabase

If db.IsMultiDbSearch Then

     Messagebox "Is On",, "MultiDbSearch"

Else

     Messagebox "Is Off",, "MultiDbSearch"

End If


Example: IsNames property

This script checks if a document has a SendTo field. If so, it mails the document to the recipients contained in SendTo. If not, it finds the first Names item on the document that contains at least one name, and mails the document to the user names contained in that Names item. If there is no Names item with at least one value, the document is not mailed.

Dim doc As NotesDocument

Dim item As NotesItem

Dim j As Integer

'...set value of doc...

Set item = doc.GetFirstItem( "SendTo" )

' if there's no SendTo item

' try to find another item of type Names, that has a value

If ( item Is Nothing ) Then

  Forall i In doc.Items

    If i.IsNames And ( i.Values( 0 ) <> "" ) Then

      Set item = i

      Exit Forall

    End If

  End Forall

  ' if we found an item of type Names

  ' mail the document to people in that item

  If Not ( item Is Nothing ) Then

    Call doc.Send( False, item.Values )

  End If

' if there is a SendTo item, no parameters needed

' mail the document

Else

  Call doc.Send( False )

End If


Example: IsNewDoc property

This script checks if a document has been saved or not before getting the corresponding document on disk and placing it in a folder of the user's choice.

Sub Click(Source As Button)

  Dim workspace As New NotesUIWorkspace

  Dim uidoc As NotesUIDocument

  Dim doc As NotesDocument

  Dim choice As String

  Set uidoc = workspace.CurrentDocument

  If uidoc.IsNewDoc Then

    Messagebox _

    ( "Save the document before placing it in a folder" )

  Else

    Set doc = uidoc.Document

    choice = Inputbox _

    ( "Please enter a folder name: ", "Which folder?" )

    Call doc.PutInFolder( choice )

  End If

End Sub


Example: IsNewNote property

This script prints a message.

Dim doc As NotesDocument

'...set value of doc...

If doc.IsNewNote Then

  Messagebox( "This document has not been saved. It's new." )

Else

  Messagebox( "This document has been saved. It's not new." )

End If


Example: CanDeleteDocuments property

This script creates an entry for Eben Klemm in the current database and gives him Author access. It gives him the right to create documents in the database and denies him the right to delete documents.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim acl As NotesACL

Dim entry As NotesACLEntry

Set db = session.CurrentDatabase

Set acl = db.ACL

Set entry = New NotesACLEntry _

( acl, "Eben Klemm", ACLLEVEL_AUTHOR )

entry.CanCreateDocuments = True

entry.CanDeleteDocuments = False

Call acl.Save


Example: IsNotesAgent property

This script tells you if the current agent is a Notes agent.

Dim session As New NotesSession

Dim agent As NotesAgent

Dim db As NotesDatabase

Set agent = session.CurrentAgent

  If agent.IsNotesAgent = True Then

    Messagebox "This is a Notes agent."

  Else

    Messagebox "This is not a Notes agent."

End If


Example: IsOnServer property

This function takes a person's last name, looks the name up in the People view of an Address Book, and returns the person's office phone number as a string. If the script is running on a server, the function uses the Domino Directory on that server; otherwise, it uses the Domino Directory on server Recife.

Function getOfficePhone( lname As String ) As String

  Dim session As New NotesSession

  Dim db As NotesDatabase

  Dim view As NotesView

  Dim doc As NotesDocument

  If session.IsOnServer Then

    ' use the Address Book on the same server as the script

    Set db = New NotesDatabase( "", "names.nsf" )

  Else

    ' use the Address Book on server Recife

    Set db = New NotesDatabase( "Recife", "names.nsf" )

  End If

  Set view = db.GetView( "People" )

  Set doc = view.GetDocumentByKey( lname )

  getOfficePhone = doc.OfficePhoneNumber( 0 )

End Function


Example: IsOpen property

This script attempts to open TODO.NSF on the server Bombay. If the database is found, it is opened, and IsOpen returns True. If the database is not found (for example, because it doesn't exist), IsOpen returns False.

Dim db As New NotesDatabase( "Bombay", "todo.nsf" )

If db.IsOpen Then

  Print( "Succesfully opened " & db.Title )

Else

  Print( "Unable to open database" )

End If


Example: IsPerson property

This script checks to see if the entry is a person.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim acl As NotesACL

Dim entry As NotesACLEntry

Set db = session.CurrentDatabase

Set acl = db.ACL

Set entry = acl.GetEntry("A Purchase")

If entry.IsPerson Then

Messagebox entry.Name & " is a person."

Else

Messagebox entry.Name & " is not a person."

End If

Call acl.Save


Examples: IsPrivate property

This script indicates whether an entry is private.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim outline As NotesOutline

Dim oe As NotesOutlineEntry

Set db = session.CurrentDatabase

Set outline = db.GetOutline("products")

Set oe = outline.GetFirst()

If oe.IsPrivate = True Then

     Messagebox "This entry is private."

Else

     Messagebox "This entry is public."

End If


Example: IsPrivateAddressBook property

This script shows an inappropriate use of the IsPrivateAddressBook property. Even if PERNAMES.NSF is indeed a Personal Address Book, the IsPrivateAddressBook property for the db object has no value because it was not retrieved from the AddressBooks property in NotesSession.

Dim db As New NotesDatabase( "", "pernames.nsf" )

If db.IsPrivateAddressBook Then

  Messagebox("This line of script will never get executed.")

Else

  Messagebox("This line of script will always get executed.")

End If


Example: IsProfile property

This example displays the properties of a profile document.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim doc As NotesDocument

Set db = session.CurrentDatabase

profileName = Inputbox("Profile name?")

profileUserName = Inputbox("User name (key)?")

Set doc = db.GetProfileDocument(profileName, profileUserName)

If doc.IsProfile Then

     Messagebox "Profile name: " & doc.NameOfProfile & _

     Chr(10) & _

     "User name (key): " & doc.Key,, doc.NameOfProfile

End If


Example: IsPublic property

This script counts the number of public and personal agents in the current database.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim publicCount As Integer

Dim personalCount As Integer

Set db = session.CurrentDatabase

publicCount = 0

personalCount = 0

Forall a In db.Agents

  If a.IsPublic Then

    publicCount = publicCount + 1

  Else

    personalCount = personalCount + 1

  End If

End Forall

Messagebox _

( "There are " & publicCount & " public agents" )

Messagebox _

( "You have " & personalCount & " personal agents" )


Example: IsPublicAddressBook property

This script shows an inappropriate use of the IsPublicAddressBook property. Even if NAMES.NSF is indeed a Domino Directory, the IsPublicAddressBook property for the db object has no value because it was not retrieved from the AddressBooks property in NotesSession.

Dim db As New NotesDatabase( "Detroit", "names.nsf" )

If db.IsPublicAddressBook Then

  Messagebox("This line of script will never get executed.")

Else

  Messagebox("This line of script will always get executed.")

End If


Example: IsPublicReader property

This script checks to see if the particular entry has read access to this database.

Sub Queryopen(Source As Notesuidocument, _

      Mode As Integer, Isnewdoc As Variant, _

      Continue As Variant)

Dim session As New NotesSession

Dim db As NotesDatabase

Dim acl As NotesACL

Dim entry As NotesACLEntry

Set db = session.CurrentDatabase

Set acl = db.acl

Set entry = acl.GetEntry("Marybeth Menaker/CAM/Lotus")

If entry.IsPublicReader Then

Messagebox entry.Name & " is a public reader."

Else

Messagebox entry.Name & " is not a public reader"

End If

End Sub


Example: IsPublicWriter property

This script checks to see if the particular entry has write access to this database.

Sub Queryopen(Source As Notesuidocument, _

          Mode As Integer, Isnewdoc As Variant, _

          Continue As Variant)

Dim session As New NotesSession

Dim db As NotesDatabase

Dim acl As NotesACL

Dim entry As NotesACLEntry

Set db = session.CurrentDatabase

Set acl = db.acl

Set entry = acl.GetEntry("Marybeth Menaker/CAM/Lotus")

If entry.IsPublicWriter Then

Messagebox entry.Name & " is a public writer."

Else

Messagebox entry.Name & " is not a public writer."

End If

End Sub


Example: IsReaders property

This script adds Jeffrey Kinnamon to any Readers items in a document.

Dim doc As NotesDocument

'...set value of doc...

Forall i In doc.Items

  If i.IsReaders Then

    Call i.AppendToTextList( "Jeffrey Kinnamon" )

    Call doc.Save( False, True )

  End If

End Forall


Example: IsResize property

This script indicates whether or not a column is resizeable.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim view As NotesView

Dim column As notesViewColumn

Set db = session.CurrentDatabase

Set view = db.Getview("Align")

Set column = view.Columns(0)

Messagebox (column.IsResize)


Example: IsResortDescending property

Indicates whether or not a resortable column can be resorted in descending order.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim view As NotesView

Dim column As notesViewColumn

Set db = session.CurrentDatabase

Set view = db.Getview("Align")

Set column = view.Columns(0)

Messagebox (column.IsResortDescending)


Example: IsResortToView property

This script is indicates whether or not a sorted column is resortable.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim view As NotesView

Dim column As notesViewColumn

Set db = session.CurrentDatabase

Set view = db.Getview("Align")

Set column = view.Columns(0)

Messagebox (column.ResortToView)


Examples: IsResponse property

  1. This script checks if there are one or more responses-only columns in the By Category view of the current database.

    2. Dim session As New NotesSession

    Dim db As NotesDatabase

    Dim view As NotesView

    Dim found As Variant

    Set db = session.CurrentDatabase

    Set view = db.GetView( "By Category" )

    found = False

    Forall c In view.Columns

      If c.IsResponse Then

        found = True

        Exit Forall

      End If

    End Forall

    If found Then

      Messagebox _

      ( "There's at least one responses-only column." )

    Else

      Messagebox( "There are no responses-only columns." )

    End If
  2. This script goes through a hierarchical view and creates a summary of each thread by "folding" the immediate responses of each parent document into the parent. It takes the column value of each response document, calculated by finding the position of the Responses-only column in the view, and appends it to the Body field of the parent. This creates a summary of the response in the parent. The script then deletes the response from the database.

    3. Assumptions:

    • There are no responses-to-responses in the view.

    • The view contains one responses-only column, and it displays pertinent information about the response (such as the Subject).

      Dim db As New NotesDatabase( "", "corn.nsf" )

      Dim view As NotesView

      Dim responsePos As Integer

      Dim doc As NotesDocument

      Dim rtitem As Variant

      Dim response As NotesDocument

      Dim tempResponse As NotesDocument

      Set view = db.GetView( "All" )

      ' find the position of the Responses-only column

      Forall c In view.Columns

        If c.IsResponse Then

          responsePos = c.Position

        End If

      End Forall

      Set doc = view.GetFirstDocument

      ' visit each main document in the view

      While Not( doc Is Nothing )

        Set rtitem = doc.GetFirstItem( "Body" )

        Set response = view.GetChild( doc )

        ' visit each response to the main document

        While Not( response Is Nothing )

          ' fold the response's column value into the parent

          Call rtitem.AppendText _

          ( response.ColumnValues( responsePos - 1 ) )

          Call rtitem.AddNewLine( 1 )

          ' save a temporary copy of current response...

          Set tempResponse = response

          ' ...so that the script can get the next response...

          Set response = view.GetNextSibling( response )

          '...and then delete the current response.

          Call tempResponse.Remove( True )

          Call view.Refresh

        Wend

        Call doc.Save( True, True )

        Set doc = view.GetNextSibling( doc )

      Wend
    For example, the All view might contain one main document and three responses. The subject and author of each response is displayed in a responses-only column:

    What's your favorite color? (Shelley Kinnamon)
    Blue (Joe Doyle)
    Purple (Peg Yip)
    Orange (Kendra Zowker)

    The script removes the three responses so that only the main document remains in the database:

    What's your favorite color? (Shelley Kinnamon)

    The Body of the main document now contains the following text:

    Blue (Joe Doyle)
    Purple (Peg Yip)
    Orange (Kendra Zowker)


Example: IsResponse property

This script checks if a document is a response.

Dim doc As NotesDocument

'...set value of doc...

If doc.IsResponse Then

  Messagebox( "This document is a response." )

Else

  Messagebox( "This document is not a response." )

End If


Example: IsResultSetAvailable method

This agent executes an SQL query and displays the column number, name, and size of each field in the result set.

Uselsx "*LSXODBC"

Sub Initialize

     Dim con As New ODBCConnection

     Dim qry As New ODBCQuery

     Dim result As New ODBCResultSet

     Dim lastName As String

     Set qry.Connection = con

     Set result.Query = qry

     con.ConnectTo("ATDB")

     lastName = Inputbox$("Last name?", "Query")

     qry.SQL = _

     "SELECT * FROM STUDENTS WHERE LASTNAME =  _

               """ & lastName & """"

     result.Execute

     If result.IsResultSetAvailable Then

          Messagebox lastName & " exists in STUDENTS"

     Else

          Messagebox lastName & " does not exist in STUDENTS"

     End If

     result.Close(DB_CLOSE)

     con.Disconnect

End Sub


Example: IsRoleEnabled method

This script creates a new document in the workspace. If the current user is a member of the Supervisor role in the database, the approval form is used to create the document; otherwise, the request form is used.

Dim workspace As New NotesUIWorkspace

Dim session As New NotesSession

Dim uidoc As NotesUIDocument

Dim acl As NotesACL

Dim entry As NotesACLEntry

Set db = session.CurrentDatabase

Set acl = db.ACL

Set entry = acl.GetEntry( session.CommonUserName )

If entry Is Nothing Then

  Set entry = acl.GetEntry( session.UserName )

End If

If entry Is Nothing Then

  Messagebox _

  "No entry for " & session.CommonUserName & _

  " or " & session.UserName,, "No entry"

  Exit Sub

End If

If entry.IsRoleEnabled( "[Supervisor]" ) Then

  Set uidoc = workspace.ComposeDocument( "", "approval" )

Else

  Set uidoc = workspace.ComposeDocument( "", "request" )

End If


Example: IsSecondaryResort property

This script indicates if a column is a secondary resortable column.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim view As NotesView

Dim column As notesViewColumn

Set db = session.CurrentDatabase

Set view = db.Getview("Align")

Set column = view.Columns(0)

Messagebox (column.IsSecondaryResort)


Example: IsSecondaryResortDescending property

This script indicates if a secondary resortable column is descending in resort order.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim view As NotesView

Dim column As notesViewColumn

Set db = session.CurrentDatabase

Set view = db.Getview("Align")

Set column = view.Columns(0)

Messagebox (column.IsSecondaryResortDescending)


Example: IsServer property

This script will check to see if the entry is a server.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim acl As NotesACL

Dim entry As NotesACLEntry

Set db = session.CurrentDatabase

Set acl = db.ACL

Set entry = acl.GetEntry("Jaba")

If entry.IsServer Then

Messagebox entry.Name & " is a server."

Else

Messagebox entry.Name & " is not a server."

End If

Call acl.Save


Example: IsShowTwistie property

This script indicates if an expandable column displays a twistie.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim view As NotesView

Dim column As notesViewColumn

Set db = session.CurrentDatabase

Set view = db.Getview("Align")

Set column = view.Columns(0)

Messagebox (column.IsShowTwistie)


Example: IsSigned property

This script checks if a document is signed.

Dim doc As NotesDocument

'...set value of doc...

If doc.IsSigned Then

  Messagebox( "This document is signed." )

Else

  Messagebox( "This document is not signed." )

End If


Example: IsSortDescending property

This script indicates if a column is sorted in descending order.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim view As NotesView

Dim column As notesViewColumn

Set db = session.CurrentDatabase

Set view = db.Getview("Align")

Set column = view.Columns(0)

Messagebox (column.IsSortDescending)


Example: IsSorted property

This script checks if a collection is sorted. Since the collection is produced using the FTSearch method, the IsSorted property is True and the script displays a dialog box stating that "This collection is sorted."

Dim session As New NotesSession

Dim db As NotesDatabase

Dim collection As NotesDocumentCollection

Set db = session.CurrentDatabase

Set collection = db.FTSearch( "white wine", 0 )

If collection.IsSorted Then

  Messagebox( "This collection is sorted" )

Else

  Messagebox( "This collection is unsorted" )

End If


Examples: IsSorted property

  1. This script checks if the first column in the By Author view of the current database is sorted.

    2. Dim session As New NotesSession

    Dim db As NotesDatabase

    Dim view As NotesView

    Dim column As NotesViewColumn

    Set db = session.CurrentDatabase

    Set view = db.GetView( "By Author" )

    Set column = view.Columns( 0 )

    If column.IsSorted Then

      Messagebox( "The first column is sorted." )

    Else

      Messagebox( "The first column is unsorted." )

    End If
  2. This script finds the documents in a view that match the key "Blowfish" and puts them into a folder.

    • The GetDocumentByKey method finds the first document in the view that matches "Blowfish."

    • To find subsequent matching documents, the script loops through the remaining documents in the view. It keeps looping as long as the document matches the key. To match the key, the document's column value for the first sorted and categorized column in the view must equal "Blowfish."

Why doesn't the script look for documents where doc.ColumnValues(0) = "Blowfish"? Because the first column in the view may or may not be the first sorted and categorized column in the view. Therefore, the script uses the IsSorted property to find the first sorted and categorized column in the view and uses column.Position - 1 to get the correct column value from the document.

Dim db As New NotesDatabase( "", "ocean.nsf" )

Dim view As NotesView

Dim column As NotesViewColumn

Dim doc As NotesDocument

Dim done As Variant

Set view = db.GetView( "By Category" )

' get the first sorted and categorized column in the view

Forall c In view.Columns

  If ( c.IsSorted And c.IsCategory ) Then

    Set column = c

    Exit Forall

  End If

End Forall

' get the first document that matches the key

Set doc = view.GetDocumentByKey( "Blowfish" )

' get the remaining documents that match the key

' since ColumnValues array starts at 0 for position 1,

' subtract 1 from the column position

While ( doc.ColumnValues( column.Position - 1 ) _

        = "Blowfish" )

  Call doc.PutInFolder( "Fishy" )

  Set doc = view.GetNextDocument( doc )

Wend


Example: IsSubForm property

This script displays the names of all the subforms in a database.

Dim session As New NotesSession

Dim db As NotesDatabase

Set db = session.CurrentDatabase

formCount = 0

msgString = ""

Forall form In db.Forms

     If form.IsSubForm Then

          formCount = formCount + 1

          msgString = msgString & Chr(10) _

          & "     " & form.Name

     End If

End Forall

If formCount > 0 Then

     Messagebox "This database has " & formCount _

     & " subform(s):" & msgString

Else

     Messagebox "This database has not subforms"

End If


Examples: IsSummary property

  1. This script creates a new Topic item using the extended class syntax. Items created with this syntax have a default IsSummary value of True.

    2. Dim session As New NotesSession

    Dim db As NotesDatabase

    Dim doc As NotesDocument

    Dim item As NotesItem

    Set db = session.CurrentDatabase

    Set doc = New NotesDocument( db )

    doc.Topic = "I have something to say"

    Set item = doc.GetFirstItem( "Topic" )

    If item.IsSummary Then

      Messagebox _

      ( "Items created this way are automatically summmary." )

    End If

    Call doc.Save( False, True )
  2. This script creates a new Topic item using New. Items created with New have a default IsSummary value of False. Since you want the Topic item to display in a view, you set IsSummary to True.

    3. Dim session As New NotesSession

    Dim db As NotesDatabase

    Dim doc As NotesDocument

    Dim item As NotesItem

    Set db = session.CurrentDatabase

    Set doc = New NotesDocument( db )

    Set item = New NotesItem _

    ( doc, "Topic", "I have something to say" )

    item.IsSummary = True

    ' must specifically set this property

    Call doc.Save( False, True )

See also
Extended class syntax


Example: IsSupported method

The following agent displays the supported options of a data source:

Uselsx "*LSXODBC"

Sub Initialize

     Dim con As New ODBCConnection

     Dim msg As String

     If Not con.ConnectTo("ATDB") Then

          Messagebox "Could not connect to ATDB"

          Exit Sub

     End If

     msg = "The following options are supported:" & Chr(10)

     If con.IsSupported(DB_SUPP_CURSORS) Then

          msg = msg & Chr(10) & "Cursors"

     End If

     If con.IsSupported(DB_SUPP_PROCEDURES) Then

          msg = msg & Chr(10) & "Stored-procedure capability"

     End If

     If con.IsSupported(DB_SUPP_READONLY) Then

          msg = msg & Chr(10) & "Read-only mode"

     End If

     If con.IsSupported(DB_SUPP_SILENTMODE) Then

          msg = msg & Chr(10) &  _

                "Silent mode for ID or password failure"

     End If

     Messagebox msg,, "Supported options for ATDB"

     con.Disconnect

End Sub


Example: IsTotal property

This script indicates if the Yearly Income view entry in the By Category view is a total.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim view As NotesView

Dim entry As NotesViewEntry

Set db = session.CurrentDatabase

Set view = db.GetView("By Category")

Set entry = view.GetEntryByKey("Yearly Income")

If entry.IsTotal Then

  Messagebox "This view entry is a total."

Else

  Messagebox "This view entry is not a total."

End If


Example: IsUIDocOpen property

This user sub checks the NotesDocument object that is passed to it and exits with a message if the object is based on a front-end document.

Sub UpdateSubject(doc As NotesDocument)

     If doc.IsUIDocOpen Then

          Messagebox _

          "Can't do Subject update from front-end",, _

          "No can do"

          Exit Sub

     End If

     Call doc.ReplaceItemValue _

     ("Subject", doc.Subject(0) & "0")

     Call doc.Save(True, False)

End Sub


Example: IsValid property

This script checks to see if the Cars view entry in the By Category view is a valid entry. If the view entry is valid, the document is placed in the Valid Entries folder. If the view entry is not valid a message is displayed.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim view As NotesView

Dim entry As NotesViewEntry

Dim doc As NotesDocument

Set db = session.CurrentDatabase

Set view = db.GetView("By Category")

Set entry = view.GetEntryByKey("Cars")

Set doc = entry.Document

If entry.IsValid Then

  Call doc.PutInFolder("Valid Entries")

Else

  Messagebox "This view entry is invalid."

End If


Example: IsValid property

This example retrieves a document, then it checks to see whether or not the document is valid.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim view As NotesView

Dim entry As NotesviewEntry

Dim vc As NotesViewEntryCollection

Dim doc As NotesDocument

Set db = session.CurrentDatabase

Set view = db.GetView("By Category")

Set vc = view.GetAllEntriesByKey("Cars")

Set entry = vc.GetFirstEntry()

Set doc = entry.document

If doc.IsValid = True Then

     Messagebox "This document is valid."

Else

     Messagebox "This document is not valid."

End If


Example: IsValueAltered method

This script executes when a field is entered and displays a message if the result set column with the same name has changed. The form that contains the button contains other scripts that declare global variables, load the result set, and process the result set. The global declarations and a portion of the Postopen script are shown.

Uselsx "*LSXODBC"

Dim con As ODBCConnection

Dim qry As ODBCQuery

Dim result As ODBCResultSet

Sub Postopen(Source As Notesuidocument)

     Set con = New ODBCConnection

     Set qry = New ODBCQuery

     Set result = New ODBCResultSet

     Set qry.Connection = con

     Set result.Query = qry

     con.ConnectTo("ATDB")

     qry.SQL = "SELECT * FROM STUDENTS ORDER BY LASTNAME"

     result.Execute

     ...

End Sub

Sub Entering(Source As Field)

     Dim workspace As New NotesUIWorkspace

     Dim uidoc As NotesUIDocument

     Set uidoc = workspace.CurrentDocument

     If result.IsValueAltered(uidoc.CurrentField) Then

          Messagebox "This field was changed by SetValue",, _

          "Field is altered"

     End If

End Sub


Example: IsValueNull method

This script executes when a field is entered and displays a message if the result set column with the same name is null. The form that contains the button contains other scripts that declare global variables, load the result set, and process the result set. The global declarations and a portion of the Postopen script are shown.

Uselsx "*LSXODBC"

Dim con As ODBCConnection

Dim qry As ODBCQuery

Dim result As ODBCResultSet

Sub Postopen(Source As Notesuidocument)

     Set con = New ODBCConnection

     Set qry = New ODBCQuery

     Set result = New ODBCResultSet

     Set qry.Connection = con

     Set result.Query = qry

     con.ConnectTo("ATDB")

     qry.SQL = "SELECT * FROM STUDENTS ORDER BY LASTNAME"

     result.Execute

     ...

End Sub

Sub Entering(Source As Field)

     Dim workspace As New NotesUIWorkspace

     Dim uidoc As NotesUIDocument

     Set uidoc = workspace.CurrentDocument

     If result.IsValueNull(uidoc.CurrentField) Then

          Messagebox "This field is null",, "Null field"

     End If

End Sub


Example: IsWebAgent property

This script determines whether the current agent is a Web agent.

Dim session As New NotesSession

Dim agent As NotesAgent

Dim db As NotesDatabase

Set agent = session.CurrentAgent

If agent.IsWebAgent = True Then

  Messagebox "This is a Web agent."

Else

  Messagebox "This is not a Web agent."

End If


Example: Italic property

This example builds a rich-text item and sets styles so that part of the text is italicized.

Sub Initialize

     Dim session As New NotesSession

     Dim db As NotesDatabase

     Set db = session.CurrentDatabase

     Dim doc As New NotesDocument(db)

     Call doc.AppendItemValue("From", session.UserName)

     Call doc.AppendItemValue("Subject",  _

                              "Meeting time changed")

     Dim richStyle As NotesRichTextStyle

     Set richStyle = session.CreateRichTextStyle

     Dim richText As New NotesRichTextItem(doc, "Body")

     Call richText.AppendText("The meeting is at ")

     richStyle.Italic = True

     Call richText.AppendStyle(richStyle)

     Call richText.AppendText("3:00")

     richStyle.Italic = False

     Call richText.AppendStyle(richStyle)

     Call richText.AppendText(" not 2:00")

     Call doc.Save(True, False)

End Sub


Examples: ItemName property

  1. This script gets the name of the item that's displayed in the first column of the By Category view in the database YAHOO.NSF. For example, if the first column displays the value of the Categories item, the ItemName property returns "Categories."

    2. Dim db As New NotesDatabase( "", "yahoo.nsf" )

    Dim view As NotesView

    Dim column As NotesViewColumn

    Dim item As String

    Set view = db.GetView( "By Category" )

    Set column = view.Columns( 0 )

    item = column.ItemName
  2. This script gets the name of the item that's displayed in the second column of the By Category view in the database YAHOO.NSF. For example, if the second column displays the value of a simple function or a formula, the ItemName property might return the internal name "$26."

    3. Dim db As New NotesDatabase( "", "yahoo.nsf" )

    Dim view As NotesView

    Dim column As NotesViewColumn

    Dim item As String

    Set view = db.GetView( "By Category" )

    Set column = view.Columns( 1 )

    item = column.ItemName


Examples: Items property

  1. This example prints the name of every item in a document. For example, if the document contains five items, the script might print "From," "SendTo," "Subject," "Body," and "DeliveredDate."

    2. Dim doc As NotesDocument

    '...set value of doc...

    Forall i In doc.Items

      Messagebox( i.Name )

    End Forall
  2. This script finds an Authors item in a document and assigns it to the authorItem object.

    3. Dim doc As NotesDocument

    Dim authorItem As NotesItem

    '...set value of doc...

    Forall item In doc.Items

      If ( item.IsAuthors ) Then

        Set authorItem = item

      End If

    End Forall


Examples: KeepSelectionFocus property

This script indicates whether an outline entry keeps selection focus.

Dim s As New NotesSession

Dim db As NotesDatabase

Dim outline As NotesOutline

Dim entry As NotesOutlineEntry

Set db = s.CurrentDatabase

Set outline = db.getOutline("DiscOutline")

Set entry = outline.GetFirst

If (entry.KeepSelectionFocus) Then

  Messagebox "Keeps selection focus",, entry.Alias

Else

  Messagebox "Does not keep selection focus",, entry.Alias

End If


Examples: Label property

This script displays the label of an outline entry.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim outline As NotesOutline

Dim oe As NotesOutlineEntry

Set db = session.CurrentDatabase

Set outline = db.GetOutline("products")

Set oe = outline.GetFirst()

Messagebox "Label: " & oe.Label


Example: Language property

The following script lists the common name and language where "John Smith" is the primary name and "Taro Yamada" is the alternate name, and the language for the alternate name is Japanese.

Dim session As New NotesSession

Dim nameslist As variant

nameslist = session.UserNameList

Forall nname in nameslist

     print ("Common name is" & nname.common)

     print ("Language is" & nname.Language)

end forall

The result looks like this:

Common name is John Smith

Language is

Common name is Taro Yamada

Language is ja


Examples: LastAccessed property

  1. This script gets the date that a document was last accessed and puts it into accessDate. For example, LastAccessed returns 10/31/95 1:51:31 PM.

    2. Dim doc As NotesDocument

    Dim accessDate As Variant

    '...set value of doc...

    accessDate = doc.LastAccessed
  2. This script changes the document Status item to "Stalled" if the document has not been accessed during the last three days.

    3. Dim doc As NotesDocument

    '...set value of doc...

    If ( Cint( Date - doc.LastAccessed ) > 3 ) Then

      doc.Status = "Stalled"

      Call doc.Save( True, True )

    End If


Example: LastExitStatus property

This agent script checks the last exit status of the current agent and prints a message in the status bar.

Sub Initialize

  Dim session As New NotesSession

  If ( session.LastExitStatus = 0 ) Then

    Print ( "Agent exited gracefully last time" )

  Else

    Print ( "Agent raised an error last time" )

  End If

End Sub


Examples: LastFTIndexed property

  1. This script gets the date that the current database was last full-text indexed. For example, the LastFTIndexed property might return 10/30/95 6:36:18 PM.

    2. Dim session As New NotesSession

    Dim db As NotesDatabase

    Dim indexDate As Variant

    Set db = session.CurrentDatabase

    indexDate = db.LastFTIndexed
  2. This script checks if the current database has been modified since the time it was last full-text indexed. If so, it updates the index.

    3. Dim session As New NotesSession

    Dim db As NotesDatabase

    Set db = session.CurrentDatabase

    If ( db.LastModified > db.LastFTIndexed ) Then

      Call db.UpdateFTIndex( False )

    End If


Examples: LastModified property

  1. This script gets the date that the current database was last modified. For example, the LastModified property might return 10/30/95 1:35:44 PM.

    2. Dim session As New NotesSession

    Dim db As NotesDatabase

    Dim modifyDate As Variant

    Set db = session.CurrentDatabase

    modifyDate = db.LastModified
  2. This script sends mail to the managers of PROJECT.NSF if the database hasn't been modified in the last thirty days.

    3. Dim db As New NotesDatabase( "", "projects.nsf" )

    Dim doc As NotesDocument

    If ( ( Today - db.LastModified ) > 30 ) Then

      Set doc = New NotesDocument( db )

      doc.Form = "Memo"

      doc.Subject = "Your database: " & db.Title

      doc.Body =  _

      "...hasn't changed in 30 days."

      Call doc.Send( False, db.Managers )

    End If


Examples: LastModified property

  1. This script gets the date that a document was last modified and puts it into modifyDate. For example, LastModified returns 10/31/95 10:42:31 AM.

    2. Dim doc As NotesDocument

    Dim modifyDate As Variant

    '...set value of doc...

    modifyDate = doc.LastModified
  2. This script sets the value of the PurgeDate item in a document, based on when the document was last modified. If it was modified 14 or more days ago, it sets the PurgeDate to today. If it was modified between seven and thirteen days ago, it sets the PurgeDate to seven days from today.

    3. Dim doc As NotesDocument

    Dim days As Integer

    '...set value of doc...

    days = Cint( Date - doc.LastModified )

    If days > 14 Then

      doc.PurgeDate = Date

    Else

      If days > 7  Then

        doc.PurgeDate = Date + 7

      End If

    End If

    Call doc.Save( True, True )


Example: LastModified property

This script gets the date that the By Author view in the current database was last modified, and puts it into modifyDate. For example, LastModified returns 10/17/95 9:15:35 PM.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim view As NotesView

Dim modifyDate As Variant

Set db = session.CurrentDatabase

Set view = db.GetView( "By Author" )

modifyDate = view.LastModified


Example: LastRow method

This agent accesses all rows of a result set starting from the last row. You must explicitly set LastRow and process it outside the loop. In the loop, each PrevRow gets the previous row in the data set. IsBeginOfData detects that the first row was processed. Although this example demonstrates the technique, stepping to previous rows is not encouraged; if you use this technique, be sure the previous rows are cached.

Uselsx "*LSXODBC"

Sub Initialize

     Dim con As New ODBCConnection

     Dim qry As New ODBCQuery

     Dim result As New ODBCResultSet

     Dim firstName As String

     Dim lastName As String

     Dim msg As String

     Set qry.Connection = con

     Set result.Query = qry

     con.ConnectTo("ATDB")

     qry.SQL = "SELECT * FROM STUDENTS ORDER BY LASTNAME"

     result.Execute

     msg = "Student names:" & Chr(10)

     result.LastRow

     firstName = result.GetValue("FIRSTNAME", firstName)

     lastName = result.GetValue("LASTNAME", lastName)

     msg = msg & Chr(10) & firstName & " " & lastName

     Do

          result.PrevRow

          firstName = result.GetValue("FIRSTNAME", firstName)

          lastName = result.GetValue("LASTNAME", lastName)

          msg = msg & Chr(10) & firstName & " " & lastName

     Loop Until result.IsBeginOfData

     Messagebox msg,, "Student Names"

     result.Close(DB_CLOSE)

     con.Disconnect

End Sub


Examples: LastRun property

  1. This script gets the date that the current agent was last run. For example, if the agent last ran on August 15, 1996 at 11:09:20 A.M., the LastRun property returns a variant containing the date-time value 8/15/96 11:09:20 AM.

    2. Dim session As New NotesSession

    Dim agent As NotesAgent

    Dim lasttime As Variant

    Set agent = session.CurrentAgent

    lasttime = agent.LastRun
  2. This script checks if the current database's full-text index has been updated since the current agent last ran. If not, it updates the index.

    3. Dim session As New NotesSession

    Dim agent As NotesAgent

    Dim db As NotesDatabase

    Set agent = session.CurrentAgent

    Set db = session.CurrentDatabase

    If ( agent.LastRun > db.LastFTIndexed ) Then

      Call db.UpdateFTIndex( False )

    End If


Example: LastRun property

  1. This agent script gets the date that the agent was last run, and puts it into runDate. For example, if the agent last ran on August 15, 1996, at 11:09:20 A.M., LastRun returns 8/15/96 11:09:20 AM. If this is the first time that the agent has run, LastRun returns 11/30/1899.

    2. Sub Initialize

      Dim session As New NotesSession

      Dim runDate As Variant

      runDate = session.LastRun

    End Sub
  2. This agent script checks if the current database's full-text index has been updated since the agent last ran. If not, it updates the index.

    3. Sub Initialize

      Dim session As New NotesSession

      Dim db As NotesDatabase

      Set db = session.CurrentDatabase

      If ( session.LastRun > db.LastFTIndexed ) Then

        Call db.UpdateFTIndex( False )

      End If

    End Sub


Example: LeftMargin property

This example sets the left margin property of a rich-text paragraph style object.

Dim session As New NotesSession

Dim db As NotesDatabase

Set db = session.Currentdatabase

Dim doc As New NotesDocument(db)

Call doc.AppendItemValue("From", session.Username)

Call doc.AppendItemValue("subject", _

"Meeting agenda")

Dim rtpStyle As NotesrichTextParagraphStyle

Set rtpStyle = session.CreateRichTextParagraphStyle

Dim richText As New NotesRichTextItem(doc, "Body")

rtpStyle.LeftMargin = RULER_ONE_INCH

Call richText.AppendParagraphStyle(rtpStyle)

Call richText.AppendText("Where are we now?")

Call richText.AddNewLine(1)

Call richText.AppendText (" Where do we go from here.")

Call doc.Save(True, False)


Examples: Level property

  1. This script displays a message about the first entry in the database. The entry db is a NotesDatabase object.

    2. Set acl = db.ACL

    Set entry = acl.GetFirstEntry

    If ( entry.Level = ACLLEVEL_READER ) Then

      Messagebox( "The first entry has Reader access." )

    End If
  2. This script gets the entry for the server Brussels in the ACL of the current database, and changes its access level to Designer.

    3. Dim session As New NotesSession

    Dim db As NotesDatabase

    Dim acl As NotesACL

    Dim entry As NotesACLEntry

    Set db = session.CurrentDatabase

    Set acl = db.ACL

    Set entry = acl.GetEntry( "Brussels" )

    If Not ( entry Is Nothing ) Then

      entry.Level = ACLLEVEL_DESIGNER

      Call acl.Save

    End If


Examples: Level property

This script displays the level of an outline entry.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim outline As NotesOutline

Dim oe As NotesOutlineEntry

Dim level As Long

Set db = session.CurrentDatabase

Set outline = db.GetOutline("products")

Set oe = outline.GetFirst()

Messagebox "Level: " & oe.Level


Example: ListDataSources method

The following agent displays the names of all the data sources on the local machine:

Uselsx "*LSXODBC"

Sub Initialize

     Dim con As New ODBCConnection

     Dim msg As String

     dsnList = con.ListDataSources

     For n% = Lbound(dsnList) To Ubound(dsnList)

          msg = msg & dsnList(n%) & Chr(10)

     Next

     Messagebox msg,,"List of DSNs"

     con.Disconnect

End Sub


Examples: ListFields method

The following agent displays the names of all the fields in the STUDENTS table of the ADTB data source:

Uselsx "*LSXODBC"

Sub Initialize

     Dim con As New ODBCConnection

     Dim msg As String

     If Not con.ConnectTo("ATDB") Then

          Messagebox "Cannot connect to ATDB"

          Exit Sub

     End If

     fields = con.ListFields("STUDENTS")

     msg = "STUDENTS contains the following fields:" & Chr(10)

     For n% = Lbound(fields) To Ubound(fields)

          msg = msg & Chr(10) & fields(n%)

     Next

     Messagebox msg,, "Fields for ATDB"

     con.Disconnect

End Sub


Examples: ListProcedures method

The following agent displays the names of all procedures for the ADTB data source:

Uselsx "*LSXODBC"

Sub Initialize

     Dim con As New ODBCConnection

     Dim msg As String

     tables = con.ListProcedures("ATDB")

     msg = "ATDB contains the following procedures:" & Chr(10)

     If Ubound(tables) = 0 Then

          Messagebox "No procedures for ATDB",, _

                     "Procedures for ATDB"

          Exit Sub

     End If

     For n% = Lbound(tables) To Ubound(tables)

          msg = msg & Chr(10) & tables(n%)

     Next

     Messagebox msg,, "Procedures for ATDB"

     con.Disconnect

End Sub


Example: ListSep property

This script indicates the list (multi-value) separator for values in a column.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim view As NotesView

Dim column As notesViewColumn

Set db = session.CurrentDatabase

Set view = db.Getview("Align")

Set column = view.Columns(0)

Messagebox (column.ListSep)


Example: ListTables method

The following agent displays the names of all the tables for the ADTB data source:

Uselsx "*LSXODBC"

Sub Initialize

     Dim con As New ODBCConnection

     Dim msg As String

     tables = con.ListTables("ATDB")

     msg = "ATDB contains the following tables:" & Chr(10)

     For n% = Lbound(tables) To Ubound(tables)

          msg = msg & Chr(10) & tables(n%)

     Next

     Messagebox msg,, "Tables for ATDB"

     con.Disconnect

End Sub


Examples: LocalTime property

  1. This script displays the value of the LSLocalTime property, which equals "04/16/96 05:36:00 PM," regardless of the computer's time zone setting.

    2. Dim dateTime As New NotesDateTime( "04/16/96 05:36 PM" )

    Messagebox( dateTime.LocalTime )
  2. This script creates a new NotesDateTime object set to the default date, and then sets its LocalTime property. The dateTime object now represents 08/18/97, with a TimeZone property of 0.

    3. Dim dateTime As New NotesDateTime( "" )

    dateTime.LocalTime = "08/18/97"


Example: LocateRow method

This agent locates all rows in a result set with "Cambridge" in field 5 and "MA" in field 6.

Uselsx "*LSXODBC"

Sub Initialize

     Dim con As New ODBCConnection

     Dim qry As New ODBCQuery

     Dim result As New ODBCResultSet

     Dim msg As String

     Set qry.Connection = con

     Set result.Query = qry

     con.ConnectTo("ATDB")

     qry.SQL = "SELECT * FROM STUDENTS ORDER BY LASTNAME"

     result.Execute

     msg = "Students from Cambridge MA:" & Chr(10)

     result.FirstRow

     Do While result.LocateRow(5, "Cambridge", 6, "MA")

          msg = msg &Chr(10)

          For i = 1 To result.NumColumns

               msg = msg & result.GetValue(i) & "  "

          Next

          If result.IsEndOfData Then Exit Do

          result.NextRow

     Loop

     Messagebox msg

     result.Close(DB_CLOSE)

     con.Disconnect

End Sub


Example: Locating a database on a server and local disk

This example prints the names of all the .NSF files in the local Domino data directory. To find different types of files, you can alternatively specify DATABASE, TEMPLATE, REPLICA_CANDIDATE, or TEMPLATE_CANDIDATE as the argument to the GetFirstDatabase method.

Sub Initialize

     Dim dbdir As New NotesDbDirectory("")

     Dim db As NotesDatabase

     Set db = dbdir.GetFirstDatabase(DATABASE)

     While Not(db Is Nothing)

          Messagebox db.Title

          Set db = dbdir.GetNextDatabase

     Wend

End Sub


Example: Locating a document by ID

This example stores the note ID of each document in a database in a string array, then uses the array in a loop of GetDocumentByID methods to access each document. You can substitute the UniversalID property and GetDocumentByUNID method in the example to use the universal ID.

Sub INITIALIZE

     Dim noteIDs()

     Dim db As New NotesDatabase _

     ("", Inputbox("Name of database file?"))

     Dim dc As NotesDocumentCollection

     Dim doc As NotesDocument

     Set dc = db.AllDocuments

     Redim noteIDs(1 To dc.Count)

     For j = 1 To dc.Count

          Set doc = dc.GetNthDocument(j)

          noteIDs(j) = doc.noteID

     Next

     Forall noteID In noteIDs

          Set doc = db.GetDocumentByID(noteID)

          Messagebox doc.Subject(0)

     End Forall

End Sub


Examples: Locating a view or folder

  1. This example finds a view in the current database.

    2. Sub Initialize

         Dim session As New NotesSession

         Dim db As NotesDatabase

         Dim view As NotesView

         Set db = session.CurrentDatabase

         Set view = db.GetView _

         (Inputbox("Exact name of view?"))

         Messagebox "View name: " & view.Name & Chr(10) _

         & "Last modified: " & view.LastModified & Chr(10) _

         & "Created: " & view.Created & Chr(10) _

         & "Universal ID: " & view.UniversalId

    End Sub
  2. This example finds the default view in the current database.

    3. Sub Initialize

         Dim session As New NotesSession

         Dim db As NotesDatabase

         Set db = session.CurrentDatabase

         REM view is NotesView object

         Forall view In db.Views

              If view.IsDefaultView Then

                   Messagebox "Default view is " & view.Name

                   Exit Forall

              End If

         End Forall

    End Sub


Examples: Locating documents within a view or folder

  1. This example accesses all the documents in the "By Category" view first to last. The GetLastDocument and GetPrevDocument methods could be substituted to access all the documents last to first.

    2. Sub Initialize

         Dim session As New NotesSession

         Dim db As NotesDatabase

         Dim view As NotesView

         Dim doc As NotesDocument

         Set db = session.CurrentDatabase

         Set view = db.GetView("By Category")

         Messagebox "View name: " & view.Name

         Set doc = view.GetFirstDocument

         While Not(doc Is Nothing)

              Messagebox "Subject: " & doc.Subject(0)

              Set doc = view.GetNextDocument(doc)

         Wend

    End Sub
  2. This example limits the view to those documents that meet the full-text search criteria for "Search string alpha" and traverses the view.

    3. Sub Initialize

         Dim session As New NotesSession

         Dim db As NotesDatabase

         Dim view As NotesView

         Dim doc As NotesDocument

         Set db = session.CurrentDatabase

         Set view = db.GetView("By Category")

         Call db.UpdateFTIndex(True)

         numDocs = view.FTSearch("""Search string alpha""", 0)

         If numDocs <> 0 Then

              Set doc = view.GetFirstDocument

              While Not(doc Is Nothing)

                   Messagebox "Subject: " & doc.Subject(0)

                   Set doc = view.GetNextDocument(doc)

              Wend

         End If

    End Sub
  3. This example uses GetAllDocumentsByKey to access all the documents in the "By Subject" view with whatever the user enters in response to Inputbox as the first characters of the first sorted column.

    4. Sub Initialize

         Dim session As New NotesSession

         Dim db As NotesDatabase

         Dim view As NotesView

         Dim dc As NotesDocumentCollection

         Dim keyString As String

         keyString = Inputbox("Subject starts with?")

         Set db = session.CurrentDatabase

         Set view = db.GetView("By Subject")

         Set dc = view.GetAllDocumentsByKey(keyString, False)

         If dc Is Nothing Then

              Messagebox keyString,, "Not found"

              Exit Sub

         End If

         For j = 1 To dc.Count

              Messagebox dc.GetNthDocument(j).Subject(0)

         Next

    End Sub
  4. This example uses GetDocumentByKey and GetNextDocument to access all the documents in the "By Subject" view with whatever the user enters in response to Inputbox as the first characters of the first sorted column.

    5. Sub Initialize

         Dim session As New NotesSession

         Dim db As NotesDatabase

         Dim view As NotesView

         Dim doc As NotesDocument

         Dim keyArray(1 To 1) As String

         keyArray(1) = Inputbox("Subject starts with?")

         Set db = session.CurrentDatabase

         Set view = db.GetView("By Subject")

         Set doc = view.GetDocumentByKey(keyArray)

         If doc Is Nothing Then

              Messagebox keyArray(1) & " not found"

              Exit Sub

         End If

         subj = Left(doc.Subject(0), Len(keyArray(1)))

         While Not(doc Is Nothing) And subj = keyArray(1)

              Messagebox "Subject: " & doc.Subject(0)

              Set doc = view.GetNextDocument(doc)

              subj = Left(doc.Subject(0), Len(keyArray(1)))

         Wend

    End Sub
  5. This example accesses all the documents in a view by moving up and down through all response and response to response documents.

    6. Sub Initialize

         Dim session As New NotesSession

         Dim db As NotesDatabase

         Dim view As NotesView

         Dim doc As NotesDocument

         Dim Child As NotesDocument

         Dim grandChild As NotesDocument

         Set db = session.CurrentDatabase

         Set view = db.GetView("By Subject")

         Set doc = view.GetFirstDocument

         While Not(doc Is Nothing)

              Messagebox "Main document: " & doc.Subject(0)

              Set child = view.GetChild(doc)

              While Not(child Is Nothing)

                   Messagebox "Response: " & child.Subject(0)

                   Set grandChild = view.GetChild(child)

                   While Not(grandChild Is Nothing)

                   Messagebox "Response to response: " & _

                   grandChild.Subject(0)

                   Set grandchild = _

                   view.GetNextSibling(grandChild)

                   Wend

                   Set child = view.GetNextSibling(child)

              Wend

              Set doc = view.GetNextSibling(doc)

         Wend

    End Sub
  6. This example displays, for each document in the "By Category" view, a message saying whether or not the document is a response document, and giving the count for its first-level response documents.

    7. Sub Initialize

         Dim session As New NotesSession

         Dim db As NotesDatabase

         Dim view As NotesView

         Dim dc As NotesDocumentCollection

         Dim doc As NotesDocument

         Set db = session.CurrentDatabase

         Set view = db.GetView("By Category")

         Set doc = view.GetFirstDocument

         While Not(doc Is Nothing)

              Set dc = doc.Responses

              If doc.IsResponse Then

                   isResponse = _

                   "This document is a response document."

              Else

                   isResponse = _

                   "This document is not a response document."

              End If

              Messagebox "Subject: " & doc.Subject(0) _

              & Chr(10) & isResponse & Chr(10) & _

              "This document has " & dc.Count _

              & " response documents."

              Set doc = view.GetNextDocument(doc)

         Wend

    End Sub
  7. This example, which is a button on a form, puts a copy of the current document in the folder named "My Favorite Documents."

    8. Sub Click(Source As Button)

         Dim workspace As New NotesUIWorkspace

         Dim uidoc As NotesUIDocument

         Dim doc As NotesDocument

         Set uidoc = workspace.CurrentDocument

         Set doc = uidoc.Document

         Call doc.PutInFolder("My Favorite Documents")

    End Sub


Examples: LogAction method

  1. This agent script logs actions to a mail memo. It performs a full-text search on the current database, and logs one action for each document that matches the full-text search query.

    2. Each time the LogAction method is called, it adds a new line to the Body item of the mail memo. For example, if FTSearch returns a collection of three documents, the body of the mail memo looks like this:

10/25/95 12:26:37 PM Botany Agent starting
10/25/95 12:26:42 PM Document Petals placed in folder.
10/25/95 12:26:44 PM Document Stems placed in folder.
10/25/95 12:26:46 PM Document Leaves placed in folder.

Sub Initialize

  Dim session As New NotesSession

  Dim db As NotesDatabase

  Dim collection As NotesDocumentCollection

  Dim currentLog As NotesLog

  Dim doc As NotesDocument

  Dim j As Integer

  Set db = session.CurrentDatabase

  Set collection = db.FTSearch( "botany", 0 )

  Set currentLog = New NotesLog( "Botany Agent" )

  Call currentLog.OpenMailLog _

  ( "Jesse Gora", "Log for Botany Agent" )

  For j = 1 To collection.Count

    Set doc = collection.GetNthDocument( j )

    Call doc.PutInFolder( "Botanist's Delight" )

    Call currentLog.LogAction( "Document " &  _

    doc.Subject( 0 ) & " placed in folder." )

  Next

  Call currentLog.Close

End Sub
  1. The call to OpenMailLog in the first script is replaced with the following:

    2. Call currentLog.OpenNotesLog( "", "agentlog.nsf" )
    Each time the LogAction method is called, it creates and saves a new document in AGENTLOG.NSF on the current computer. For example, if FTSearch returns a collection of three documents, one of the new documents created in AGENTLOG.NSF has the following items:

    A$PROGNAME	"Botany Agent"

    A$LOGTIME	10/25/95 01:22:24 PM

    A$USER		"Kerry Bowling"

    A$LOGTYPE	"Action"

    A$ACTION		"Document Petals placed

                    in folder."
  2. The call to OpenMailLog in the first script is replaced with the following:

    3. Call currentLog.OpenFileLog( "c:\log.txt" )
    Each time the LogAction method is called, it adds a new line of text to LOG.TXT. For example, if FTSearch returns a collection of three documents, LOG.TXT looks like this:

    Botany Agent: 10/25/95 01:23:33 PM: Document Petals placed in folder.

    Botany Agent: 10/25/95 01:23:35 PM: Document Stems placed in folder.

    Botany Agent: 10/25/95 01:23:37 PM: Document Leaves placed in folder.


Example: LogActions property

This script disables and enables the action logging.

Dim currentLog As New NotesLog _

( "Turning Actions On and Off" )

Call currentLog.OpenMailLog _

( "Charlie Pycha", "Here's your log" )

currentLog.LogActions = False

Call currentLog.LogAction( "This action never gets logged." )

'...do some other stuff...

currentLog.LogActions = True

Call currentLog.LogAction( "This action does get logged." )

Call currentLog.Close


Examples: LogError method

  1. This script logs a Notes error to a file. The lsERR_NOTES_DATABASE_NOTOPEN error occurs when a database cannot be opened; here, it occurs if Notes cannot locate the current user's mail database after the call to the OpenMail method. If this happens, control passes to the logDbOpenError label, and the error code and string get placed into the file LOG.TXT. For example, the line in LOG.TXT looks like this:

    2. Ornithology Agent: 10/25/95 02:48:40 PM: Error (4063): Unable to open db CPycha.nsf
    This script must include the file LSXBEERR.LSS in order to use the Notes error constants.

    Sub Initialize

      On Error lsERR_NOTES_DATABASE_NOTOPEN Goto logDbOpenError

      Dim currentLog As NotesLog

      Dim db As NotesDatabase

      Dim collection As NotesDocumentCollection

      Set currentLog = New NotesLog( "Ornithology Agent" )

      Set db = New NotesDatabase( "", "" )

      Call db.OpenMail

      Call currentLog.OpenFileLog( "c:\log.txt" )

      Set collection = db.AllDocuments

      ' error might occur here

      Call currentLog.Close

      Exit Sub

    logDbOpenError:

      Call currentLog.LogError _

      ( lsERR_NOTES_DATABASE_NOTOPEN, _

      "Unable to open db " & db.FileName )

      Resume Next

    End Sub
  2. This script logs a user-defined error to a file. The script performs a full-text search on the current database, looking for the word "Rocks." If it does not find any matching documents, the script logs an error to another NotesDatabase on the same computer. Neither Notes nor LotusScript considers this condition to be an error, but you can use the LogError method to log any condition that prevents the successful completion of a script.

    3. Sub Initialize

      Dim currentLog As NotesLog

      Dim session As New NotesSession

      Dim db As NotesDatabase

      Dim collection As NotesDocumentCollection

      Dim doc As NotesDocument

      Set currentLog = New NotesLog( "Geology Agent" )

      Call currentLog.OpenNotesLog( "", "agentlog.nsf" )

      Set db = session.CurrentDatabase

      Set collection = db.FTSearch( "Rocks", 0 )

      If ( collection.Count = 0 ) Then

        Call currentLog.LogError( 0, "No documents found." )

      Else

        Set newsletter = New NotesNewsletter( collection )

        Set doc = newsletter.FormatMsgWithDoclinks( db )

        Call doc.Send( False, "Thalia Ruben" )

      End If

      Call currentLog.Close

    End Sub
  3. This agent script logs a LotusScript error to a mail memo. The error ErrDivisionByZero occurs when a script attempts to divide a number by zero. When this happens, control passes to the LogThisError label, where the LogError method adds a line of text to the body of the mail memo, which looks like this:

    4. 10/25/95 04:58:29 PM 	Let's do division starting

    10/25/95 04:58:29 PM 	Error (11): Division by zero
    This script must include the file LSERR.LSS in order to use the LotusScript error constants.

    Sub Initialize

      On Error ErrDivisionByZero Goto LogThisError

      Dim currentLog As New NotesLog( "Let's do division" )

      Dim x As Integer, y As Integer, z As Integer

      Call currentLog.OpenMailLog _

      ( "Joe Perron", "Division log" )

      y = 9

      z = 0

      x = y / z            ' error

      Call currentLog.Close

      Exit Sub

    LogThisError:

      Call currentLog.LogError( ErrDivisionByZero, _

      Error$( ErrDivisionByZero ) )

      Resume Next

    End Sub
  4. The call to OpenMailLog in the third script (above) is replaced with the following:

    5. Call currentLog.OpenNotesLog( "", "agentlog.nsf" )
    In this case, the LogError method creates a new document in AGENTLOG.NSF. The document contains the following items:

    A$PROGNAME	"Let's do division"

    A$LOGTIME 	10/25/95 04:42:24 PM

    A$USER		"Kerry Bowling"

    A$LOGTYPE	"Error"

    A$ERRCODE	11

    A$ERRMSG	"Division by zero"
  5. The call to OpenMailLog in the third script (above) is replaced with the following:

    6. Call currentLog.OpenFileLog( "c:\log.txt" )
    The LogError method adds a new line of text to LOG.TXT. For example, LOG.TXT looks like this:

    Let's do division: 10/25/95 04:49:51 PM: Error (11): Division by zero


Example: LogErrors property

This script disables and enables error logging.

Dim currentLog As New NotesLog( "Turning Errors On and Off" )

Call currentLog.OpenMailLog _

( "Charlie Pycha", "Here's your log" )

currentLog.LogErrors = False

Call currentLog.LogError _

( 0, "This error never gets logged." )

'...do some other stuff...

currentLog.LogErrors = True

Call currentLog.LogError( 0, "This error does get logged." )

Call currentLog.Close


Example: GetLSDOMasterRevision property

The following agent displays the revision level of the ODBC (LS:DO) LSX:

Uselsx "*LSXODBC"

Sub Initialize

     Dim con As New ODBCConnection

     Messagebox con.GetLSDOMasterRevision,,  _

      "LS:DO Master Revision"

End Sub


Example: LSGMTTime property

This script converts a date from a NotesDateTime object to a LotusScript variant of type DATE. The variant gmt represents 04/16/96 10:36:00 PM, if the script runs on a computer set to Eastern Standard Time and daylight savings time is not observed.

Dim dateTime As New NotesDateTime( "04/16/96 05:36 PM" )

Dim gmt As Variant

gmt = dateTime.LSGMTTime


Examples: LSLocalTime property

  1. This script converts a date from a NotesDateTime object to a LotusScript variant of type DATE. The variant lstime represents 04/16/96 05:36:00 PM. The value of the dateTime's TimeZone property is lost in the conversion because LotusScript variants do not store time zone information.

    2. Dim dateTime As New NotesDateTime( "04/16/96 05:36 PM" )

    Dim lstime As Variant

    lstime = dateTime.LSLocalTime
  2. This script sets a new NotesDateTime object to the default date, and then sets its LSLocalTime property. The dateTime object now represents 08/18/97 12:00:00 AM.

    3. Dim dateTime As New NotesDateTime( "" )

    dateTime.LSLocalTime = Datenumber( 1997, 8, 18 )


Example: Mailing a document

This example of a form button creates a document, copies to it the Subject and Body fields from the current document, and mails the document to a group called "Marketing." The document is not saved.

Sub Click(Source As Button)

     Dim session As New NotesSession

     Dim workspace As New NotesUIWorkspace

     Dim db As NotesDatabase

     Dim uidoc As NotesUIDocument

     Dim doc As NotesDocument, doc2 As NotesDocument

     Dim item As NotesItem

     Set uidoc = workspace.CurrentDocument

     Set doc = uidoc.Document

     Set db = session.CurrentDatabase

     Set doc2 = New NotesDocument(db)

     Set item = doc.GetFirstItem("Subject")

     Call item.CopyItemToDocument(doc2, "Subject")

     Set item = doc.GetFirstItem("Body")

     Call item.CopyItemToDocument(doc2, "Body")

     Call doc2.Send(True, "Marketing")

End Sub


Example: MakeResponse method

This script makes the second document in a view a response to the first document in a view. It also modifies the Form item in the second document so that it displays in the user interface as a Response.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim view As NotesView

Dim docA As NotesDocument

Dim docB As NotesDocument

Set db = session.CurrentDatabase

Set view = db.GetView( "All documents" )

Set docA = view.GetFirstDocument

Set docB = view.GetNextDocument( docA )

Call docB.MakeResponse( docA )

docB.Form = "Response"

Call docB.Save( True, True )


Example: Making a Domino log

This example appends the date and the message "Agent 4 invoked" to AGENT4.LOG in the local Domino data directory every time the agent runs.

Sub Initialize

     Dim agentLog As New NotesLog("Agent 4 log")

     Call agentLog.OpenFileLog("AGENT4.LOG")

     Call agentLog.LogAction("Agent 4 invoked")

End Sub


Example: Making a Domino newsletter

This agent example creates a newsletter consisting of links to all the documents in the current database and mails the newsletter to the Marketing group.

Sub Initialize

     Dim session As New NotesSession

     Dim db As NotesDatabase

     Dim dc As NotesDocumentCollection

     Dim news As NotesNewsletter

     Dim doc As NotesDocument

     Set db = session.CurrentDatabase

     Call db.UpdateFTIndex(True)

     Set dc = db.FTSearch("Acme", 0)

     Set news = New NotesNewsletter(dc)

     news.SubjectItemName = "Subject"

     news.DoSubject = True

     Set doc = news.FormatMsgWithDoclinks(db)

     Call doc.Send(True, "Marketing")

End Sub


Examples: Managers property

  1. This script displays the name of every manager in the current database. For example, it might display "Helen Anda," "LocalDomainServers," and "Sales."

    2. Dim session As New NotesSession

    Dim db As NotesDatabase

    Set db = session.CurrentDatabase

    Forall m In db.Managers

      Messagebox( m )

    End Forall
  2. This action script prompts a user for a suggestion and then mails the suggestion to the managers of the current database.

    3. Sub Click(Source As Button)

      Dim session As New NotesSession

      Dim db As NotesDatabase

      Dim doc As NotesDocument

      Set db = session.CurrentDatabase

      Set doc = New NotesDocument( db )

      doc.Form = "Memo"

      doc.Subject = "Suggestion for "+ db.Title

      doc.Body = Inputbox$ _

      ( "Please enter your suggestion: ", db.Title )

      Call doc.Send( False, db.Managers )

    End Sub
  3. An application consists of two databases that work together. This script finds all the managers of the first database and assigns them manager access to the second database. (The script must have manager access to the second database in order for the script to run).

    4. Dim db1 As New NotesDatabase _

    ( "Key West", "cserv\datadict.nsf" )

    Dim db2 As New NotesDatabase _

    ( "Key West", "cserv\calltrak.nsf" )

    Forall mgr In db1.Managers

      Call db2.GrantAccess( mgr, ACLLEVEL_MANAGER )

    End Forall


Example: MaxLevel property

This script changes the maximum level of navigation for a view navigator, then displays the result..

Dim session As New NotesSession

Dim db As NotesDatabase

Dim view As NotesView

Dim nav As NotesViewNavigator

Set db = session.CurrentDatabase

Set view = db.GetView("By Category")

Set nav = view.CreateViewNavFromCategory("Products")

If nav.MaxLevel<> = 9 Then

nav.MaxLevel = 9

End If

Messagebox nav.MaxLevel


Example: MaxRows property

This agent limits the result set to what the user specifies, defaulting to the complete result set.

Uselsx "*LSXODBC"

%INCLUDE "lsconst.lss"

Sub Initialize

     Dim con As New ODBCConnection

     Dim qry As New ODBCQuery

     Dim result As New ODBCResultSet

     Dim firstName As String

     Dim lastName As String

     Dim msg As String

     Set qry.Connection = con

     Set result.Query = qry

     con.ConnectTo("ATDB")

     qry.SQL = "SELECT * FROM STUDENTS ORDER BY LASTNAME"

     result.Execute

     If Messagebox("", MB_YESNO, _

     "Do you want the whole result set?") = IDYES Then

          maxRows = 0

     Else

          maxRows = Inputbox("How many rows?", _

                             "MaxRows", "50")

          If maxRows = "" Then maxRows = 0

     End If

     result.MaxRows = maxRows

     msg = "Student names:" & Chr(10)

     Do

          result.NextRow

          firstName = result.GetValue("FIRSTNAME", firstName)

          lastName = result.GetValue("LASTNAME", lastName)

          msg = msg & Chr(10) & firstName & " " & lastName

     Loop Until result.IsEndOfData

     Messagebox msg,, "Student Names"

     con.Disconnect

End Sub


Example: MaxSize property

This following script prints the size, quota, and maximum size of the current database.

Dim db As NotesDatabase

Dim session As New NotesSession

Set db = session.CurrentDatabase

Print "Database size is: ", db.Size

Print "Database Quota is: ", db.SizeQuota

Print "Database Maximum Size is: ", db.MaxSize, "K"


Examples: Name property

  1. This script gets the name of the first entry of the access control list of the current database, and puts it into the variable entryName. For example, Name might return "-Default-."

    2. Dim session As New NotesSession

    Dim db As NotesDatabase

    Dim acl As NotesACL

    Dim entry As NotesACLEntry

    Dim entryName As String

    Set db = session.CurrentDatabase

    Set acl = db.ACL

    Set entry = acl.GetFirstEntry

    entryName = entry.Name
  2. This button script prompts the user for an access level, and then places the names of entries with that access level into the People field on the current document. For example, if the user enters "Designer," and Sharron Karasic and Brandon Giles have Designer access to the current database, the script places "Sharron Karasic" and "Brandon Giles" into the People field. If the user enters an invalid access level, or if there are no entries at that access level, the People field remains unchanged.

    3. The GetLevelConstant sub converts a string, such as "Designer," into the corresponding constant, such as ACLLEVEL_DESIGNER.

    Sub Click(Source As Button)

      Dim workspace As New NotesUIWorkspace

      Dim uidoc As NotesUIDocument

      Dim session As New NotesSession

      Dim db As NotesDatabase

      Dim acl As NotesACL

      Dim entry As NotesACLEntry

      Dim levelString As String

      Dim levelConstant As Integer

      Set uidoc = workspace.CurrentDocument

      Set db = session.CurrentDatabase

      Set acl = db.ACL

      levelString = Inputbox$( "What level?" )

      ' function call to convert the string

      ' into an ACLLEVEL constant

      levelConstant = GetLevelConstant( levelString )

      ' go through all the entries in the ACL

      Set entry = acl.GetFirstEntry

      While Not ( entry Is Nothing )

        ' if the entry has the level that the user chose

        If ( entry.Level = levelConstant ) Then

          ' append the entry's name to the text list

          ' in the People field

          Call uidoc.FieldAppendText _

          ( "People", entry.Name & "; " )

        End If

        Set entry = acl.GetNextEntry( entry )

      Wend

      ' refresh current document so that

      ' text list displays nicely

      Call uidoc.Refresh

    End Sub

    Function GetLevelConstant( desiredLevel As String )

      Dim levelConstant As Integer

      Select Case desiredLevel

      Case "Manager":

        levelConstant = ACLLEVEL_MANAGER

      Case "Designer":

        levelConstant = ACLLEVEL_DESIGNER

      Case "Editor":

        levelConstant = ACLLEVEL_EDITOR

      Case "Author":

        levelConstant = ACLLEVEL_AUTHOR

      Case "Reader":

        levelConstant = ACLLEVEL_READER

      Case "No Access":

        levelConstant = ACLLEVEL_NOACCESS

      End Select

      GetLevelConstant = levelConstant

    End Function


Example: Name property

This script gets the name of the current agent. For example, if this script is a part of the Token agent, the Name property returns "Token."

Dim session As New NotesSession

Dim agent As NotesAgent

Dim n As String

Set agent = session.CurrentAgent

n = agent.Name


Example: Name property

This LotusScript agent gets the name of a database directory.

Sub Initialize

    Dim dbdir As New NotesDbDirectory _

    (Inputbox("Enter name", "Directory name"))

    If dbdir.Name = "" Then

        Messagebox "Local",, "Database directory"

    Else

        Messagebox dbdir.Name,, "Database directory"

    End If

End Sub

This Visual Basic code gets the name of a database directory.

Private Sub DbName_Click()

Dim s As New NotesSession

s.Initialize

Dim dir As NotesDbDirectory

Set dir = s.GetDbDirectory(Text1)

If dir.name = "" Then

    MsgBox "Local", , "Directory name"

Else

    MsgBox dir.name, , "Directory name"

End If

End Sub


Examples: Name property

This script displays the name of an outline.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim outline As NotesOutline

Set db = session.CurrentDatabase

Set outline = db.GetOutline("MyOutline")

Messagebox outline.Name


Example: Name property

This script displays the names of all the forms in a database.

Dim session As New NotesSession

Dim db As NotesDatabase

Set db = session.CurrentDatabase

formCount = 0

msgString = ""

Forall form In db.Forms

     formCount = formCount + 1

     msgString = msgString & Chr(10) & "     " & form.Name

End Forall

Messagebox "This database has " & _

formCount & " forms:" & msgString


Example: Name property

This script gets the name of an item. The Name property returns "Body."

Dim doc As NotesDocument

Dim item As NotesItem

Dim itemName As String

'...set value of doc...

Set item = doc.GetFirstItem( "Body" )

itemName = item.Name


Example: Name property

This script gets the name of the "City picture" object in the Body item of a document, and puts it into objectName. The Name property returns "City picture."

Dim doc As NotesDocument

Dim rtitem As Variant

Dim object As NotesEmbeddedObject

Dim objectName As String

'...set value of doc...

Set rtitem = doc.GetFirstItem( "Body" )

If ( rtitem.Type = RICHTEXT ) Then

  Set object = rtitem.GetEmbeddedObject( "City picture" )

  objectName = object.Name

End If


Example: Name property

This script gets a view's name and puts it into viewName. The Name property returns "By Category."

Dim session As New NotesSession

Dim db As NotesDatabase

Dim view As NotesView

Dim viewName As String

Set db = session.CurrentDatabase

Set view = db.GetView( "By Category" )

viewName = view.Name


Example: NameObject property

This Visual Basic code adds the common name of every ACL entry to a list box.

Private Sub ACLEntryName_Click()

Dim s As New NotesSession

s.Initialize

Dim dir As NotesDbDirectory

Dim db As NotesDatabase

Dim acl As NotesACL

Dim acle As NotesACLEntry

Set dir = s.GetDbDirectory("")

Set db = dir.OpenDatabase("Web test")

Set acl = db.acl

Set acle = acl.GetFirstEntry

While Not (acle Is Nothing)

    List1.AddItem (acle.NameObject.Common)

    Set acle = acl.GetNextEntry(acle)

Wend

End Sub


Example: NextRow method

This agent accesses all rows of a result set starting from the first row. The first NextRow method after the Execute method positions you at the first row. Each subsequent NextRow gets the next row in the data set. IsEndOfData detects that the last row was processed.

Uselsx "*LSXODBC"

Sub Initialize

     Dim con As New ODBCConnection

     Dim qry As New ODBCQuery

     Dim result As New ODBCResultSet

     Dim firstName As String

     Dim lastName As String

     Dim msg As String

     Set qry.Connection = con

     Set result.Query = qry

     con.ConnectTo("ATDB")

     qry.SQL = "SELECT * FROM STUDENTS ORDER BY LASTNAME"

     result.Execute

     msg = "Student names:" & Chr(10)

     Do

          result.NextRow

          firstName = result.GetValue("FIRSTNAME", firstName)

          lastName = result.GetValue("LASTNAME", lastName)

          msg = msg & Chr(10) & firstName & " " & lastName

     Loop Until result.IsEndOfData

     Messagebox msg,, "Student Names"

     result.Close(DB_CLOSE)

     con.Disconnect

End Sub


Example: NoteID property

This script gets the NoteID of doc and places it into the nid variable.

Dim doc As NotesDocument

Dim nid As String

'...set value of doc...

nid = doc.NoteID


Example: NoteID property

This script displays the NoteID of the view entry Volkswagen in the By Category view.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim view As NotesView

Dim entry As NotesViewEntry

Set db = session.CurrentDatabase

Set view = db.GetView("By Category")

Set entry = view.GetEntryByKey("Volkswagen")

Messagebox entry.NoteID


Examples: NotesACL class

  1. This script gets the ACL for a database on server Maputo, and uses the GetFirstEntry method to find the first entry in its ACL.

    2. Dim db As New NotesDatabase("Maputo", "notefile\none.nsf")

    Dim acl As NotesACL

    Dim entry As NotesACLEntry

    Set acl = db.ACL

    Set entry = acl.GetFirstEntry
  2. This script gets the ACL for the current database, and uses GetEntry to find Dyetra Jones in its ACL.

    3. Dim session As New NotesSession

    Dim db As NotesDatabase

    Dim acl As NotesACL

    Dim entry As NotesACLEntry

    Set db = session.CurrentDatabase

    Set acl = db.ACL

    Set entry = acl.GetEntry( "Dyetra Jones" )


Examples: NotesACLEntry class

  1. This script uses New to give Shelly McPhail Editor access to a database.

    2. Dim db As New NotesDatabase _

    ( "Quito", "data\discuss.nsf" )

    Dim acl As NotesACL

    Set acl = db.ACL

    Dim person As New NotesACLEntry _

    ( acl, "Shelly McPhail", ACLLEVEL_EDITOR )

    Call acl.Save
  2. This script uses New to give Bill Ehrhardt Designer access to a database. It also creates a new role, called Project Leader, and enables the role for Bill.

    3. Dim db As New NotesDatabase _

    ( "Quito", "data\discuss.nsf" )

    Dim acl As NotesACL

    Set acl = db.ACL

    Call acl.AddRole( "Project Leader" )

    Dim leader As New NotesACLEntry _

    ( acl, "Bill Ehrhardt", ACLLEVEL_DESIGNER )

    Call leader.EnableRole( "Project Leader" )

    Call acl.Save
  3. This script uses New to add the "Terminations" group to the current database, and assign it No Access.

    4. Dim session As New NotesSession

    Dim db As NotesDatabase

    Dim acl As NotesACL

    Dim entry As NotesACLEntry

    Set db = session.CurrentDatabase

    If Not ( db.IsOpen ) Then

      Call db.Open( "", "" )

    End If

    Set acl = db.ACL

    Set entry = New NotesACLEntry _

    ( acl, "Terminations", ACLLEVEL_NOACCESS )

    Call acl.Save


Examples: NotesAgent class

  1. This script finds the Cleansing Agent in the current database, and assigns it to the agent object. It uses the Agents property defined in NotesDatabase.

    2. Dim session As New NotesSession

    Dim db As NotesDatabase

    Dim agent As NotesAgent

    Set db = session.CurrentDatabase

    Forall a In db.Agents

      If ( a.Name = "Cleansing Agent" ) Then

        Set agent = a

        Exit Forall

      End If

    End Forall
  2. This agent script gets the current agent, puts it into the agent object, and then gets its name. For example, if this script runs as part of the Ticket agent, the Name property returns "Ticket."

    3. Dim session As New NotesSession

    Dim agent As NotesAgent

    Dim n As String

    Set agent = session.CurrentAgent

    n = agent.Name


Example: NotesBuildVersion property

This script displays the Notes build version in which a selected document resides.

Dim session As New NotesSession

Messagebox session.NotesBuildVersion


Example: NotesColor property

This example builds a rich-text item and sets styles so that part of the text is red and part is dark magenta.

Sub Initialize

     Dim session As New NotesSession

     Dim db As NotesDatabase

     Set db = session.CurrentDatabase

     Dim doc As New NotesDocument(db)

     Call doc.AppendItemValue("From", session.UserName)

     Call doc.AppendItemValue("Subject",  _

                              "Meeting time changed")

     Dim richStyle As NotesRichTextStyle

     Set richStyle = session.CreateRichTextStyle

     Dim richText As New NotesRichTextItem(doc, "Body")

     richStyle.NotesColor = COLOR_RED

     Call richText.AppendStyle(richStyle)

     Call richText.AppendText("The meeting is at ")

     richStyle.NotesColor = COLOR_DARK_MAGENTA

     Call richText.AppendStyle(richStyle)

     Call richText.AppendText("3:00")

     richStyle.NotesColor = COLOR_RED

     Call richText.AppendStyle(richStyle)

     Call richText.AppendText(" not 2:00")

     Call doc.Save(True, False)

End Sub


Examples: NotesDatabase class

  1. This script creates a NotesDatabase object called db and uses New to assign a database to it. The database is located at the top level of the Domino data directory on server Barcelona. If the database exists, New automatically opens the database, so you can access the database's properties and methods immediately.

    2. Dim db As NotesDatabase

    Set db = New NotesDatabase( "Barcelona", "plan.nsf" )

    Messagebox( db.Title )
  2. This script achieves the same result as the example above, but declares a NotesDatabase object db and calls New in one line.

    3. Dim db As New NotesDatabase( "Barcelona", "plan.nsf" )

    Messagebox( db.Title )
  3. This script uses IsOpen to test if the database QUACK.NSF exists on the current computer. If not, it uses the Create method to create a new database on disk.

    4. Dim db As New NotesDatabase( "", "quack.nsf" )

    If db.IsOpen Then

      Messagebox( "The database quack.nsf already exists." )

    Else

      Messagebox( "Creating the database quack.nsf...")

      Call db.Create( "", "", True )

      db.Title = "Ducks of North America"

    End If
  4. This script calls New while declaring the db object. It assigns db to a database located in a directory called SOUNDS, inside the directory SENSES. (The SENSES directory, in turn, is located inside the Domino data directory.)

    5. If this script runs on a workstation, it opens the CLUNK.NSF database on the local computer.

    If this script runs on the server Khartoum, it opens the CLUNK.NSF database on the server Khartoum.

    Dim db As New NotesDatabase _

    ( "", "senses\sounds\clunk.nsf" )
    On a Macintosh, if CLUNK.NSF is located in the Sounds folder, inside the Senses folder, the script looks like this:

    Dim db As New NotesDatabase _

    ( "", "senses:sounds:clunk.nsf" )
  5. This script gives Brian Flokka Editor access to the current database. The current database is the one in which the script is running. Using the CurrentDatabase property in NotesSession avoids having to use file names in scripts and makes scripts easily portable from one database to another.

    6. Dim session As New NotesSession
    Dim db As NotesDatabase
    Set db = session.CurrentDatabase
    Call db.GrantAccess( "Brian Flokka", ACLLEVEL_EDITOR )

  6. This script uses the Open method to check if a database exists on the server Asuncion. If the database exists, the script adds the Supervisors group to the ACL; if it doesn't exist, the script does nothing.

    7. Dim db As New NotesDatabase( "", "" )

    If db.Open( "Asuncion", "salesdocs.nsf" ) Then

      Call db.GrantAccess( "Supervisors", ACLLEVEL_EDITOR )

    End If
  7. This script shows how you can use New in combination with the OpenIfModified method to open a database only if it's been modified after a certain date. The script checks if SALESDOCS.NSF on the current server has been modified since yesterday--if so, it opens the database and compacts it.

    8. Dim db As New NotesDatabase( "", "" )

    Dim dateTime As New NotesDateTime( "Today" )

    Call dateTime.AdjustDay( -1 )

    If db.OpenIfModified( "", "salesdocs.nsf", dateTime ) Then

      Call db.Compact

    End If
  8. This script uses New in combination with the CreateFromTemplate method to create a new discussion database on the server Juno.

    9. Dim template As New NotesDatabase _

    ( "Anchorage", "discuss.ntf" )

    Dim brandNewDb As NotesDatabase

    Set brandNewDb = template.CreateFromTemplate _

    ( "Juno", "suggest.nsf", True )

    brandNewDb.Title = "Suggestions for Giving Campaign 1996"


Examples: NotesDateRange class

  1. This example sets the StartDateTime and EndDateTime properties of a NotesDateRange object, then displays the value of the Text property. The Text property, at this point, has the value: "08/18/96 01:36:22 PM - 08/19/96 01:36:22 PM."

    2. Dim dateRange As NotesDateRange

    Dim session As New NotesSession

    Dim dateTime1 As New NotesDateTime("08/18/96 01:36:22 PM")

    Dim dateTime2 As New NotesDateTime("08/19/96 01:36:22 PM")

    Set dateRange = session.CreateDateRange()

    Set dateRange.StartDateTime = dateTime1

    Set dateRange.EndDateTime = dateTime2

    Messagebox dateRange.Text
  2. This example writes a value to the Text property, then displays the LocalTime property of the StartDateTime and EndDateTime properties (which are NotesDateTime objects). The LocalTime properties, at this point, are "08/18/96 01:36:22 PM" and "08/19/96 01:36:22 PM."

    3. Dim dateRange As NotesDateRange

    Dim session As New NotesSession

    Set dateRange = session.CreateDateRange()

    dateRange.Text= _

    "08/18/96 01:36:22 PM - 08/19/96 01:36:22 PM"

    Messagebox dateRange.StartDateTime.LocalTime

    Messagebox dateRange.EndDateTime.LocalTime
  3. This example sets a value for a NotesDateRange object, then changes the NotesDateTime object that the EndDateTime property is based on. This implicitly changes the EndDateTime property.

    4. Dim dateRange As NotesDateRange

    Dim session As New NotesSession

    Dim dateTime1 As New NotesDateTime("Today")

    Dim dateTime2 As New NotesDateTime("Tomorrow")

    Set dateRange = session.CreateDateRange()

    Set dateRange.StartDateTime = dateTime1

    Set dateRange.EndDateTime = dateTime2

    Messagebox dateRange.Text

    Call dateTime2.AdjustDay(1)

    Messagebox dateRange.Text


Examples: NotesDateTime class

  1. This script creates a new NotesDateTime object that represents August 18, 1995 at 1:36:22 PM.

    2. Dim dateTime As NotesDateTime

    Set dateTime = New NotesDateTime( "08/18/95 01:36:22 PM" )

    Messagebox( dateTime.LocalTime )

    Messagebox( dateTime.GMTTime )
    • The script displays the LocalTime property in a dialog box: "08/18/95 01:36:22 PM."

    • The script displays the GMTTime property in a dialog box: "08/18/95 05:36:22 PM GMT," for example, if the script runs on a computer set to Eastern Standard Time and daylight savings time is observed; or "08/18/95 06:36:22 PM GMT" if the machine is set to Central Standard Time.

  2. This script creates a new NotesDateTime object identical to the one created in the script above.

    3. Dim dateTime As NotesDateTime

    Set dateTime = New NotesDateTime( "08-18-95 01:36:22 PM" )
  3. This script raises the error "Invalid Date" because it is unable to interpret the date format.

    4. Dim dateTime As NotesDateTime

    Set dateTime = New NotesDateTime( "August 18, 1995 01:36:22 PM" )
  4. This script creates a new NotesDateTime object that represents today's date and then displays a dialog box: for example, if today is August 21, 1995, the script displays "08/21/95" in a dialog box. The time component of the NotesDateTime object is not set.

    5. Dim dateTime As NotesDateTime

    Set dateTime = New NotesDateTime( "Today" )

    Messagebox( dateTime.LocalTime )
  5. This script creates a new NotesDateTime object set to the default date of November 30, 1899. The time component is not set.

    6. Dim dateTime As New NotesDateTime( "" )
  6. This script creates a new NotesDateTime object that represents April 16, 1996 at 20:30. The date component is stored as 08:30:00 PM.

    7. Dim dateTime As New NotesDateTime( "04/16/96 20:30" )

    Messagebox( dateTime.LSLocalTime )

    Messagebox( dateTime.GMTTime )
    • The script displays the LocalTime property in a dialog box: "04/16/96 08:30:00 PM."

    • The script displays the GMTTime property in a dialog box: "04/17/96 03:30:00 AM," for example, if the script runs on a computer set to Pacific Standard Time and daylight savings time is observed.

  7. This script creates two new NotesDateTime objects. The first represents January 15, 1997; the second represents January 15, 2000.

    8. Dim olderDateTime As New NotesDateTime( "01/15/97" )

    Dim newerDateTime As New NotesDateTime( "01/15/2000" )
  8. This script gets the value of the purgeDate item in a document and places it into a NotesDateTime object. The time zone setting of purgeDate is preserved. For example, if purgeDate has a value of 03/21/96 04:54:33 PM in Eastern Standard Time, the dateTime object represents 03/21/96 04:54:33 PM and its TimeZone property equals 5.

    9. Dim doc As NotesDocument

    Dim item As NotesItem

    Dim dateTime As NotesDateTime

    '...set value of doc...

    Set item = doc.GetFirstItem( "purgeDate" )

    Set dateTime = item.DateTimeValue
  9. This script also gets the value of the purgeDate item in a document, but places it into a variant called value. The LSLocalTime property is then set to value. The time zone setting of purgeDate is not preserved because the LotusScript variant value does not store it. Therefore, the dateTime object might represent 03/21/96 04:54:33, but its TimeZone property defaults to zero.

    10. Dim doc As NotesDocument

    Dim item As NotesItem

    Dim dateTime As NotesDateTime

    Dim value As Variant

    '...set value of doc...

    Set item = doc.GetFirstItem( "purgeDate" )

    Set dateTime = New NotesDateTime( "" )

    value = item.Values

    dateTime.LSLocalTime = value( 0 )
  10. This script sets the Schedule field of the first document in a collection to 09:00 PM. The same value is displayed for both the LocalTime and GMTTime properties. This is because the TimeZone property of the dateTime object defaults to zero when you do not specify both the time and the date in the dateTime parameter.

    11. Dim session As New NotesSession

    Dim db As NotesDatabase

    Dim dateTime As NotesDateTime

    Dim c As NotesDocumentCollection

    Dim doc As NotesDocument

    Dim scheditem As NotesItem

    Set db = session.CurrentDatabase

    Set dateTime = New NotesDateTime("09:00 PM")

    Set c = db.AllDocuments

    Set doc = c.GetFirstDocument()

    Set scheditem = doc.ReplaceItemValue("Schedule", dateTime)

    Call doc.save(True,True)

    Messagebox "Local time: " & dateTime.LocalTime & Chr(10)_

    & "GMT: " & dateTime.GMTTime


Example: NotesDbDirectory class

This LotusScript agent gets the first database on the server Snapper.

Sub Initialize

    Dim dbdir As New NotesDbDirectory("Snapper")

    Dim db As NotesDatabase

    Set db = dbdir.GetFirstDatabase(DATABASE)

    Msgbox db.Title, , db.FileName

End Sub

This Visual Basic code using COM gets the first database on the server Snapper.

Private Sub GetFirst_Click()

Dim s As New NotesSession

s.Initialize

Dim dir As NotesDbDirectory

Dim db As NotesDatabase

Set dir = s.GetDbDirectory("Snapper")

Set db = dir.GetFirstDatabase(NOTES_DATABASE)

MsgBox db.Title, , db.FileName

End Sub


Examples: NotesDocument class

  1. This script creates a new document in the current database, sets its Subject, and saves it. The document does not have a form associated with it; if a user opens the document in the user interface, Notes uses the default database form to display it.

    2. Dim session As New NotesSession

    Dim db As NotesDatabase

    Dim doc As NotesDocument

    Set db = session.CurrentDatabase

    Set doc = New NotesDocument ( db )

    doc.Subject = "New building"

    Call doc.Save( True, True )
  2. This script creates a new document in the current database, sets its Form and Body items, and saves it. If a user opens the document in the user interface, Notes uses the Status form to display it (if a form by that name exists in the current database).

    3. Dim session As New NotesSession

    Dim db As NotesDatabase

    Dim doc As NotesDocument

    Set db = session.CurrentDatabase

    Set doc = New NotesDocument ( db )

    doc.Form = "Status"

    doc.Body = "Client meeting postponed."

    Call doc.Save( True, True )
  3. This script creates and mails (but doesn't save) a new document from the current database. It sets the Form to "Memo" so that its recipient can read it as a mail memo. The document is encrypted for Susanna Coil.

    4. Dim session As New NotesSession

    Dim db As NotesDatabase

    Dim doc As NotesDocument

    Set db = session.CurrentDatabase

    Set doc = New NotesDocument( db )

    doc.Form = "Memo"

    doc.Subject = "Reminder!"

    doc.EncryptOnSend = True

    doc.Body = "A document awaits your approval in " _

    + db.Title

    Call doc.Send( False, "Susanna Coil" )


Examples: NotesDocumentCollection class

  1. This script uses the AllDocuments property in NotesDatabase to get a NotesDocumentCollection object representing all the documents in a database.

    2. Dim db As New NotesDatabase( "Ankara", "project.nsf" )

    Dim collection As NotesDocumentCollection

    Set collection = db.AllDocuments
  2. This script uses the Search method in NotesDatabase to get a NotesDocumentCollection object representing all of the documents created after March 14, 1995 whose Subject contains "lake."

    3. Dim db As New NotesDatabase( "Ankara", "project.nsf" )

    Dim dateTime As New NotesDateTime( "03/14/95" )

    Dim selection As String

    Dim collection As NotesDocumentCollection

    selection = "@Contains( Subject; ""lake"" )"

    Set collection = db.Search( selection, dateTime, 0 )


Examples: NotesEmbeddedObject class

The following two scripts demonstrate the differences between accessing objects using the EmbeddedObjects property in NotesDocument and NotesRichTextItem. Both scripts access the last document in the All Documents view of HILL.NSF on the server SanFrancisco.

The document contains the following:

  • A Word Pro embedded object called "Word Pro Document" in the Body item

  • A Microsoft Excel object link called "MS® Excel Worksheet" in the Body item

  • An Ami Pro embedded object, created in Notes Release 3, called "Ami Pro Document" in the Body item

  • A file attachment called "CASTLE.BMP" in the Body item

  • A Freelance Graphics embedded object called "Freelance Presentation" in the Description item

  • A 1-2-3 embedded object called "123 Worksheet" that is embedded on the form used to create the document, and has been subsequently activated and edited by a user

  1. This script uses the EmbeddedObjects property in NotesDocument, and displays the following:

    • "Word Pro Document"

    • "MS Excel Worksheet"

    • "Freelance Presentation"

    • "123 Worksheet"

      Dim db As NotesDatabase

      Dim view As NotesView

      Dim doc As NotesDocument

      Set db = New NotesDatabase( "SanFrancisco", "hill.nsf" )

      Set view = db.GetView( "All Documents" )

      Set doc = view.GetLastDocument

      Forall o In doc.EmbeddedObjects

        Messagebox( o.Name )

      End Forall
  2. This script uses the EmbeddedObjects property in NotesRichTextItem, and displays the following:

    • "Word Pro Document"

    • "MS Excel Worksheet"

    • "Ami Pro Document"

    • "" (represents the file attachment CASTLE.BMP, whose Name property is an empty string).

      Dim db As NotesDatabase

      Dim view As NotesView

      Dim doc As NotesDocument

      Dim rtitem As Variant

      Set db = New NotesDatabase( "SanFrancisco", "hill.nsf" )

      Set view = db.GetView( "All documents" )

      Set doc = view.GetLastDocument

      Set rtitem = doc.GetFirstItem( "Body" )

      If ( rtitem.Type = RICHTEXT ) Then

        Forall o In rtitem.EmbeddedObjects

          Messagebox( o.Name )

        End Forall

      End If


Example: NotesFont property

This example builds a rich-text item and sets styles so that part of the text is Helvetica and part is Courier.

Sub Initialize

     Dim session As New NotesSession

     Dim db As NotesDatabase

     Set db = session.CurrentDatabase

     Dim doc As New NotesDocument(db)

     Call doc.AppendItemValue("From", session.UserName)

     Call doc.AppendItemValue("Subject",  _

                              "Meeting time changed")

     Dim richStyle As NotesRichTextStyle

     Set richStyle = session.CreateRichTextStyle

     Dim richText As New NotesRichTextItem(doc, "Body")

     richStyle.NotesFont = FONT_HELV

     Call richText.AppendStyle(richStyle)

     Call richText.AppendText("The meeting is at ")

     richStyle.NotesFont = FONT_COURIER

     Call richText.AppendStyle(richStyle)

     Call richText.AppendText("3:00")

     richStyle.NotesFont = FONT_HELV

     Call richText.AppendStyle(richStyle)

     Call richText.AppendText(" not 2:00")

     Call doc.Save(True, False)

End Sub


Example: NotesForm class

This script displays the names of all the forms in the current database.

Sub Initialize

     Dim session As New NotesSession

     Dim db As NotesDatabase

     Set db = session.CurrentDatabase

     Forall form In db.Forms

          Messagebox form.Name

     End Forall

End Sub


Example: NotesInternational class

The following example examines three international settings and displays a setting's value if it deviates from what the script considers standard.

Dim session As New NotesSession

Dim international As NotesInternational

Dim exString As String

Set international = session.International

If international.CurrencySymbol <> "$" Then

     exString = "Currency symbol is " _

     & international.CurrencySymbol

End If

If international.DecimalSep <> "." Then

     If exString <> "" Then

          exString = exString & Chr(10)

     End If

     exString = exString & "Decimal separator is " _

     & international.DecimalSep

End If

If international.IsTime24Hour Then

     If exString <> "" Then

          exString = exString & Chr(10)

     End If

     exString = exString & "Time is 24-hour"

End If

If exString = "" Then

     Messagebox "No exceptions",, "Display exceptions"

Else

     Messagebox exString,, "Display exceptions"

End If


Examples: NotesItem class

  1. This script creates three new items in a document: a text item, a number item, and a date-time item.

    2. Dim doc As NotesDocument

    Dim textItem As NotesItem

    Dim numberItem As NotesItem

    Dim dateTimeItem As NotesItem

    '...set value of doc...

    Set textItem = New NotesItem _

    ( doc, "Region", "South America" )

    Set numberItem = New NotesItem( doc, "Earnings", 98 )

    Set dateTimeItem =  New NotesItem _

    ( doc, "LastAccessed", Today )

    Call doc.Save( True, True )
  2. This script creates a new text item in a document and gives it multiple values. The values in the text list are Bicycle, Train, and Foot.

    3. Dim doc As NotesDocument

    Dim textListItem As NotesItem

    Dim newValues( 0 To 2 ) As String

    '...set value of doc...

    newValues( 0 ) = "Bicycle"

    newValues( 1 ) = "Train"

    newValues( 2 ) = "Foot"

    Set textListItem = New NotesItem _

    ( doc, "Choices", newValues )

    Call doc.Save( True, True )
  3. This script creates a new Authors item in a document. The values in the item are Mariko Nakamura and Pierre Singer.

    4. Dim doc As NotesDocument

    '...set value of doc...

    Dim newValues( 1 To 2 ) As String

    newValues( 1 ) = "Mariko Nakamura"

    newValues( 2 ) = "Pierre Singer"

    Dim authorsItem As New NotesItem(doc, "docAuthors",  _

    newValues, AUTHORS)

    Call doc.Save( True, True )


Examples: NotesLog class

  1. This script opens a mail message for logging and mails it to Jimmy Ho.

    2. Sub Initialize

      Dim currentLog As New NotesLog( "Checkup Agent" )

      Call currentLog.OpenMailLog( "Jimmy Ho",  _

      "Log for Checkup Agent" )

      Call currentLog.Close

    End Sub
    The mail message contains the following in the Body item:

    04/26/95 12:19:40 PM Checkup Agent starting

  2. This script opens a mail message for logging. It then logs one action for each document found in the current database, and mails the message.

    3. Sub Initialize

      Dim currentLog As New NotesLog( "Cleansing Agent" )

      Call currentLog.OpenMailLog( "Jimmy Ho",  _

      "Log for Cleansing Agent" )

      Dim session As New NotesSession

      Dim db As NotesDatabase

      Dim collection As NotesDocumentCollection

      Dim doc As NotesDocument

      Set db = session.CurrentDatabase

      Set collection = db.AllDocuments

      Set doc = collection.GetFirstDocument

      count% = 0

      While Not ( doc Is Nothing )

        count% = count% + 1

        Call currentLog.LogAction( "Processed document " + _

        Cstr( count% ) )

        Set doc = collection.GetNextDocument( doc )

      Wend

      Call currentLog.Close

    End Sub
    If there are four documents in the database, Jimmy Ho receives a mail memo that contains the following in the Body item:

    04/26/95 10:50:17 AM Cleansing Agent starting
    04/26/95 10:50:17 AM Processed document 1
    04/26/95 10:50:17 AM Processed document 2
    04/26/95 10:50:17 AM Processed document 3
    04/26/95 10:50:17 AM Processed document 4

  1. This script opens a Notes database for logging. If it can't find the "All by Category" view in the current database, it logs an error.

    2. Sub Initialize

      viewName$ = "All by Category"

      Dim session As New NotesSession

      Dim db As NotesDatabase

      Dim view As NotesView

      Dim agent As NotesAgent

      Dim currentLog As NotesLog

      Set db = session.CurrentDatabase

      Set agent = session.CurrentAgent

      Set currentLog = New NotesLog _

      ( agent.Name + " Agent in " + _

      db.Title + " on " + db.Server )

      Call currentLog.OpenNotesLog( "", "agentlog.nsf" )

      Set view = db.GetView( viewName$ )

      If view Is Nothing Then

        Call currentLog.LogError _

        ( 0, "Unable to find view " + viewName$ )

      End If

      Call currentLog.Close

    End Sub
    One new document gets created in the AGENTLOG.NSF database, containing the log name, the current date and time, the error code, and error description.


Examples: NotesMIMEEntity class

  1. The following example gets a Body item as a MIME entity and displays the properties of the main (or only) part

    2. Sub Initialize

        Dim s As New NotesSession

        Dim db As NotesDatabase

        Dim dc As NotesDocumentCollection

        Dim doc As NotesDocument

        Dim body As NotesItem

        Dim mime As NotesMIMEEntity

        Dim m As String

        Set db = s.CurrentDatabase

        s.ConvertMime = False ' Do not convert MIME to rich text|

        Set dc = db.UnprocessedDocuments

        Set doc = dc.GetFirstDocument

        While Not(doc Is Nothing)

            Set body = doc.GetFirstItem("Body")

            If body.Type = MIME_PART Then

            Set mime = body.GetMimeEntity

            m = "Content type:" & Chr(9) & mime.ContentType _

            & Chr(13) & "Content subtype:" & Chr(9) _

            & mime.ContentSubtype & Chr(13) & "Headers" _

            & Chr(13) & mime.Headers & Chr(13) _

            & "Content" & Chr(13) & mime.ContentAsText

            Messagebox m,, doc.GetItemValue("Subject")(0)

            Else

            Messagebox "Not MIME",, doc.GetItemValue("Subject")(0)

            End If

            Set doc = dc.GetNextDocument(doc)

        Wend

    End Sub
  2. The following example walks through all the parts of a multipart MIME entity and displays their properties.

    3. Sub Initialize

        Dim s As New NotesSession

        Dim db As NotesDatabase

        Dim dc As NotesDocumentCollection

        Dim doc As NotesDocument

        Dim body As NotesItem

        Dim mime As NotesMIMEEntity, mime2 As NotesMIMEEntity

        Dim subj As String

        Set db = s.CurrentDatabase

        s.ConvertMime = False ' Do not convert MIME to rich text|

        Set dc = db.UnprocessedDocuments

        Set doc = dc.GetFirstDocument

        While Not(doc Is Nothing)

            Set body = doc.GetFirstItem("Body")

            If body.Type = MIME_PART Then

                Set mime = body.GetMimeEntity

                While Not(mime Is Nothing)

                 Call mimeit(mime, doc.GetItemValue("Subject")(0))

                 Set mime2 = mime.GetFirstChildEntity

                 If mime2 Is Nothing Then

                   Set mime2 = mime.GetNextSibling

                 End If

                 If mime2 Is Nothing Then

                    Set mime2 = mime.GetParentEntity

                    If Not(mime2 Is Nothing) Then

                       Set mime2 = mime2.GetNextSibling

                    End If

                 End If

                    Set mime = mime2

                Wend

            Else

                Messagebox "Not MIME",, doc.GetItemValue("Subject")(0)

            End If

            Set doc = dc.GetNextDocument(doc)

        Wend

    End Sub

    Sub mimeit (mime As NotesMIMEEntity, subj As String)

        Dim m As String

        m = "Content type:" & Chr(9) & mime.ContentType _

        & Chr(13) & "Content subtype:" & Chr(9) _

        & mime.ContentSubtype & Chr(13) _

        & "Headers" & Chr(13) & mime.Headers & Chr(13) _

        & "Content" & Chr(13) & mime.ContentAsText

        Messagebox m,, subj

    End Sub


Example: NotesName class

This example displays the properties for a NotesName object unless the property is empty.

Dim session As New NotesSession

Dim userName As New NotesName(session.UserName)

If userName.IsHierarchical Then

     Messagebox userName.Canonical,, "Canonical name"

     Messagebox userName.Abbreviated,, "Abbreviated name"

End If

Messagebox userName.Common,, "Common name"

If userName.Country <> "" Then

     Messagebox userName.Country,, "Country"

End If

If userName.Organization <> "" Then

     Messagebox userName.Organization,, "Organization"

End If

If userName.OrgUnit1 <> "" Then

     Messagebox userName.OrgUnit1,, "OrgUnit1"

End If

If userName.OrgUnit2 <> "" Then

     Messagebox userName.OrgUnit2,, "OrgUnit2"

End If

If userName.OrgUnit3 <> "" Then

     Messagebox userName.OrgUnit3,, "OrgUnit3"

End If

If userName.OrgUnit4 <> "" Then

     Messagebox userName.OrgUnit4,, "OrgUnit4"

End If

If userName.Given <> "" Then

     Messagebox userName.Given,, "Given"

End If

If userName.Surname <> "" Then

     Messagebox userName.Surname,, "Surname"

End If

If userName.Initials <> "" Then

     Messagebox userName.Initials,, "Initials"

End If

If userName.Generation <> "" Then

     Messagebox userName.Generation,, "Generation"

End If

If userName.ADMD <> "" Then

     Messagebox userName.ADMD,, "ADMD"

End If

If userName.PRMD <> "" Then

     Messagebox userName.PRMD,, "PRMD"

End If

If userName.Keyword <> "" Then

     Messagebox userName.Keyword,, "Keyword"

End If


Examples: NotesNewsletter class

  1. This script performs a full-text search on the current database and creates a newsletter with a link to each matching document. The newsletter gets mailed to Sharron Karasic.

    2. Dim session As New NotesSession

    Dim db As NotesDatabase

    Dim collection As NotesDocumentCollection

    Dim newsletter As NotesNewsletter

    Dim doc As NotesDocument

    Set db = session.CurrentDatabase

    Set collection = db.FTSearch( "arachnid", 15 )

    If ( collection.Count > 0 ) Then

      Set newsletter = New NotesNewsletter( collection )

      Set doc = newsletter.FormatMsgWithDoclinks( db )

      doc.Form = "Memo"

      doc.Subject = "The Arachnid Report"

      Call doc.Send( False, "Sharron Karasic" )

    End If
  2. This view action script uses the UnprocessedDocuments property in NotesDatabase to get a collection of documents currently selected in the view. If there are five or fewer selected documents, the script creates a rendering of each document in the collection and saves it in the current user's mail database.

    3. Sub Click(Source As Button)

      Dim session As New NotesSession

      Dim db As NotesDatabase

      Dim mailDb As NotesDatabase

      Dim collection As NotesDocumentCollection

      Dim newsletter As NotesNewsletter

      Dim doc As NotesDocument

      Set db = session.CurrentDatabase

      Set mailDb = New NotesDatabase( "", "" )

      Call mailDb.OpenMail

      Set collection = db.UnprocessedDocuments

      Set newsletter = New NotesNewsletter( collection )

      If ( collection.Count > 5 ) Then

        Messagebox( "Please select five documents or fewer" )

      Else

        For j = 1 To collection.Count

          Set doc = newsletter.FormatDocument( mailDb, j )

          Call doc.Save( True, True )

      Next

      End If

    End Sub


Examples: NotesOutline class

This script creates a new outline called MyOutline and displays its name.

Sub Click(Source As Button)

     Dim session As New NotesSession

     Dim db As NotesDatabase

     Dim outline As NotesOutline

     Set db = session.CurrentDatabase

     Set outline = db.CreateOutline("MyOutline")

     Messagebox outline.Name

End Sub


Examples: NotesRegistration class

  1. This example shows both RegisterNewUser and AddUserToAddressbook methods used together. The AddUserToAddressBook method is only needed if you call RegisterNewUser with UpdateAddressBook = False.

    2. Dim newreg As New notesregistration

    Dim session As New notessession

    Dim db As notesdatabase

    Set db = session.currentdatabase

    Dim certidfile As String, org As String, _

             certpw As String

    org = "TestOrg"

    length% = 2

    certidfile = "c:\notes\data\Redsox.id"

    certpw = "pw"

    newreg.RegistrationLog = "certlog.nsf"

    newreg.IDType = ID_HIERARCHICAL

    newreg.Expiration = Datevalue("December 31, 1998")

    newreg.MinPasswordLength = length%

    newreg.IsNorthAmerican = True

    newreg.CertifierIDFile = certidfile

    newreg.RegistrationServer = db.Server

    newreg.OrgUnit = org

    newreg.CreateMailDb = True

    newreg.StoreIDInAddressBook = True

    newreg.Updateaddressbook = False

    MailFile = "Mail\toleary.nsf"

    Firstname = "Troy"

    Lastname = "O'Leary"

    RegServer = "Fenway/Redsox"

    comment = "Comment contents"

    IDfile = "toleary.id"

    userPassword "password"

    middleinit = "M"

    location = "office"

Call newreg.RegisterNewUser( Lastname, IDfile, _

    RegServer, Firstname, middleinit, certpw, _

    location, comment, MailFile, "", userPassword, _

    NOTES_FULL_CLIENT )

Call newreg.AddUserToAddressbook("c:\notes\" & IDfile, _

    Firstname & " " & Lastname, Lastname, userPassword, _

    Firstname, middleinit, RegServer, MailFile, _

    fwdaddress, location, comment )


Examples: NotesRichTextItem class

  1. This script creates a new rich-text item called ProjectDescription and adds a text value to it.

    2. Dim doc As NotesDocument

    Dim rtitem As NotesRichTextItem

    '...set value of doc...

    Set rtitem = New NotesRichTextItem _

    ( doc, "ProjectDescription" )

    Call rtitem.AppendText _

    ( "Cartoon book for children ages 9-12" )

    Call doc.Save( False, True )
  2. This script achieves the same result as the one above, but also copies the newly created rich-text item to a second document. Because NotesRichTextItem inherits from NotesItem, the rtitem object can use methods defined in both NotesRichTextItem (such as AppendText) and NotesItem (such as CopyItemToDocument).

    3. Dim docA As NotesDocument

    Dim docB As NotesDocument

    Dim rtitem As NotesRichTextItem

    '...set values of docA and docB...

    Set rtitem = New NotesRichTextItem _

    ( docA, "ProjectDescription" )

    Call rtitem.AppendText _

    ( "Cartoon book for children ages 9-12" )

    Call rtitem.CopyItemToDocument( docB, "" )

    Call docA.Save( False, True )

    Call docB.Save( False, True )
  3. This script creates a new NotesRichTextItem called "Body" on a mail memo. It uses the AppendDocLink method to place a link to the current document in the Body, and the Send method to mail the memo to Frank Glennel.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim memo As NotesDocument

Dim rtitem As NotesRichTextItem

Set db = session.CurrentDatabase

'...set value of doc...

Set memo = New NotesDocument( db )

Set rtitem = New NotesRichTextItem( memo, "Body" )

Call rtitem.AppendDocLink( doc, db.Title )

memo.Subject = "Here's a link to the document"

Call memo.Send( False, "Frank Glennel" )
  1. This script gets an existing rich-text item called ProjectDescription and adds a carriage return and a text value to it. Notice how rtitem is declared a variant, since the GetFirstItem method returns a NotesItem that may or may not be a NotesRichTextItem. Since Type is a property defined in NotesItem, you can use it with a NotesRichTextItem as well. The script tests the variant to see if it is rich-text; if so, it uses NotesRichTextItem methods on the variant. For more information, see the GetFirstItem method in NotesDocument.

Dim doc As NotesDocument

Dim rtitem As Variant

'...set value of doc...

Set rtitem = doc.GetFirstItem( "ProjectDescription" )

If rtitem.Type = RICHTEXT Then

  Call rtitem.AddNewLine( 1 )

  Call rtitem.AppendText _

  ( "Book is 64 pages, full color." )

End If

Call doc.Save( False, True )


Example: NotesRichTextParagraphStyle class

This script creates a new rich-text item and appends a paragraph style.

Dim session As New NotesSession

Dim db As NotesDatabase

Set db = session.CurrentDatabase

Dim doc As New NotesDocument(db)

Call doc.AppendItemValue("From", session.Username)

Call doc.AppendItemValue("Subject", _

"Meeting agenda")

Dim rtpStyle As NotesRichTextParagraphStyle

Set rtpStyle = session.CreateRichTextParagraphStyle

Dim richText As New NotesRichTextItem(doc, "Body"

rtpStyle.FirstLineLeftMargin = RULER_ONE_INCH

Call richText.AppendText("Where are we now?")

Call richText.AppendParagraphStyle(rtpStyle)

Messagebox "First line, left margin: " & rtpStyle.FirstLineLeftMargin

Call doc.Save(True, False)


Example: NotesRichTextStyle class

This example builds a rich-text item using text solicited from the user. Style attributes are set so that the text appears in 14-point Courier.

Sub Initialize

     Dim session As New NotesSession

     Dim db As NotesDatabase

     Set db = session.CurrentDatabase

     Dim doc As New NotesDocument(db)

     Call doc.AppendItemValue _

     ("From", session.UserName)

     Call doc.AppendItemValue _

     ("Subject", Inputbox("Subject?"))

     Call doc.AppendItemValue _

     ("Categories", Inputbox("Category?"))

     Dim richStyle As NotesRichTextStyle

     Set richStyle = session.CreateRichTextStyle

     richStyle.NotesFont = FONT_COURIER

     richStyle.FontSize = 14

     Dim richText As New NotesRichTextItem(doc, "Body")

     Call richText.AppendStyle(richStyle)

     newPara = Inputbox _

     ("Paragraph of text for ""Body"" item")

     firstPara = True

     While newPara <> ""

          If firstPara Then

               firstPara = False

          Else

               Call richText.AddNewLine(2)

          End If

          Call richText.AppendText(newPara)

          newPara = Inputbox _

          ("Paragraph of text for ""Body"" item")

     Wend

     Call doc.Save(True, False)

End Sub


Example: NotesSession class

This script creates a new NotesSession and uses it to access the current database (the database in which the script is running). This technique avoids hard-coding the file names of databases into scripts.

Dim session As New NotesSession

Dim db As NotesDatabase

Set db = session.CurrentDatabase

If ( db.IsOpen ) Then

  Print db.Title

Else

  Call db.Open( "", "" )

  Print db.Title

End If


Examples: NotesTimer class

This example maintains and reports the elapsed time since a document is opened, unless the user disables the timer. The example has several scripts.

  1. These declarations are in the (Globals) (Declarations) script for the form. The variable elapsedTime is used by various objects on the form. The NotesTimer object elapsedTimer must be in effect during the execution of a number of scripts on the form.

    2. Dim elapsedTime As Integer

    Dim elapsedTimer As NotesTimer

    %INCLUDE "lsconst.lss"
  2. When a document based on this form opens, the NotesTimer object is created with an interval of 1 second. An event handler for the Alarm event of the object is established.

    3. Sub Postopen(Source As Notesuidocument)

         Set elapsedTimer = New NotesTimer(1, _

         "Elapsed time since opening document")

         elapsedTime = 0

         On Event Alarm From elapsedTimer _

         Call elapsedTimerHandler

    End Sub
  3. This user sub is the event handler specified in the On Event statement above. It simply increments the global variable by 1 each time it is called.

    4. Sub elapsedTimerHandler(Source As NotesTimer)

         elapsedTime = elapsedTime + 1

    End Sub
  4. This script is for a button on the form. The script displays the time accumulated in the global variable.

    5. Sub Click(Source As Button)

         Dim etime As Integer

         Dim minutes As Integer

         etime = elapsedTime

         If etime < 60 Then

              Messagebox etime & " second(s)",, _

              "Elapsed time since opening document"

         Else

              minutes = 0

              Do While etime > 59

                   minutes = minutes + 1

                   etime = etime - 60

              Loop

              Messagebox minutes & " minute(s), " _

              & etime & " second(s)",, _

              "Elapsed time since opening document"

         End If

    End Sub
  5. This example queries the Enabled property of the NotesTimer object and toggles it if the user wants to.

    6. Sub Click(Source As Button)

         If elapsedTimer.Enabled Then

              If Messagebox _

              ("Do you want to disable the timer?", _

              MB_YESNO + MB_ICONQUESTION, _

              "Elapsed timer is enabled") = IDYES Then

                   elapsedTimer.Enabled = False

              End If

         Else

              If Messagebox _

              ("Do you want to enable the timer?", _

              MB_YESNO + MB_ICONQUESTION, _

              "Elapsed timer is disabled") = IDYES Then

                   elapsedTimer.Enabled = True

              End If

         End If

    End Sub


Example: NotesUIDatabase class

This example tracks the number of document deletions that occur while a database is open.

(Declarations)

Dim deleteCount As Integer

Sub Postopen(Source As Notesuidatabase)

     deleteCount = 0

End Sub

Sub Querydocumentdelete(Source As Notesuidatabase, Continue As Variant)

     If Continue Then

          deleteCount = deleteCount + Source.Documents.Count

     End If

End Sub

Sub Querydocumentundelete(Source As Notesuidatabase, Continue As Variant)

     If Continue Then

          deleteCount = deleteCount - Source.Documents.Count

     End If

End Sub

Sub Postdocumentdelete(Source As Notesuidatabase)

     Messagebox Source.Documents.Count _

     & " deleted or marked for deletion"

End Sub

Sub Queryclose(Source As Notesuidatabase, Continue As Variant)

     Messagebox deleteCount & " documents deleted",, _

     "Net deletions"

End Sub


Example: NotesUIDocument class

This script uses a NotesUIWorkspace to get the current document. It then uses the FieldGetText method to print the Subject field of the current document.

Dim workspace As New NotesUIWorkspace

Dim uidoc As NotesUIDocument

Set uidoc = workspace.CurrentDocument

Messagebox( uidoc.FieldGetText( "Subject" ) )


Examples: NotesUIView class

  1. This example examines the current view as it is opened and queries the user if the view is a calendar view.

    2. Sub Queryopen(Source As Notesuiview, Continue As Variant)

        Dim view As NotesView

        Set view = Source.View

        If view.IsCalendar Then

          If Messagebox("Do you want to continue?", _

            MB_ICONQUESTION,"Calendar view") = IDNO

          Then

            Continue = False

          End If

        End If

    End Sub
  2. This view action button prints the current view.

    3. Dim wks As New NotesUIworkspace

    Dim View As NotesUIView

    Set View = wks.currentview

    Call view.print()


Example: NotesUIWorkspace class

This script uses a NotesUIWorkspace to get the current document. It then uses the FieldGetText method to print the Subject field of the current document.

Dim workspace As New NotesUIWorkspace

Dim uidoc As NotesUIDocument

Set uidoc = workspace.CurrentDocument

Messagebox( uidoc.FieldGetText( "Subject" ) )


Example: NotesVersion property

This form action script gets the release of Notes currently running and puts it in the variable version. For example, if the script runs on a workstation with Notes Release 4, the NotesVersion property returns "Notes Release 4." If the script runs on a server with Notes Release 4.1, the NotesVersion property returns "Notes Release 4.1."

Dim session As New NotesSession

Dim version As String

version = session.NotesVersion


Examples: NotesView class

  1. This script finds the By Category view in a mail database and then gets the first document in the view.

    2. Dim db As New NotesDatabase( "Havana","mail\cbanner.nsf" )

    Dim view As NotesView

    Dim doc As NotesDocument

    Set view = db.GetView( "By Category" )

    Set doc = view.GetFirstDocument
  2. This script calls GetView using a view's alias instead of its full name.

    3. Dim db As New NotesDatabase( "Havana", "calendar.nsf" )

    Dim view As NotesView

    Set view = db.GetView( "CategoryView" )
  3. You can access hidden views the same way as any other view; include the parentheses in the view name. This script gets a hidden view in a calendar database.

    4. Dim db As New NotesDatabase( "Havana", "calendar.nsf" )

    Dim view As NotesView

    Set view = db.GetView( "(Days by Key)" )
  4. This finds the default view of a database. It uses the Views property from the NotesDatabase class and the IsDefault property from the NotesView class.

    5. Dim db As New NotesDatabase( "Havana", "calendar.nsf" )

    Dim view As NotesView

    Forall v In db.Views

      If v.IsDefaultView Then

        Set view = v

        Exit Forall

      End If

    End Forall


Examples: NotesViewColumn class

  1. This script displays the position number and title of every column in the By Category view of the current database.

    2. Dim session As New NotesSession

    Dim db As NotesDatabase

    Dim view As NotesView

    Set db = session.CurrentDatabase

    Set view = db.GetView( "By Category" )

    Forall c In view.Columns

      Messagebox( c.Position & " " & c.Title )

    End Forall

    For example, if the By Category view has five columns, two of which have titles and three of which are untitled, the script displays five dialog boxes with the following values:
    • 1

    • 2

    • 3 Date

    • 4

    • 5 Topic

  2. This script gets the third column in the By Category view of the current database. The array returned by the Columns property starts at element 0, so view.Columns( 2 ) corresponds to the third column in the view.

    3. Dim session As New NotesSession

    Dim db As NotesDatabase

    Dim view As NotesView

    Dim column As NotesViewColumn

    Set db = session.CurrentDatabase

    Set view = db.GetView( "By Category" )

    Set column = view.Columns( 2 )
  3. This script finds the first sorted column in the By Author view of the YAHOO.NSF database on the current machine and assigns it to the column object.

    4. Dim db As New NotesDatabase( "", "yahoo.nsf" )

    Dim view As NotesView

    Dim column As NotesViewColumn

    Set view = db.GetView( "By Author" )

    Forall c In view.Columns

      If c.IsSorted Then

        Set column = c

        Exit Forall

      End If

    End Forall


Examples: NotesViewEntry class

  1. This script finds the current view entry and prints the number of its immediate children.

    2. Dim session As New NotesSession

    Dim db As NotesDatabase

    Dim view As NotesView

    Dim entry As NotesViewEntry

    Set db = session.CurrentDatabase

    Set view = db.GetView("By Category")

    Set entry = view.GetEntryByKey("Inventory")

    Messagebox entry.ChildCount
  2. This script finds the document associated with the view entry.

    3. Dim session As New NotesSession

    Dim db As NotesDatabase

    Dim view As NotesView

    Dim entry As NotesViewEntry

    Dim doc As NotesDocument

    Set db = session.CurrentDatabase

    Set view = db.GetView("By Category")

    Set entry = view.GetEntryByKey("Product Specifications")

    Set doc = entry.Document
  3. This script displays the universal ID of the Parts document which is associated with the current view entry, Cars.

    4. Dim session As New NotesSession

    Dim db As NotesDatabase

    Dim view As NotesView

    Dim entry As NotesViewEntry

    Set db = session.CurrentDatabase

    Set view = db.GetView("By Category")

    Set entry = view.GetEntryByKey("Cars")


Examples: NotesViewEntryCollection class

  1. This script gets a collection of view entries under the category Baseball in the By Category view and uses the PutAllInFolder method to place them in the Sports folder.

    2. Dim session As New NotesSession

    Dim db As NotesDatabase

    Dim view As NotesView

    Dim vc As NotesViewEntryCollection

    Set db = session.CurrentDatabase

    Set view = db.GetView("By Category")

    Set vc = view.GetAllEntriesByKey("Baseball")

    Call vc.PutAllInFolder("Sports")
  2. This script uses the GetNthEntry method to retrieve the third entry from the view entry collection.

    3. Dim session As New NotesSession

    Dim db As NotesDatabase

    Dim view As NotesView

    Dim entry As NotesViewEntry

    Dim vc As NotesViewEntryCollection

    Set db = session.CurrentDatabase

    Set view = db.GetView("By Category")

    Set vc = view.GetAllEntriesByKey("Books")

    Set entry = vc.GetNthEntry(3)


Examples: NotesViewNavigator class

  1. This script displays the universal ID of the last document entry in a view navigator.

    2. Dim session As New NotesSession

    Dim db As NotesDatabase

    Dim view As NotesView

    Dim entry As NotesViewEntry

    Dim nav As NotesViewNavigator

    Set db = session.CurrentDatabase

    Set view = db.GetView("By Category")

    Set nav = view.CreateViewNav

    Set entry = nav.GetLastDocument

    Messagebox "UNID: " & entry.UniversalID
  2. This script returns the next to last entry in the view navigator and puts the associated document in a folder.

    3. Dim session As New NotesSession

    Dim db As NotesDatabase

    Dim view As NotesView

    Dim entryA As NotesViewEntry

    Dim entryB As NotesViewEntry

    Dim nav As NotesViewNavigator

    Dim doc As NotesDocument

    Set db = session.CurrentDatabase

    Set view = db.GetView("By Category")

    Set nav = view.CreateViewNav

    Set entryA = nav.GetLastDocument

    Set entryB = nav.GetPrevDocument(entryA)

    Set doc = entryB.Document

    Call doc.PutInFolder("My Favorites")
  3. This script displays the universal ID of the user-specified entry in a view navigator.

    4. Dim session As New NotesSession

    Dim db As NotesDatabase

    Dim view As NotesView

    Dim entry As NotesViewEntry

    Dim nav As NotesViewNavigator

    Dim doc As NotesDocument

    Set db = session.CurrentDatabase

    Set view = db.GetView("By Category")

    Set nav = view.CreateViewNav

    Set entry = nav.GetPos(Inputbox$("Entry position: "), ".")

    Messagebox "Entry UNID: " & entry.UniversalID


Examples: NumActions property

  1. This script gets the number of actions logged and places it into the variable count. Here, NumActions returns 2.

    2. Dim currentLog As New NotesLog( "Database log" )

    Dim count As Integer

    Call currentLog.OpenNotesLog( "", "agentlog.nsf" )

    Call currentLog.LogAction( "This is action number one" )

    Call currentLog.LogAction( "This is action number two" )

    count = currentLog.NumActions
  2. This agent script logs actions and errors to a database, and sends an e-mail memo to the agent's owner letting her know how many actions the script logged. For example, if Susanna Tallan owns the Thread Agent and it logs five actions, the script sends a mail memo to Susanna with "Thread Agent logged 5 actions" in the Subject.

    3. Sub Initialize

      Dim session As New NotesSession

      Dim agent As NotesAgent

      Dim db As NotesDatabase

      Dim doc As NotesDocument

      Set agent = session.CurrentAgent

      Set db = session.CurrentDatabase

      Dim currentLog As New NotesLog _

      ( "Log for " & agent.Name )

      Call currentLog.OpenNotesLog( "", "agentlog.nsf" )

      '...log some actions and errors...

      Set doc = New NotesDocument( db )

      doc.Form = "Memo"

      doc.Subject = agent.Name & " logged " & _

      currentLog.NumActions & " actions"

      Call doc.Send( False, agent.Owner )

    End Sub


Example: NumberAttrib property

This script displays the attributes for numerica values in a column.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim view As NotesView

Dim column As notesViewColumn

Set db = session.CurrentDatabase

Set view = db.Getview("Align")

Set column = view.Columns(0)

Messagebox (column.NumberAttrib)


Example: NumberDigits property

This script displays the number of decimal places for numeric values in a column.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim view As NotesView

Dim column As notesViewColumn

Set db = session.CurrentDatabase

Set view = db.Getview("Align")

Set column = view.Columns(0)

Messagebox (column.NumberDigits)


Example: NumberFormat property

This script displays a constant integer for the numeric values in a column.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim view As NotesView

Dim column As notesViewColumn

Set db = session.CurrentDatabase

Set view = db.Getview("Align")

Set column = view.Columns(0)

Messagebox (column.NumberFormatProperty)


Example: NumColumns method

This agent executes an SQL query and displays the number of columns in the result set. See FieldName for another example.

Uselsx "*LSXODBC"

Sub Initialize

     Dim con As New ODBCConnection

     Dim qry As New ODBCQuery

     Dim result As New ODBCResultSet

     Set qry.Connection = con

     Set result.Query = qry

     con.ConnectTo("ATDB")

     qry.SQL = "SELECT * FROM STUDENTS"

     result.Execute

     Messagebox result.NumColumns,,  _

        "Number of columns in result set"

     result.Close(DB_CLOSE)

     con.Disconnect

End Sub


Examples: NumErrors property

  1. This script gets the number of errors logged and places it into the variable count. Here, NumErrors returns 3.

    2. Dim currentLog As New NotesLog( "Database log" )

    Dim count As Integer

    Call currentLog.OpenNotesLog( "", "agentlog.nsf" )

    Call currentLog.LogError( 1, "This is error number one" )

    Call currentLog.LogError( 2, "This is error number two" )

    Call currentLog.LogError _

    ( 3, "This is error number three" )

    count = currentLog.NumErrors
  2. This agent script logs actions and errors to a database, and sends an e-mail memo to the agent's owner letting her know how many errors the script logged. For example, if Susanna Tallan owns the Thread Agent and it logs two errors, the script sends a mail memo to Susanna with "Thread Agent logged 2 errors" in the Subject.

    3. Sub Initialize

      Dim session As New NotesSession

      Dim agent As NotesAgent

      Dim db As NotesDatabase

      Dim doc As NotesDocument

      Set agent = session.CurrentAgent

      Set db = session.CurrentDatabase

      Dim currentLog As New NotesLog _

      ( "Log for " & agent.Name )

      Call currentLog.OpenNotesLog( "", "agentlog.nsf" )

      '...log some actions and errors...

      Set doc = New NotesDocument( db )

      doc.Form = "Memo"

      doc.Subject = agent.Name & " logged " &  _

      currentLog.NumErrors & " errors"

      Call doc.Send( False, agent.Owner )

    End Sub


Example: NumParameters method

This example shows two actions (the Click subs) that set and get parameters for the SQL query in the Postopen sub. Although the query in the Postopen sub contains exactly two parameters, these actions work for a variable number of parameters. The actions use NumParameters for loop control in processing the parameters.

Uselsx "*LSXODBC"

Dim con As ODBCConnection

Dim qry As ODBCQuery

Dim result As ODBCResultSet

Sub Postopen(Source As Notesuidocument)

     Set con = New ODBCConnection

     Set qry = New ODBCQuery

     Set result = New ODBCResultSet

     Set qry.Connection = con

     Set result.Query = qry

     con.ConnectTo("ATDB")

     qry.SQL = "SELECT * FROM STUDENTS WHERE " & _

     "LASTNAME = ?lastName? AND FIRSTNAME = ?firstName?"

End Sub

Sub Click(Source As Button)

     Dim inputParameter As String

     For i = 1 To result.NumParameters

          inputParameter = Inputbox$(result.GetParameterName(i), _

          "Parameter " & i)

          Call result.SetParameter(i, _

           "'" & inputParameter & "'")

     Next

End Sub

Sub Click(Source As Button)

     Dim msg As String

     msg = "Parameter name = parameter value" & Chr(10)

     For i = 1 To result.NumParameters

          msg = msg & Chr(10) & result.GetParameterName(i) _

          & " = " & result.GetParameter(i)

     Next

     Messagebox msg,, "Parameters"

End Sub

Sub Queryclose(Source As Notesuidocument, Continue As Variant)

     result.Close(DB_CLOSE)

     con.Disconnect

End Sub


Example: NumRows method

This agent uses a For loop, NumRows, and CurrentRow to access all rows in a result set. The LastRow that precedes the loop is essential; otherwise, NumRows is not correct.

Uselsx "*LSXODBC"

Sub Initialize

     Dim con As New ODBCConnection

     Dim qry As New ODBCQuery

     Dim result As New ODBCResultSet

     Dim firstName As String

     Dim lastName As String

     Dim msg As String

     Set qry.Connection = con

     Set result.Query = qry

     con.ConnectTo("ATDB")

     qry.SQL = "SELECT * FROM STUDENTS ORDER BY LASTNAME"

     result.Execute

     result.LastRow

     msg = "Student names:" & Chr(10)

     For  i = 1 To result.NumRows

          result.CurrentRow = i

          firstName = result.GetValue("FIRSTNAME", firstName)

          lastName = result.GetValue("LASTNAME", lastName)

          msg = msg & Chr(10) & firstName & " " & lastName

     Next

     Messagebox msg,, "Student Names"

     result.Close(DB_CLOSE)

     con.Disconnect

End Sub


Example: ODBCConnection class

This agent declares a new ODBCConnection object and connects to a user-specified data source.

Uselsx "*LSXODBC"

Sub Initialize

     Dim con As New ODBCConnection

     con.ConnectTo(Inputbox("ODBC data source name", "DSN"))

     While Not con.IsConnected

          dsn = Inputbox("ODBC data source name", _

          "Connection not made ...")

          If dsn = "" Then Exit Sub

          con.ConnectTo(dsn)

     Wend

     Messagebox "Connected to " & con.DataSourceName,, _

     "Connection made ..."

     con.Disconnect

End Sub


Example: ODBCQuery class

The following agent creates a query that retrieves all the rows in the STUDENTS table of the ATDB data source.

Uselsx "*LSXODBC"

Sub Initialize

     Dim con As New ODBCConnection

     Dim qry As New ODBCQuery

     Dim result As New ODBCResultSet

     Dim firstName As String

     Dim lastName As String

     Dim msg As String

     Set qry.Connection = con

     Set result.Query = qry

     con.ConnectTo("ATDB")

     qry.SQL = "SELECT * FROM STUDENTS"

     result.Execute

     msg = "Student names:" & Chr(10)

     If result.IsResultSetAvailable Then

          Do

               result.NextRow

               firstName = result.GetValue("FIRSTNAME", _

                                           firstName)

               lastName = result.GetValue("LASTNAME", _

                                          lastName)

               msg = msg & Chr(10) & firstName & " " & _

               lastName

          Loop Until result.IsEndOfData

          Messagebox msg,, "Student Names"

          result.Close(DB_CLOSE)

     Else

          Messagebox "Cannot get result set for STUDENTS"

          Exit Sub

     End If

     con.Disconnect

End Sub


Example: ODBCResultSet class

This agent executes an SQL query. The agent also displays some of the ODBCResultSet properties after the Execute method and after all the rows in the result set are accessed.

Uselsx "*LSXODBC"

Dim con As ODBCConnection

Dim qry As ODBCQuery

Dim result As ODBCResultSet

Dim firstName As String

Dim lastName As String

Dim msg As String

Sub Initialize

     Set con = New ODBCConnection

     Set qry = New ODBCQuery

     Set result = New ODBCResultSet

     Set qry.Connection = con

     Set result.Query = qry

     con.ConnectTo("ATDB")

     qry.SQL = "SELECT * FROM STUDENTS"

     If Not result.Execute Then

          Messagebox result.GetExtendedErrorMessage,, _

                     result.GetErrorMessage

          Exit Sub

     End If

     REM Display result set properties after Execute

     Call DisplayResultSetProperties

     msg = "Student names:" & Chr(10)

     Do

          result.NextRow

          firstName = result.GetValue("FIRSTNAME", firstName)

          lastName = result.GetValue("LASTNAME", lastName)

          msg = msg & Chr(10) & firstName & " " & lastName

     Loop Until result.IsEndOfData

     Messagebox msg,, "Student Names"

     REM Display result set properties after processing

     REM result set

     Call DisplayResultSetProperties

     result.Close(DB_CLOSE)

     con.Disconnect

End Sub

Sub DisplayResultSetProperties

     If result.IsResultSetAvailable Then

          If result.NumRows = DB_ROWSUNKNOWN Then

               rows$ = "Not determined yet"

          Else

               rows$ = Cstr(result.NumRows)

          End If

          Messagebox _

          "NumColumns = " & result.NumColumns & Chr(10) & _

          "NumRows = " & rows$ & Chr(10) &  _

          "IsBeginOfData = " & result.IsBeginOfData & _

          Chr(10) & "IsEndOfData = " & result.IsEndOfData & _

          Chr(10) & "CurrentRow = " & result.CurrentRow,,  _

          "Result set properties"

     Else

          Messagebox "Result set not available",,  _

          "No result set"

     End If

End Sub


Examples: Open method

  1. This script opens the first database found on the current computer (local machine if the script runs on a workstation, server if the script runs on a server).

    2. Dim directory As New NotesDbDirectory( "" )

    Dim db As NotesDatabase

    Set db = directory.GetFirstDatabase( DATABASE )

    Call db.Open( "", "" )
  2. This LotusScript agent opens each database in the AddressBooks property of NotesSession. The NotesDatabase variable, book, must be treated as a Variant to be used as an AddressBooks element.

    3. Sub Initialize

        Dim s As New NotesSession

        Forall book In s.AddressBooks

            book.open "", ""

            Messagebox book.Title,, "Address book"

        End Forall

    End Sub
  3. This Visual Basic code opens each database in the AddressBooks property of NotesSession. The NotesDatabase variable, book, must be treated as a Variant to be used as an AddressBooks element.

    4. Private Sub Open_Click()

    Dim s As New NotesSession

    s.Initialize

    For Each book In s.AddressBooks

        book.Open

        List1.AddItem (book.Title)

    Next

    End Sub
  4. This script opens the SALES.NSF database on the server HongKong.

    5. Dim db As New NotesDatabase( "", "" )

    Call db.Open( "HongKong", "sales.nsf" )
  5. This script tests for the existence of a specific database. You have a script that archives documents from one database to an archive database. If the archive database doesn't exist, the script creates it; otherwise, the script opens it.

    6. Dim archiveDb As New NotesDatabase( "", "" )

    Dim originalDb As New NotesDatabase( "", "product.nsf" )

    Dim collection As NotesDocumentCollection

    Dim doc As NotesDocument

    If ( Not ( archiveDb.Open( "", "archive\" &  _

    originalDb.FileName ) ) ) Then

      Set archiveDb = originalDb.CreateCopy( "", "archive\"  _

      & originalDb.FileName )

      Call archiveDb.GrantAccess( "Ivan Ash", ACL_MANAGER )

    End If


Example: OpenAgentLog method

This code, which must executed in an agent, opens the agent's log for output and writes an action message to it.

Dim agentLog As New NotesLog("Agent log")

Call agentLog.OpenAgentLog

Call agentLog.LogAction("Action one")

Call agentLog.Close


Example: OpenByReplicaID method

This script attempts to open a database on the server Moscow.

Dim db As New NotesDatabase( "", "" )

If db.OpenByReplicaID( "Moscow", "85255FA900747B84" ) Then

  Print( db.Title & " was successfully opened" )

Else

  Print( "Unable to open database" )

End If


Example: OpenDatabase method

This script opens the database PLAN.NSF in the NEW directory on the server Algiers. The database is opened to the All by Category view, scrolled to the category called Current.

Sub Click(Source As Button)

  Dim workspace As New NotesUIWorkspace

  Call workspace.OpenDatabase _

  ( "Algiers", "new\plan", "All by Category", _

  "Current", False, False )

End Sub


Examples: OpenDatabase method

This Visual Basic code opens a database in the local Domino or Notes directory.

Private Sub OpenDatabase_Click()

On Error GoTo errorHandler

Dim s As New NotesSession

s.Initialize

Dim dir As NotesDbDirectory

Dim db As NotesDatabase

Set dir = s.GetDbDirectory("")

Set db = dir.OpenDatabase("quack.nsf")

MsgBox db.Title, , db.FilePath

Exit Sub

errorHandler:

If Err.Number = ERR_SYS_FILE_NOT_FOUND Then

    MsgBox "File not found in Notes directory", , "No quack"

Else

    MsgBox Err.Description, , Err.Number

End If

End Sub


Examples: OpenDatabaseByReplicaID method

This Visual Basic code opens a database on a server that is a replica of a local database.

Private Sub OpenByRepID_Click()

On Error GoTo errorHandler

Dim s As New NotesSession

s.Initialize

Dim dir As NotesDbDirectory

Dim db As NotesDatabase

Dim repID As String

Set dir = s.GetDbDirectory("")

Set db = dir.OpenDatabase("quack.nsf")

repID = db.ReplicaID

Set dir = s.GetDbDirectory("Snapper")

Set db = dir.OpenDatabaseByReplicaID(repID)

MsgBox db.Title, , db.FilePath

Exit Sub

errorHandler:

MsgBox Err.Description, , Err.Number

End Sub


Examples: OpenDatabaseIfModified

This Visual Basic code opens a local database if it has been modified since yesterday.

Private Sub OpenIfMod_Click()

On Error GoTo errorHandler

Dim s As New NotesSession

s.Initialize

Dim dir As NotesDbDirectory

Dim db As NotesDatabase

Dim dt As NotesDateTime

Set dt = s.CreateDateTime("Yesterday")

Set dir = s.GetDbDirectory("")

Set db = dir.OpenDatabaseIfModified("names.nsf", dt)

MsgBox db.Title, , db.FilePath

Exit Sub

errorHandler:

MsgBox Err.Description, , Hex(Err.Number)

End Sub


Example: OpenFileDialog method

This script displays the FileOpen dialog.

Dim workspace As New NotesUIWorkspace

Dim files As Variant

files = workspace.OpenFileDialog(True, "File List", _

        "", "c:")

Dim messagelist As String

Forall filelist In files

     messagelist = messagelist & filelist & Chr(10)

End Forall

Messagebox messagelist

For another example, please refer to the Alarms Dialog subform and the Calendar Profile form of the Mail template.


Examples: OpenFileLog method

  1. This script opens a file called LOG.TXT on the C drive. Each action and error gets appended to the file in a separate line without writing over the existing contents of the file.

    2. Dim currentLog As New NotesLog( "Script log" )

    Call currentLog.OpenFileLog( "c:\log.txt" )

    '...log some actions and errors...

    Call currentLog.Close
  2. This script opens a file called SCRIPTS.TXT in the LOGS directory of the C drive. The existing contents of the file are removed before actions and errors get added to the file.

    3. Dim currentLog As New NotesLog( "Script log" )

    currentLog.OverwriteFile = True

    Call currentLog.OpenFileLog( "c:\logs\scripts.txt" )

    '...log some actions and errors...

    Call currentLog.Close


Example: OpenFrameSet method

This script opens the specified frameset.

Dim workspace As New NotesUIWorkspace

Call workspace.OpenframeSet("myFrameset")


Example: OpenIfModified method

This script opens SALES.NSF on the server Paris, if the database has been modified since January 20, 1995.

Dim db As NotesDatabase

Dim dateTime As NotesDateTime

Set db = New NotesDatabase( "", "" )

Set dateTime = New NotesDateTime( "01/20/95" )

If ( db.OpenIfModified( "Paris", "sales.nsf", _

dateTime ) = True ) Then

  Messagebox( db.Title & " has been modified since " &  _

  dateTime.LocalTime )

Else

  Messagebox( "Database not modified since date specified." )

End If


Examples: Opening a database

  1. This example opens a database on the local machine, prints some of the properties of the database object, and closes the database. The user supplies the database name, which does not need the .NSF extension.

    2. Sub Initialize

         Dim db As New NotesDatabase _

         ("", Inputbox("File name"))

         Messagebox "Title: " & db.Title & Chr(10) _

         & "File name: " & db.FileName

         If db.IsOpen Then

              Messagebox "Closing database"

              db.Close

         Else

              Messagebox "Database is already closed"

         End If

    End Sub
  2. This example opens the current database.

    3. Sub Initialize

         Dim session As New NotesSession

         Dim db As NotesDatabase

         Set db = session.CurrentDatabase

         Messagebox "Title: " & db.Title & Chr(10) _

         & "File name: " & db.FileName

         If db.IsOpen Then msg = "open" Else msg = "closed"

         Messagebox "Database is " & msg

    End Sub
  3. This example shows that the database represented by the object db is closed until opened with the Open method.

    4. Sub Initialize

         Dim db As New NotesDatabase("", "")

         If db.IsOpen Then Messagebox "Is open" _

         Else Messagebox "Not open"

         Call db.Open("", Inputbox("File name?"))

         Messagebox "Title: " & db.Title & Chr(10) _

         & "File name: " & db.FileName

         If db.IsOpen Then Messagebox "Is open" _

         Else Messagebox "Not open"

         Call db.Close

         If db.IsOpen Then Messagebox "Is open" _

         Else Messagebox "Not open"

    End Sub
  4. This example traverses the local databases and opens the database whose title is specified by the user. The call to the Open method specifies null parameters because the database object already exists, having been returned by the GetFirstDatabase or GetNextDatabase method of NotesDbDirectory.

    5. Sub Initialize

         Dim dbdir As New NotesDbDirectory("")

         Dim db As NotesDatabase

         Dim dc As NotesDocumentCollection

         Dim doc As NotesDocument

         Set db = dbdir.GetFirstDatabase(DATABASE)

         dbTitle = Inputbox("Title of database?")

         While Not(db Is Nothing)

              If db.Title = dbTitle Then

                   Call db.Open("", "")

                   Set dc = db.AllDocuments

                   For j = 1 To dc.Count

                        Set doc = dc.GetNthDocument(j)

                        Messagebox "Subject: " & _

                        doc.Subject(0)

                   Next

                   Exit Sub

              End If

              Set db = dbdir.GetNextDatabase

         Wend

    End Sub
  5. This example opens the user's mail database.

    6. Sub Initialize

         Dim db As New NotesDatabase("", "")

         Call db.OpenMail

         If db.IsOpen Then

              Messagebox "Title: " & db.Title

         End If

    End Sub
  6. This example opens the database on the server Market whose replica ID is the same as the local database named SALES2.

    7. Sub Initialize

         Dim dbLocal As New NotesDatabase("", "SALES2")

         Dim dbRemote As New NotesDatabase("", "")

         If dbRemote.OpenByReplicaID("Market", _

         dbLocal.ReplicaID) Then

              Messagebox "Remote database opened OK"

         Else

              Messagebox "Remote database did not open"

         End If

    End Sub


Example: OpenMail method

This script assigns the current user's mail database to the db object. It displays the title and server of the database; for example, "Bob Moore's Mail on server Buenos Aires."

Dim db As New NotesDatabase( "", "" )

Call db.OpenMail

Messagebox( db.Title & " on server " & db.Server )


Examples: OpenMailDatabase method

This Visual Basic code opens the current user's database.

Private Sub OpenMail_Click()

Dim s As New NotesSession

s.Initialize

Dim dir As NotesDbDirectory

Dim db As NotesDatabase

Set dir = s.GetDbDirectory("")

Set db = dir.OpenMailDatabase

MsgBox db.Title & " on " & db.Server, , db.FilePath

End Sub


Examples: OpenMailLog method

  1. This agent script opens up a mail log. When the Close method is called, the mail memo gets sent to Thalia Ruben, with "Here's the Linguist Log" in the Subject. Actions and errors are in the Body of the memo.

Sub Initialize

  Dim currentLog As NotesLog

  Set currentLog = New NotesLog( "Linguist Log" )

  Call currentLog.OpenMailLog _

  ( "Thalia Ruben", "Here's the Linguist Log" )

  '...log some actions and errors...

  currentLog.Close

End Sub
  1. This agent script opens up a mail log that gets sent to the owner of the current agent. For example, if Susanna Tallan owns the Archiving Agent in the Project Histories database, the memo gets sent to Susanna, with "Archiving Agent in Project Histories" in the Subject. Actions and errors are in the Body of the memo.

    2. Sub Initialize

      Dim session As New NotesSession

      Dim db As NotesDatabase

      Dim agent As NotesAgent

      Set db = session.CurrentDatabase

      Set agent = session.CurrentAgent

      Dim currentLog As NotesLog

      Set currentLog = New NotesLog( agent.Name )

      Call currentLog.OpenMailLog _

      ( agent.Owner, agent.Name & " in " & db.Title )

      '...log some actions and errors...

      Call currentLog.Close

    End Sub


Examples: OpenNotesLog method

  1. This script opens AGENTLOG.NSF on the current computer. Each time an action or error is logged, a new document gets created in AGENTLOG.NSF.

    2. Dim currentLog As New NotesLog( "Database log" )

    Call currentLog.OpenNotesLog( "", "agentlog.nsf" )

    '...log some actions and errors...

    Call currentLog.Close
  2. This script searches the Notes data directory of the current computer to find the first database that inherits its design from the StdR4AgentLog template. When the script finds the database, it opens the database for logging.

Dim currentLog As NotesLog

Dim directory As NotesDbDirectory

Dim db As NotesDatabase

Dim done As Variant

Set currentLog = New NotesLog( "Database log" )

Set directory = New NotesDbDirectory( "" )

Set db = directory.GetFirstDatabase( DATABASE )

done = False

While Not ( db Is Nothing ) And Not done

  Call db.Open( "", "" )

  If ( db.DesignTemplateName = "StdR4AgentLog" ) Then

    done = True

  Else

    Set db = directory.GetNextDatabase

  End If

Wend

Call currentLog.OpenNotesLog( db.Server, db.FilePath )

'...log some actions and errors

Call currentLog.Close


Example: OpenPage method

This script opens the specified page in the current target frame.

Dim workspace As New NotesUIWorkspace

Call workspace.OpenPage("banner")


Example: OpenView method

This example triggers the QueryOpen and PostOpen events of the default view and changes to the "By Category" view.

Sub Postopen(Source As Notesuidatabase)

     Call Source.OpenView("By Category")

End Sub


Example: OpenWithFailover method

This script opens the SALES.NSF database on the server HongKong, or another server in the cluster.

Dim db As New NotesDatabase( "", "" )

Call db.OpenWithFailover( "HongKong", "sales.nsf" )


Examples: OverwriteFile property

  1. This script opens the LOG.TXT file for logging. The existing contents of the file are removed before any actions or errors are logged.

    2. Dim currentLog As New NotesLog( "Bump on a Log" )

    currentLog.OverwriteFile = True

    Call currentLog.OpenFileLog( "c:\log.txt" )

    '...log some actions and errors...

    Call currentLog.Close
  2. This agent script sets the OverwriteFile property to True if the agent last ran over seven days ago. If the agent last ran within the last seven days, it sets the OverwriteFile property to False.

    3. Sub Initialize

      Dim session As New NotesSession

      Dim db As NotesDatabase

      Dim agent As NotesAgent

      Dim collection As NotesDocumentCollection

      Dim doc As NotesDocument

      Dim currentLog As NotesLog

      Set db = session.CurrentDatabase

      Set agent = session.CurrentAgent

      Set collection = db.UnprocessedDocuments

      Set currentLog = New NotesLog( "Log for " & agent.Name )

      If ( ( Today - agent.LastRun ) > 7 ) Then

        currentLog.OverwriteFile = True

      Else

        currentLog.OverwriteFile = False

      End If

      Call currentLog.OpenFileLog( "c:\log.txt" )

      Call currentLog.LogAction _

      ( collection.Count & " docs being processed." )

      '....code to process each document...

      Call currentLog.Close

    End Sub


Examples: Owner property

  1. This script gets the name of the person who last modified the current agent. For example, if Yukiko Kitarmura/Tokyo/Production created the agent and then Mariko Ikebuchi/Tokyo/Production modified it, Mariko is considered to be the owner and the CurrentAgent property returns "CN=Mariko Ikebuchi/OU=Tokyo/O=Production."

    2. ' created by Yukiko Kitamura 11/28/95

    ' modified by Mariko Ikebuchi 12/17/95

    Dim session As New NotesSession

    Dim agent As NotesAgent

    Dim owner As String

    Set agent = session.CurrentAgent

    owner = agent.Owner
  2. This agent script goes through the unprocessed documents in the current database and logs an action for each document it processes. The script uses the Owner property to send the log to the owner of the agent.

    3. Sub Initialize

      Dim session As New NotesSession

      Dim agent As NotesAgent

      Dim db As NotesDatabase

      Dim collection As NotesDocumentCollection

      Dim currentLog As NotesLog

      Dim doc As NotesDocument

      Set agent = session.CurrentAgent

      Set db = session.CurrentDatabase

      Set collection = db.UnprocessedDocuments

      Set currentLog = New NotesLog( "Log for " & agent.Name )

      Call currentLog.OpenMailLog _

      ( agent.Owner, currentLog.ProgramName )

      For j = 1 To collection.Count

        Set doc = collection.GetFirstDocument()

        '...do whatever to the document...

        Call session.UpdateProcessedDoc( doc )

        Call currentLog.LogAction _

        ( "Processed " & doc.Subject( 0 ) )

      Next

      Call currentLog.Close

    End Sub
    For example, if the agent is called "Brandon's Agent," is owned by Brandon Herkle, and processes three documents, Brandon receives a mail memo with the subject "Log for Brandon's Agent" that has the following Body:

    08/10/95 04:35:02 PM Log for Brandon's Agent starting

    08/10/95 04:35:02 PM Processed Status Report for Anthony Pycha

    08/10/95 04:35:02 PM Processed Status Report for David Dinauer

    08/10/95 04:35:02 PM Processed Status Report for Mary Jo Mastro


Example: Parent property

This script finds the parent view of the view entry Cars and prints its universal ID.

Dim session As New NotesSession

Dim db As New NotesDatabase("","test.nsf")

Dim view As NotesView

Dim entry As NotesViewEntry

Dim parentView As NotesView

Set view = db.GetView("By Category")

Set entry = view.GetEntryByKey("Cars")

Set parentView = entry.Parent

Messagebox parentView.UniversalID


Example: Parent property

This script displays the universal ID of the parent view.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim view As NotesView

Dim vc As NotesViewEntryCollection

Dim parentV As NotesView

Set db = session.CurrentDatabase

Set view = db.GetView("By Category")

Set vc = view.GetAllEntriesByKey("Cars")

Set ParentV = vc.Parent

Messagebox "UNID: " & vc.ParentV.UniversalID


Example: Parent property

This script prints the title of the NotesDatabase object from which an ACL was retrieved (db), and title of the NotesDatabase object returned by the Parent property (parentDb). The titles are the same, because db and parentDb represent the same database, SOMEDOCs.NSF.

Dim db As New NotesDatabase( "", "somedocs.nsf" )

Dim parentDb As NotesDatabase

Dim acl As NotesACL

Set acl = db.ACL

Set parentDb = acl.Parent

Messagebox( db.Title )

Messagebox( parentDb.Title )


Example: Parent property

This script gets the parent access control list of an entry.

Dim db As New NotesDatabase( "", "parent.nsf" )

Dim acl As NotesACL

Dim parentACL As NotesACL

Dim entry As NotesACLEntry

Set acl = db.ACL

Set entry = acl.GetFirstEntry

Set parentACL = entry.Parent ' acl and parentACL are same


Examples: Parent property

This script gets the parent database of the current agent. For example, if this agent is running in the database WHOAMI.NSF, then the db object represents WHOAMI.NSF.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim agent As NotesAgent

Set agent = session.CurrentAgent

Set db = agent.Parent


Example: Parent property

This script gets the parent database of a collection. Since db and parentDb represent the same database, this script prints the title of MOTHER.NSF twice.

Dim db As New NotesDatabase( "", "mother.nsf" )

Dim parentDb As NotesDatabase

Dim collection As NotesDocumentCollection

Set collection = db.AllDocuments

Set parentDb = collection.Parent

Messagebox( db.Title )

Messagebox( parentDb.Title )


Examples: Parent property

This Visual Basic code displays the parent user name of a NotesDateRange object.

Private Sub DRParent_Click()

Dim s As New NotesSession

Dim dr As NotesDateRange

s.Initialize

Set dr = s.CreateDateRange

MsgBox dr.Parent.UserName, , "Parent user name"

End Sub


Examples: Parent property

This Visual Basic code displays the parent user name of a NotesDateTime object.

Private Sub DTParent_Click()

Dim s As New NotesSession

Dim dt As NotesDateTime

s.Initialize

Set dt = s.CreateDateTime(Today)

MsgBox dt.Parent.UserName, , "Parent user name"

End Sub


Example: Parent property

This script gets the current Notes session. It then displays the name of the platform on which the current session is running; for example, if the script is running in Windows®, the script might display "Windows/32."

Dim db As New NotesDatabase( "Tegucigalpa", "cbanner.nsf" )

Dim session As NotesSession

Set session = db.Parent

Messagebox( session.Platform )


Examples: Parent property

This Visual Basic code displays the parent user name of a NotesDbDirectory object.

Private Sub DbParent_Click()

Dim s As New NotesSession

s.Initialize

Dim db As NotesDbDirectory

Set db = s.GetDbDirectory("")

MsgBox db.Parent.UserName, , "Parent user name"

End Sub


Examples: Parent property

This Visual Basic code displays the parent title of a NotesForm object.

Private Sub FormParent_Click()

Dim s As New NotesSession

s.Initialize

Dim dir As NotesDbDirectory

Dim db As NotesDatabase

Dim form As NotesForm

Set dir = s.GetDbDirectory("")

Set db = dir.OpenDatabase("Web test")

Set form = db.GetForm("Main Document")

MsgBox form.Parent.Title, , "Title of parent"

End Sub


Examples: Parent property

This Visual Basic code displays the parent user name of a NotesInternational object.

Private Sub IntlParent_Click()

Dim s As New NotesSession

s.Initialize

Dim intl As NotesInternational

Set intl = s.International

MsgBox intl.Parent.UserName, , "Parent user name"

End Sub


Example: Parent property

This script gets the parent document of an item. Since doc and parentDoc represent the same document, the script prints the same NoteID twice.

Dim doc As NotesDocument

Dim parentDoc As NotesDocument

Dim item As NotesItem

Dim itemName As String

'...set value of doc...

Set item = doc.GetFirstItem( "Body" )

Set parentDoc = item.Parent

Messagebox( doc.NoteID )

Messagebox( parentDoc.NoteID )


Examples: Parent property

This Visual Basic code displays the parent user name of a NotesLog object.

Private Sub LogParent_Click()
Dim s As New NotesSession
s.Initialize
Dim log As NotesLog
Set log = s.CreateLog("Log 1")
MsgBox log.Parent.UserName, , "Parent user name"
End Sub


Examples: Parent property

This Visual Basic code displays the parent user name of a NotesName object.

Private Sub NameParent_Click()

Dim s As New NotesSession

s.Initialize

Dim name As NotesName

Set name = s.CreateName("Marie LeBlanc")

MsgBox name.Parent.UserName, , "Parent user name"

End Sub


Examples: Parent property

This Visual Basic code displays the parent user name of a NotesNewsletter object.

Private Sub NewsParent_Click()

Dim s As New NotesSession

s.Initialize

Dim news As NotesNewsletter

Dim dir As NotesDbDirectory

Dim db As NotesDatabase

Dim dc As NotesDocumentCollection

Set dir = s.GetDbDirectory("")

Set db = dir.OpenDatabase("Web test")

Set dc = db.AllDocuments

Set news = s.CreateNewsletter(dc)

MsgBox news.Parent.UserName, , "Parent user name"

End Sub


Examples: Parent property

This Visual Basic code displays the name of the parent view of a NotesViewColumn object.

Private Sub ViewColumnParent_Click()

Dim s As New NotesSession

s.Initialize

Dim dir As NotesDbDirectory

Dim db As NotesDatabase

Dim v As NotesView

Dim vc As NotesViewColumn

Set dir = s.GetDbDirectory("")

Set db = dir.OpenDatabase("Web test")

Set v = db.GetView("Main View")

Set vc = v.GetColumn(1)

MsgBox vc.Parent.Name, , "Name of parent view"

End Sub


Examples: Parent property

This Visual Basic code displays the parent name of a NotesOutlineEntry object.

Private Sub OutlineEntryParent_Click()

Dim s As New NotesSession

s.Initialize

Dim outline As NotesOutline

Dim oe As NotesOutlineEntry

Dim dir As NotesDbDirectory

Dim db As NotesDatabase

Set dir = s.GetDbDirectory("")

Set db = dir.OpenDatabase("Web test")

Set outline = db.GetOutline("Main Outline")

Set oe = outline.GetFirst

MsgBox oe.Parent.name, , "Parent name"

End Sub


Examples: Parent property

This Visual Basic code displays the UserName property of the parent session of a NotesRichTextStyle object.

Private Sub ParentRTS_Click()

Dim s As New NotesSession

Dim r As NotesRichTextStyle

s.Initialize

Set r = s.CreateRichTextStyle

MsgBox r.Parent.UserName, , "Parent user name"

End Sub


Example: Parent property

This script prints the title of the NotesDatabase object from which a view was retrieved (db), and the title of the NotesDatabase object returned by the Parent property (parentDb). The titles are the same, because db and parentDb represent the same database, FATHER.NSF.

Dim db As New NotesDatabase( "", "father.nsf" )

Dim parentDb As NotesDatabase

Dim view As NotesView

Set view = db.GetView( "By Category" )

Set parentDb = view.Parent

Messagebox( db.Title )

Messagebox( parentDb.Title )


Examples: ParentDatabase property

  1. This script prints the title of the NotesDatabase object from which a document was retrieved (db), and the title of the NotesDatabase object returned by the ParentDatabase property (parentDb). The titles are the same, because db and parentDb represent the same database, SOMEDOCS.NSF.

    2. Dim db As New NotesDatabase( "", "somedocs.nsf" )

    Dim parentDb As NotesDatabase

    Dim collection As NotesDocumentCollection

    Dim doc As NotesDocument

    Set collection = db.AllDocuments

    Set doc = collection.GetFirstDocument

    Set parentDb = doc.ParentDatabase

    Messagebox( db.Title )

    Messagebox( parentDb.Title )
  2. This script shows a function that takes a document and returns its parent document (or Nothing if the document has no parent). The function uses the ParentDatabase property to get db, a NotesDatabase object representing the database that doc is in. Once the script has db, it can call GetDocumentByUNID to find doc's parent.

    3. Function GetParentDocument( doc As NotesDocument )

      Dim db As NotesDatabase

      Dim parentDoc As NotesDocument

      Set db = doc.ParentDatabase

      If doc.IsResponse Then

        Set parentDoc = db.GetDocumentByUNID _

        ( doc.ParentDocumentUNID )

      End If

      Set GetParentDocument = parentDoc

    End Function
    This function can be called from any script. For example:

    dim myQuestion as NotesDocument

    dim yourAnswer as NotesDocument

    '...set value of yourAnswer...

    set myQuestion = GetParentDocument( yourAnswer )


Examples: ParentDatabase property

This Visual Basic code displays the parent title of a NotesOutline object.

Private Sub OutlineParent_Click()

Dim s As New NotesSession

s.Initialize

Dim outline As NotesOutline

Dim dir As NotesDbDirectory

Dim db As NotesDatabase

Set dir = s.GetDbDirectory("")

Set db = dir.OpenDatabase("Web test")

Set outline = db.GetOutline("Main Outline")

MsgBox outline.ParentDatabase.Title, , "Title of parent"

End Sub


Examples: ParentDocumentUNID property

  1. This script displays a message.

    2. Dim parentUnid As String

    parentUnid = doc.ParentDocumentUNID

    If ( parentUnid = "" ) Then

      Messagebox( "This document has no parent." )

    Else

      Messagebox( "The parent's UNID is " + parentUNID )

    End If
  2. This script uses ParentDocumentUNID and the GetDocumentByUNID method in NotesDatabase to find the parent document of a response.

    3. Dim response As NotesDocument

    Dim parent As NotesDocument

    '...set value of response...

    Set parent = db.GetDocumentByUNID _

    ( response.ParentDocumentUNID )


Example: ParentView property

This script prints the title of the NotesView object from which a document was retrieved (view), and the title of the NotesView object returned by the ParentView property (parentView). The titles are the same, because view and parentView represent the same view, the Main View in SOMEDOCS.NSF.

Dim db As New NotesDatabase( "", "somedocs.nsf" )

Dim view As NotesView

Dim parentView As NotesView

Dim doc As NotesDocument

Set view = db.GetView( "Main View" )

Set doc = view.GetFirstDocument

Set parentView = doc.ParentView

Messagebox( view.Name )

Messagebox( parentView.Name )


Example: ParentView property

This script displays the name of the parent view of a view navigator.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim view As NotesView

Dim entry As NotesViewEntry

Dim nav As NotesViewNavigator

Dim pv As NotesView

Set db = session.CurrentDatabase

Set view = db.GetView("By Category")

Set nav = view.CreateViewNav

Set pv = nav.ParentView

Messagebox pv.Name


Example: PassThruHTML property

This script creates a rich-text item and marks it as pass-thru HTML.

Sub Initialize

     Dim session As New NotesSession

     Dim db As NotesDatabase

     Set db = session.CurrentDatabase

     Dim doc As New NotesDocument(db)

     Call doc.AppendItemValue("From", session.UserName)

     Call doc.AppendItemValue("Subject", _

     "Meeting time changed")

     Dim richStyle As NotesRichTextStyle

     Set richStyle = session.CreateRichTextStyle

     Dim richText As New NotesRichTextItem(doc, "Body")

     richStyle.PassThruHTML = True

     Call richText.AppendStyle(richStyle)

     Call richText.AppendText("<B>Hello</B>")

     Call doc.Save(True, False)

End Sub


Example: Paste method

This button script cuts the contents of the current field and pastes them into the next field.

Sub Click(Source As Button)

  Dim workspace As New NotesUIWorkspace

  Dim uidoc As NotesUIDocument

  Set uidoc = workspace.CurrentDocument

  Call uidoc.SelectAll

  Call uidoc.Cut

  Call uidoc.GotoNextField

  Call uidoc.Paste

End Sub


Example: PercentUsed property

This script gets the percent used of WHITESPC.NSF and puts it into the variable used. For example, PercentUsed returns 84.1.

Dim db As New NotesDatabase( "", "whitespc.nsf" )

Dim used As Double

used = db.PercentUsed


Example: PickListStrings method

  1. This example displays the resources dialog.

    2. Dim workspace As New NotesUIWorkspace

    Dim picklist As Variant

    picklist = workspace.Pickliststrings(2)
  2. This example displays a custom dialog showing only the documents that appear under the Test category in the By Category view of a database.

    3. Dim workspace As New NotesUIWorkspace

    Dim picklist As Variant

    picklist = workspace.Pickliststrings(3,1,"","c:\lotus\notes\data\Test.nsf",_

             "By Category", "Document picker",_

             "Please select some documents the document(s).",_

              2,"Test")


Example: Platform property

This script gets the current platform and puts it into the variable plat. For example, if the script runs on a Windows 3.1 workstation, the Platform property returns "Windows/16".

Dim session As New NotesSession

Dim plat As String

plat = session.Platform


Example: PlayTune method

This example displays a list of sounds available on your system, then plays the user-specified sound.

Dim workspace As New NotesUIWorkspace

Dim tunes As Variant

tunes = workspace.GetListOfTunes()

Dim messagelist As String

Forall tunelist In tunes

     messagelist = messagelist & tunelist & Chr(10)

End Forall

Messagebox messagelist

Call workspace.PlayTune(Inputbox("Tune name:"))


Examples: Position property

  1. This script gets the position of the first column in the By Author view of LAERTES.NSF. The Position property returns 1.

    2. Dim db As New NotesDatabase( "Elsinore", "laertes.nsf" )

    Dim view As NotesView

    Dim column As NotesViewColumn

    Dim pos As Integer

    Set view = db.GetView( "By Author" )

    Set column = view.Columns( 0 )

    pos = column.Position
  2. This script does the same as the script above, except it gets the second column in the By Author view. The Position property returns 2.

    3. Dim db As New NotesDatabase( "Elsinore", "laertes.nsf" )

    Dim view As NotesView

    Dim column As NotesViewColumn

    Dim pos As Integer

    Set view = db.GetView( "By Author" )

    Set column = view.Columns( 1 )

    pos = column.Position


Example: PostModeChange event

This script appends text to the ProblemHistory field every time the user switches from read to Edit mode in the current document.

Sub Postmodechange(Source As Notesuidocument)

  Dim dateTime As New NotesDateTime( "Today" )

  If source.EditMode Then

    Call source.FieldAppendText _

    ( "ProblemHistory", _

    "Problem edited on " & dateTime.LocalTime )

  End If

End Sub


Examples: PostOpen event

  1. This script checks if the current document's CheckedOut field contains "Yes." If so, it displays a message telling the user that the document is checked out.

    2. Sub Postopen(Source As Notesuidocument)

      If ( source.FieldGetText( "CheckedOut" ) = "Yes" ) Then

        Messagebox("This document is currently checked out.")

      End If

    End Sub
  2. This script checks if the user has created a new document. If so, it puts a new value in the ProblemHistory field that records when the problem report was created.

    3. Sub Postopen(Source As Notesuidocument)

      Dim dateTime As New NotesDateTime( "Today" )

      If source.IsNewDoc Then

        Call source.FieldSetText _

        ( "ProblemHistory", _

        "Problem opened on " & dateTime.LocalTime )

      End If

    End Sub
  3. This script checks if the user has opened an Employee Request document in Edit mode. If so, it guides the user through the document, based on the contents of the Owner field. The document is completed in three stages:

  • The employee enters the request. If the Owner field contains "Employee," the script prompts the employee for the text of the request. The Owner field is changed to "Manager," and the document is saved and closed.

  • The manager approves or rejects the request. If the Owner field contains "Manager," the script displays a dialog box with Yes and No buttons, asking the Manager if she approves the request. The Status field gets set to either "Approved" or "Rejected," the Owner field is changed to "Human Resources," and the document is saved and closed.

  • The Human Resources person approves or rejects the Manager's decision. If the Owner field contains "Human Resources," the script displays a dialog box with Yes and No buttons, asking the Human Resources person if he approves the Manager's decision. The Confirmation field gets set to either "Approved" or "Rejected," and the document is saved and closed.

This script must include the file LSCONST.LSS in order to work properly.

Sub Postopen(Source As Notesuidocument)

  Dim ownerType As String

  Dim employeeRequest As String

  Dim result As Integer

  If source.EditMode Then

    ownerType = source.FieldGetText( "Owner" )

    Select Case ownerType

    ' 1. Employee enters the request in a dialog box

    Case "Employee":

      employeeRequest = Inputbox$ _

      ( "Please enter your request", "Request" )

      Call source.FieldSetText("Request", employeeRequest)

      Call source.FieldSetText("Owner", "Manager")

     ' 2. Manager approves or rejects the request

    Case "Manager":

      result = Messagebox _

      ( "Do you approve this employee's request?", _

      MB_YESNO, "Approve" )

      If ( result = IDYES ) Then

        Call source.FieldSetText( "Status", "Approved" )

      Else

        Call source.FieldSetText( "Status", "Rejected" )

      End If

      Call source.FieldSetText("Owner", "Human Resources")

    ' 3. Human Resources approves or rejects

    ' the Manager's decision

    Case "Human Resources":

      result = Messagebox _

      ( "Do you approve this manager's decision?", _

      MB_YESNO, "Confirm" )

      If ( result = IDYES ) Then

        Call source.FieldSetText _

        ( "Confirmation", "Approved" )

      Else

        Call source.FieldSetText _

        ( "Confirmation", "Rejected" )

      End If

    End Select

    ' After each step, the document is saved and closed

    Call source.Save

    Call source.Close

  End If

End Sub


Example: PostPaste event

This example uses a variable that is global to the NotesUIView events to count the number of paste operations and display the total.

(Declarations)

Dim pasteCount As Integer

Sub Postopen(Source As Notesuiview)

     pasteCount = 0

End Sub

Sub Postpaste(Source As Notesuiview)

     pasteCount = pasteCount + source.Documents.Count

End Sub

Sub Queryclose(Source As Notesuiview, Continue As Variant)

     Messagebox pasteCount & " documents pasted",, _

     "Paste operations"

End Sub


Example: PostRecalc event

Each time the current document is recalculated, this script updates the contents of the address field. The document contains a keyword field called city, which is set to refresh the fields each time one of its keywords changes. Therefore, this script gets called any time the user changes the city field. The script modifies the contents of the address field, based on the contents of the city field.

Sub Postrecalc(Source As Notesuidocument)

  Dim location As String

  location = source.FieldGetText( "city" )

  Select Case location

  Case "Cambridge"

    Call source.FieldSetText( "address", "5 Memorial Drive" )

  Case "Chicago"

    Call source.FieldSetText( "address", "44 Diversey Blvd" )

  Case "Paris"

    Call source.FieldSetText( "address", "32 Rue Henri IV" )

  End Select

End Sub


Examples: PostSave event

  1. This script closes a document after it has been saved.

    2. Sub Postsave(Source As Notesuidocument)

         Call Source.Close

    End Sub
  2. This example sends a copy of a new or edited document to anyone listed in the "Reviewers" field after the document has been saved.

    3. Sub Postsave(Source As Notesuidocument)

         Dim session As New NotesSession

         Dim workspace As New NotesUIWorkspace

         Dim db As NotesDatabase

         Dim uidoc As NotesUIDocument

          Dim doc As NotesDocument

         Dim doc2 As NotesDocument

         Dim item As NotesItem

         Set uidoc = workspace.CurrentDocument

         Set doc = uidoc.Document

         Set db = session.CurrentDatabase

         Set doc2 = New NotesDocument(db)

         Set item = doc.GetFirstItem("Subject")

         Call item.CopyItemToDocument(doc2, "Subject")

         Set item = doc.GetFirstItem("Reviewers")

         Call item.CopyItemToDocument(doc2, "SendTo")

         Set item = doc.GetFirstItem("Body")

         Call item.CopyItemToDocument(doc2, "Body")

         Call doc2.Send(False, doc.Reviewers)

    End Sub


Example: PreviewDocLink property

This script displays the preview pane each time the user puts the cursor in a particular field.

Sub Entering(Source As Field)

  Dim workspace As New NotesUIWorkspace

  Dim uidoc As NotesUIDocument

  Set uidoc = workspace.CurrentDocument

  uidoc.PreviewDocLink = True

End Sub


Example: PreviewParentDoc property

This script displays the current document's parent in the preview pane when the user opens the document.

Sub Postopen(Source As Notesuidocument)

  source.PreviewParentDoc = True

End Sub


Example: PrevRow method

This agent accesses all rows of a result set starting from the last row. You must explicitly set LastRow and process it outside the loop. In the loop, each PrevRow gets the previous row in the data set. IsBeginOfData detects that the first row was processed.

Uselsx "*LSXODBC"

Sub Initialize

     Dim con As New ODBCConnection

     Dim qry As New ODBCQuery

     Dim result As New ODBCResultSet

     Dim firstName As String

     Dim lastName As String

     Dim msg As String

     Set qry.Connection = con

     Set result.Query = qry

     con.ConnectTo("ATDB")

     qry.SQL = "SELECT * FROM STUDENTS ORDER BY LASTNAME"

     result.Execute

     msg = "Student names:" & Chr(10)

     result.LastRow

     firstName = result.GetValue("FIRSTNAME", firstName)

     lastName = result.GetValue("LASTNAME", lastName)

     msg = msg & Chr(10) & firstName & " " & lastName

     Do

          result.PrevRow

          firstName = result.GetValue("FIRSTNAME", firstName)

          lastName = result.GetValue("LASTNAME", lastName)

          msg = msg & Chr(10) & firstName & " " & lastName

     Loop Until result.IsBeginOfData

     Messagebox msg,, "Student Names"

     result.Close(DB_CLOSE)

     con.Disconnect

End Sub


Examples: Print method

  1. This form action script displays the File Print dialog box, where the user can select settings for printing the current document, or select Cancel.

    2. Sub Click(Source As Button)

      Dim workspace As New NotesUIWorkspace

      Dim uidoc As NotesUIDocument

      Set uidoc = workspace.CurrentDocument

      Call uidoc.Print

    End Sub
  2. This form action script prints one copy of the current document, without displaying the File Print dialog box.

    3. Sub Click(Source As Button)

      Dim workspace As New NotesUIWorkspace

      Dim uidoc As NotesUIDocument

      Set uidoc = workspace.CurrentDocument

      Call uidoc.Print( 1 )

    End Sub
  3. This script prints one copy of pages 2 and 3 of the current document.

    4. Sub Click(Source As Button)

      Dim workspace As New NotesUIWorkspace

      Dim uidoc As NotesUIDocument

      Set uidoc = workspace.CurrentDocument

      Call uidoc.Print( 1, 2, 3 )

    End Sub


Example: Print method

This script prints the current view.

Dim workspace As New NotesUIWorkspace

Dim uiview As NotesUIView

Set uiview = workspace.Currentview

Call uiview.Print()


Example: Priority property

This script checks the replication priority and if it is set to Medium the script will change the priority to Low. In order to save the change, Call Save() is used.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim rep As NotesReplication

Set db = session.CurrentDatabase

Set rep = db.ReplicationInfo

  If rep.Priority = DB_REPLICATION_PRIORITY_MED Then

    rep.Priority = DB_REPLICATION_PRIORITY_LOW

  End If

Call rep.Save()


Example: ProgramName property

This script displays a dialog box that says "Maple Log."

Dim currentLog As New NotesLog( "Maple Log" )

Dim logName As String

Call currentLog.OpenFileLog( "c:\log.txt" )

logName = currentLog.ProgramName

Messagebox( logName )


Example: Prompt method

This script prompts a user for their password. If the password supplied is not xyzabc, the user is promted again until the correct password is supplied.

Dim workspace As New NotesUIWorkspace

Dim askme As Variant

Do Until askme = "xyzabc"

     askme = workspace.Prompt(PROMPT_PASSWORD, _

     "Password", "Please type your password.", "", "")

Loop


Example: ProtectReaders property

This script toggles protection for the readers field.

Dim session As New NotesSession

Dim db As NotesDatabase

Set db = session.CurrentDatabase

formNameIn = Lcase(Inputbox("Name of form?"))

Forall form In db.Forms

     If Lcase(form.Name) = formNameIn Then

          If form.ProtectReaders Then

               form.ProtectReaders = False

               Messagebox "ProtectReaders is set for " _

               & form.Name

          Else

               form.ProtectReaders = True

               Messagebox "ProtectReaders is not set for " _

               & form.Name

          End If

          Exit Sub

     End If

End Forall

Messagebox "The form """ & formNameIn & """ does not exist"


Example: ProtectReaders property

This script toggles protection for the readers field.

Dim session As New NotesSession

Dim db As NotesDatabase

Set db = session.CurrentDatabase

viewNameIn = Lcase(Inputbox("Name of view?"))

Forall view In db.Views

   If Lcase(view.Name) = viewNameIn Then

      If view.ProtectReaders Then

         view.ProtectReaders = False

         Messagebox "ProtectReaders is set for " _

               & view.Name

      Else

         view.ProtectReaders = True

         Messagebox "ProtectReaders is not set for " _

               & view.Name

      End If

      Exit Sub

   End If

End Forall

Messagebox "The view """ & viewNameIn & """ does not exist"


Example: ProtectUsers property

This script toggles protection for the form users field.

Dim session As New NotesSession

Dim db As NotesDatabase

Set db = session.CurrentDatabase

formNameIn = Lcase(Inputbox("Name of form?"))

Forall form In db.Forms

     If Lcase(form.Name) = formNameIn Then

          If form.ProtectUsers Then

               form.ProtectUsers = False

               Messagebox "ProtectUsers is set for " _

               & form.Name

          Else

               form.Protectusers = True

               Messagebox "ProtectUsers is not set for " _

               & form.Name

          End If

          Exit Sub

     End If

End Forall

Messagebox "The form """ & formNameIn & """ does not exist"


Example: PutAllInFolder method

The following example puts all the documents found through the FTSearch method of NotesDatabase into a folder "Spicy" inside another folder "Recipes."

Dim session As New NotesSession

Dim db As NotesDatabase

Dim collection As NotesDocumentCollection

Set db = session.CurrentDatabase

Set collection = db.FTSearch( "cayenne", 20 )

Call collection.PutAllInFolder( "Recipes\Spicy" )


Example: PutAllInFolder method

This script gets all of the entries in the category Fox in the By Category view and puts them in the Machines folder.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim view As NotesView

Dim vc As NotesViewEntryCollection

Set db = session.CurrentDatabase

Set view = db.GetView("By Category")

Set vc = view.GetAllEntriesByKey("Fox")

Call vc.PutAllInFolder("Machines")


Examples: PutInFolder method

  1. This script puts a document in the folder Jambalaya.

    2. Dim doc As NotesDocument

    '...set value of doc...

    Call doc.PutInFolder( "Jambalaya" )
  2. This script puts a document in the folder Spicy, which is located inside the folder Recipes.

    3. Dim doc As NotesDocument

    '...set value of doc...

    Call doc.PutInFolder( "Recipes\Spicy" )
  3. This script puts a document in the private folder called Greens.

    4. Dim doc As NotesDocument

    '...set value of doc...

    Call doc.PutInFolder( "Greens" )
  4. This script performs a full-text search in the current database and places the top twenty matching documents in a folder called Spicy. If the folder does not exist, one will be created.

    5. Dim session As New NotesSession

    Dim db As NotesDatabase

    Dim dc As NotesDocumentCollection

    Dim doc As NotesDocument

    Set db = session.CurrentDatabase

    Set dc = db.FTSearch("cayenne",20)

    Set doc = dc.GetFirstDocument

    While Not(doc Is Nothing)

        Call doc.PutInFolder("Spicy",True)

        Set doc = dc.GetNextDocument(doc)

    Wend
  5. This script selects all the documents within a document collection that contain the field "Conflict", and moves them to a folder.

    6. Dim s As New NotesSession

    Dim db As NotesDatabase

    Dim dc As NotesDocumentCollection

    Dim doc As NotesDocument

    Set db = s.CurrentDatabase

    Set dc = db.AllDocuments

    Set doc = dc.GetFirstDocument

    While Not(doc Is Nothing)

         If doc.IsResponse Then

            If doc.HasItem("$Conflict") Then

               Call doc.PutInFolder("Conflicts")

            End If

         End If

         Set doc = dc.GetNextDocument(doc)

    Wend


Example: Query property

This example sets up the necessary query connections in the Postopen script of a form. The Connection property of ODBCQuery must specify an ODBCConnection object. The Query property of ODBCResultSet must specify the ODBCQuery object.

Uselsx "*LSXODBC"

Dim con As ODBCConnection

Dim qry As ODBCQuery

Dim result As ODBCResultSet

Sub Postopen(Source As Notesuidocument)

     Set con = New ODBCConnection

     Set qry = New ODBCQuery

     Set result = New ODBCResultSet

     Set qry.Connection = con

     Set result.Query = qry

End Sub

Sub Click(Source As Button)

     Dim firstName As String

     Dim lastName As String

     Dim msg As String

     con.ConnectTo("ATDB")

     qry.SQL = "SELECT * FROM STUDENTS"

     result.Execute

     msg = "Student names:" & Chr(10)

     Do

          result.NextRow

          firstName = result.GetValue("FIRSTNAME", firstName)

          lastName = result.GetValue("LASTNAME", lastName)

          msg = msg & Chr(10) & firstName & " " & lastName

     Loop Until result.IsEndOfData

     Messagebox msg,, "Student names"

     result.Close(DB_CLOSE)

     con.Disconnect

End Sub


Example: Query property

This script displays the text of the query that produced the view entry collection.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim view As NotesView

Dim vc As NotesViewEntryCollection

Set db = session.CurrentDatabase

Set view = db.GetView("By Category")

Set vc = view.GetAllEntriesByKey("Cars")

Messagebox "Query text: " & vc.Query


Examples: Query property

This script gets the query for the Cleansing Agent in the current database and puts it into the variable selection.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim agent As NotesAgent

Set db = session.CurrentDatabase

Dim selection As String

agentList = db.Agents

Forall a In agentList

  If ( a.Name = "Cleansing Agent" ) Then

    Set agent = a

  End If

End Forall

selection = agent.Query

Some sample results:

  • If the Cleansing Agent searches for documents that contain the word "tulip," Query returns ("tulip").

  • If it searches for documents that contain the word tulip and were created on September 19, 1996, Query returns ("tulip") AND ([_CreationDate] = 09/19/96).

  • If it searches for documents that use the Response form, Query returns (([Form]="Response")).

  • If it searches for documents that use the Response form and contain the phrase "mustard greens" in the Subject field, Query returns (([Form]="Response")) AND ([Subject] CONTAINS (mustard greens)).


Examples: Query property

  1. This script gets a collection of documents that match a full-text search query. The Query property returns "white wine."

    2. Dim session As New NotesSession

    Dim db As NotesDatabase

    Dim collection As NotesDocumentCollection

    Dim search As String

    Set db = session.CurrentDatabase

    Set collection = db.FTSearch( "white wine", 0 )

    search = collection.Query
  2. This script gets a collection of documents that match a search query. The Query property returns "@Contains(Subject; "Bicycle")."

    3. Dim session As New NotesSession

    Dim db As NotesDatabase

    Dim dateTime As NotesDateTime

    Dim collection As NotesDocumentCollection

    Dim search As String

    Set db = session.CurrentDatabase

    Set dateTime = New NotesDateTime( "07/21/95" )

    Set collection = db.Search _

    ( "@Contains(Subject;""Bicycle"")", dateTime, 2 )

    search = collection.Query


Examples: QueryAccess method

  1. This script gets the access level for Susanna Coyle in the database CHECK.NSF.

    2. Dim db As NotesDatabase

    Dim level As Integer

    Set db = New NotesDatabase( "Belem", "check.nsf" )

    level = db.QueryAccess( "Susanna Coyle" )
    • If Susanna Coyle has Author access to the database, level contains ACLLEVEL_AUTHOR.

    • If Susanna Coyle is a member of a group that has Designer access to the database, and Susanna is not otherwise listed in the ACL, level contains ACLLEVEL_DESIGNER.

    • If Susanna Coyle is a member of one group that has Editor access to the database and another group that has Designer access to the database, and Susanna is not otherwise listed in the ACL, level contains ACLLEVEL_DESIGNER.

    • If Susanna Coyle is not explicitly listed in the ACL and is not a member of any groups listed in the ACL, but the Default access of the database is Reader, level contains ACLLEVEL_READER.

  2. This form action script checks the current user's access level to a database before looking up a series of values from that database. If the user does not have Reader access or better, a message is displayed and the script exits. If the user has Reader access or better, the target database is opened and column values from its Product view are appended to the Body field of the currently open document.

    3. Sub Click(Source As Button)

      Dim session As New NotesSession

      Dim workspace As New NotesUIWorkspace

      Dim uidoc As NotesUIDocument

      Dim db As New NotesDatabase( "Cambridge", "sites.nsf" )

      Dim view As NotesView

      Dim doc As NotesDocument

      If ( db.QueryAccess( session.CommonUserName ) < _

      ACLLEVEL_READER ) Then

        Messagebox( "The information from " + db.Title +  _

        " is unavailable." )

      Else

        Set uidoc = workspace.CurrentDocument

        Set view = db.GetView( "Locations" )

        Set doc = view.GetFirstDocument

        While Not ( doc Is Nothing )

          Call uidoc.FieldAppendText( "Body",  _

                                      doc.ColumnValues( 0 ) )

          Set doc = view.GetNextDocument( doc )

        Wend

      End If

    End Sub


Example: QueryAddToFolder event

This example discontinues an add to folder operation if the user responds no to a query.

(Globals) (Declarations)

%INCLUDE "lsconst.lss"

Sub Queryaddtofolder(Source As Notesuiview, Target As Variant, Continue As Variant)

     Dim doc As NotesDocument

     Dim docList As String

     For j = 1 To Source.Documents.Count

          Set doc = Source.Documents.GetNthDocument(j)

          docList = docList & Chr(10) & doc.Subject(0)

     Next

     If Messagebox("Do you want to add these documents to " _

     & Target & "?" & Chr(10) & docList, _

     MB_YESNO + MB_ICONQUESTION, _

     "Add to folder") = IDNO Then

          Continue = False

     End If

End Sub


Examples: QueryClose event

  1. This script asks users if they're sure they want to exit the current document. If they click the Yes button, the document closes; if they click No, the document remains open.

    2. In order to use the constants associated with the Messagebox function, this script must include the file LSCONST.LSS.

    Sub Queryclose(Source As Notesuidocument, _

    Continue As Variant)

      Dim answer As Integer

      answer = Messagebox _

      ( "Do you want to exit this document?", _

      MB_YESNO, "Document" )

      If ( answer = IDNO ) Then

        continue = False

      End If

    End Sub
  2. If a user has been editing the current document and closes it, Notes first asks if the user wants to save the document. Regardless of the response, this script then asks if the user wants to mail the document. If the user clicks the Yes button, the document gets mailed to whoever is listed in the SendTo field.

    3. In order to use the constants associated with the Messagebox function, this script must include the file LSCONST.LSS.

    Sub Queryclose(Source As Notesuidocument, Continue As Variant)

      Dim answer As Integer

      If source.EditMode Then

        answer = Messagebox _

        ("Do you want to mail this doc?", MB_YESNO, "Mail" )

        If ( answer = IDYES ) Then

          Call source.Send

        End If

      End If

    End Sub


Example: QueryExecuteTimeOut property

The following agent sets a 5-second time-out on executing an SQL query.

Uselsx "*LSXODBC"

Sub Initialize

     Dim con As New ODBCConnection

     Dim qry As New ODBCQuery

     Dim result As New ODBCResultSet

     Dim firstName As String

     Dim lastName As String

     Dim msg As String

     Set qry.Connection = con

     Set result.Query = qry

     con.ConnectTo("ATDB")

     qry.SQL = "SELECT * FROM STUDENTS ORDER BY LASTNAME"

     qry.QueryExecuteTimeOut = 5

     result.Execute

     msg = "Student names:" & Chr(10)

     If result.IsResultSetAvailable Then

          Do

               result.NextRow

               firstName = result.GetValue("FIRSTNAME", _

                                           firstName)

               lastName = result.GetValue("LASTNAME", _

                                          lastName)

               msg = msg & Chr(10) & firstName & " " & _

               lastName

          Loop Until result.IsEndOfData

     Else

          Messagebox "Cannot get result set for STUDENTS"

          Exit Sub

     End If

     Messagebox msg,, "Student Names"

     con.Disconnect

End Sub


Examples: QueryModeChange event

  1. This script prevents the user from switching to Edit mode and displays a message informing the user that the document cannot be edited.

    2. Sub Querymodechange(Source As Notesuidocument, Continue As Variant)

      If Not ( source.EditMode ) Then

        Messagebox("Sorry, the text you wrote can't be edited.")

        continue = False

      End If

    End Sub
  2. This script checks if the user is switching from Read mode to Edit mode. If so, and if the Status field contains "Closed," the script displays a message and prevents the user from switching to Edit mode.

Sub Querymodechange(Source As Notesuidocument, Continue As Variant)

  If Not ( source.EditMode ) Then

    currentStatus = source.FieldGetText( "Status" )

    If ( currentStatus = "Closed" ) Then

      Messagebox _

      ( "Document available for browsing only." )

      continue = False

    End If

  End If

End Sub


Examples: QueryOpen event

  1. This script prevents the user from creating a new document.

    2. Sub Queryopen(Source As Notesuidocument, _

    Mode As Integer,  _

    Isnewdoc As Variant, Continue As Variant)

      If IsNewDoc Then

        Messagebox _

        ( "Only one Setup document is permitted" )

        continue = False

      End If

    End Sub
  2. This script prevents the user from creating a Setup document if one already exists in the database. When the user tries to create a new document, the script checks if there is a document in the Setup view. If so, a Setup document already exists in the database and the user is prevented from creating another one.

    3. Sub Queryopen(Source As Notesuidocument, _

    Mode As Integer,  _

    Isnewdoc As Variant, Continue As Variant)

      Dim session As New NotesSession

      Dim db As NotesDatabase

      Dim view As NotesView

      Dim doc As NotesDocument

      ' Check if the user is trying to create a new Setup doc

      If IsNewDoc Then

        Set db = session.CurrentDatabase

        Set view = db.GetView( "Setup" )

        Set doc = view.GetFirstDocument

        ' Check if a Setup doc already exists in the db

        If Not ( doc Is Nothing ) Then

          Messagebox _

          ("Only one Setup document permitted.")

          ' If so, don't let user create another one

          continue = False

        End If

      End If

    End Sub
  3. This script checks if the user is a member of the Supervisor role. If so, the user can open the document; if not, or if the user is not listed in the access control list, the user cannot open the document.

Sub Queryopen(Source As Notesuidocument, _

Mode As Integer,  _

Isnewdoc As Variant, Continue As Variant)

  Dim session As New NotesSession

  Dim db As NotesDatabase

  Dim acl As NotesACL

  Dim entry As NotesACLEntry

  Set db = session.CurrentDatabase

  Set acl = db.ACL

  Set entry = acl.GetEntry( session.UserName )

  If ( entry Is Nothing ) Then

    continue = False

  Elseif Not ( entry.IsRoleEnabled( "Supervisor" ) ) Then

    continue = False

  End If

End Sub


Example: QueryOpenDocument event

This example stores the user's "work area" in a variable that is global to the NotesUIView scripts. Documents whose category is not identical to the user's work area are not opened.

(Declarations)

Dim workArea As String

Sub Postopen(Source As Notesuiview)

     workArea = Inputbox("What is your work area?", _

     "Work area", "Marketing")

End Sub

Sub Queryopendocument(Source As Notesuiview,  _

                      Continue As Variant)

     Dim docs As NotesDocumentCollection

     Dim doc As NotesDocument

     Set docs = Source.Documents

     Set doc = docs.GetFirstDocument()

     If Ucase(doc.Categories(0)) <> Ucase(workArea) Then

          Continue = False

     End If

End Sub


Example: QueryPaste event

This example discontinues a paste operation if the user responds no.

(Globals) (Declarations)

%INCLUDE "lsconst.lss"

Sub Querypaste(Source As Notesuiview, Continue As Variant)

     If Messagebox _

     ("Do you want to proceed with this paste operation?", _

     MB_YESNO + MB_ICONQUESTION, _

     "Paste operation") = IDNO Then

          Continue = False

     End If

End Sub


Example: QueryRecalc event

This example discontinues a recalculation of the view if the user responds no.

(Globals) (Declarations)

%INCLUDE "lsconst.lss"

Sub Queryrecalc(Source As Notesuiview, Continue As Variant)

     If Messagebox("Do you really want to recalc?", _

     MB_YESNO + MB_ICONQUESTION, _

     "Recalc operation") = IDNO Then

          Continue = False

     End If

End Sub


Examples: QuerySave event

  1. This script prevents the user from saving the current document if there is nothing in the Title field. It displays a message and moves the insertion point to the Title field.

    2. Sub Querysave(Source As Notesuidocument,  _

                  Continue As Variant)

      If ( source.FieldGetText( "Title" ) = "" ) Then

        Messagebox( "You must enter a title." )

        Call source.GotoField( "Title" )

        continue = False

      End If

    End Sub
  2. This script checks the contents of the dueDate field when the user tries to save the current document, and updates the ProjectStatus field accordingly. If the dueDate is less than four days away, it puts "Urgent" into the ProjectStatus field; if it's less than six days away, it puts "Hurry up a little" into the field; if it's six or seven days away, it puts "No worries" into the field.

    3. Sub Querysave(Source As Notesuidocument, Continue As Variant)

      Dim targetDate As String

      Dim todayDateTime As NotesDateTime

      Dim dueDateTime As NotesDateTime

      Dim daysLeft As Long

      Call source.Refresh

      Set todayDateTime = New NotesDateTime( "Today" )

      Set dueDateTime = New NotesDateTime _

      ( source.FieldGetText( "dueDate" ) )

      daysLeft = ( dueDateTime.TimeDifference _

      ( todayDateTime ) ) / 86400

      Select Case daysLeft

      Case 1, 2, 3:

        status = "Urgent"

      Case 4, 5, 6:

        status = "Hurry up a little"

      Case 6, 7:

        status = "No worries"

      End Select

      Call source.FieldSetText( "ProjectStatus", status )

    End Sub


Examples: Readers property

  1. This example adds names to the readers field.

    2. Dim session As New NotesSession

    Dim db As NotesDatabase

    Dim form As NotesForm

    Dim newReaders(0 To 63) As String

    Dim reader As String

    Set db = session.CurrentDatabase

    Set form = db.GetForm(Inputbox("Name of form?"))

    If Isempty(form.Readers) Then

         n = 0

    Else

         For j = 0 To Ubound(form.Readers)

              newReaders(j) = form.Readers(j)

              Messagebox "Current reader: " & newReaders(j)

         Next

         n = Ubound(form.Readers) + 1

    End If

    reader = Inputbox("Name of reader?")

    Do While reader <> ""

         newReaders(n) = reader

         reader = Inputbox("Name of reader?")

         n = n + 1

    Loop

    form.Readers = newReaders
  2. This example replaces the contents of the readers field.

    3. REM Replaces $READERS in total with what the  _

    REM user specifies here

    Dim session As New NotesSession

    Dim db As NotesDatabase

    Dim form As NotesForm

    Dim newReaders(0 To 63) As String

    Dim reader As String

    Dim emptyReaders As Variant

    Set db = session.CurrentDatabase

    Set form = db.GetForm(Inputbox("Name of form?"))

    n = 0

    reader = Inputbox("Name of reader?")

    Do While reader <> ""

         newReaders(n) = reader

         reader = Inputbox("Name of reader?")

         n = n + 1

    Loop

    form.Readers = newReaders


Examples: Readers property

  1. This example adds names to the readers field.

    2. Dim session As New NotesSession

    Dim db As NotesDatabase

    Dim view As NotesView

    Dim newReaders(0 To 63) As String

    Dim reader As String

    Set db = session.CurrentDatabase

    Set view = db.GetView("By Category")

    If Isempty(view.Readers) Then

         n = 0

    Else

         For j = 0 To Ubound(view.Readers)

              newReaders(j) = view.Readers(j)

              Messagebox "Current reader: " & newReaders(j)

         Next

         n = Ubound(view.Readers) + 1

    End If

    reader = Inputbox("Name of reader?")

    Do While reader <> ""

         newReaders(n) = reader

         reader = Inputbox("Name of reader?")

         n = n + 1

    Loop

    view.Readers = newReaders
  2. This example replaces the contents of the readers field.

    3. REM Replaces $READERS in total with what the  _

        user specifies here

    Dim session As New NotesSession

    Dim db As NotesDatabase

    Dim view As NotesView

    Dim newReaders(0 To 63) As String

    Dim reader As String

    Dim emptyReaders As Variant

    Set db = session.CurrentDatabase

    Set view = db.GetView("By Category")

    n = 0

    reader = Inputbox("Name of reader?")

    Do While reader <> ""

         newReaders(n) = reader

         reader = Inputbox("Name of reader?")

         n = n + 1

    Loop

    view.Readers = newReaders


Example: ReadOnly property

This example contains an action that, depending on user input, displays and toggles the ReadOnly property.

Uselsx "*LSXODBC"

%INCLUDE "lsconst.lss"

Sub Postopen(Source As Notesuidocument)

     Set con = New ODBCConnection

     Set qry = New ODBCQuery

     Set result = New ODBCResultSet

     Set qry.Connection = con

     Set result.Query = qry

     con.ConnectTo("ATDB")

     qry.SQL = "SELECT * FROM STUDENTS ORDER BY LASTNAME"

     result.Execute

     ...

End Sub

Sub Click(Source As Button)

     If result.ReadOnly Then

       If Messagebox("Do you want to allow updates?", _

       MB_YESNO, "Updates disallowed (ReadOnly)") = IDYES Then

            result.ReadOnly = False

       End If

     Else

       If Messagebox("Do you want to disallow updates?", _

       MB_YESNO, "Updates allowed") = IDYES Then

            result.ReadOnly = True

       End If

     End If

End Sub


Example: ReCertify method

The following script shows you how to recertify an ID file.

Dim reg As New NotesRegistration

Dim ceridfile As String, org As String, certpw As string

org = "Test"

length% = 2

certidfile = "c:\noteids\redsox\Redsox.id"

certpw = "pw"

reg.RegistrationLog = "certlog.nsf"

reg.IDType = ID_HIERARCHICAL

reg.CertifierIDFile = certidfile

reg.Expiration = Datevalue("December 12, 1999")

reg.RegistrationServer = "MoonBeam/RedSox"

comment$ = "comment text"

IDFile$ = "c:\noteids\redsox\Imerloni.id"

Call reg.ReCertify( IDFile$, certpw$, comment$)


Example: Refresh method

This script refreshes the current document whenever the user moves the cursor out of a particular field.

Sub Exiting(Source As Field)

  Dim workspace As New NotesUIWorkspace

  Dim uidoc As NotesUIDocument

  Set uidoc = workspace.CurrentDocument

  Call uidoc.Refresh

End Sub

For example, this script might run whenever the user exits the Group field. If Supervisor is a computed field with the formula

@If( Group = "Editorial"; "Stephanie Mavis";  _

     Group = "Graphic Design"; "David Mayar"; _

     Group = "Production"; "Peter Orveton"; "" )

the Supervisor field recalculates its value whenever the user exits the Group field.


Example: Refresh method

This script creates a new document that gets indexed in the By Category view of the current database. As the script demonstrates, the document is not accessible to any NotesView methods until the Refresh method has been called.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim view As NotesView

Dim newDoc As NotesDocument

Dim doc As NotesDocument

Set db = session.CurrentDatabase

Set view = db.GetView( "By Category" )

' create a new document with Latest news category

Set newDoc = New NotesDocument( db )

newDoc.Form = "Main Topic"

newDoc.Categories = "Latest news"

newDoc.Subject = "Just created this doc"

Call newDoc.Save( True, True )

' try to get first document in Latest news category

Set doc = view.GetDocumentByKey( "Latest news" )

' even though doc is saved, it doesn't appear in view yet

If ( doc Is Nothing ) Then

  Messagebox( "Refresh the view" )

End If

Call view.Refresh

' after refresh, try again

Set doc = view.GetDocumentByKey( "Latest news" )

If ( doc Is Nothing ) Then

  Messagebox( "Something's wrong" )

Else

  Messagebox( "Now that view is refreshed, doc appears" )

End If


Example: RefreshHideFormulas method

This script recalculates the hide-when formulas on the current document whenever a user exits a particular field. For example, a graphic on a form is hidden whenever Status = "Draft." The following script runs whenever the user exits the Status field. Therefore, when the user changes the Status field to "Draft" and exits the field, the graphic is hidden; when the user changes the Status field to "Final" and exits the field, the graphic is displayed.

Sub Exiting(Source As Field)

  Dim workspace As New NotesUIWorkspace

  Dim uidoc As NotesUIDocument

  Set uidoc = workspace.CurrentDocument

  Call uidoc.RefreshHideFormulas

End Sub


Example: RegisterNewCertifier method

The following script shows you how to register a new certifier ID file.

Dim reg As New NotesRegistration

Call reg.RegisterNewCertifier( "Lotus", _

         "c:\lotus\notes\cert2.ID", _

         "cpassword", "North America")


Example: RegisterNewServer method

The following script shows you how to register a new server ID file.

Dim reg As New NotesRegistration

reg.CertifierIDFile = "c:\lotus\notes\cert.ID"

reg.Expiration = Today + 1095

reg.IDType = ID_HIERARCHICAL

reg.IsNorthAmerican = False

reg.MinPasswordLength = 5

reg.OrgUnit = "Darn Thing"

reg.UpdateAddressbook = True

reg.StoreIDInAddressbook = True

Call reg.RegisterNewServer("Local", "c:\lotus\notes\Server2.ID", _

       "Lotus", "spassword", "cpassword", "Reading", _

       "Registering new Server", "MoonBeam", "Administrator", _

       "AddressBook")


Example: RegisterNewUser method

  1. The following script shows you how to register a new user ID file.

    2. Dim reg As New NotesRegistration

    reg.CreateMailDB = True

    reg.CertifierIDFile = "c:\lotus\notes\cert.ID"

    reg.Expiration = Today + 1095

    reg.IDType = ID_HIERARCHICAL

    reg.IsNorthAmerican = False

    reg.MinPasswordLength = 5

    reg.OrgUnit = "Darn Thing"

    reg.UpdateAddressbook = True

    reg.StoreIDInAddressbook = True

    Call reg.RegisterNewUser("Smith", "c:\lotus\notes\JSmith.ID", _

           "Gold", "Joseph", "V", "cpassword", "Reading", _

           "ToolKit Specialist", "mail\JSmith.nsf", "", _

           "password", NOTES_LIMITED_CLIENT)
  2. This example registers three new users and sets their alternate user name and the language for the alternate user name.

    3. Dim reg As New NotesRegistration

    Dim orgs (0 To 10) As String

    Dim langs (0 To 10) As String

    reg.CreateMailDB = True

    reg.CertifierIDFile = "c:\lotus\notes\cert.ID"

    reg.Expiration = Today + 1095

    reg.IDType = ID_HIERARCHICAL

    reg.IsNorthAmerican = False

    reg.MinPasswordLength = 5

    reg.OrgUnit = "Organization"

    reg.UpdateAddressbook = True

    reg.StoreIDInAddressbook = True

    orgs(1) = "Japanese OU"

    langs(1) = "ja"

    orgs(2) = "PRC OU"

    langs(2) = "zh-CN"

    orgs(3) = "Korean OU"

    langs(3) = "ko"

    reg.AltOrgUnit = orgs

    reg.AltOrgUnitLang = langs

    Call reg.RegisterNewUser("Taylor", "c:\lotus\notes\MTaylor.ID", _

           "Ankara","Mike" , "", "certpassword", "West", _

           "Engineer", "mail\MTaylor.nsf", "", _

           "password", NOTES_LIMITED_CLIENT, _

           "Japanese name for Mike", "ja")

    Call reg.RegisterNewUser("Miller", "c:\lotus\notes\JMiller.ID", _

           "Ankara","Jane" , "", "certpassword", "West", _

           "Engineer", "mail\JMiller.nsf", "", _

           "password", NOTES_LIMITED_CLIENT, _

           "Chinese name for Jane", "zh-CN")

    Call reg.RegisterNewUser("O'Brien", "c:\lotus\notes\SOBrien.ID", _

           "Ankara","Steve" , "", "certpassword", "East", _

           "Engineer", "mail\SOBrien.nsf", "", _

           "password", NOTES_LIMITED_CLIENT, _

           "Korean name for Steve", "ko")


Example: Reload method

This button script reloads the current front-end document from the corresponding back-end document.

Sub Click(Source As Button)

  Dim workspace As New NotesUIWorkspace

  Dim uidoc As NotesUIDocument

  Set uidoc = workspace.CurrentDocument

  If Not ( uidoc.IsNewDoc ) Then

    Call uidoc.Reload

  End If

End Sub


Example: Remove method

This script finds Shelly McPhail's entry in the access control list of the current database and removes it. Shelly is then no longer listed in the ACL, and has the -Default- access.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim acl As NotesACL

Dim entry As NotesACLEntry

Set db = session.CurrentDatabase

Set acl = db.ACL

Set entry = acl.GetEntry( "Shelly McPhail" )

Call entry.Remove

Call acl.Save


Examples: Remove method

  1. This script removes the CalculateTotals agent from the current database.

    2. Dim session As New NotesSession

    Dim db As NotesDatabase

    Set db = session.CurrentDatabase

    Forall a In db.Agents

      If ( a.Name = "CalculateTotals" ) Then

        Call a.Remove

      End If

    End Forall
  2. This script deletes the agent that's currently running. When the agent finishes running, it will no longer exist in the database.

    3. ' Self-destructing agent created 08/18/95 by N. Allen

    Dim session As New NotesSession

    Dim agent As NotesAgent

    Set agent = session.CurrentAgent

    Call agent.Remove
  3. This script finds the disabled agents in the current database that are owned by the current user, and asks if the user wants to delete them. If so, it deletes the agents from the database.

    4. The script uses an array of type NotesAgent, arbitrarily declared to be ten elements, to hold the agents that are disabled and owned by the current user.

    Sub Click(Source As Button)

      Dim session As New NotesSession

      Dim db As NotesDatabase

      Dim agentArray( 1 To 10 ) As NotesAgent

      Dim count As Integer

      Dim r As String

      Set db = session.CurrentDatabase

      count = 0

      ' find agents owned by current user and disabled

      Forall a In db.Agents

        If ( a.Owner = session.UserName ) And _

        Not ( a.IsEnabled ) Then

          count = count + 1

          Set agentArray( count ) = a

        End If

      End Forall

      r = Inputbox$( "You have " & count &  _

      " disabled agents. Delete them?" )

      If ( r = "yes" ) Or ( r = "y" ) Then

        ' go through each agent that's owned by current

        ' user and disabled

        Forall b In agentArray

          Call b.Remove

        End Forall

      End If

    End Sub


Example: Remove method

This script deletes BYEBYE.NSF if it has not been modified in the last 100 days.

Dim db As New NotesDatabase( "", "byebye.nsf" )

If ( ( Today - db.LastModified ) > 100 ) Then

  Call db.Remove

End If


Examples: Remove method

  1. This script removes a document from a database, unless another user has modified it.

    2. Dim doc As NotesDocument

    '...set value of doc...

    If ( doc.Remove( False ) = True ) Then

      Messagebox _

      ( "The document was deleted from the database." )

    Else

      Messagebox _

      ( "Doc not deleted. Another user modified it." )

    End If
  2. This script removes a document from a database, regardless of whether another user has modified it. It does not use the Remove method's return value.

    3. Dim doc As NotesDocument

    '...set value of doc...

    Call doc.Remove( True )
  3. This script gets the universal ID of the current UI document, marks the document for deletion and closes it. The script then retrieves the back-end NotesDocument object from the database and removes it with the NotesDocument Remove method.

    4. Dim session As New NotesSession

    Dim db As NotesDatabase

    Dim workspace As New NotesUIWorkspace

    Dim uidoc As NotesUIDocument

    Dim docA As NotesDocument

    Dim s As String

    Set db = session.CurrentDatabase

    Set uidoc = workspace.CurrentDocument

    Set docA = uidoc.document

    s = docA.UniversalID

    Call uidoc.deletedocument()

    Set docB = db.getDocumentByUNID(s)

    Call docB.Remove(True)

    Call workspace.viewrefresh()


Example: Remove method

This script removes a form from a database.

Dim session As New NotesSession

Dim db As NotesDatabase

Set db = session.CurrentDatabase

formNameIn = Lcase(Inputbox("Name of form?"))

Forall form In db.Forms

     If Lcase(form.Name) = formNameIn Then

          If Messagebox("Do you really want to delete " _

          & form.Name & "?", _

          4 + 32) = 6 Then

               Messagebox form.Name & " removed"

               Call form.Remove()

          Else

               Messagebox form.Name & " not removed"

          End If

          Exit Sub

     End If

End Forall

Messagebox "The form """ & formNameIn & """ does not exist"


Example: Remove method

This script removes the Useless item from a document.

Dim doc As NotesDocument

Dim item As NotesItem

'...set value of doc...

Set item = doc.GetFirstItem( "Useless" )

Call item.Remove

Call doc.Save( False, True )


Example: Remove method

This script removes the "City picture" embedded object from the Body item in a document.

Dim doc As NotesDocument

Dim rtitem As Variant

Dim object As NotesEmbeddedObject

'...set value of doc...

Set rtitem = doc.GetFirstItem( "Body" )

If ( rtitem.Type = RICHTEXT ) Then

  Set object = rtitem.GetEmbeddedObject( "City picture" )

  Call object.Remove

  Call doc.Save( True, True )

End If


Example: Remove method

This script deletes the Sales Leads view from the current database. Your salespeople are now in deep trouble.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim view As NotesView

Set db = session.CurrentDatabase

Set view = db.GetView( "Sales Leads" )

Call view.Remove


Examples: RemoveACLEntry method

This Visual Basic code removes the ACL entry specified by the EntryName text box.

Private Sub ACLRemove_Click()

Dim s As New NotesSession

s.Initialize

Dim dir As NotesDbDirectory

Dim db As NotesDatabase

Dim acl As NotesACL

Set dir = s.GetDbDirectory("")

Set db = dir.OpenDatabase("Web test")

Set acl = db.acl

If acl.GetEntry(SessionForm.EntryName) Is Nothing Then

    MsgBox SessionForm.EntryName, , "Entry does not exist"

Else

    Call acl.RemoveACLEntry(SessionForm.EntryName)

    Call acl.Save

End If

End Sub


Example: RemoveAll method

This example deletes all the documents collected by the FTSearch method if the number of documents in the collection does not equal 2.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim collection As NotesDocumentCollection

Set db = session.CurrentDatabase

Set collection = db.FTSearch("Annual reports", 10)

If collection.Count <> 2 Then

    Call collection.RemoveAll(False)

End If


Example: RemoveAll method

This script removes all of the documents associated with the entry December in the By Category view.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim view As NotesView

Dim vc As NotesViewCollection

Set db = seesion.CurrentDatabase

Set view = db.GetView("By Category")

Set vc = view.GetAllEntriesByKey("December")

Call vc.RemoveAll(True)


Example: RemoveAllFromFolder method

This example removes all the documents in the collection from the folder "Spicy" which is in another folder "Recipes."

Dim session As New NotesSession

Dim db As NotesDatabase

Dim collection As NotesDocumentCollection

Set db = session.CurrentDatabase

Set collection = db.FTSearch( "cayenne", 20 )

Call collection.RemoveAllFromFolder( "Recipes\Spicy" )


Example: RemoveAllFromFolder method

This script removes all the documents under the category "craft projects" from the Christmas folder and puts them in the "Leisure time" folder.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim view As NotesView

Dim vc As NotesViewEntryCollection

Set db = session.CurrentDatabase

Set view = db.GetView("Christmas")

Set vc = view.GetAllEntriesByKey("craft projects")

Call vc.RemoveAllFromFolder("Christmas")

Call vc.PutAllInfolder("Leisure time")


Examples: RemoveFromFolder method

  1. This example uses RemoveFromFolder to remove a document from the folder Jambalaya.

    2. Dim doc As NotesDocument

    '...set value of doc...

    Call doc.RemoveFromFolder( "Jambalaya" )
  2. This example uses RemoveFromFolder to remove a document from the folder Spicy, which is located inside the folder Recipes.

    3. Dim doc As NotesDocument

    '...set value of doc...

    Call doc.RemoveFromFolder( "Recipes\Spicy" )


Examples: RemoveItem method

  1. This script removes the Subject item from a document.

    2. Dim mainDoc As NotesDocument

    '...set value of mainDoc...

    Call mainDoc.RemoveItem( "Subject" )

    Call mainDoc.Save( True, True )
  2. This script removes all file attachments from a document.

    3. Dim doc As NotesDocument

    '...set value of doc...

    Call doc.RemoveItem( "$FILE" )

    Call doc.Save( True, True )
  3. This sub lets you change the name of any item in a document. First it uses ReplaceItemValue to put the contents of the item with the old name into a new item with the new name. Then it uses RemoveItem to remove the item with the old name.

    4. Sub changeField _

    ( doc As NotesDocument, oldName As String, _

    newName As String )

      If doc.HasItem( oldName ) Then

        Call doc.ReplaceItemValue( newName,  _

        doc.GetItemValue( oldName ) )

        Call doc.RemoveItem( oldName )

        Call doc.Save( False, True )

      End If

    End Sub
    For example, to change the name of the phone item to officePhone without losing the item's value, a script makes the following call:

    Dim doc as NotesDocument

    '...set value of doc...

    Call changeField( doc, "phone", "officePhone" )
  4. This sub takes a collection of documents and removes the stored form from each document. It uses RemoveItem to delete the five fields that make up a stored form in a document: $TITLE, $INFO, $WINDOWTITLE, $BODY and $ACTIONS.

    5. Sub removeStoredForm( collection As NotesDocumentCollection )

      Dim doc As NotesDocument

      For i = 1 To collection.Count

        Set doc = collection.GetNthDocument( i )

        If doc.HasItem( "$TITLE" ) Then

          formName = doc.GetItemValue( "$TITLE" )

          Call doc.ReplaceItemValue( "Form", formName )

          Call doc.RemoveItem( "$TITLE" )

          Call doc.RemoveItem( "$INFO" )

          Call doc.RemoveItem( "$WINDOWTITLE" )

          Call doc.RemoveItem( "$BODY" )

          Call doc.RemoveItem( "$ACTIONS" )

          Call doc.Save( True, True )

        End If

      Next

    End Sub


Example: Removing a document

This example performs a full-text search on a database and removes all documents containing the word "deleteme."

Sub Initialize

     Dim session As New NotesSession

     Dim db As NotesDatabase

     Set db = session.CurrentDatabase

     Call db.UpdateFTIndex(True)

     Set dc = db.FTSearch("deleteme", 0)

     For j = 1 To dc.Count

          Set doc = dc.GetNthDocument(j)

          Call doc.Remove(True)

     Next

End Sub


Example: Removing a view or folder

This example removes a user specified-view or folder from the current database.

Sub Click(Source As Button)

     Dim session As New NotesSession

     Dim db As NotesDatabase

     Dim view As NotesView

     Set db = session.CurrentDatabase

     viewName = Inputbox$("Name of view")

     If viewName = "" Then Exit Sub

     Set view = db.GetView(viewName)

     Call view.Remove

End Sub


Examples: Removing an item

  1. This example uses the Remove method of the NotesItem class to remove all the ModifiedBy items in the database. To handle multiple items with the same name, the code removes items in a loop that tests HasItem.

    2. Sub Initialize

         Dim session As New NotesSession

         Dim db As NotesDatabase

         Dim dc As NotesDocumentCollection

         Dim doc As NotesDocument

         Dim item As NotesItem

         Set db = session.CurrentDatabase

         Set dc = db.AllDocuments

         For j = 1 To dc.Count

              Set doc = dc.GetNthDocument(j)

              While doc.HasItem("ModifiedBy")

                   Set item = doc.GetFirstItem("ModifiedBy")

                   Call item.Remove

                   Call doc.Save(True, False)

              Wend

         Next

    End Sub
  2. This example uses the RemoveItem method of the NotesDocument class to remove all the ModifiedBy items in the database.

    3. Sub Initialize

         Dim session As New NotesSession

         Dim db As NotesDatabase

         Dim dc As NotesDocumentCollection

         Dim doc As NotesDocument

         Set db = session.CurrentDatabase

         Set dc = db.AllDocuments

         For j = 1 To dc.Count

              Set doc = dc.GetNthDocument(j)

              While doc.HasItem("ModifiedBy")

                   Call doc.RemoveItem("ModifiedBy")

                   Call doc.Save(True, False)

              Wend

         Next

    End Sub


Examples: Removing documents from a view entry collection

  1. This example removes all of the documents associated with the entries in the view entry collection called Fox.

    2. Sub Initialize

         Dim session As New NotesSession

         Dim db As NotesDatabase

         Dim view As NotesView

         Dim vc As NotesViewEntryCollection

         Set db = session.Currentdatabase

         Set view = db.GetView("By Category")

         Set vc = view.GetAllEntriesByKey("Fox")

         Call vc.RemoveAll(True)

    End Sub
  2. This example removes all of the documents associated with entries in a folder called Jazz.

    3. Sub Initialize

         Dim session As New NotesSession

         Dim db As NotesDatabase

         Dim view As NotesView

         Dim vc As NotesViewEntryCollection

         Set db = session.CurrentDatabase

         Set view = db.GetView("By Category")

         Set vc = view.GetAllEntriesByKey("Trumpet players")

         Call vc.RemoveAllFromFolder("Jazz")

    End Sub


Example: RenameRole method

This script renames the "HR Contact" role to the "Human Resources" role. Anyone who previously had the HR Contact role now has the Human Resources role instead.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim acl As NotesACL

Set db = session.CurrentDatabase

Set acl = db.ACL

Call acl.RenameRole( "HR Contact", "Human Resources" )

Call acl.Save


Example: RenderToRTItem method

This script creates a picture of document A and places it into the Body item of the newly-created document B.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim view As NotesView

Dim docA As NotesDocument

Dim docB As NotesDocument

Dim rtitem As NotesRichTextItem

Dim success As Variant

Set db = session.CurrentDatabase

'...set value of docA...

Set docB = New NotesDocument( db )

Set rtitem = New NotesRichTextItem( docB, "Body" )

docB.Form = "Main Topic"

docB.Subject = "It's a picture of the document"

Call docB.Save( True, True )

success = docA.RenderToRTItem( rtitem )

Call docB.Save( True, True )


Examples: ReplaceItemValue method

  1. This script changes the value of the EstimatedCost item to 122.

    2. Dim doc As NotesDocument

    Dim item As NotesItem

    '...set value of doc...

    Set item = doc.ReplaceItemValue( "EstimatedCost", 122 )

    Call doc.Save( True, True )
  2. This script achieves the same result using the extended class syntax.

    3. Dim doc As NotesDocument

    '...set value of doc...

    doc.EstimatedCost = 122

    Call doc.Save( True, True )
  3. This script changes the value of the EstimatedCost item to "Too much", which also changes the type of the item from Number to Text.

    4. Dim doc As NotesDocument

    Dim item As NotesItem

    '...set value of doc...

    Set item = doc.ReplaceItemValue _

    ( "EstimatedCost", "Too much" )

    Call doc.Save( True, True )


Example: ReplicaID property

This script displays the replica ID of the current database. For example, it might display "852561C1004D958F."

Dim session As New NotesSession

Dim db As NotesDatabase

Set db = session.CurrentDatabase

Messagebox( db.ReplicaID )


Example: Replicate method

This script replicates the current database with the database replica on the server Berlin.

Dim session As New NotesSession

Dim db As NotesDatabase

Set db = session.CurrentDatabase

Call db.Replicate( "Berlin" )


Examples: Replication class

  1. This script displays the date after which documents will not be included in replication (CutOffDate) and the number of days after which documents are automatically deleted (CutOffInterval) and then changes the interval to 30.

    2. Dim session As New NotesSession

    Dim db As NotesDatabase

    Dim rep As NotesReplication

    Set db = session.CurrentDatabase

    Set rep = db.ReplicationInfo

    Messagebox rep.CutOffDate

    Messagebox rep.CutOffInterval

      If rep.CutOffInterval <> 30 Then

        rep.CutOffInterval = 30

      End If

    Call rep.Save()
  2. This script deselects "Remove documents not modified in the last: __ days" in the replication settings if the CutOffInterval property is 30 days.

    3. Dim session As New NotesSession

    Dim db As NotesDatabase

    Dim rep As NotesReplication

    Set db = session.CurrentDatabase

    Set rep = db.ReplicationInfo

      If rep.CutOffInterval = 30 Then

        rep.CutOffDelete = False

      End If

    Call rep.Save()


Example: ReplicationInfo property

This script displays the cut off interval in the replication settings of a database.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim rep As NotesReplication

Set db = session.CurrentDatabase

Set rep = db.ReplicationInfo

Messagebox rep.cutoffinterval

Call rep.Save()


Example: Reset method

This script replicates the database, then resets the replication properties to their last saved settings.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim rep As NotesReplication

Set db = session.CurrentDatabase

Set rep = db.ReplicationInfo

Call db.Replicate("Xanadu")

Call rep.Reset()

Call rep.Save()


Examples: Responses property

These two scripts work together to place the currently open document (in the user interface) and its responses, including all responses-to-responses, in a folder. The first script is a form action script that the user can activate from a document on the workspace. It gets doc, the document on disk that corresponds to the currently open document, and places it in a folder of the user's choice. It then calls the PutAllResponsesInFolder sub.

Sub Click(Source As Button)

  Dim workspace As New NotesUIWorkspace

  Dim uidoc As NotesUIDocument

  Dim doc As NotesDocument

  Dim choice As String

  Set uidoc = workspace.CurrentDocument

  Set doc = uidoc.Document

  choice = Inputbox( "Please enter a folder name:", _

  "Which folder?" )

  Call doc.PutInFolder( choice )

  Call PutAllResponsesInFolder( doc, choice )

End Sub

The PutAllResponsesInFolder sub takes a parent document and a folder name, and places the responses and responses-to-responses of the parent document into the specified folder. The sub places each response to the parent document into the specified folder. For each response, the sub calls itself to place any responses to the response into the folder. This recursive behavior allows you to access every descendant of the parent document, no matter how many levels deep it is nested. If there are no responses, the sub exits.

Sub PutAllResponsesInFolder _

( doc As NotesDocument, folderName As String )

  Dim collection As NotesDocumentCollection

  Dim currentResponse As NotesDocument

  Set collection = doc.Responses

  Set currentResponse = collection.GetFirstDocument

  ' Put immediate responses to doc into the folder

  ' If there are none, sub exits and returns to calling sub

  While Not ( currentResponse Is Nothing )

    Call currentResponse.PutInFolder( folderName )

    ' Recursive call to put immediate responses to

    ' currentResponse in folder

    Call PutAllResponsesInFolder _

    ( currentResponse, folderName )

    Set currentResponse = collection.GetNextDocument _

    ( currentResponse )

  Wend

End Sub


Examples: Retrieving data from an external database

  1. This agent declares new ODBCConnection, ODBCQuery, and ODBCResultSet objects; connects to a data source; associates the ODBCConnection object with the ODBCQuery object and the ODBCResultSet object with the ODBCQuery object; specifies and executes a query; and examines the result set from the first to last row.

    2. Uselsx "*LSXODBC"

    Sub Initialize

         Dim con As New ODBCConnection

         Dim qry As New ODBCQuery

         Dim result As New ODBCResultSet

         Dim firstName As String

         Dim lastName As String

         Dim msg As String

         If Not con.ConnectTo("ATDB") Then

              Messagebox "Could not connect to ATDB",, _

                         "Error connecting"

              Exit Sub

         End If

         Set qry.Connection = con

         Set result.Query = qry

         qry.SQL = "SELECT * FROM STUDENTS ORDER BY LASTNAME"

         result.Execute

         msg = "Student names:" & Chr(10)

         If result.IsResultSetAvailable Then

              Do

                   result.NextRow

                   firstName = result.GetValue("FIRSTNAME")

                   lastName = result.GetValue("LASTNAME")

                   msg = msg & Chr(10) & firstName & " " _

                         & lastName

              Loop Until result.IsEndOfData

              result.Close(DB_CLOSE)

         Else

              Messagebox "No data retrieved for STUDENTS",, _

                         "No data"

              Exit Sub

         End If

         Messagebox msg,, "Student Names"

         con.Disconnect

    End Sub
  2. This script executes when the user exits from the Part_Number field in a Parts document. The script executes a query using the value of Part_Number in the WHERE clause of the SELECT statement, then fills in the PartName, Cost, and Description fields based on values in the retrieved record.

    3. Sub Exiting(Source As Field)

         Dim con As New ODBCConnection

         Dim qry As New ODBCQuery

         Dim res As New ODBCResultSet

         Dim ws As New Notesuiworkspace

         Dim uidoc As Notesuidocument

         Set uidoc = ws.CurrentDocument

         If con.ConnectTo("PARTS") Then

              Set qry.Connection = con

              qry.SQL =  _

                  "select * from PARTS where PART_NO = '" + _

              uidoc.FieldGetText("Part_Number") + "'"

              Set res.Query = qry

              res.Execute

              If res.IsResultSetAvailable = True Then

                   res.FirstRow

                   Call uidoc.FieldSetText("Part_Number", _

                   res.GetValue("PART_NO"))

                   Call uidoc.FieldSetText("Part_Name", _

                   res.GetValue("PART_NAME"))

                   Call uidoc.FieldSetText("Price", _

                   res.GetValue("COST"))

                   Call uidoc.FieldSetText("Description", _

                   res.GetValue("DESCRIPTION"))

              Else

                   Messagebox("No information found for " + _

                   uidoc.FieldGetText("Part_Number") )

              End If

              res.Close(DB_CLOSE)

              con.Disconnect

         Else

              Messagebox("Could not connect to database server")

         End If

    End Sub
  3. This agent sets the parameters in an SQL query before executing it. NumParameters is used as the upper bound of a loop, and GetParameterName is used to prompt for each parameter value.

    4. Sub Initialize

         Dim con As New ODBCConnection

         Dim qry As New ODBCQuery

         Dim result As New ODBCResultSet

         Dim inputParameter As String

         Dim firstName As String

         Dim lastName As String

         Dim msg As String

         Set qry.Connection = con

         Set result.Query = qry

         con.ConnectTo("ATDB")

         qry.SQL = "SELECT * FROM STUDENTS" & _

         " WHERE FIRSTNAME = ?firstName? AND LASTNAME = _

           ?lastName?"

         For i = 1 To result.NumParameters

              inputParameter = _

              Inputbox$(result.GetParameterName(i), _

              "Parameter " & i)

              Call result.SetParameter(i, "'" _

                   & inputParameter & "'")

         Next

         result.Execute

         msg = "Student name: " & Chr(10)

         If result.IsResultSetAvailable Then

              result.NextRow

              studentNo = result.GetValue _

                          ("STUDENT_NO", studentNo)

              firstName = result.GetValue _

                          ("FIRSTNAME", firstName)

              lastName = result.GetValue("LASTNAME", lastName)

              msg = msg & Chr(10) & studentNo & " " & _

                    firstName & " " & lastName

         Else

              Messagebox "Cannot get result set"

              Exit Sub

         End If

         Messagebox msg,, "Student name"

         con.Disconnect

    End Sub

See also
Retrieving data from an external database


Example: RevokeAccess method

This script revokes David Perron's access to the current database.

Dim session As New NotesSession

Dim db As NotesDatabase

Set db = session.CurrentDatabase

Call db.RevokeAccess( "David Perron" )


Example: RightMargin property

This example sets the right margin property of a rich-text paragraph style object.

Dim session As New NotesSession

Dim db As NotesDatabase

Set db = session.Currentdatabase

Dim doc As New NotesDocument(db)

Call doc.AppendItemValue("From", session.Username)

Call doc.AppendItemValue("subject", _

"Meeting agenda")

Dim rtpStyle As NotesrichTextParagraphStyle

Set rtpStyle = session.CreateRichTextParagraphStyle

Dim richText As New NotesRichTextItem(doc, "Body")

rtpStyle.RightMargin = RULER_ONE_INCH

Call richText.AppendParagraphStyle(rtpStyle)

Call richText.AppendText("Where are we now?")

Call richText.AddNewLine(1)

Call richText.AppendText (" Where do we go from here.")

Call doc.Save(True, False)


Examples: Roles property

  1. This script displays the name of every role in the current database. For example, it might display "[HR Contact]," "[Supervisor]," and "[Project Leader]."

    2. Dim session As New NotesSession

    Dim db As NotesDatabase

    Dim acl As NotesACL

    Set db = session.CurrentDatabase

    Set acl = db.ACL

    Forall r In acl.Roles

      Messagebox( r )

    End Forall
  2. This script lets the user enter a role name into a dialog box. The script then displays the name of each entry for which the role is enabled in a field on the current document called People. The script adds brackets to the role name that the user enters, and then uses the Roles property to make sure that the name exists in the current database. If not, an error message is displayed; if so, the script continues.

    3. Dim workspace As New NotesUIWorkspace

    Dim uidoc As NotesUIDocument

    Dim session As New NotesSession

    Dim db As NotesDatabase

    Dim acl As NotesACL

    Dim entry As NotesACLEntry

    Dim roleName As String

    Dim foundRole As Variant

    Set uidoc = workspace.CurrentDocument

    Set db = session.CurrentDatabase

    Set acl = db.ACL

    roleName = Inputbox$( "Enter the name of the role" )

    ' add brackets to role

    roleName = "[" & roleName & "]"

    foundRole = False

    ' check to see if the role exists in the database

    Forall r In acl.Roles

      If ( r = roleName ) Then

        foundRole = True

        Exit Forall

      End If

    End Forall

    If ( foundRole = False ) Then

      Messagebox _

      ( "Sorry, " & roleName & " is not a role" )

    ' if the role exists, check each acl entry to see if role

    ' is enabled for entry

    ' if so, add entry name to the People field

    ' on the current document,

    ' followed by a semicolon, the multi-value separator

    Else

      Set entry = acl.GetFirstEntry

      While Not ( entry Is Nothing )

        If ( entry.IsRoleEnabled( roleName ) = True ) Then

          Call uidoc.FieldAppendText _

          ( "People", entry.Name & ";" )

        End If

        Set entry = acl.GetNextEntry( entry )

      Wend

    End If

    ' refresh current document so People field displays nicely

    Call uidoc.Refresh


Example: Roles property

This script displays all the roles that are enabled for Bob Kidder. For example, the script might display "[Project Leader]" and "[Writer]."

Dim session As New NotesSession

Dim db As NotesDatabase

Dim acl As NotesACL

Dim entry As NotesACLEntry

Set db = session.CurrentDatabase

Set acl = db.ACL

Set entry = acl.GetEntry( "Bob Kidder" )

Forall r In entry.Roles

  Messagebox( r )

End Forall


Example: RowLines property

This script shows the number of lines in each row of the By Category view of the current database.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim view As NotesView

Set db = session.CurrentDatabase

Set view = db.GetView("By Category")

Messagebox "Number of row lines in view: " & view.RowLines


Examples: Ruler property

These two scripts work together. The first displays the ruler whenever the user places the insertion point in a particular field. The second hides the ruler whenever the user moves the insertion point out of the field.

Sub Entering(Source As Field)

  Dim workspace As New NotesUIWorkspace

  Dim uidoc As NotesUIDocument

  Set uidoc = workspace.CurrentDocument

  uidoc.Ruler = True

End Sub

Sub Exiting(Source As Field)

  Dim workspace As New NotesUIWorkspace

  Dim uidoc As NotesUIDocument

  Set uidoc = workspace.CurrentDocument

  uidoc.Ruler = False

End Sub


Example: Run method

  1. This agent runs the agent named "Agent to be run LotusScript."

    2. Sub Initialize

        Dim s As New NotesSession

        Dim db As NotesDatabase

        Dim agent As NotesAgent

        Set db = s.CurrentDatabase

        Set agent = db.GetAgent("Agent to be run LotusScript")

        If agent.Run = 0 Then

             Messagebox "Agent ran",, "Success"

        Else

            Messagebox "Agent did not run",, "Failure"

        End If

    End Sub
    This is "Agent to be run LotusScript."

    Sub Initialize

        Dim s As New NotesSession

        Dim agent As NotesAgent

        Set agent = s.CurrentAgent

        Dim db As NotesDatabase

        Set db = s.CurrentDatabase

        Dim memo As New NotesDocument(db)

        memo.Form = "Memo"

        memo.SendTo = s.UserName

        memo.Subject = "Message from LotusScript agent"

        memo.Body = "The agent is running as " & s.UserName

        Call memo.Send(False)

    End Sub
  2. This agent runs the agent named "Agent to be run parameter LotusScript," passing it the NoteID of a newly created document.

    3. Sub Initialize

        Dim s As New NotesSession

        Dim db As NotesDatabase

        Dim doc As NotesDocument

        Dim agent As NotesAgent

        Set db = s.CurrentDatabase

        REM Create document containing data to be passed

        Set doc = New NotesDocument(db)

        doc.TriggerUserName = s.UserName

        Call doc.Save(True, False)

        REM Start agent and pass NoteID of document

        Set agent = db.GetAgent("Agent to be run parameter LotusScript")

        If agent.Run(doc.NoteID) = 0 Then

            Messagebox "Agent ran",, "Success"

        Else

            Messagebox "Agent did not run",, "Failure"

        End If

    End Sub
    This is "Agent to be run parameter LotusScript." It accesses the passed NoteID through ParameterDocID, accesses the referenced document, and removes it.

    Sub Initialize

        Dim s As New NotesSession

        Dim agent As NotesAgent

        Set agent = s.CurrentAgent

        Dim db As NotesDatabase

        Dim doc As NotesDocument

        Set db = s.CurrentDatabase

        REM Get document used for passing data

        Set doc = db.GetDocumentByID(agent.ParameterDocID)

        REM Send mail containing passed data

        Dim memo As New NotesDocument(db)

        memo.Form = "Memo"

        memo.SendTo = s.UserName

        memo.Subject = "Message from LotusScript agent"

        memo.Body = "The agent was started by " & doc.TriggerUserName(0)

        Call memo.Send(False)

        REM Delete document used for passing data

        Call doc.Remove(True)

    End Sub


Example: RunOnServer method

  1. This agent runs the agent named "Agent to be run LotusScript."

    2. Sub Initialize

        Dim s As New NotesSession

        Dim db As NotesDatabase

        Dim agent As NotesAgent

        Set db = s.CurrentDatabase

        Set agent = db.GetAgent("Agent to be run LotusScript")

        If agent.RunOnServer = 0 Then

             Messagebox "Agent ran",, "Success"

        Else

            Messagebox "Agent did not run",, "Failure"

        End If

    End Sub
    This is "Agent to be run LotusScript."

    Sub Initialize

        Dim s As New NotesSession

        Dim agent As NotesAgent

        Set agent = s.CurrentAgent

        Dim db As NotesDatabase

        Set db = s.CurrentDatabase

        Dim memo As New NotesDocument(db)

        memo.Form = "Memo"

        memo.SendTo = s.UserName

        memo.Subject = "Message from LotusScript agent"

        memo.Body = "The agent is running as " & s.UserName

        Call memo.Send(False)

    End Sub
  2. This agent runs the agent named "Agent to be run parameter LotusScript," passing it the NoteID of a newly created document.

    3. Sub Initialize

        Dim s As New NotesSession

        Dim db As NotesDatabase

        Dim doc As NotesDocument

        Dim agent As NotesAgent

        Set db = s.CurrentDatabase

        REM Create document containing data to be passed

        Set doc = New NotesDocument(db)

        doc.TriggerUserName = s.UserName

        Call doc.Save(True, False)

        REM Start agent and pass NoteID of document

        Set agent = db.GetAgent("Agent to be run parameter LotusScript")

        If agent.RunOnServer(doc.NoteID) = 0 Then

            Messagebox "Agent ran",, "Success"

        Else

            Messagebox "Agent did not run",, "Failure"

        End If

    End Sub
    This is "Agent to be run parameter LotusScript." It accesses the passed NoteID through ParameterDocID, accesses the referenced document, and removes it.

    Sub Initialize

        Dim s As New NotesSession

        Dim agent As NotesAgent

        Set agent = s.CurrentAgent

        Dim db As NotesDatabase

        Dim doc As NotesDocument

        Set db = s.CurrentDatabase

        REM Get document used for passing data

        Set doc = db.GetDocumentByID(agent.ParameterDocID)

        REM Send mail containing passed data

        Dim memo As New NotesDocument(db)

        memo.Form = "Memo"

        memo.SendTo = s.UserName

        memo.Subject = "Message from LotusScript agent"

        memo.Body = "The agent was started by " & doc.TriggerUserName(0)

        Call memo.Send(False)

        REM Delete document used for passing data

        Call doc.Remove(True)

    End Sub


Example: Save method

This script changes replication priority of the current database and saves the result.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim rep As NotesReplication

Set db = session.CurrentDatabase

Set rep = db.ReplicationInfo

  If rep.Priority <> DB_REPLICATION_PRIORITY_HIGH Then

    rep.Priority = DB_REPLICATION_PRIORITY_HIGH

  End If

Call rep.Save()


Examples: Save method

  1. This script adds a new role to the access control list of the current database, and saves the ACL. If the script did not call Save, the role would not be added.

    2. Dim session As New NotesSession

    Dim db As NotesDatabase

    Dim acl As NotesACL

    Set db = session.CurrentDatabase

    Set acl = db.ACL

    Call acl.AddRole( "HR Contact" )

    Call acl.Save
  2. This script prompts the user for the name of a person. The script creates a new entry for the person in the ACL of the current database, and gives the entry Author access. The script then asks the user to confirm the ACL change. If the user selects Yes, the change is saved. If the user selects No, the change is not saved.

    3. In order to use the constants associated with the Messagebox function, this script must include the file LSCONST.LSS.

    Dim session As New NotesSession

    Dim db As NotesDatabase

    Dim acl As NotesACL

    Dim entry As NotesACLEntry

    Dim newName As String

    Dim confirm As Integer

    Set db = session.CurrentDatabase

    Set acl = db.ACL

    newName = Inputbox$ _

    ( "Who do you want to add?", "Name" )

    Set entry = New NotesACLEntry _

    ( acl, newName, ACLLEVEL_AUTHOR )

    confirm = Messagebox _

    ( "Are you sure?", MB_YESNO, "Confirm" )

    If ( confirm = IDYES ) Then

      Call acl.Save

    End If


Examples: Save method

  1. This script creates and saves a new document in the current database. Because the document is new, there is no chance of conflicting edits, so the first parameter is False.

    2. Dim session As New NotesSession

    Dim db As NotesDatabase

    Dim doc As NotesDocument

    Set db = session.CurrentDatabase

    Set doc = New NotesDocument( db )

    doc.Form = "Main Topic"

    doc.Subject = "Here's a new document"

    Call doc.Save( False, False )
  2. This view action script changes the Status item on each document selected in a view. If someone else edits one of the documents at the same time, the document is not saved. Instead, a response document that contains the change to the Status item is created and saved.

    3. Dim session As New NotesSession

    Dim db As NotesDatabase

    Dim collection As NotesDocumentCollection

    Dim doc As NotesDocument

    Set db = session.CurrentDatabase

    Set collection = db.UnprocessedDocuments

    Set doc = collection.GetFirstDocument()

    While Not(doc Is Nothing)

        doc.Status = "Processed by view action"

        Call doc.Save( False, True )

        Set doc = collection.GetNextDocument( doc)

    Wend
  3. This view action script changes the Status item on each document selected in a view. If someone else edits one of the documents at the same time, the document is not saved. For each selected document, the script displays a message informing the user if the document was saved or not.

    4. Dim session As New NotesSession

    Dim db As NotesDatabase

    Dim collection As NotesDocumentCollection

    Dim doc As NotesDocument

    Set db = session.CurrentDatabase

    Set collection = db.UnprocessedDocuments

    Set doc = collection.GetFirstDocument()

    While Not(doc Is Nothing)

        doc.Status = "Processed by view action"

        If ( doc.Save( False, False ) = True ) Then

            Messagebox "Document " & doc.UniversalID & " successfully saved"

        Else

            Messagebox "Document " & doc.UniversalID & " was not saved"

        End If

        Set doc = collection.GetNextDocument( doc)

    Wend
  4. This script changes the Status item in a document. Because the first parameter is True, the document gets saved, even if someone else edits the document while the script runs.

    5. Dim doc As NotesDocument

    '...set value of doc...

    doc.Status = "This change gets saved no matter what"

    Call doc.Save( True, True )


Examples: SavedData property

  1. This script gets the SavedData document for the current agent script and sets its RunDate item to today's date.

    2. Dim session As New NotesSession

    Dim doc As NotesDocument

    Set doc = session.SavedData

    doc.RunDate = Date

    Call doc.Save( True, True )
  2. This agent script compares the maximum number of leads generated by a salesperson in the current week with the maximum number of leads generated last week. The script checks a view that contains Lead documents filled out by each salesperson. The first column in the view sorts the number of leads generated by each salesperson in descending order, so that the Lead document with the highest number of leads is first in the view. The NumLeads item on this document (which represents the maximum number of leads generated this week) is compared with the MaxLeads item on the SavedData document (which represents the maximum number of leads generated last week), and the Summary item is updated accordingly. The MaxLeads item on the SavedData document is then updated and both documents are saved.

Sub Initialize

  Dim session As New NotesSession

  Dim db As NotesDatabase

  Dim view As NotesView

  Dim doc, agentDoc As NotesDocument

  Dim d As Integer

  Set db = session.CurrentDatabase

  Set view = db.GetView _

  ( "This week's leads by salesperson" )

  ' first document in view has the most leads

  Set doc = view.GetFirstDocument

  Set agentDoc = session.SavedData

  ' the first time agent runs,

  ' there are no items on SavedData

  ' so set the MaxLeads item to zero

  If Not( agentDoc.HasItem( "MaxLeads" ) ) Then

    agentDoc.MaxLeads = 0

    Call agentDoc.Save( True, True )

  End If

  d = doc.NumLeads( 0 ) - agentDoc.MaxLeads( 0 )

  If ( d > 0 ) Then

    doc.Summary = Abs( d ) & _

    " more leads than last week's max."

  Elseif ( d < 0 ) Then

    doc.Summary = Abs( d ) & _

    " less leads than last week's max..."

  Else

    doc.Summary = _

    "You matched last week's max number of leads."

  End If

  ' put this week's max leads onto SavedData

  agentDoc.MaxLeads = doc.NumLeads

  Call doc.Save( True, True )

  Call agentDoc.Save( True, True )

End Sub


Examples: SaveMessageOnSend property

  1. This script sets the SaveMessageOnSend property for NotesDatabase object doc to True:

    2. Dim doc As NotesDocument

    '...set value of doc..

    doc.SaveMessageOnSend = True
  2. This example creates, mails, and saves a new document in the current database. The document Form is set to Main Topic so that the document displays properly in the database; the form is also mailed along with the document so that the document displays properly in the recipient's mail database.

    3. Dim session As New NotesSession

    Dim db As NotesDatabase

    Dim doc As NotesDocument

    Set db = session.CurrentDatabase

    Set doc = New NotesDocument( db )

    doc.SaveMessageOnSend = True

    doc.Form = "Main Topic"

    doc.Subject =  _

    "Here's a new document that's going to be saved and mailed."

    Call doc.Send( True, "Carl Pycha" )

See also
Mailing a document


Example: SaveNewVersion method

This form action script saves the changes that have been made to the current document. The changes are saved in a new document, which becomes a response document to the original, the parent document of the original, or a sibling document of the original, depending on the version option on the form.

Sub Click(Source As Button)

  Dim workspace As New NotesUIWorkspace

  Dim uidoc As NotesUIDocument

  Set uidoc = workspace.CurrentDocument

  Call uidoc.SaveNewVersion

End Sub


Examples: SaveToDisk property

This example saves a document except for the "Temp" item. Other scripts in the form have initialized and manipulated the NotesDocument object and its items.

(Globals) (Declarations)

Dim doc As NotesDocument

Sub Queryclose(Source As Notesuidocument, Continue As Variant)

     Dim item As NotesItem

     Set item = doc.GetFirstItem("Temp")

     item.SaveToDisk = False

     Call doc.Save(True, False)

End Sub


Examples: Search method

  1. This script uses @IsResponseDoc to get a collection of all the response documents in a database that were created or modified after December 1, 1994.

    2. Dim db As New NotesDatabase("Katmandu","somedocs.nsf")

    Dim collection As NotesDocumentCollection

    Dim dateTime As New NotesDateTime("12/01/94")

    Set collection = db.Search("@IsResponseDoc",dateTime,0)
  2. This script reminds project participants of their due date by mailing them a Project document from a database. The ReminderDate item on each document is used to indicate when a reminder should be sent. The Search method gets all Project documents whose ReminderDate item is set to today, mails the document, and updates the ReminderDate field to one week later.

    3. Sub Initialize

      Dim db As New NotesDatabase("","reminder.nsf")

      Dim collection As NotesDocumentCollection

      Dim doc As NotesDocument

      Dim dateTime As New NotesDateTime("12/01/94")

      Dim nextDateTime As NotesDateTime

      searchFormula$ = "Form = ""Project"" _

                    & ReminderDate = @Today"

      Set collection = db.Search(searchFormula$,dateTime,0)

      ' Create a date that's one week from today.

      ' That's when the project participants

      ' get their next reminder.

      Set nextDateTime = New NotesDateTime("Today")

      Call nextDateTime.AdjustDay(7)

      ' For each document with reminder date today,

      ' send document to project participants

      ' Then update the ReminderDate field

      ' with a date one week from today.

      For i = 1 To collection.Count

        Set doc = collection.GetNthDocument(i)

        Call doc.Send( True )

        Call doc.ReplaceItemValue("ReminderDate",  _

                      nextDateTime.LSLocalTime )

        Call doc.Save( True, False )

      Next

    End Sub


Example: SelectAll method

This form action script copies the contents of the FirstDraft field, and pastes it into the Revision field.

Sub Click(Source As Button)

  Dim workspace As New NotesUIWorkspace

  Dim uidoc As NotesUIDocument

  Set uidoc = workspace.CurrentDocument

  Call uidoc.GotoField( "FirstDraft" )

  Call uidoc.SelectAll

  Call uidoc.Copy

  Call uidoc.GotoField( "Revision" )

  Call uidoc.Paste

End Sub


Examples: Send method

  1. This script mails a document and its form. The document is mailed to the recipients contained in the SendTo item of the document.

    2. Dim doc as NotesDocument

    '...set value of doc...

    Call doc.Send( True )
  2. This script sets the value of the SendTo item in a document. It then mails the document and its form. The document gets mailed to Carl Pycha.

    3. Call doc.ReplaceItemValue( "SendTo", "Carl Pycha" )

    Call doc.Save( False, True )

    Call doc.Send( True )
  3. This script mails a document to Sally Bowles. The form is not mailed.

    4. Call doc.Send( False, "Sally Bowles" )
  4. This script mails a document and its form to Jim Dinauer, Betty Dinauer, and Mary Sticka.

    5. Dim recipients( 1 To 3 ) As String

    recipients( 1 ) = "Jim Dinauer"

    recipients( 2 ) = "Betty Dinauer"

    recipients( 3 ) = "Mary Sticka"

    Call doc.Send( True, recipients )
  5. This script mails a document to anyone listed in its DocAuthor field.

    6. Call doc.Send( True, doc.DocAuthor )
  6. This script creates a new document in the current database and mails it to Elissa Minty.

    7. Dim session As New NotesSession

    Dim db As NotesDatabase

    Dim doc As NotesDocument

    Set db = session.CurrentDatabase

    Set doc = New NotesDocument( db )

    doc.Form = "Memo"

    doc.SendTo = "Elissa Minty"

    doc.Subject = "Here's the document you wanted"

    Call doc.Send( False )


Example: Send method

This script sets the contents of the SendTo field based on the contents of the Status field, and then mails the document. Before the document is saved, the SendTo field gets the manager's name if the Status is New, the HR contact's name if the Status is Approved, and the employee's name if the Status is rejected.

Sub Querysave(Source As Notesuidocument, Continue As Variant)

  s = source.FieldGetText( "Status" )

  Select Case s

  Case "New" :

    Call source.FieldSetText _

    ( "SendTo", source.FieldGetText( "Manager" ) )

  Case "Approved" :

    Call source.FieldSetText _

    ( "SendTo", source.FieldGetText( "HRContact" ) )

  Case "Rejected" :

    Call source.FieldSetText _

    ( "SendTo", source.FieldGetText( "Employee" ) )

  End Select

  Call source.Send

End Sub


Examples: SentByAgent property

  1. This script checks if a document was sent by a script and, if so, deletes it.

    2. Dim doc As NotesDocument

    '...set value of doc...

    If doc.SentByAgent Then

      Call doc.Remove( True )

    End If
  2. This agent script runs when new mail is received in the current database, and processes newly received mail documents. The script checks each mail document to see if it was sent by a person; if so, it sends a reply; if not, it does nothing.

    3. Dim session As New NotesSession

    Dim db As NotesDatabase

    Dim collection As NotesDocumentCollection

    Dim memo As NotesDocument

    Dim reply As NotesDocument

    Set db = session.CurrentDatabase

     ' get new mail memos

    Set collection = db.UnprocessedDocuments

    Set memo = collection.GetFirstDocument()

    While Not(memo Is Nothing)

        If Not( memo.SentByAgent ) Then

            Set reply = memo.CreateReplyMessage( False )

            reply.Subject = "Re: " & memo.Subject( 0 )

            reply.Body = _

            "I'm out of the office until 3/15. John."

            Call reply.Send( False )

        End If

        Call session.UpdateProcessedDoc( memo )

        Set memo = collection.GetNextDocument(memo)

    Wend


Example: Server property

This script displays a message about the current database.

Dim session As New NotesSession

Dim db As NotesDatabase

Set db = session.CurrentDatabase

If ( db.Server = "" ) Then

  Messagebox( "This database is local." )

Else

  Messagebox( "This database is on a server." )

End If


Example: ServerName property

This script gets the name of the server that the current agent is running on. For example, if this agent is scheduled to run once a week on the server Osaka, the ServerName property returns "Osaka."

Dim session As New NotesSession

Dim agent As NotesAgent

Dim server As String

Set agent = session.CurrentAgent

server = agent.ServerName


Examples: ServerName property

This Visual Basic code displays the server name or an exception message if it is running on a client.

Private Sub ServerName_Click()

Dim s As New NotesSession

s.Initialize

If s.ServerName <> Null Then

    MsgBox s.ServerName, , "ServerName"

Else

    MsgBox "Running on a client", , "Not a server"

End If

End Sub


Examples: SetCurrentLocation method

  1. This script sets the current workstation location to Internet.

    2. Dim workspace As New NotesUIWorkspace

    Call workspace.SetCurrentLocation("Internet")
  2. This script launches the Choose Location dialog and allows the use to select the location from a list.

    3. Dim workspace As New NotesUIWorkspace

    Call workspace.SetCurrentLocation("")


Examples: SetEnvironmentVar method

  1. This script sets the value of the HomeTown environment variable to "Salvador." The following line gets added to the user's NOTES.INI (or Notes Preferences) file: $HomeTown=Salvador

    2. Dim session As New NotesSession

    Call session.SetEnvironmentVar( "HomeTown", "Salvador" )
  2. These two form scripts work together to set and retrieve the HomeTown environment variable. The first script places the contents of the HomeTown environment variable into the HomeTown field of a newly-created document. Every time the user composes a document with the form, the HomeTown field is automatically filled in with the value of the environment variable. The second script places the contents of the HomeTown field into the HomeTown environment variable whenever the user saves the document.

    3. Sub Postopen(Source As Notesuidocument)

      Dim session As New NotesSession

      town = session.GetEnvironmentString( "HomeTown" )

      If source.IsNewDoc Then

        Call source.FieldSetText( "HomeTown",  town )

      End If

    End Sub

    Sub Querysave(Source As Notesuidocument, _

    Continue As Variant)

      Dim session As New NotesSession

      Call session.SetEnvironmentVar _

      ("HomeTown",source.FieldGetText("HomeTown"))

    End Sub


Examples: SetNoteLink method

  1. This example sets the Type property of the first entry in the products outline to Link - Database and the Value property to the name of the database being linked to -- in this case, it's a database called urlTester.nsf. Note that notesDatabase is the first parameter and does not require empty objects to be passed for the remaining two parameters.

    2. Dim session As New NotesSession

    Dim db As NotesDatabase

    Dim db2 As New NotesDatabase("","")

    Dim outline As NotesOutline

    Dim entry As NotesOutlineEntry

    Set db = session.CurrentDatabase

    Set outline = db.GetOutline("products")

    Set entry = outline.GetFirst()

    Call db2.Open("","urlTester.nsf")

    Call entry.SetNoteLink(db2)

    Call outline.save()
  2. This example sets the Type property of the child of the first entry in the products outline to Link - View and the Value property to By Category. Note that because notesView is the second parameter, an empty object is passed in for the first parameter, but the third parameter is not needed.

    3. Dim session As New NotesSession

    Dim db As NotesDatabase

    Dim outline As NotesOutline

    Dim entryA As NotesOutlineEntry

    Dim entryB As NotesOutlineEntry

    Dim v As NotesView

    Dim emptyDB As NotesDatabase

    Set db = session.CurrentDatabase

    Set v = db.GetView("By Category")

    Set outline = db.GetOutline("products")

    Set entryA = outline.GetFirst()

    Set entryB = outline.getChild(entryA)

    Call entryB.SetNoteLink(emptyDB,v)

    Call outline.save()
  3. This example sets the Type property of the last entry in the products outline to Link and the Value property to the first document in the document collection. Note that the first and second parameters are passed in as empty objects because the notesDocument is the third parameter.

    4. Dim session As New NotesSession

    Dim db As NotesDatabase

    Dim collection As NotesDocumentCollection

    Dim doc As NotesDocument

    Dim outline As NotesOutline

    Dim entry As NotesOutlineEntry

    Dim v As NotesView

    Dim emptyDB As NotesDatabase

    Dim emptyView As NotesView

    Set db = session.CurrentDatabase

    Set collection = db.AllDocuments

    Set doc=collection.GetFirstDocument

    Set outline = db.GetOutline("products")

    Set entry = outline.GetLast()

    Call entry.SetNoteLink(emptyDB,emptyView,doc)

    Call outline.save()


Examples: SetNow method

  1. This script creates a new NotesDateTime with the default date, and then resets it to the current date and time. For example, if the SetNow method executes at 8:04:04 PM on August 15, 1996, then dateTime represents 08/15/96 08:04:04 PM.

    2. Dim dateTime As New NotesDateTime( "" )

    Call dateTime.SetNow
  2. This script sets the PurgeDate item in a document to two months from now. For example, if the SetNow method executes at 8:04:04 PM on August 15, 1996, then PurgeDate has a value of 10/15/96 8:04:04 PM.

    3. Dim doc As NotesDocument

    '...set value of doc...

    Dim dateTime As New NotesDateTime( "" )

    Call dateTime.SetNow

    Call dateTime.AdjustMonth( 2 )

    Set doc.PurgeDate = dateTime

    Call doc.Save( True, True )


Example: SetParameter method

This example shows a form action (the Click sub) that sets the parameters for the SQL query in the Postopen sub. Although the query in the Postopen sub contains exactly two string parameters, the action works for a variable number of string parameters. Note that the Click sub places single quotes around the value of the string parameter.

Uselsx "*LSXODBC"

Dim con As ODBCConnection

Dim qry As ODBCQuery

Dim result As ODBCResultSet

Sub Postopen(Source As Notesuidocument)

     Set con = New ODBCConnection

     Set qry = New ODBCQuery

     Set result = New ODBCResultSet

     Set qry.Connection = con

     Set result.Query = qry

     con.ConnectTo("ATDB")

     qry.SQL = "SELECT * FROM STUDENTS WHERE " & _

     "LASTNAME = ?lastName? AND FIRSTNAME = ?firstName?"

End Sub

Sub Click(Source As Button)

     Dim inputParameter As String

     For i = 1 To result.NumParameters

          inputParameter = Inputbox$(result.GetParameterName(i), _

          "Parameter " & i)

          Call result.SetParameter(i, "'" &  _

                                  inputParameter & "'")

     Next

End Sub

Sub Queryclose(Source As Notesuidocument, Continue As Variant)

     result.Close(DB_CLOSE)

     con.Disconnect

End Sub


Example: SetTab method

This script sets a tab in a rich-text paragraph style object.

Dim session As New NotesSession

Dim db As NotesDatabase

Set db = session.CurrentDatabase

Dim doc As New NotesDocument(db)

Call doc.AppendItemValue("From", session.UserName)

Call doc.AppendItemValue("Subject", _

     "Meeting time changed")

Dim rtpStyle As NotesRichTextParagraphStyle

Dim pos As Long

Dim interval As Long

Set rtpStyle = session.CreateRichTextParagraphStyle

pos = RULER_ONE_INCH

Call rtpStyle.SetTab(pos, TAB_DECIMAL)

Dim richText As New NotesRichTextItem(doc, "Body")

Call richText.AppendParagraphStyle(rtpStyle)

Call richText.AddTab(1)

Call richText.AppendText("The meeting is at 2:00 not 3:00")

Call doc.Save(True, False)


Example: SetTabs method

This example sets tabs at a regular interval in a rich-text paragraph style object.

Dim session As New NotesSession

Dim db As NotesDatabase

Set db = session.CurrentDatabase

Dim doc As New NotesDocument(db)

Call doc.AppendItemValue("From", session.UserName)

Call doc.AppendItemValue("Subject", _

     "Meeting time changed")

Dim rtpStyle As NotesRichTextParagraphStyle

Dim pos As Long

Dim interval As Long

Set rtpStyle = session.CreateRichTextParagraphStyle

pos = RULER_ONE_INCH

interval = RULER_ONE_CENTIMETER

Call rtpStyle.SetTabs(3, pos, interval, TAB_DECIMAL)

Dim richText As New NotesRichTextItem(doc, "Body")

Call richText.AppendParagraphStyle(rtpStyle)

Call richText.AddTab(1)

Call richText.AppendText("One")

Call richText.AddTab(1)

Call richText.AppendText("Two")

Call richText.AddTab(1)

Call richText.AppendText("Three")

Call doc.Save(True, False)


Example: SetTargetFrame method

This script opens a page into a specific target frame.

Dim workspace As New NotesUIWorkspace

Call workspace.SetTargetFrame("top")

Call workspace.OpenPage("banner")


Example: SetValue method

This agent changes the value of a row and column specified by the user.

Uselsx "*LSXODBC"

Sub Initialize

     Dim con As New ODBCConnection

     Dim qry As New ODBCQuery

     Dim result As New ODBCResultSet

     Dim msg As String

     Set qry.Connection = con

     Set result.Query = qry

     con.ConnectTo("ATDB")

     qry.SQL = "SELECT * FROM STUDENTS ORDER BY LASTNAME"

     result.Execute

     result.LastRow ' Fetch all data into memory at start

     soughtrow = Inputbox _

     ("Which row do you want to change?", "Which row?")

     If soughtrow = "" Then

          Messagebox "No value entered for row",, "Bad row"

          Exit Sub

     End If

     If soughtrow < 1 Or soughtrow > result.NumRows Then

          Messagebox "Row out of range",, "Bad row"

          Exit Sub

     End If

     result.CurrentRow = soughtrow

     For i = 1 To result.NumColumns

          msg = msg & "  " & result.GetValue(i)

     Next

     soughtcolumn = Inputbox(msg, "Which column?")

     If soughtcolumn = "" Then

          Messagebox "No value entered for column",,  _

                     "Bad column"

          Exit Sub

     End If

     If soughtcolumn = "" Or soughtcolumn < 1 _

     Or soughtcolumn > result.NumColumns Then

          Messagebox "Column out of range",, "Bad column"

          Exit Sub

     End If

     newValue = Inputbox$("Enter new value", "SetValue", _

     result.GetValue(Cint(soughtcolumn)))

     If newValue = "" Then

          Messagebox "No value entered"

          Exit Sub

     End If

     Call result.SetValue(Cint(soughtcolumn), newValue)

     result.UpdateRow

     result.Close(DB_CLOSE)

     con.Disconnect

End Sub


Example: SiblingCount property

This script displays the number of siblings belonging to the Cars view entry in the By Category view.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim view As NotesView

Dim entry As NotesViewEntry

Set db = session.CurrentDatabase

Set view = db.GetView("By Category")

Set entry = view.GetEntryByKey("Cars")

Messagebox entry.SiblingCount?


Example: Sign method

This script creates a new document in the current database, signs it, saves it, and gets the name of the certificate that verified the signature. The document is signed with the current user Notes ID.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim doc As NotesDocument

Dim verifyName As String

Set db = session.CurrentDatabase

Set doc = New NotesDocument( db )

doc.Form = "Main Topic"

doc.Subject = "A signed document"

Call doc.Sign

Call doc.Save( False, True )

verifyName = doc.Verifier


Example: Signer property

This script gets the name of the person who signed a document and puts it into the variable person. For example, if Eben Law signed the document, person contains "Eben Law."

Dim doc As NotesDocument

Dim person As String

'...set value of doc...

person = doc.Signer


Examples: SignOnSend property

  1. This script sets the SaveMessageOnSend property for the NotesDatabase object doc to True.

    2. Dim doc As NotesDocument

    '...set value of doc...

    doc.SignOnSend = True
  2. This script creates, mails, and signs a new memo.

    3. Dim session As New NotesSession

    Dim db As NotesDatabase

    Dim doc As NotesDocument

    Set db = session.CurrentDatabase

    Set doc = New NotesDocument( db )

    doc.SignOnSend = True

    doc.Form = "Memo"

    doc.Subject = "Here's a signed mail memo."

    Call doc.Send( False, "Carl Pycha" )


Example: SilentMode property

The following button script toggles the SilentMode property at the user's direction. The ODBCConnection object must be global to retain its state between invocations of the button.

Uselsx "*LSXODBC"

%INCLUDE "lsconst.lss"

Dim con As ODBCConnection

Sub Postopen(Source As Notesuidocument)

     Set con = New ODBCConnection

End Sub

Sub Click(Source As Button)

     If con.SilentMode Then

          If(Messagebox("Do you want to turn it off", _

          MB_YESNO, "SilentMode is on") = IDYES) Then

               con.SilentMode = False

          End If

     Else

          If(Messagebox("Do you want to turn it on", _

          MB_YESNO, "SilentMode is off") = IDYES) Then

               con.SilentMode = True

          End If

     End If

End Sub


Example: Size property

This script gets the size of the current database.

Dim session As New NotesSession

Dim db As NotesDatabase

Set db = session.CurrentDatabase

Dim size As Double

size = db.Size


Example: Size property

This script gets the size of a document and puts it into sizeInBytes. For example, Size returns 135.

Dim doc As NotesDocument

Dim sizeInBytes As Long

'...set value of doc...

sizeInBytes = doc.Size


Example: SizeQuota property

This script gets the size quota of SMALL.NSF and puts it into the variable quota.

Dim db As New NotesDatabase( "", "small.nsf" )

Dim quota As Long

quota = db.SizeQuota


Example: Source property

This script gets the source of the application used to create the "City picture" object in the Body item of a document, and puts it into sourceName. For example, the Source property returns "EXT58753."

Dim doc As NotesDocument

Dim rtitem As Variant

Dim object As NotesEmbeddedObject

Dim sourceName As String

'...set value of doc...

Set rtitem = doc.GetFirstItem( "Body" )

If ( rtitem.Type = RICHTEXT ) Then

  Set object = rtitem.GetEmbeddedObject( "City picture" )

  sourceName = object.Source

End If


Example: Spacing property

This script displays the amount of spacing between rows in the Orders view of the current database.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim view As NotesView

Set db = session.CurrentDatabase

Set view = db.GetView("Orders")

Messagebox "Spacing between rows: " & view.Spacing


Example: SpacingAbove property

This example sets the amount of space above a rich-text paragraph style object.

Dim session As New NotesSession

Dim db As NotesDatabase

Set db = session.Currentdatabase

Dim doc As New NotesDocument(db)

Call doc.AppendItemValue("From", session.Username)

Call doc.AppendItemValue("subject","Meeting agenda")

Dim rtpStyle As NotesrichTextParagraphStyle

Set rtpStyle = session.CreateRichTextParagraphStyle

Dim richText As New NotesRichTextItem(doc,"Body")

rtpStyle.SpacingAbove = SPACING_ONE_POINT_50

Call richText.AppendParagraphStyle(rtpStyle)

Call richText.AppendText("Where are we now?")

Call doc.Save(True, False)


Example: SpacingBelow property

This example sets the amount of space below a rich-text paragraph style object.

Dim session As New NotesSession

Dim db As NotesDatabase

Set db = session.Currentdatabase

Dim doc As New NotesDocument(db)

Call doc.AppendItemValue("From", session.Username)

Call doc.AppendItemValue("subject","Meeting agenda")

Dim rtpStyle As NotesrichTextParagraphStyle

Set rtpStyle = session.CreateRichTextParagraphStyle

Dim richText As New NotesRichTextItem(doc,"Body")

rtpStyle.SpacingBelow = SPACING_ONE_POINT_50

Call richText.AppendParagraphStyle(rtpStyle)

("Where are we now?")

Call doc.Save(True, False)


Example: SpellCheck method

This script checks the spelling of a UI document.

Sub Click(Source As Button)

     Dim workspace As New NotesUIWorkspace

     Dim uidoc As NotesUIDocument

     Set uidoc = workspace.CurrentDocument

     Call uidoc.SpellCheck()

End Sub


Example: SQL property

The following example of a view script sets a default query in the Postopen script, then allows the user to specify alternate queries in the Click event of an action. A second action displays the current query. A third action executes the query and displays fields from the result set.

Uselsx "*LSXODBC"

Dim con As ODBCConnection

Dim qry As ODBCQuery

Dim result As ODBCResultSet

Dim defaultQuery As String

Sub Postopen(Source As Notesuiview)

     Set con = New ODBCConnection

     Set qry = New ODBCQuery

     Set result = New ODBCResultSet

     Set qry.Connection = con

     Set result.Query = qry

     defaultQuery = "SELECT * FROM STUDENTS"

     qry.SQL = defaultQuery

End Sub

Sub Click(Source As Button)

     Dim inputSQL As String

     inputSQL = Inputbox("Defaults to: " & defaultQuery, _

     "SQL statement", qry.SQL)

     If inputSQL = "" Then inputSQL = defaultSQL

     qry.SQL = inputSQL

End Sub

Sub Click(Source As Button)

     Messagebox qry.SQL,, "SQL statement"

End Sub

Sub Click(Source As Button)

     Dim firstName As String

     Dim lastName As String

     Dim msg As String

     con.ConnectTo("ATDB")

     result.Execute

     If result.IsResultSetAvailable Then

          msg = "Student names:" & Chr(10)

          Do

               result.NextRow

               firstName = result.GetValue("FIRSTNAME", _

                                           firstName)

               lastName = result.GetValue("LASTNAME", _

                                          lastName)

               msg = msg & Chr(10) & firstName & " " & _

               lastName

          Loop Until result.IsEndOfData

          Messagebox msg,, "Student names"

          result.Close(DB_CLOSE)

     Else

          Messagebox "Cannot get result set"

          Exit Sub

     End If

     con.Disconnect

End Sub


Example: StampAll method

This example solicits a value from the user and writes it to the Subject item in every document in the database.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim dc As NotesDocumentCollection

Dim doc As NotesDocument

Set db = session.CurrentDatabase

Set dc = db.FTSearch("Business reports",10)

newField = Inputbox("NewField value?")

Call dc.StampAll("Subject", newField)


Example: StampAll method

This script requests a value from the user and writes it to the NewField item in every document associated with the entries in the Cars view collection in the By Category view.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim view As NotesView

Dim vc As NotesViewEntryCollection

Set db = session.CurrentDatabase

Set view = db.GetView("By Category")

Set vc = view.GetAllEntriesByKey("Cars")

newField = Inputbox("NewField value?")

Call vc.StampAll("NewField", newField)


Example: Strikethrough property

This example builds a rich-text item and sets styles so that part of the text is bold and another part of the text is struck through.

Sub Initialize

     Dim session As New NotesSession

     Dim db As NotesDatabase

     Set db = session.CurrentDatabase

     Dim doc As New NotesDocument(db)

     Call doc.AppendItemValue("From", session.UserName)

     Call doc.AppendItemValue("Subject",  _

     "Meeting time changed")

     Dim richStyle As NotesRichTextStyle

     Set richStyle = session.CreateRichTextStyle

     Dim richText As New NotesRichTextItem(doc, "Body")

     Call richText.AppendText("The meeting is at ")

     richStyle.Bold = True

     Call richText.AppendStyle(richStyle)

     Call richText.AppendText("3:00")

     richStyle.Bold = False

     Call richText.AppendStyle(richStyle)

     Call richText.AppendText(" not ")

     richStyle.Strikethrough = True

     Call richText.AppendStyle(richStyle)

     Call richText.AppendText("2:00")

     Call doc.Save(True, False)

End Sub


Example: SwitchToID method

The following script shows you how to switch to a different ID file.

Dim reg As New NotesRegistration

Dim UserName As String

UserName = reg.SwitchToID( "c:\lotus\notes\MDeslau.ID", _

                           "matches")

Print UserName


Example: Tabs property

This example displays the number of tabs in a rich-text paragraph style object.

Dim session As New NotesSession

Dim db As NotesDatabase

Set db = session.Currentdatabase

Dim doc As New NotesDocument(db)

Call doc.AppendItemValue("From", session.Username)

Call doc.AppendItemValue("subject", _

"Meeting agenda")

Dim rtpStyle As NotesrichTextParagraphStyle

Set rtpStyle = session.CreateRichTextParagraphStyle

Dim richText As New NotesRichTextItem(doc, "Body")

Call richText.AppendParagraphStyle(rtpStyle)

Call richText.AppendText("Where are we now?")

Messagebox "Number of Tabs: " & rtpStyle.Tabs

Call doc.Save(True, False)


Examples: Target property

  1. This script indicates whether or not the current agent works on all documents in the database.

    2. Dim session As New NotesSession

    Dim agent As NotesAgent

    Set agent = session.CurrentAgent

    If agent.Target = TARGET_ALL_DOCS Then

         Messagebox "This agent works on all docs."

    Else

         Messagebox "This agent does not work on all docs."

    End If
  2. This script determines the target of the current agent and displays the result.

    3. Dim session As New NotesSession

    Dim agent As NotesAgent

    Dim db As NotesDatabase

    Set agent = session.CurrentAgent

    targetDoc = agent.Target

    Select Case targetDoc

    Case TARGET_ALL_DOCS : targetDoc = "all documents."

    Case TARGET_NEW_DOCS : targetDoc = "new documents."

    Case TARGET_NEW_OR_MODIFIED_DOCS : targetDoc = "new or modified documents."

    Case TARGET_SELECTED_DOCS : targetDoc = "selected documents."

    Case TARGET_ALL_DOCS_IN_VIEW : targetDoc = "all documents in view."

    Case TARGET_UNREAD_DOCS_IN_VIEW : targetDoc = "unread documents in view."

    Case TARGET_NONE : targetDoc = "none."

    End Select

    Messagebox "The target of this agent is " & targetDoc


Examples: TemplateName property

  1. This script gets the template name of DISCUSS4.NTF. The TemplateName property returns "StdR4Disc."

    2. Dim db As New NotesDatabase( "", "discuss4.ntf" )

    Dim template As String

    template = db.TemplateName

    Messagebox( template )
  2. Given a user name, server, and file name, this sub creates a new mail file for the user from the mail template. It uses the TemplateName property to find the StdR4Mail template.

    3. Sub createMailFile( user As String, server As String, _

    file As String )

      Dim templateDb As NotesDatabase

      Dim mailDb As NotesDatabase

      Dim directory As New NotesDbDirectory( server )

      Set templateDb = directory.GetFirstDatabase( TEMPLATE )

      While Not ( templateDb.TemplateName = "StdR4Mail" )

        Set templateDb = directory.GetNextDatabase

      Wend

      Call templateDb.Open( "", "" )

      Set mailDb = templateDb.CreateFromTemplate _

      ( server, "mail\"+file, True )

      mailDb.Title = user + " Mail"

      Call mailDb.GrantAccess( "Administrators", _

          ACLLEVEL_MANAGER )

      Call mailDb.GrantAccess( user, ACLLEVEL_EDITOR )

      If ( server <> "" ) Then

        Call mailDb.GrantAccess( server, ACLLEVEL_MANAGER )

      End If

    End Sub
    A sample call to this sub might look like this:

    Call createMailFile( "Brandon Herkle", "Pyongyang", _

      "brandon.nsf" )


Examples: Text property

  1. This script uses the Text property to get the contents of the Categories item, which is a text list. Suppose Categories contains three values: "pine tree," "maple tree," and "spruce tree." The Text property returns the string "pine tree;spruce tree;maple tree" and places it in the contents variable.

    2. Dim doc As NotesDocument

    '...set value of doc...

    Dim item As NotesItem

    Dim contents As String

    Set item = doc.GetFirstItem( "Categories" )

    contents = item.Text
  2. This script uses the Text property to get the contents of the Amount item, which is of type Number. Suppose the Amount item contains 35.2. The Text property returns the string "35.2" and places it in the contents variable.

    3. Dim doc As NotesDocument

    Dim item As NotesItem

    Dim contents As String

    '...set value of doc...

    Set item = doc.GetFirstItem( "Amount" )

    contents = item.Text
  3. This function takes any NotesDocument and uses the Text property to create a plain-text rendering of it. For each item on the document whose name does not contain "$", the function places the name and text of the item into the Body item of a new document. The new document is returned to the calling routine. Note that plainItem is declared as a NotesRichTextItem only so that the script can use the AddNewLine method to insert new lines to separate each item.

    4. Function createPlainDoc( doc As NotesDocument ) As NotesDocument

      Dim db As NotesDatabase

      Dim plainDoc As NotesDocument

      Dim plainItem As NotesRichTextItem

      Set db = doc.ParentDatabase

      Set plainDoc = New NotesDocument( db )

      Set plainItem = New NotesRichTextItem _

      ( plainDoc, "Body" )

      itemList = doc.Items

      Forall i In itemList

        If ( Instr( i.Name, "$" ) = 0 ) Then

          Call plainItem.AppendText( i.Name + ": " + i.Text )

          Call plainItem.AddNewLine( 1 )

        End If

      End Forall

      Set createPlainDoc = plainDoc

    End Function


Example: TimeDateFmt property

This script displays the format of time-date data in a column.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim view As NotesView

Dim column As notesViewColumn

Set db = session.CurrentDatabase

Set view = db.Getview("Align")

Set column = view.Columns(0)

Messagebox (column.TimeDateFmt)


Example: TimeDifference method

This script checks to see if a document has been modified within the last seven days. If it hasn't, it mails a reminder memo to the document's authors.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim doc As NotesDocument

Dim newDoc As NotesDocument

Dim weekDateTime As NotesDateTime

Dim modifiedDateTime As NotesDateTime

Set db = session.CurrentDatabase

'...set value of doc...

Set weekDateTime = New NotesDateTime( "Today" )

Set modifiedDateTime = New NotesDateTime( "" )

Call weekDateTime.AdjustDay( -7 )  ' set to one week ago

modifiedDateTime.LSLocalTime = doc.LastModified

If weekDateTime.TimeDifference( modifiedDateTime ) > 0  Then

  Set newDoc = New NotesDocument( db )

  newDoc.Form = "Memo"

  newDoc.Subject = _

  "Reminder: please update your project plan"

  Call newDoc.Send( False, doc.Authors )

End If


Example: TimeFmt property

This script displays the format of time data in a column.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim view As NotesView

Dim column As notesViewColumn

Set db = session.CurrentDatabase

Set view = db.Getview("Align")

Set column = view.Columns(0)

Messagebox (column.TimeFmt)


Example: TimeOnly property

This script displays the current date and time on two lines.

Sub Initialize

     Dim dateTime As New NotesDateTime( "" )

     dateTime.LSLocalTime = Now

     Messagebox _

     "Date:   " & dateTime.DateOnly & Chr(10) & _

     "Time:   " & dateTime.TimeOnly,, "Current date and time"

End Sub


Examples: TimeZone property

This script displays the TimeZone property of a newly-created NotesDateTime object.

Dim dateTime As New NotesDateTime( "04/16/96 05:36 PM" )

Messagebox( dateTime.TimeZone )
  • If the script runs on a computer set to Greenwich Mean Time, the TimeZone property is 0.

  • If the script runs on a computer set to Eastern Standard Time, the TimeZone property is 5.

  • If the script runs on a computer set to Alaska-Hawaii Standard Time, the TimeZone property is 10.


Example: TimeZoneFmt property

This script displays the format of the time zone for time data in a column.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim view As NotesView

Dim column As notesViewColumn

Set db = session.CurrentDatabase

Set view = db.Getview("Align")

Set column = view.Columns(0)

Messagebox (column.TimeZoneFmt)


Example: Title property

This script attempts to find the Topic column in the By Author view of the current database, if such a column exists.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim view As NotesView

Dim column As NotesViewColumn

Set db = session.CurrentDatabase

Set view = db.GetView( "By Author" )

Forall c In view.Columns

  If ( c.Title = "Topic" ) Then

    Set column = c

    Exit Forall

  End If

End Forall

If ( column Is Nothing ) Then

  Messagebox( "There's no column named Topic" )

Else

  Messagebox( "Found the Topic column" )

End If


Examples: Title property

  1. This script displays the title of the current database.

    2. Dim session As New NotesSession

    Dim db As NotesDatabase

    Set db = session.CurrentDatabase

    Messagebox( db.Title )
  2. This script changes the title of the SAFFRON.NSF database to "Herb Discussion."

    3. Dim db As New NotesDatabase( "", "saffron.nsf" )

    db.Title = "Herb Discussion"
  3. This script has no effect, since it is not possible to change the Title of the current database.

    4. Dim session As New NotesSession

    Dim db As NotesDatabase

    Set db = session.CurrentDatabase

    db.Title = "Marketing Discussion"


Example: TopLevelEntryCount property

This script displays the number of top-level entries in the Stock view of the current database.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim view As NotesView

Set db = session.CurrentDatabase

Set view = db.GetView("Stock")

Messagebox "Number of top level entries: " & view.TopLevelEntryCount


Examples: Trigger property

  1. This script indicates whether or not the current is triggered manually.

    2. Dim session As New NotesSession

    Dim agent As NotesAgent

    Set agent = session.CurrentAgent

    If agent.Trigger= TRIGGER_MANUAL Then

         Messagebox "Manual"

    Else

         Messagebox "Not manual"

    End If
  2. This script determines when the current agent runs and displays the result.

    3. Dim session As New NotesSession

    Dim agent As NotesAgent

    Dim db As NotesDatabase

    Set agent = session.CurrentAgent

    triggerDoc = agent.Trigger

    Select Case triggerDoc

    Case TRIGGER_NONE : triggerDoc = _

    "This agent doesn't have a schedule."

    Case TRIGGER_SCHEDULED : triggerDoc = _

    "This agent runs when it is scheduled."

    Case TRIGGER_AFTER_MAIL_DELIVERY : triggerDoc = _

    "This agent runs after there is new mail."

    Case TRIGGER_MANUAL : triggerDoc = "This agent runs manually."

    Case TRIGGER_DOC_PASTED : triggerDoc = _

    "This agent runs when documents have been pasted."

    Case TRIGGER_DOC_UPDATE : triggerDoc = _

    "This agent runs if documents have been updated."

    Case TRIGGER_BEFORE_MAIL_DELIVERY : triggerDoc = _

    "This agent runs before new mail."

    End Select

    Messagebox triggerDoc


Examples: Type property

This script displays the type of outline entry retrieved from the "products" outline.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim outline As NotesOutline

Dim oe As NotesOutlineEntry

Dim Type As Long

Set db = session.CurrentDatabase

Set outline = db.GetOutline("products")

Set oe = outline.GetFirst()

Messagebox "Type: " & oe.Type


Example: Type property

This script gets the type of the Topic item in a document. The itemType variable gets the value TEXT.

Dim doc As NotesDocument

Dim item As NotesItem

Dim itemType As Integer

'...set value of doc...

Set item = doc.GetFirstItem( "Topic" )

itemType = item.Type


Example: Type property

This script counts the number of embedded objects, object links, and file attachments in the Body item of a document, and prints the results in the status bar. For example, the script prints "3 attachments 2 links 4 objects."

Dim doc As NotesDocument

Dim rtitem As Variant

Dim attachCount As Integer

Dim linkCount As Integer

Dim objectCount As Integer

'...set value of doc...

Set rtitem = doc.GetFirstItem( "Body" )

attachCount = 0

linkCount = 0

objectCount = 0

If ( rtitem.Type = RICHTEXT ) Then

  Forall o In rtitem.EmbeddedObjects

    Select Case o.Type

    Case EMBED_ATTACHMENT:

      attachCount = attachCount + 1

    Case EMBED_OBJECTLINK:

      linkCount = linkCount + 1

    Case EMBED_OBJECT:

      objectCount = objectCount + 1

    End Select

  End Forall

End If

Print( attachCount & " attachments " & linkCount & _

" links " & objectCount & " objects " )


Example: Underline property

This example builds a rich-text item and sets styles so that part of the text is underlined.

Sub Initialize

     Dim session As New NotesSession

     Dim db As NotesDatabase

     Set db = session.CurrentDatabase

     Dim doc As New NotesDocument(db)

     Call doc.AppendItemValue("From", session.UserName)

     Call doc.AppendItemValue("Subject",  _

                              "Meeting time changed")

     Dim richStyle As NotesRichTextStyle

     Set richStyle = session.CreateRichTextStyle

     Dim richText As New NotesRichTextItem(doc, "Body")

     Call richText.AppendText("The meeting is at ")

     richStyle.Underline = True

     Call richText.AppendStyle(richStyle)

     Call richText.AppendText("3:00")

     richStyle.Underline = False

     Call richText.AppendStyle(richStyle)

     Call richText.AppendText(" not 2:00")

     Call doc.Save(True, False)

End Sub


Examples: UniformAccess property

The following example toggles the UniformAccess property at the user's direction.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim acl As NotesACL

Set db = session.CurrentDatabase

Set acl = db.ACL

If acl.UniformAccess Then

     If Messagebox("Do you want to toggle?", _

     MB_YESNO + MB_ICONQUESTION, _

     "Uniform access is in effect") = IDYES Then

          acl.UniformAccess = False

          Call acl.Save

     End If

Else

     If Messagebox("Do you want to toggle?",_

     MB_YESNO + MB_ICONQUESTION, _

     "Uniform access is not in effect") = IDYES Then

          acl.UniformAccess = True

          Call acl.Save

     End If

End If


Example: UniversalID property

This script displays the universal ID of the Cars view entry in the By Category view.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim view As NotesView

Dim entry As NotesViewEntry

Set db = session.CurrentDatabase

Set view = db.GetView("By Category")

Set entry = view.GetEntryByKey("Cars")

Messagebox entry.UniversalID


Examples: UniversalID property

  1. This script gets the universal ID of the NotesDocument object doc.

    2. Dim doc As NotesDocument

    Dim unid As String

    '...set value of doc...

    unid = doc.UniversalID
  2. This script creates a document and sets it UNID based on user input. The script delivers an error message if the UNID turns out to be a duplicate.

    3.      On Error 4000 Goto doError

         ' Database already contains a document with this ID

         Dim session As New NotesSession

         Dim db As NotesDatabase

         Dim doc As NotesDocument

         Dim invoiceID As Variant

         Dim universalID As String*32

         Set db = session.CurrentDatabase

         Set doc = New NotesDocument(db)

         doc.Subject = "New invoice"

         invoiceID = Inputbox _

         ("Enter invoice number - max of 8 digits")

         If Not Isnumeric(invoiceID) Then

              Messagebox "Invoice number must be numeric"

              Exit Sub

         End If

         If Len(invoiceID) > 8 Then

              Messagebox "Max of 8 digits"

              Exit Sub

         End If

         doc.InvoiceID = Cstr(invoiceID)

         universalID = "AAAABBBBCCCCDDDDEEEEFFFF" & invoiceID

         doc.UniversalID = universalID

         Call doc.Save( True, True )

         Exit Sub

    doError:

         Messagebox _

         "Invoice number " & invoiceID & " already used"

         Exit Sub


Example: UniversalID property

This script gets the universal ID of the By Author view in the current database, and puts it into the variable id.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim view As NotesView

Dim id As String

Set db = session.CurrentDatabase

Set view = db.GetView( "By Author" )

id = view.UniversalID


Examples: UnprocessedDocuments property

  1. This view action script allows a user to approve multiple requisitions at once by processing the currently selected documents in the Requisitions view. UnprocessedDocuments returns the documents currently selected in the view. The script iterates over each document and, if the Approver item contains the current user's name, it sets the Approved item to "Yes."

    2. Sub Click(Source As Button)

      Dim session As New NotesSession

      Dim db As NotesDatabase

      Dim collection As NotesDocumentCollection

      Dim doc As NotesDocument

      Set db = session.CurrentDatabase

      Set collection = db.UnprocessedDocuments

      For i = 1 To collection.Count

        Set doc = collection.GetNthDocument( i )

        Set item = doc.GetFirstItem( "Approver" )

        If item.Contains( session.UserName ) Then

          doc.Approved = "Yes"

          Call doc.Save( False, True )

        End If

      Next

    End Sub
  2. This agent script runs on all newly created and modified documents, and its purpose is to modify the Status item of each document it processes.

    • If the agent does not contain any searches, and runs for the first time on October 17, 1995, UnprocessedDocuments returns all the documents in the database. The script puts "Processed by agent on 10/17/95" into the Status item of each document, saves the document, and marks it as processed. If the agent runs again the next day, and five documents have been created or modified since the 17th, UnprocessedDocuments returns only those five documents--all other documents have been marked as processed--and puts "Processed by agent on 10/18/95" into the Status item. If the agent runs again the next day, and one document has been created since the 18th, UnprocessedDocuments returns one document.

    • If the agent does contain searches, and runs for the first time on October 17, 1995, UnprocessedDocuments returns all the documents in the database that meet the search criteria. For example, it returns all documents whose Subject field contains the word "Pablo." If the agent runs again the next day, and five documents have been created or modified since the 17th, but only two of them contain "Pablo" in the Subject, UnprocessedDocuments returns those two documents. If the agent runs again the next day, and one document has been created since the 18th, but it does not contain "Pablo" in the Subject, UnprocessedDocuments returns an empty NotesDocumentCollection.

      Sub Initialize

        Dim session As New NotesSession

        Dim db As NotesDatabase

        Dim collection As NotesDocumentCollection

        Dim dateTime As NotesDateTime

        Dim doc As NotesDocument

        Dim j As Integer

        Set db = session.CurrentDatabase

        Set collection = db.UnprocessedDocuments

        Set dateTime = New NotesDateTime( "Today" )

        For j = 1 To collection.Count

          Set doc = collection.GetNthDocument( j )

          doc.Status = "Processed by agent on " _

          & dateTime.LocalTime

          Call doc.Save( True, True )

          Call session.UpdateProcessedDoc( doc )

        Next

      End Sub
  3. This agent script runs on all unread documents, and its purpose is to put unread documents into a folder.

    • If the agent does not contain a search, UnprocessedDocuments returns all unread documents in the database each time the agent runs, regardless of whether the agent has already run on some of the unread documents.

    • If the agent does contain searches, UnprocessedDocuments returns all unread documents in the database that meet the search criteria, regardless of whether the agent has already run on some of the unread documents.

      Sub Initialize

        Dim session As New NotesSession

        Dim db As NotesDatabase

        Dim collection As NotesDocumentCollection

        Dim doc As NotesDocument

        Dim j As Integer

        Set db = session.CurrentDatabase

        Set collection = db.UnprocessedDocuments

        For j = 1 To collection.Count

          Set doc = collection.GetNthDocument( j )

          Call doc.PutInFolder _

          ( "Stop dreaming! Read these documents!" )

        Next

      End Sub


Examples: UnprocessedFTSearch method

  1. This view action script allows a user to perform a full-text search on the currently selected documents in the view. UnprocessedFTSearch returns the documents currently selected in the view that contain the word "botany," and places them into a folder.

    2. Sub Click(Source As Button)

      Dim session As New NotesSession

      Dim db As NotesDatabase

      Dim collection As NotesDocumentCollection

      Dim doc As NotesDocument

      Set db = session.CurrentDatabase

      Set collection = db.UnprocessedFTSearch( "botany", 0 )

      For i = 1 To collection.Count

        Set doc = collection.GetNthDocument( i )

        Call doc.PutInFolder( "Botanist's Delight" )

      Next

    End Sub
  2. This agent script runs on all newly created and modified documents that contain the word "botany." Its purpose is to modify the Status item of each document it processes.

    • If the agent does not contain any searches defined in the Agent Builder, and runs for the first time on October 17, 1995, UnprocessedFTSearch returns all the documents in the database that contain the word "botany." The script puts "Processed by agent on 10/17/95" into the Status item of each returned document, saves the document, and marks it as processed. If the agent runs again the next day, and five documents have been created or modified since the 17th, UnprocessedFTSearch searches only those five documents--all other documents have been marked as processed--and returns those that contain "botany." The script puts "Processed by agent on 10/18/95" into the Status item of each returned document. If the agent runs again the next day, and one document has been created since the 18th, UnprocessedFTSearch returns the document only if it contains "botany"; otherwise, it returns a NotesDocumentCollection with zero documents.

    • If the agent does contain searches defined in the Agent Builder, and runs for the first time on October 17, 1995, UnprocessedFTSearch returns all the documents in the database that meet the search criteria defined in the Agent Builder and contain the word "botany." If the agent runs again the next day, and five documents have been created or modified since the 17th, but only two of them contain meet the search criteria defined in the Agent Builder and contain the word "botany," UnprocessedFTSearch returns those two documents. If the agent runs again the next day, and one document has been created since the 18th, but it does not meet the search criteria defined in the Agent Builder, or does not contain the word "botany," UnprocessedFTSearch returns an empty NotesDocumentCollection.

      Sub Initialize

        Dim session As New NotesSession

        Dim db As NotesDatabase

        Dim collection As NotesDocumentCollection

        Dim dateTime As NotesDateTime

        Dim doc As NotesDocument

        Dim j As Integer

        Set db = session.CurrentDatabase

        Set collection = db.UnprocessedFTSearch( "botany", 0 )

        Set dateTime = New NotesDateTime( "Today" )

        For j = 1 To collection.Count

          Set doc = collection.GetNthDocument( j )

          doc.Status = "Processed by agent on " _

          & dateTime.LocalTime

          Call doc.Save( True, True )

          Call session.UpdateProcessedDoc( doc )

        Next

      End Sub
  3. This agent script runs on all unread documents that contain the word "URGENT," and puts these documents into a folder.

    • If the agent does not contain a search defined in the Agent Builder, UnprocessedFTSearch returns all unread documents in the database that contain the word "URGENT," regardless of whether the agent has already run on some of the unread documents at an earlier time.

    • If the agent does contain searches defined in the Agent Builder, UnprocessedFTSearch returns all unread documents in the database that meet the search criteria defined in the Agent Builder and contain the word "URGENT," regardless of whether the agent has already run on some of the unread documents at an earlier time.

      Sub Initialize

        Dim session As New NotesSession

        Dim db As NotesDatabase

        Dim collection As NotesDocumentCollection

        Dim doc As NotesDocument

        Dim j As Integer

        Set db = session.CurrentDatabase

        Set collection = db.UnprocessedFTSearch( "URGENT", 0 )

        For j = 1 To collection.Count

          Set doc = collection.GetNthDocument( j )

          Call doc.PutInFolder _

          ( "Stop dreaming! Read these documents!" )

        Next

      End Sub


Examples: UnprocessedSearch method

  1. This view action script allows a user to perform a search on the currently selected documents in the view. UnprocessedSearch returns the documents currently selected in the view that were created after May 20, 1995 and contain "botany" in the Subject item, and places them into a folder.

    2. Sub Click(Source As Button)

      Dim session As New NotesSession

      Dim db As NotesDatabase

      Dim dateTime As NotesDateTime

      Dim collection As NotesDocumentCollection

      Dim doc As NotesDocument

      Set db = session.CurrentDatabase

      Set dateTime = New NotesDateTime( "05/20/95" )

      Set collection = db.UnprocessedSearch _

      ( "@Contains( Subject; ""botany"" )", dateTime, 0 )

      For i = 1 To collection.Count

        Set doc = collection.GetNthDocument( i )

        Call doc.PutInFolder( "Botanist's Delight" )

      Next

    End Sub
  2. This agent script runs on all newly created and modified documents that were created after May 20, 1995 and contain "botany" in the Subject item. The script's purpose is to modify the Status item of each document it processes.

    • If the agent does not contain any searches defined in the Agent Builder, and runs for the first time on October 17, 1995, UnprocessedSearch returns all the documents in the database that were created after May 20, 1995 and contain "botany" in the Subject item. The script puts "Processed by agent on 10/17/95" into the Status item of each returned document, saves the document, and marks it as processed. If the agent runs again the next day, and five documents have been created or modified since the 17th, UnprocessedSearch searches only those five documents -- all other documents have been marked as processed -- and returns those that were created after May 20, 1995 and contain "botany" in the Subject item. The script puts "Processed by agent on 10/18/95" into the Status item of each returned document. If the agent runs again the next day, and one document has been created since the 18th, UnprocessedSearch returns the document only if it was created after May 20, 1995 and contains "botany" in the Subject item; otherwise, it returns a NotesDocumentCollection with zero documents.

    • If the agent does contain searches defined in the Agent Builder, and runs for the first time on October 17, 1995, UnprocessedSearch returns all the documents in the database that meet the search criteria defined in the Agent Builder, were created after May 20, 1995, and contain "botany" in the Subject item. If the agent runs again the next day, and five documents have been created or modified since the 17th, but only two of them meet the search criteria defined in the Agent Builder, were created after May 20, 1995, and contain the word "botany", UnprocessedSearch returns those two documents. If the agent runs again the next day, and one document has been created since the 18th, but it does not meet the search criteria defined in the Agent Builder, or was created before May 20, 1995, or does not contain "botany" in the Subject item, UnprocessedSearch returns an empty NotesDocumentCollection.

      Sub Initialize

        Dim session As New NotesSession

        Dim db As NotesDatabase

        Dim dateTime As NotesDateTime

        Dim collection As NotesDocumentCollection

        Dim todayDateTime As NotesDateTime

        Dim doc As NotesDocument

        Dim j As Integer

        Set db = session.CurrentDatabase

        Set dateTime = New NotesDateTime( "05/20/95" )

        Set collection = db.UnprocessedSearch _

        ( "@Contains( Subject; ""botany"" )", dateTime, 0 )

        Set todayDateTime = New NotesDateTime( "Today" )

        For j = 1 To collection.Count

          Set doc = collection.GetNthDocument( j )

          doc.Status = "Processed by agent on " & _

          todayDateTime.LocalTime

          Call doc.Save( True, True )

          Call session.UpdateProcessedDoc( doc )

        Next

      End Sub
  3. This agent script runs on all unread documents that were created after January 20, 1996 and contain "URGENT" in the Subject item. The script's purpose is to put these documents into a folder.

    • If the agent does not contain a search defined in the Agent Builder, UnprocessedSearch returns all unread documents in the database that were created after January 20, 1996 and contain "URGENT" in the Subject item, regardless of whether the agent has already run on some of the unread documents at an earlier time.

    • If the agent does contain searches defined in the Agent Builder, UnprocessedSearch returns all unread documents in the database that meet the search criteria defined in the Agent Builder, were created after January 20, 1996, and contain the word "URGENT", regardless of whether the agent has already run on some of the unread documents at an earlier time.

      Sub Initialize

        Dim session As New NotesSession

        Dim db As NotesDatabase

        Dim dateTime As NotesDateTime

        Dim collection As NotesDocumentCollection

        Dim doc As NotesDocument

        Dim j As Integer

        Set db = session.CurrentDatabase

        Set dateTime = New NotesDateTime( "01/20/96" )

        Set collection = db.UnprocessedSearch _

        ( "@Contains( Subject; ""URGENT"" )", dateTime, 0 )

        For j = 1 To collection.Count

          Set doc = collection.GetNthDocument( j )

          Call doc.PutInFolder _

          ( "Stop dreaming! Read these documents!" )

        Next

      End Sub


Example: UpdateAll method

This is an example of an agent that runs on, "All new and modified documents since last run." The UnprocessedDocuments method collects all new and modified documents since the last run. The UpdateAll method marks those documents so that they will be recognized as old documents on subsequent runs.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim collection As NotesDocumentCollection

Dim doc As NotesDocument

Set db = session.CurrentDatabase

Set collection = db.UnprocessedDocuments

Call collection.UpdateAll


Examples: UpdateFTIndex method

  1. This script updates the full-text index of the current database if the database has been modified since the time the index was updated.

    2. Dim session As New NotesSession

    Dim db As NotesDatabase

    Set db = session.CurrentDatabase

    If ( db.LastModified > db.LastFTIndexed ) Then

      Call db.UpdateFTIndex( False )

    End If
  2. This script checks if INDEXME.NSF has a full-text index. If not, it asks the user if the user wants to create an index. If the user selects Yes, the script creates an index.

    3. This script must include the file LSCONST.LSS.

    Dim db As New NotesDatabase( "", "indexme.nsf" )

    Dim collection As NotesDocumentCollection

    Dim answer As Integer

    If Not ( db.IsFTIndexed ) Then

      answer = Messagebox _

      ( "Do you want to create an index?", MB_YESNO )

      If ( answer = IDYES ) Then

        Call db.UpdateFTIndex( True )

      End If

    End If

    Set collection = db.FTSearch( "blue", 0 )

    '...do something with collection...


Example: UpdateProcessedDoc method

This agent script is part of an agent that runs on newly created and modified documents since last run. The script gets the unprocessed documents in the current database, and marks each one as processed. For example, the first time the script runs, UnprocessedDocuments returns all of the documents in the database and UpdateProcessedDoc marks them all as processed.

The second time the script runs (and each time thereafter), UnprocessedDocuments returns those documents that UpdateProcessedDoc has not touched; for example, if three new documents have been added to the database and one existing document has been modified since the first time the agent ran, UnprocessedDocuments returns a collection of four documents.

Sub Initialize

  Dim session As New NotesSession

  Dim db As NotesDatabase

  Dim collection As NotesDocumentCollection

  Dim doc As NotesDocument

  Set db = session.CurrentDatabase

  Set collection = db.UnprocessedDocuments

  For j = 1 To collection.Count

    Set doc = collection.GetNthDocument( j )

    Call session.UpdateProcessedDoc( doc )

  Next

End Sub

For more examples, see the UnprocessedDocuments property, the UnprocessedFTSearch method, or the UnprocessedSearch method, in NotesDatabase.


Example: UpdateRow method

This agent changes the value of a row and column specified by the user.

Uselsx "*LSXODBC"

Sub Initialize

     Dim con As New ODBCConnection

     Dim qry As New ODBCQuery

     Dim result As New ODBCResultSet

     Dim msg As String

     Set qry.Connection = con

     Set result.Query = qry

     con.ConnectTo("ATDB")

     qry.SQL = "SELECT * FROM STUDENTS ORDER BY LASTNAME"

     result.Execute

     result.LastRow

     currentRow = Inputbox _

       ("Which row do you want to change?", "Which row?")

     If currentRow = "" Then

          Messagebox "No value entered for row",, "Bad row"

          Exit Sub

     End If

     If currentRow < 1 Or currentRow > result.NumRows Then

          Messagebox "Row out of range",, "Bad row"

          Exit Sub

     End If

     result.CurrentRow = currentRow

     For i = 1 To result.NumColumns

          msg = msg & "  " & result.GetValue(i)

     Next

     currentColumn = Inputbox(msg, "Which column?")

     If currentColumn = "" Then

          Messagebox _

          "No value entered for column",, "Bad column"

          Exit Sub

     End If

     If currentColumn = "" Or currentColumn < 1 _

     Or currentColumn > result.NumColumns Then

          Messagebox "Column out of range",, "Bad column"

          Exit Sub

     End If

     newValue = Inputbox$("Enter new value", "SetValue", _

     result.GetValue(Cint(currentColumn)))

     If newValue = "" Then

          Messagebox "No value entered"

          Exit Sub

     End If

     Call result.SetValue(Cint(currentColumn), newValue)

     result.UpdateRow

     result.Close(DB_CLOSE)

     con.Disconnect

End Sub


Examples: URL property

This script returns the URL of an entry.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim outline As NotesOutline

Dim oe As NotesOutlineEntry

Set db = session.CurrentDatabase

Set outline = db.GetOutline("products")

Set oe = outline.GetFirst()

Messagebox "URL: " & oe.URL


Examples: URLDatabase property

This Visual Basic code displays the title and database name of the default Web Navigator database.

Private Sub URLDatabase_Click()

Dim s As New NotesSession

Dim db As NotesDatabase

s.Initialize

Set db = s.URLDatabase

MsgBox db.Title, , db.FilePath

End Sub


Example: URLOpen method

This script opens the user's specified home page each time they open the Personal Web Navigator database:

Sub Postopen(Source As Notesuidatabase)

     Dim db As NotesDatabase

     Dim view As NotesView

     Dim profile As NotesDocument

     'intialize variables

     Set db = Source.Database

     Set view = db.GetView("(Internet Profile)")

     Set profile = view.GetFirstDocument

     If (profile Is Nothing) Then Exit Sub

     'open up the url

     If (profile.StartUpOptions(0) = "1") Then

          Set w = New NotesUIWorkspace

          w.UrlOpen profile.OpenUrl(0)

     End If

End Sub


Example: UseLSX method

This initialization script for a form loads the lsx file identified as LSXODBC in the registry, initialization file, or preferences file.

Sub Initialize

     Dim workspace As New NotesUIWorkspace

     Call workspace.UseLSX("*LSXODBC")

End Sub


Examples: UserName property

  1. In this button script, the variable user gets assigned the current user's name. Because the script runs on the workstation, the user's name belongs to the person using Notes at the time. For example, if user Stew Malone/Editorial/Acme clicks the button, the UserName property returns "CN=Stew Malone/OU=Editorial/O=Acme."

    2. Sub Click(Source As Button)

      Dim session As New NotesSession

      Dim user As String

      user = session.UserName

    End Sub
  2. In this agent script, the variable user gets assigned the current user's name. For example, if the agent runs when new mail arrives on server Toronto/Editorial/Acme, the UserName property returns "CN=Toronto/OU=Editorial/O=Acme" because the current user is the server. If user Stew Malone/Editorial/Acme runs the agent manually from the menu, it returns "CN=Stew Malone/OU=Editorial/O=Acme" because the current user is Stew Malone.

    3. Sub Initialize

      Dim session As New NotesSession

      Dim user As String

      user = session.CommonUserName

    End Sub


Examples: UserNameObject property

This Visual Basic code displays the current user's common name.

Private Sub UserNameObject_Click()

Dim s As New NotesSession

s.Initialize

MsgBox s.UserNameObject.Common, , "Common user name"

End Sub


Examples: UseRowID property

This example shows you how to enable "select by row ID" mode, and then access rows by their IDs, for example, in an Informix database. Remember to place the qry.UseRowID = True statement before the qry.SQL = [SQL statement] in your script, as shown below.

Uselsx "*LSXODBC"

Sub Postopen(Source As Notesuidocument)

     Set con = New ODBCConnection

     Set qry = New ODBCQuery

     Set result = New ODBCResultSet

     Set qry.Connection = con

     Set result.Query = qry

End Sub

Sub Click(Source As Button)

     Dim firstName As String

     Dim lastName As String

     Dim msg As String

     con.ConnectTo("ATDB")

     qry.UseRowID = True

     qry.SQL = "SELECT * FROM STUDENTS"

     result.Execute

     msg = "Student names:" & Chr(10)

     Do

          result.NextRow

          firstName = result.GetValue("FIRSTNAME", firstName)

          lastName = result.GetValue("LASTNAME", lastName)

          msg = msg & Chr(10) & firstName & " " & lastName

     Loop Until result.IsEndOfData

     Messagebox msg,, "Student names"

     result.Close(DB_CLOSE)

     con.Disconnect

End Sub


Examples: Using environment variables

  1. This button example increments the environment variable $SeqNo by one and prints the result. (This script would not be reliable on a server for maintaining a system of sequential numbers.)

    2. Sub Click(Source As Button)

         Dim session As New NotesSession

         seqNo = session.GetEnvironmentValue("SeqNo")

         If Isempty(seqNo) Then

              Call session.SetEnvironmentVar("SeqNo", 1)

         Else

              seqNo = seqNo + 1

              Call session.SetEnvironmentVar _

              ("SeqNo", Cint(seqNo))

         End If

         Messagebox session.GetEnvironmentValue("SeqNo")

    End Sub
  2. This agent example prints the value of a system environment variable. GetEnvironmentString is used to accept an environment variable that is either a number or a string. The second argument to GetEnvironmentString is true so that a dollar sign is not prepended to the name of the environment variable.

    3. Sub Initialize

         Dim session As New NotesSession

         envVarName = Inputbox$("Environment variable name")

         envVar = session.GetEnvironmentString(envVarName, _

         True)

         If envVar = "" Then

              Messagebox(envVarName & " not set")

         Else

              Messagebox(envVarName & " = " & envVar)

         End If

    End Sub


Examples: Using OLE

  1. This example represents two command buttons on a Visual Basic form. The first button writes a new document in an existing Domino database by creating a NotesSession object through OLE and creating NotesDatabase and NotesDocument objects through Notes methods. The second button frees the memory used by the Domino object before unloading the Visual Basic form.

    2. Private Sub Command1_Click()

         Dim session As Object

         Dim db As Object

         Dim doc As Object

         Set session = CreateObject("Notes.NotesSession")

         Set db = session.GetDatabase("", "test4.nsf")

         Set doc = db.CreateDocument()

         doc.Form = "Main Topic"

         doc.Subject = Form1.Text3.Text

         doc.Body = Form1.Text2.Text

         Call doc.Save(True, False)

    End Sub

    Private Sub Command2_Click()

         Set doc = Nothing

         Set db = Nothing

         Set session = Nothing

         Unload Form1

    End Sub
  2. This example represents a command button on a Visual Basic form. The button launches Notes if it is not already running, then opens test4.nsf in the local data directory.

    3. Private Sub Command3_Click()

         Dim ws As Object

         Set ws = CreateObject("Notes.NotesUIWorkspace")

         Call ws.OpenDatabase("", "test4.nsf")

    End Sub


Examples: Using OLE custom controls

  1. This example creates a new spreadsheet control in the Body field of a new document, or accesses the existing control in an existing document, and sets the background color to red.

    2. Sub Postopen(Source As Notesuidocument)

         Source.EditMode = True

         Call Source.GoToField("Body")

         If source.IsNewDoc Then

              Set area2Sheet = Source.CreateObject _

              ("Area 2 Sheet", _

              "Lotus.Spreadsheet.1")

         Else

              Set area2Sheet = Source.GetObject _

              ("Area 2 Sheet")

         End If

         area2Sheet.BackColor = 255 ' Red

    End Sub
  2. This example creates a form action that executes when an embedded OLE custom control (a spreadsheet) detects a mouse click. The Postopen script calls the spreadsheet's ActionLinkSet method to associate the action "Display column and row" with the click event. The action script displays the spreadsheet's Col and Row properties. The action must be named "Display column and row" and must have "Publish action with OLE object" set.

    3. (Globals) (Declarations)

    %INCLUDE "econsts.txt"

    %INCLUDE "ssconsts.txt"

    %INCLUDE "lsconst.lss"

    (Form)

    Sub Postopen(Source As Notesuidocument)

         Source.EditMode = True

         Call Source.GoToField("Body")

         If source.IsNewDoc Then

              Set area2Sheet = Source.CreateObject _

              ("Area 2 Sheet", _

             "Lotus.Spreadsheet.1")

         Else

              Set area2Sheet = Source.GetObject _

              ("Area 2 Sheet")

         End If

         Call area2Sheet.ActionLinkSet _

         (LC_CLICK, "Display column and row")

    End Sub

    (Action)

    Sub Objectexecute(Source As Button, Data As Variant)

         Dim workspace As New NotesUIWorkspace

         Dim uidoc As NotesUIDocument

         Set uidoc = workspace.CurrentDocument

         Set area2Sheet = uidoc.GetObject("Area 2 Sheet")

         Messagebox "Column = " & area2Sheet.Col & Chr(10) & _

         "Row = " & area2Sheet.Row,, "Column and row"

    End Sub
  3. This example handles the Click event for a Spreadsheet component inserted in the form through the UI. The script displays the spreadsheet's Col and Row properties when the user clicks within the component. See the next example for an alternative.

    4. Sub Click(Source As Ltssheet, Nrow As Long, Ncol As Long)

         Messagebox "Column = " & Source.Col & Chr(10) & _

         "Row = " & Source.Row,, "Column and row"

    End Sub
  4. As an alternative to the previous example, you can use the second and third parameters of the Click event in place of the Row and Col properties of Ltssheet.

    5. Sub Click(Source As Ltssheet, Nrow As Long, Ncol As Long)

         Messagebox "Column = " & Ncol & Chr(10) & _

         "Row = " & Nrow,, "Column and row"

    End Sub


Example: ValueLength property

This function takes any NotesDocument object and returns the total size of the document's attachments, in bytes.

Function AttachmentSizes( doc As NotesDocument ) As Integer

  Dim itms As Variant

  Dim totalSize As Integer

  itms = doc.Items

  totalSize = 0

  Forall i In itms

    If ( i.Type = ATTACHMENT ) Then

      totalSize = totalSize + i.ValueLength

    End If

  End Forall

  AttachmentSizes = totalSize

End Function


Example: Values property

This script gets the contents of a Subject item. The Values property returns an array even though the Subject item contains a single string.

Dim doc As NotesDocument

'...set value of doc...

Dim item As NotesItem

Set item = doc.GetFirstItem( "Subject" )

Forall v In item.Values

  Messagebox( v )

End Forall


Example: Verbs property

This script displays each verb associated with the "City picture" embedded object in the Body item of a document. For example, the script displays "Edit" and "Open."

Dim doc As NotesDocument

Dim rtitem As Variant

Dim object As NotesEmbeddedObject

'...set value of doc...

Set rtitem = doc.GetFirstItem( "Body" )

If ( rtitem.Type = RICHTEXT ) Then

  Set object = rtitem.GetEmbeddedObject( "City picture" )

  Forall v In object.Verbs

    Messagebox( v )

  End Forall

End If


Example: Verifier property

This script creates a new document in the current database, signs it, saves it, and gets the name of the certificate that verified the signature. For example, this property might return "Acme Development Corporation."

Dim session As New NotesSession

Dim db As NotesDatabase

Dim doc As NotesDocument

Dim verifyName As String

Set db = session.CurrentDatabase

Set doc = New NotesDocument( db )

doc.Form = "Main Topic"

doc.Subject = "A signed document"

Call doc.Sign

Call doc.Save( False, True )

verifyName = doc.Verifier


Examples: ViewRefresh method

  1. This view action script refreshes the view that's currently open.

    2. Sub Click(Source As Button)

      Dim workspace As New NotesUIWorkspace

      Call workspace.ViewRefresh

    End Sub
  2. This view action script creates and saves a document in the current database. It then refreshes the current view so that the new document displays in the view.

    3. Sub Click(Source As Button)

      Dim workspace As New NotesUIWorkspace

      Dim session As New NotesSession

      Dim db As NotesDatabase

      Dim doc As NotesDocument

      Set db = session.CurrentDatabase

      ' create the document and save to disk

      Set doc = New NotesDocument( db )

      doc.Subject = "This is my new doc"

      doc.From = session.UserName

      Call doc.Save( True, True )

      ' refresh current view to display the new document

      Call workspace.ViewRefresh

    End Sub
  3. The following button script saves the current document, refreshes the view (called "Main") and then closes the document.

    4. Sub Click(Source As Button)

      ' Declare all variables

      Dim workspace As New NotesUIWorkspace

      Dim session As New NotesSession

      Dim uidoc As NotesUIDocument

      Dim view As NotesView

      Dim db As NotesDatabase

      'Set all variables

      Set uidoc = workspace.CurrentDocument

      Set db = session.CurrentDatabase

      Set view = db.GetView( "Main" )

      'Save current document, refresh "Main" view

      'and close document

      Call uidoc.Save

      Call view.Refresh

      Call workspace.ViewRefresh

      Call uidoc.Close

    End Sub


Examples: Views property

  1. This script displays the names of all the views and folders in the current database.

    2. Dim session As New NotesSession

    Dim db As NotesDatabase

    Set db = session.CurrentDatabase

    Forall v In db.Views

      Messagebox(  v.Name  )

    End Forall
  2. This script uses the Views property to find the default view of the current database and assign it to the view object.

    3. Dim session As New NotesSession

    Dim db As NotesDatabase

    Dim view As NotesView

    Set db = session.CurrentDatabase

    Forall v In db.Views

      If v.IsDefaultView Then

        Set view = v

        Exit Forall

      End If

    End Forall


Example: Width property

This script displays the width of a column.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim view As NotesView

Dim column As notesViewColumn

Set db = session.CurrentDatabase

Set view = db.Getview("Align")

Set column = view.Columns(0)

Messagebox (column.Width)


Example: WindowTitle property

This form action script prompts the user with a dialog box before deleting the current document. (The action displays only when the current document is in Read mode, since documents can't be deleted while in Edit mode).

Sub Click(Source As Button)

  Dim workspace As New NotesUIWorkspace

  Dim uidoc As NotesUIDocument

  Dim choice As String

  Set uidoc = workspace.CurrentDocument

  choice = Inputbox( "Do you want to delete " +  _

  uidoc.WindowTitle + "?","" )

  If ( choice = "yes" ) Or ( choice = "y" ) Then

    Call uidoc.DeleteDocument

  End If

End Sub


Examples: Working with a rich-text item

  1. This button example prints properties for a rich-text item. If you are creating a new document, you must save it before clicking the button.

    2. Sub Click(Source As Button)

         Dim workspace As New NotesUIWorkspace

         Dim uidoc As NotesUIDocument

         Dim doc As NotesDocument

         REM Do not Dim item either as NotesItem

         REM or NotesRichTextItem or else a type mismatch may

         REM occur depending on the name of the field the

         REM user enters

         Set uidoc = workspace.CurrentDocument

         Set doc = uidoc.Document

         Set item = doc.GetFirstItem(Inputbox("Name of item"))

         If item.Type <> RICHTEXT Then

              Messagebox "Not rich text"

              Exit Sub

         End If

         Messagebox "Name: " & item.Name

         Messagebox "Text:" & Chr(10) & item.Text

         Messagebox "ValueLength: " & item.ValueLength

         Messagebox  "Values:" & Chr(10) & item.Values

    End Sub
  2. This button example formats a rich text item as a text string.

    3. Sub Click(Source As Button)

         Dim workspace As New NotesUIWorkspace

         Dim uidoc As NotesUIDocument

         Dim doc As NotesDocument

         Dim item as NotesRichTextItem

         Set uidoc = workspace.CurrentDocument

         Set doc = uidoc.Document

         Set item = doc.GetFirstItem("Body")

         Messagebox item.GetFormattedText(False, 40)

    End Sub
  3. This action example creates a new rich text item as the Body field in a standard discussion database. The example reads blocks of text from the user until the user returns an empty string, writes the user text to the rich text item, and separates the blocks of text with two newline characters so that each block appears as a paragraph.

    4. Sub Initialize

         Dim session As New NotesSession

         Dim db As NotesDatabase

         Set db = session.CurrentDatabase

         Dim doc As New NotesDocument(db)

         Call doc.AppendItemValue _

         ("From", session.UserName)

         Call doc.AppendItemValue _

         ("Subject", Inputbox("Subject?"))

         Call doc.AppendItemValue _

         ("Categories", Inputbox("Category?"))

         Dim richText As New NotesRichTextItem(doc, "Body")

         newPara = Inputbox _

         ("Paragraph of text for ""Body"" item")

         firstPara = True

         While newPara <> ""

              If firstPara Then

                   firstPara = False

              Else

                   Call richText.AddNewLine(2)

              End If

              Call richText.AppendText(newPara)

              newPara = Inputbox _

              ("Paragraph of text for ""Body"" item")

         Wend

         Call doc.Save(True, False)

    End Sub
  4. This example adds a page break to a rich text item.

    5. Sub Initialize

         Dim workspace As New NotesUIWorkspace

         Dim uidoc As NotesUIDocument

         Dim doc As NotesDocument

         Dim rtitem As Variant

         Set uidoc = workspace.CurrentDocument

         Set rtitem = doc.GetFirstItem("Body")

         If rtitem.Type <> RICHTEXT Then

              Messagebox "Body is not a rich text item."

         End If

         Call rtitem.AddPageBreak

         Call doc.Save(False, True)

    End Sub


Examples: Working with embedded objects

  1. This form action example displays properties of all the embedded objects in a document.

    2. Sub Click(Source As Button)

         Dim workspace As New NotesUIWorkspace

         Dim uidoc As NotesUIDocument

         Dim doc As NotesDocument

         Dim item As Variant

         Set uidoc = workspace.CurrentDocument

         Set doc = uidoc.Document

         Set item = doc.GetFirstItem("Body")

         Forall embobj In item.EmbeddedObjects

              verbs = "No verbs"

              Select Case embobj.Type

              Case EMBED_OBJECTLINK : _

              embobjType = "Object link"

              Case EMBED_ATTACHMENT : _

              embobjType = "Attachment"

              Case EMBED_OBJECT : embobjType = "Object"

                   verbs = "Verbs:"

                   Forall verb In embobj.Verbs

                        verbs = verbs & " " & verb

                   End Forall

              End Select

              Messagebox "Name: " & embobj.Name & Chr(10) _

              & "Class: " & embobj.Class & Chr(10) _

              & "File size: " & embobj.FileSize & Chr(10) _

              & "Type: " & embobjType & Chr(10) & verbs

         End Forall

    End Sub
  2. This form action example activates the first or only embedded object in a document.

    3. Sub Click(Source As Button)

         Dim workspace As New NotesUIWorkspace

         Dim uidoc As NotesUIDocument

         Dim doc As NotesDocument

         Dim item As Variant

         Set uidoc = workspace.CurrentDocument

         Set doc = uidoc.Document

         Set item = doc.GetFirstItem("Body")

         If item.EmbeddedObjects(0) Is Nothing Then

              Messagebox "No embedded object in document"

              Exit Sub

         End If

         If item.EmbeddedObjects(0).Type <> EMBED_OBJECT Then

              Messagebox "Object not an embedded object"

              Exit Sub

         End If

         Call item.EmbeddedObjects(0).Activate(True)

    End Sub


Examples: Working with tabs

  1. This example sets a tab in a rich-text paragraph style object.

    2. Sub Initialize

         Dim session As New NotesSession

         Dim db As NotesDatabase

         Set db = session.CurrentDatabase

         Dim doc As New NotesDocument(db)

         Call doc.AppendItemValue("From", session.Username)

         Call doc.AppendItemValue("subject", _

         "Meeting agenda")

         Dim rtpStyle As NotesrichTextParagraphStyle

         Set rtpStyle = session.CreateRichTextParagraphStyle

         Dim richText As New NotesRichTextItem(doc, "Body")

         Call richText.AppendParagraphStyle(rtpStyle)

         Call richText.AppendText("Meeting agenda")

         Messagebox "Number of Tabs: " & rtpStyle.Tabs

         Call doc.Save(True, False)

    End Sub
  2. This example sets tabs at a specified interval in a rich-text paragraph style object.

    3. Sub Initialize

         Dim session As New NotesSession

         Dim db As NotesDatabase

         Set db = session.CurrentDatabase

         Dim doc As New NotesDocument(db)

         Call doc.AppendItemValue("From", session.UserName)

         Call doc.AppendItemValue("Subject", _

              "Meeting time changed")

         Dim rtpStyle As NotesRichTextParagraphStyle

         Dim pos As Long

         Dim interval As Long

         Set rtpStyle = session.CreateRichTextParagraphStyle

         pos = RULER_ONE_INCH

         interval = RULER_ONE_CENTIMETER

         Call rtpStyle.SetTabs(3, pos, interval, TAB_DECIMAL)

         Dim richText As New NotesRichTextItem(doc, "Body")

         Call richText.AppendParagraphStyle(rtpStyle)

         Call richText.AddTab(1)

         Call richText.AppendText("The meeting is a 3:00.")

         Call doc.Save(True, False)

    End Sub

See also
Working with tabs


Examples: FolderReferencesEnabled property

  1. The following script creates a new document in the database, puts it into "view1", "view2", and "view3" folders, then prints out all folder references and a count for each document.

    2. Sub Initialize

    Dim session As New NotesSession

    Dim db As NotesDatabase

    Dim doc As NotesDocument

    Set db = session.CurrentDatabase

    If(db.FolderReferencesEnabled) Then

       Messagebox "Folder References enabled"

    Else

       Messagebox "Folder References are not enabled"

       Messagebox "Enabling Folder References"

       db.FolderReferencesEnabled = True

    End If

    db.FolderReferencesEnabled = True

    Set doc = db.CreateDocument

    If Not (doc Is Nothing) Then

      Call doc.AppendItemValue("Name", "Test Document Name")

      Call doc.AppendItemValue("Topic", "Test Document Topic")

      Call doc.Save(True, True)

      Messagebox "Adding document to views"

      doc.PutInFolder("view1")

      doc.PutInFolder("view2")

      doc.PutInFolder("view3")

      Call doc.Save(True, True)

    End If

    Dim doccoll As NotesDocumentCollection

    Set doccoll = db.AllDocuments

    Set doc = doccoll.GetFirstDocument

    While Not (doc Is Nothing)

      i=0

      Forall FolderReference In doc.FolderReferences

      i=i+1

      Messagebox doc.noteid, " ", i, " ", FolderReference

      End Forall

      Set doc = doccoll.GetNextDocument(doc)

    Wend

    End Sub


Example: IsCaseSensitiveSort property

This script indicates if a column is sorted without regard to case.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim view As NotesView

Dim column As notesViewColumn

Set db = session.CurrentDatabase

Set view = db.Getview("Align")

Set column = view.Columns(0)

Messagebox (column.IsCaseSensitiveSort)


Example: IsResortAscending property

This script indicates whether or not a resortable column can be resorted in ascending order.

Dim session As New NotesSession

Dim db As NotesDatabase

Dim view As NotesView

Dim column As notesViewColumn

Set db = session.CurrentDatabase

Set view = db.Getview("Align")

Set column = view.Columns(0)

Messagebox (column.IsResortAscending)


Example: PickListCollection Method

  1. This example displays the documents in the By Author view of a database called Zippy in a modal window.

    2. Dim session As New NotesSession

    Dim workspace As New NotesUIWorkspace

    Dim db As NotesDatabase

    Dim collection As NotesDocumentCollection

    Set db=session.CurrentDatabase

    'Launches a modal window dispaying all of the documents in the By Author 'view of the database Zippy

    Set collection = workspace.PickListCollection(1, True,_

          "ZippyServer","Zippy","By Author","My Dialog", _

          "Please select a document or two.")
  2. This example displays the documents in the By Author view of a database called Zippy in a modal window and saves the selected documents to a folder called "My Folder" when the user clicks o.k.

    3. Dim session As New NotesSession

    Dim workspace As New NotesUIWorkspace

    Dim db As NotesDatabase

    Dim collection As NotesDocumentCollection

    Set db=session.CurrentDatabase

    'Launches a modal window dispaying all of the documents in the By Author 'view of the database Zippy

    Set collection = workspace.PickListCollection(1, True, _

           "ZippyServer","Zippy","By Author","My Dialog", _

           "Please select a document or two.")

    'The following line puts the selected documents in a folder called My 'Folder. The value True means that a folder will be created if one does not 'already exist.

    Call collection.PutAllInFolder("My Folder",True)

See also
PickListCollection method


Working with an embedded object

The EmbeddedObjects property of NotesRichTextItem is an array of all the embedded objects, linked objects, and file attachments in a rich text item, which are of the NotesEmbeddedObject class. The HasEmbedded property of NotesDocument tells you whether a document contains any embedded objects.

Note This feature is not supported under OS/2, under UNIX, or on the Macintosh.

To get all the embedded objects in a document, including objects that were originally embedded in the form from which the document was created, use the EmbeddedObjects property of NotesDocument.

To locate pre-R4 file attachments not associated with a rich text item, get all the items in the document, for example, by using the Items property of NotesDocument. Test the Type property of each item for ATTACHMENT. To get an attachment of this type, use the GetAttachment method of NotesDocument.

The following table lists the properties of NotesEmbeddedObject.

Property | Data type | Description
Class | String | (Read-only) Name of the application that created the object (does not apply to attachments)
FileSize | Long | (Read-only) Size of the object (does not apply to embedded and linked objects)
FitBelowFields | Boolean | {Read-Write) Sizes the embedded object to fit below the first layout in the document.
FitToWindow | Boolean | (Read-Write). Sizes the embedded object to fit the document window
Name | String | (Read-only) Name used to reference an object that was embedded through LotusScript
Object | Variant | (Read-only) OLE handle for an object that is loaded
Parent | NotesRichTextItem | (Read-only) Rich-text item that contains the object
RunReadOnly | Boolean | (Read-Write) Runs the embedded object when reading the document
Source | String | (Read-only) File name or OLE syntax for the source document/item of the object
Type | Integer constant | (Read-only) Type of object: EMBED_OBJECTLINK, EMBED_ATTACHMENT, EMBED_OBJECT
Verbs | Variant (array of strings) | (Read-only) Verbs that an OLE/2 embedded object supports

NotesEmbeddedObject has the following methods:

  • Activate causes OLE to load the object and returns a handle to the OLE object (on systems supporting OLE).

  • DoVerb executes an object verb (on systems supporting OLE).

  • ExtractFile copies a file attachment to a file.

  • Remove removes the object from its rich text item. You must call the Save method of NotesDocument to implement the removal in storage.

See examples
Examples: Working with embedded objects