13.2 Connecting to external data sources using DECS

---

13.2 Connecting to external data sources using DECS

As of the time of writing, the only connection tool that is shipped with Domino 6.5 for Linux on zSeries is Domino Enterprise Connection Services (DECS), and the only DECS connector available is for DB2 7.1 or higher. Lotus Enterprise Integration (LEI) is not part of the initial release, nor are DECS Connectors for any product other than DB2. The DB2 database must be on the same system as the Domino server, or you must configure a connection to another DB2 database through DB2 code on the Domino system.

In addition to the DECS functionality, you can use a Data Connection Resource (DCR) to connect to external data. DCRs are a new feature in Domino 6 which enable you to access external database data directly from your Notes application without going through the DECS Administration database.

This chapter provides an introduction to building an application using a DCR. For more information, see Domino Designer 6: A Developer's Handbook, SG24-6854.

13.2.1 Configuring DECS

In order to use a DCR, you need to install Domino Enterprise Connection Services (DECS). During configuration of the Domino server, in the Server Audience Screen, place a checkmark beside DECS. This will install the DECS task and configure it to run automatically.

13.2.2 Running DECS

DECS begins running as you bring up the Domino server. The DECS task is controlled by parameters in the notes.ini file. The ServerTasks line in the notes.ini file shows all of the tasks that Domino will run on a continuous basis. The DECS task is included on this line.

If, instead, you wish to control the DECS task manually, remove the DECS entry from the ServerTasks line. Then when Domino is started, DECS will not start automatically. You must start DECS manually until you change the notes.ini file to again include the DECS task.

To start the DECS task manually, type the following at your Domino console:

    LOAD DECS 

Domino will respond with a task response indicating that the task has started. The first time DECS is started, it will create the DECS Administration Database from the administration template that was included as part of the Domino installation process.

To manually stop the DECS task, type the following at your Domino console:

    TELL DECS QUIT 

Domino will respond indicating that the task has shut down.

The only supported data source for DECS connections for Linux on zSeries is DB2. Next we tell you how to connect Domino and DB2.

13.2.3 Preparing DB2 to connect with DECS or DCR

The name of the DB2 subsystem we used in building our activities is DB2. The name of the database we used is sample, and the username is db2inst1. The DB2 sample database has several tables that were defined when it was built. We accessed them using DCRs.

To start the DB2 database manager, log in to your Linux guest with your DB2 user ID (for example, db2inst1). Issue the command start dbm. For more information about starting the database manager and testing your connection to a database, see 10.5, "DB2: starting the database manager" on page 265.

Also, ensure that DECS has been started. You can have it start automatically when your Domino server comes up, or you can issue a command to start it. There is a utility called dctest that will test the connectivity of your workstation client through DECS to DB2. For more information on starting DECS and testing connectivity, see 10.6, "DECS: starting and testing connectivity" on page 266.

13.2.4 Connecting Domino with DB2 using DCR

We created a simple Notes database to show how to integrate a Domino application with DB2 databases. It is an organization database that holds employee data such as names, address information, expertise, and salary information. We kept the application simple so we could concentrate on the integration features.

The first thing we did was to create a DCR named Test DCR using the "Shared Resources -- Data Connections" section of the designer; see Figure 13-1 on page 319.

Figure 13-1: Create DCR

When creating the DCR, we specified the Class and Type of database to connect to. (This can only be RDBMS and DB2, as of the time of writing.)Then we entered the database name, the username, and password for the user on the DB2 system; see Figure 13-2 on page 319.

Figure 13-2: DCR properties

By pressing the Browse metadata button at the bottom of the property box, we could browse the tables in our DB2 database and select the one that we needed need to use for our connection; see Figure 13-3.

Figure 13-3: Browsing external metadata

Next we created a form with fields that we mapped to the fields in the DB2 database. When we created a field, we checked the "External data source" checkbox in the properties box and the data source portion of the dialog box opened; see Figure 13-4 on page 320.

Figure 13-4: DCR field

Pressing browse allowed us to select the DCR, table, and DB2 field that we wanted mapped to our Domino field; see Figure 13-5. Note that the type of field (text, numeric, date, and so on) is indicated by the icon to the left of the field name.

Figure 13-5: Browsing the DB2 data

When we set up the mapping, we also must choose whether the field is a key field or a data field. If it is a data field, we must also choose if the data is to be stored locally.

Key fields are the link between the form and the backend database or application. Note that key fields are always stored locally, as well as on the backend.

Storing the data locally means that the data is always available to Domino. In Domino language, this is the equivalent of turning a "computed for display" field into a "computed" field.

After we defined our DCR and fields, we had to import the key fields into our Domino database from DB2. We clicked Import external records in the action bar of the designer client; see Figure 13-6. This creates "stub" documents in the Domino DB with just the key fields in them. Then, when the document is opened, the real time portion of DECS populates the data from the DB2 database.

Figure 13-6: Importing key database fields into Domino

After we imported the key fields, we had to check the "Allow connections using DCRs" box in the database properties box. Importing keys will not work if the checkbox is selected; you will receive an error message.

Figure 13-7 shows the form that stores the employee data. All the fields are text, except for:

• DispName:, which is a computed for display field that proper cases the person's name

• Birthdate:, which is a date/time field

• Age:, which is a computed field that calculates the person's age based on their birth date

Figure 13-7: Form design

When the document is opened, DECS pulls the data from the DB2 database and populates the form. Figure 13-8 shows the form with live DB2 data displayed.

Figure 13-8: Live DB2 data

The Notes client can then be used to update and maintain the DB2 database, and Domino replication can be used to distribute the data throughout an organization.

This gives you a brief overview of the use and power of DCRs. For more information, refer to these IBM Redbooks:

• Domino Designer 6: A Developer's Handbook, SG24-6854 for more information about DCRs

• Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connectors, SG24-5862 for more information on DECS and zSeries

---