DB2 as a Domino Data Store
When planning a DB2-based Domino application, remember that end users do not need their own DB2 connectivity. The Domino server fulfills this responsibility.
Creating a DB2-hosted Domino database results in a small NSF file that is created on the file system of the Domino server in its data directory. This file is typically smaller than a megabyte (often only a few kilobytes). DB2-backed Domino servers can replicate and cluster with traditional NSF-based Domino servers, so that both environments can co-exist if necessary. This can be particularly useful when testing Domino DB2 integration with existing Domino data.
The Domino and DB2 servers have the following possible relationships:
- The DB2 UDB server is installed locally on the Domino server.
- The DB2 UDB server is installed on a remote host accessible to the Domino server.
Testing environments typically leverage a DB2 UDB server that is installed locally on the machine where Domino is installed. The obvious advantage of this is local connectivity to the DB2 data store.
Prerequisites
Before you can install and configure DB2 as a Domino data store, there are several considerations you must address.
The Domino server must run Domino 7 or later. You must also install either the DB2 UDB server locally, or a DB2 Run-Time client, to catalog the DB2 "DOMINO" database. For remote installations where the DB2 server does not reside on the same host as the Domino server, one of the following must be installed locally on the machine where the Domino server executes in order for it to communicate with the DB2 host:
Domino 7 and DB2 are available for these operating-system platforms:
The Domino server that will store its data in DB2 must have transactional logging enabled prior to installing DB2. To enable transaction logging, edit the Domino Server document belonging to the Domino server that will use DB2-based storage. Select the Transactional Logging tab and set the Transactional logging option to Enabled. Next, allocate at least 192 MB in the Maximum log space field:
After transactional logging has been enabled, restart the Domino server. Domino will create the requested storage for the new transaction logs upon restart. You should see a message similar to the following, indicating that the requested logs are being created:
A DB2 installation account is necessary to install the DB2 software. Create this account and use it to log in to a local computer to install DB2. This user account is also used by the DB2 Server Enablement tool. This account can be either a local or domain user account created via either Windows or AIX. It must be a member of the Administrators group in use by the computer on which the DB2 software is to be installed. The account must also have the following privileges:
- Act as part of the operating system
- Create a token object
- Log in as a service
- Increase quotas
- Replace a process level token
When you're ready to install the DB2 software, use this account to log in to the target machine. Start the setup program, which includes important information detailing DB2 installation prerequisites. There is also a link to begin the product installation. Click it when all installation requirements have been met.
Installation and Configuration
This section examines an installation where the DB2 server is installed on the same machine as Domino.
The Setup wizard first prompts for an installation type. For DB2/Domino integration, you can select a Typical installation; Data warehousing and Satellite administration capability are not needed:
As the install program completes its work, it starts the DB2 software and displays a First Steps dialog. This dialog provides a link to create the sample database, which provides a convenient testing mechanism to verify connectivity to the DB2 server and the ability to catalog its databases. To create the sample database, click the Create Sample Database link located at the top left of the First Steps dialog. This displays the Create Sample Databases dialog. Confirm that the DB2 UDB sample option is checked, and then click OK.
It can take several minutes to create the sample database. If successful, a message will confirm that the sample database was created.
Testing Connectivity to the DB2 Instance
The DB2 Server Enablement tool will fail if it cannot connect to the DB2 instance hosting the DOMINO database. We recommend that you test connectivity from the Domino host to the DB2 instance prior to enabling DB2 Domino storage. To do so, you must first determine which port the DB2 instance hosting the DOMINO database binds to. If you don't have this information, you can determine it by launching the DB2 Control Center: right-click on the Server, and select the Export Server Profile option from the Context menu.
Selecting Export Server Profile prompts you for a destination filename. If successful, the Control Center responds by displaying the following dialog box:
After you export the file, open it and locate a section titled [inst>Instance Name], where Instance Name is the name of DB2 instance hosting the DOMINO database. Be sure that the Instance Name matches; many DB2 deployments have more than one instance deployed. After you find a match, locate the entry for PortNumber.
This entry appears in bold in the following output (in this example, the instance is located at port 50000):
[inst>DB2]
NodeType=4
NodeNumber=0
DB2Comm=TCPIP
Authentication=SERVER
HostName=db2domino.acme.com
ServiceName=db2c_DB2
PortNumber=50000
IpAddress=192.168.1.104
QuietMode=No
SPMName=ISSL
TMDatabase=1ST_CONN
If you have uninstalled and reinstalled any versions of the DB2 software, then your DB2 instance may not communicate via port 50000. Instead, DB2 may increment to a higher port number, such as 50001. Verifying the contents of the PortNumber variable in the Domino DB2 instance increases the likelihood that the connectivity test succeeds.
Verifying DB2 Version Information
In some cases, it may be necessary to verify the version of DB2 installed to ensure it meets the requirements of Domino. To verify the version information of your DB2 software, open a DB2 Command Line Processor window and enter the db2level command:
Additional DB2 Configuration
The SYSCTRL group name must be set within DB2. The Domino online help documentation describes how to do this using the Command Line Processor. It can also be done using the Control Center. This section examines this step using the Command Line Processor.
To update SYSCTRL_GROUP, open a Command Line Processor window. Review the current configuration by typing GET DBM CFG at the prompt. Verify that the value is not set by reviewing the results. Set this value if needed.
The following screen shot shows the DB2 instance in need of this configuration step:
To set this value to DB2DOM, type the following into the Command Line Processor window:
After DB2DOM has been added to the SYSCTRL_GROUP, stop, and restart the DB2 instance using the DB2STOP and DB2START commands.
The DB2 Server Enablement Tool
The DB2 Server Enablement tool configures Domino to use DB2 as its data store. The tool is available via the Domino 7 Administrator and is disabled by default. It resides in the Configuration tab, under DB2 Server Tools (you will notice the grayed-out tasks indicating that all DB2 Server Tools are disabled):
The DB2 Server Enablement tool requires that a DLL file be added to the Domino executable directory. In this example, the file is added to C:\Lotus\Domino as shown in the following figure:
If this file is added to the executable directory while the Domino server is running, restart it as well as any Domino Administrator clients connected to it. Then verify that the Enable Server for DB2… tool has been enabled.
Click Enable Server for DB2… when you are ready to enable your DB2-based Domino server. The following dialog box appears:
Verify that all requirements have been met, and then click Continue. The Domino 7 Administrator displays the DB2 Server Enablement tool. The DB2 Server tab of the dialog prompts for information needed to create the DB2 DOMINO database. Be sure that you have the name of the DB2 instance you intend to use for your DB2 DOMINO database. This value is specified in the DB2 database name field and defaults to DOMINO. You can choose another name for the DB2 database the tool creates, if needed. The DB2 datastore directory field is an optional field.
This dialog also allows you to specify whether the default Domino datastore for new databases is NSF-based or DB2-based. There is an option to Immediately update the server's Domino Directory with DB2 information, which when selected causes the tool to process this update immediately. If deselected, update is later processed by AdminP.
Next, click the DB2 Access tab and enter an OS account name to be used by Domino to access DB2. This dialog also requires the password associated with the OS account. After you enter this information, the Enable button is activated.
Clicking Enable displays the Enable Server for DB2 Results dialog, similar to the following figure:
This step adds notes.ini variables to the server document. These variables are processed when the server restarts. Specifically, this step sets the notes.ini variable DB2Init=Create to direct the Domino server to create the requested DB2-based DOMINO database upon restart. If the Domino server successfully creates this database upon restart, it sets the notes.ini variable from DB2Init=Create to DB2Init=OK.
After the Domino server has been enabled for DB2 storage, the DB2 tab appears in the DB2-enabled Domino server document as shown in the following figure:
The field values should reflect those entered via the DB2 Server Enablement tool.
It is a good idea to open the DB2 Control Center and confirm that the DOMINO database was created on the DB2 server. There are cases when the Domino server console may report that the database was created, when in fact it wasn't. You should see something similar to the screen shot that follows if the DB2 Domino data store was successfully created.
After the Domino server has been enabled for DB2 storage, you can take advantage of the benefits of using DB2 storage for new Domino databases. (Bear in mind that this does not convert existing Domino databases to DB2 storage.) At this point, you can optionally install the DB2 Access Server, which is necessary for creating DB2 Access Views and Query Views. These are discussed in the remainder of this chapter.