NotesDatabase (LotusScript)

Containment

Contained by: NotesDbDirectory, NotesSession, and NotesUIDatabase

Contains: NotesACL, NotesAgent, NotesDocument, NotesDocumentCollection, NotesForm, NotesNoteCollection, NotesOutline, NotesReplicationNodeType, NotesView

Properties

Methods

CreateDocumentCollection

GetAllUnreadDocuments

GetModifiedDocumentsWithOptions

GetNamedDocument

GetNamedDocCollection

GetOption

GetOutline

GetProfileDocCollection

GetProfileDocument

GetQueryResultsProcessor

QueryAccessPrivileges

UnprocessedFTSearchRange

UnprocessedSearch

UpdateFTIndex

Creation and access

There are several ways you 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 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, SizeWarning, 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 the following factors:

The script 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 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 access level to databases and servers corresponds to the access level of the script owner (the person who last saved the script). When a script runs on a workstation, the access level to databases and servers corresponds to the access level of the current user.

Example

NotesDatabase (LotusScript®)