Some terms you need to understand before connecting to a Domino system include: Domino runtime system, Domino environment, Domino Connection, port, database, logon and directory. You will learn about them in the following sections.

Before you can carry out any action within the framework of the Domino Connection, you must initialize the Domino runtime system with the class method

To end a Domino session from your application, you should always execute the shutDown class method to free memory and implicitly close all databases and documents that may still be open.

While you shut down, you are not prompted to save open documents. Be sure to save all in-memory objects before shutting down. Be aware that the Domino Connection ensures automatic deinitialization during image save. That means you must restart your Domino environment after every image save. If you find this inconvenient you may override this behavior with the following method:

In this case, however, it is absolutely necessary to be sure that the Domino connection is ended before ending the Smalltalk development environment with

You do not need to shut down the AbtLnEnvironment after each operation. It is common practice to start the environment when you start working on your application and shut down when you save your image. The samples provided with the VA Smalltalk Domino Connection regularly start and shutdown the environment only for completeness.

If you need to access variables stored in the notes.ini file, there is an easy way to achieve that. Use the getNotesIni class method to receive a dictionary. You'll find keys and values assigned that reflect the contents of the notes.ini file.

The environment also can find the location of local Domino or Notes names and address books for you. Use the localNameAndAddressBooks class method to receive an ordered collection of database names.

Lotus Domino and Lotus Notes are client-server products which allows the distribution of document data to a variety of locations. A Domino application or a Notes database can be found local on your computer or remote on a server. The server can be accessed through local area networks or remote communication lines. A client system or Smalltalk program which needs to access data on the server must specify where and how to retrieve the data. Use the AbtLnConnection class for a practical aggregation of the variables.

If a Domino server or Notes server is accessible through more than a single networking or communication line, you may want to specify which line to use for communications. Depending on the urgency or cost efficiency you might prefer either a cheap low throughput line or a costly high priority communication link. You can specify and access the communication port in the AbtLnConnection class using the port: and port methods. The ports available on your server are configured in the names and address book respectively in the server configuration. Ports are specified by a name (usually something like NetBIOS or TCP). Do not confuse this notion of port with a TCP/IP network port that is represented by a number. Domino Connection does not support IIOP as communication protocol.

Part of an AbtLnConnection is the specification of a server name. You can set and get the server name using the server: and server methods. Depending on whether your system is set up to use hierarchical names or not, you must comply with certain naming formats. Do not confuse Domino server names with TCP host names. See your Domino documentation on server names. For your convenience there a two class methods to set up connections to local databases and to your mail server.

As you might know from your own experience with the Notes client program, Notes uses "lazy logon", which means you can work without a logon until you actually access protected data. This behavior is not always desirable, so the Domino Connection supplies an explicit protocol to force logon to a Domino server whenever you like.

Here is sample code showing how you would logon to your mail server if you were set up on a LAN:

There is no need to explicitly close a connection. When you shut down AbtLnEnvironment all connections will be closed implicitly. However, be sure to close databases and database views whenever recommended in this documentation. Open databases and views allocate significant amounts of memory.

If you need to browse your local databases or if you want to get hold of your Domino networking environment, there is a set of classes to use. To understand the model you should be familiar with the concept of a directed graph. Besides AbtLnNotesDirectoryView you should look at AbtLnTreeNode and its subclasses. AbtLnTreeNode offers two methods: children and parent. If you imagine a Domino system to be set up like the following graphic, you can use the children protocol to retrieve a collection of subsequent tree nodes. Using the parent protocol, you'll get the upper level node.

Here is a sample that shows all databases in the data directory on your local workstation in the System Transcript window:

(Note that you directly expand the 'local' port node into local directories). You will find text of the following format on your Transcript window:

or

You can easily navigate into the subdirectories by sending the children message to the directory nodes.