Represents a Notes® database.
Containment
Contained
by: NotesDbDirectory, NotesSession, and NotesUIDatabase
Contains: NotesACL, NotesAgent, NotesDocument, NotesDocumentCollection, NotesForm, NotesNoteCollection, NotesOutline, NotesReplication, NotesView
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.