Domino Connection


Establishing a connection

This section describes concepts you need to understand to establish a connection between VisualAge Smalltalk and a Domino or Notes system. It also includes instructions to establish an actual Domino Connection.

Smalltalk classes

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.

Domino environment

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

AbtLnEnvironment startUp.

To end a Domino session from your application, you should always execute the shutDownclass 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:

AbtLnEnvironment autoShutDown: false

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

AbtLnEnvironment shutDown
Note:If you have problems starting up your Domino runtime system, you may have problems with the PATH settings of your operating system. Make sure that the Domino or Notes system DLLs are globally accessible (in your PATH statement on Windows, in your LIBPATH statement on OS/2) and that the additional DLL which is delivered with Domino Connection is properly installed in your VisualAge binary directory.

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 VisualAge Smalltalk Domino Connection regularly start and shutdown the environment only for completeness.

Accessing environment variables

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.

Accessing multiple address books

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.

Domino Connection

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.

Ports

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.

Servers

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:

| connection |
"Initialize your Domino runtime system"
AbtLnEnvironment startUp.
 
"create a connection to the default mail server"
connection := AbtLnConnection mailServer.
 
"force logon and prompt for password if your ID requires any"
connection logOn.
 
"find out you mail server's name and your communication port
read results from the transcript window"
Transcript nextPutAll: connection server; cr.
Transcript nextPutAll: connection port; cr.
 
"Deinitialize Domino"
AbtLnEnvironment shutDown.

Closing a connection

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.

Domino database directory

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.
Sample database directory structure

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

| directoryTree localNode |
"Initialize your Domino runtime system"
AbtLnEnvironment startUp.
 
"get the virtual root node of the directory tree"
directoryTree := AbtLnDirectoryView new root.
 
"find out which one is the 'local' node"
localNode := directoryTree children detect: [ :portNode |
portNode isLocal ].
 
"expand the portnode and find directories and databases
located in the data directory"
localNode children do: [ :databaseOrDirectoryNode |
Transcript nextPutAll:
databaseOrDirectoryNode asString; cr].
 
"Deinitialize runtime system"
AbtLnEnvironment shutDown.

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

DatabaseTitle [ DatabaseFilename.NSF ]

or

[DirectoryName]

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

VisualAge parts

Making connections to a Domino or Notes data source using parts is even more convenient. The classes give you more control, but the parts will connect easily to any server that is reachable from your workstation. You will need to familiarize yourself with the following terms that are described below: access set, Domino Connection specification, and Domino Connection alias.

Domino access set (AbtNotesAccessSet)
Domino Connection saves objects that specify the connection to a certain Domino application or Notes database (so called connections specifications) in an access set. An access set is a class which is associated with your application, much like the classes that define your visual and non-visual parts. An access set can hold one or many connection specifications. When you create a new application, you will be prompted automatically when it is necessary to create an access set.

Domino Connection specification
A Domino Connection specification is designed to grant access to a particular database. It is composed of a database name, a server specification, and some additional attributes that help you tailor custom behavior. To find out about connection specifications in your system first try to open the connection specification window which is available from the Options menu in the Visual Organizer window.
Note:If you do not find the menu entry, your Domino Connection is not installed correctly. Refer to the installation notes for proper installation instructions.

Click on Domino Connection to open the connection specification overview. Your result should look something like this:

Note:If you open the connection specification window for the first time, there might be no entries in the listboxes. Load the Domino Connection sample application to find at least four predefined connection specifications.

Connection definitions

If you find an empty list, here is a step-by-step procedure to create your own connection spec:

  1. Select New to open the Domino Connection Definition window.
    New connection
  2. If you open the connection specification window for the first time in the current application, you will be prompted for an access set name. Remember that access sets are classes and choose a capitalized first letter for the name of your access set. Next specify a server name and a database name in the appropriate fields in the connection specification window.
    Note:If you are not sure about your Domino servers name, you should ask your Domino administrator. You also can specify local in the server name field to define access to databases on your workstation. There are two ways to specify a database path:
    • If your database is on your workstation, you can either specify a path relative to your data directory (find the definition of the data directory in your notes.ini, keyword (DIRECTORY) or you can specify a full operating system path including drive letter for databases outside your data directory.
    • If your database is located on a server, you can only specify a path which is resolved relative to the server's data directory.

    For the following examples, you will work with one of the sample databases which come with VisualAge Smalltalk Domino Connection. If you have copied them into your local data directory (which was suggested in the post installation procedure), you must type in the name of the database and specify an entry for the server.

    There is an even more convenient way to define the essentials of a connection specification: use the Find button to open the Domino directory view. Depending on your system setup you might find a variety of first level category entries in the browser or you might just find a single entry saying: local, if you are not connected to a server.


    Figure DDIRV not displayed.

  3. Click on the [+] icon left of the local workstation icon to expand the default directory tree. Select the vasample directory icon and expand it. Now select the vasample.nsf database and press OK.
    Figure DDIRVSE not displayed.
    Note:The display format in the database browser is as follows: A computer icon is displayed for a server, a folder icon represents a directory entry and a notebook stands for a database. Directory names are displayed in [ ] brackets, database information is composed of the database title, and the database name in [ ] brackets.
  4. Now return to the new connection specification window. You are ready to specify a connection alias. A connection alias is a symbolic name that is used in all Domino Connection parts to reference a particular database connection. Name your sample connection ConToSample.
    Figure CONTS not displayed.
    Note:You can set up an application using a connection alias for development referencing a temporary database. When you want to deploy the application, you can change the connection alias to let your application operate on different database, even on a different server. Be aware that changing a connection alias for a prefabricated application can cause problems if the newly selected database has structural differences compared to the old one. (It is similar to copying view and form definitions from one Domino database to another. They will only work if there are corresponding field definition and documents in that database).
  5. Now select an access set from the appropriate dropdown list in which the newly created connection specification will be stored. . You might use the access set that was created when you opened the connection specification window for the first time or you can create another access set using the New button.

Copying connection specification from other application
If you have loaded several applications that define connection specifications, you might want to use one of those already defined. Select the connection specification you want to copy from the upper listbox and press the Copy to application button. The spec is copied to the lower listbox and is available for future use in your application.
Note:The Copy to button is showing the name of the applications that is selected in the Visual Organizer and thus looks different depending on what application you are working on.


[ Top of Page | Previous Page | Next Page | Table of Contents ]