Requirements & Specific Steps for Enterprise Integration Between Domino and Db2/Oracle

Mindwatering Incorporated

Author: Tripp W Black

Created: 07/31/2002 at 01:28 PM


Domino Upgrades / Installations, Notes Developer Tips
Software (Re)Configuration
LSX (LotusScript Extensions/Connectors)

  • Domino server installed and running.
    Notes: Must be the Application or Enterprise level server.
  • DECS installed with desired LSX Connectors
  • Client software installed on Domino server's operating system.
    e.g. the DB2 CAE (now the DB2 Run-time client or the full Connect Client)
    (The CAE is the name in the redbook, what is on the DB2 client CD is: "IBM DB2 Client". You can do the minimal install of only the run-time components.)
  • Protocols and ports necessary for the client software to talk to the the remote relational server
    eg. TCP/IP to the server port 54321
  • Username, password, and any necessary configuration (e.g. profile) on remote server.
    e.g.add the following line to the .profile file on for the username: ". /dba/db2/udb/sqllib/db2profile"
  • Username in appropriate database groups on the DB2 side to give the desired access.

Sample Steps:
Assumes both servers (e.g. Domino and DB2) installed and running.

NT 4.0 SP6A with Domino R5
1. Create a login ID (e.g. domdata) to be used for the data access.
    You could use the Domino "notes" ID but it is not recommended as all developers would then know the system id and password.

2. Put the ID in the groups necessary to give access to the database tables desired.
    If Domino is only reading information then it needs read access, otherwise it needs add and update access, too.
    Also remember to give execute access to any stored procedures that the LCX code needs to call.

3. If using DB2, edit the user's profile on the remote server for the database being accessed.
    The profile will look something like this: ". /dba/db2/udb/sqllib/db2profile".

4. Install the specific client on the Domino Server box.
    For DB2, you need the "DB2 CAE" client on the box with the Domino Server. It turns out that the CAE is the runtime only install of the IBM DB2 (Personal) Client.
    For Oracle 9, there is on "Universal Installer". Install the thinnest client possible.
    Configuration Information Needed:
    Server: ex.
    (domain name or IP address)
    Database: ex. MYDB
    (name or alias)
    Network Protocol:ex. TCPIP
    Port:ex. 520020
    For DB2, you need to catalog remote nodes and then "register" the remote database(s) in the database catalog. To do this use the database catalog command.
    1. => catalog tcpip node thisnode remote mydb2server.mydomain.local server 5000
    2. => catalog db sameple as mysample at node thisnode
    3. => connect to mysample as db2admin using db2admin (to test the new connection node)

    Easier, is to install the full connect client rather than just the run-time one. The full client has a Configuration Assistant (CA) which has a gui to help you complete these steps.

5. In the Domino directory on the server (d:/Lotus/Domino), find and run the LCTest. If this works, any problems you have are most like developer side errors. (Starting in Domino6 this is now DCTEST.EXE or ndctest.exe)
    LCTest (ndctest) requires that you specify the database the user and the password. (Use the alias name you used when setting up the database link in step 4.)

    All admin side configuration is working correctly.

    No Success:
    There is a configuration issue. Use the error scenarios below to help troubleshoot
    • Error stating the database does not exist/not found, check the alias you used here vs. step 4.
    • Error with the word permission, there is a problem with the group additions in step 2.
    • Error stating the library does not exist or you cannot connect, check the alias for the database. If that is correct, check your user profile.
    • Error stating that the connector cannot be found, then reinstall the LSX stuff off the Domino Server CD or download it from and make sure that you install all the connectors or at least this one that is missing.

6. Tests and Gotchas
    Verify the DB2 (or Oracle, etc) client and Domino are in the path statement if on windows. If linux, verify the file (will give error with exact library if missing) has link in right location (see other doc in db for more info) and that the .profile for the Domino user has been updated with the connection info.

    If you can connect from the Configuration Assistant (DB2), and you can LCTest, then check the path (if on windows) and the profile file (if on linux).
    Also verify that the Server security settings includes the signer of the DECS admin db (if using a DECS connector) and the signer of applications with DCRs also is in the field.

    Verify DECS is running.
    (see tech doc 2116399 on IBM web site.)
7. Verify Domino can see/use the connector using DECS administrator.
    Open DECS Administrator. Create a Connection and browse tables. If you can browse table made it. You are ready to write code.

    If you cannot, take a look at the error message:
    1. If it lists "libraries missing" in the error message, you are not talking to the connector (Did you update your .profile or PATH?)
    2. If it lists DB2 or ORA (for the DB2 or ORACLE client connectors), then you are having an issue with the database client installed on the server.
    3. If the error mentions a specific LS object or something Notes'ish then check your code.

8. Run a sample code test from within a Domino database.
    Run test code in a domino database. These can be found on in the LSX developer database on the server.

previous page