DB2/2 and RS/6000 are trademarks of International Business Machines
Corporation. ..... The lccon6.pdf file is available for download at http://www.notes.
net. ..... You can also connect to DB2 on an iSeries or mainframe using DDCS
gateway.
IBM Corporation Lotus Software, IBM Software Group One Rogers Street Cambridge, MA 02142
All Rights Reserved.
List of Trademarks Domino, cc:Mail, Notes, NotesBench, Domino Connectors, Domino Enterprise Connection Services, IBM Lotus Enterprise Integrator for Domino (LEI), and Notes/FX are trademarks; and Freelance, Freelance Graphics, Lotus, Lotus Notes, LotusScript, Notes Mail, NotesSQL, NotesView, 1-2-3, Organizer, SmartIcons, and SmartSuite are registered trademarks of Lotus Development Corporation and/or IBM Corporation in the United States, other countries, or both. OS/2 Warp and PowerPC are trademarks and AIX, IBM, OS/2 Presentation Manager, and SNA are registered trademarks, and DB2/2 and RS/6000 are trademarks of International Business Machines Corporation. Tivoli/Courier is a trademark of Tivoli Systems and/or IBM Corporation in the United States, other countries, or both. All other trademarks are the property of their respective owners.
Disclaimer THIS DOCUMENTATION IS PROVIDED FOR REFERENCE PURPOSES ONLY. WHILE EFFORTS WERE MADE TO VERIFY THE COMPLETENESS AND ACCURACY OF THE INFORMATION CONTAINED IN THIS DOCUMENTATION, THIS DOCUMENTATION IS PROVIDED "AS IS" WITHOUT ANY WARRANTY WHATSOEVER AND TO THE MAXIMUM EXTENT PERMITTED, LOTUS DISCLAIMS ALL IMPLIED WARRANTIES, INCLUDING WITHOUT LIMITATION THE IMPLIED WARRANTIES OF MERCHANTABILITY, NONINFRINGEMENT AND FITNESS FOR A PARTICULAR PURPOSE, WITH RESPECT TO THE SAME. LOTUS SHALL NOT BE RESPONSIBLE FOR ANY DAMAGES, INCLUDING WITHOUT LIMITATION, DIRECT, INDIRECT, CONSEQUENTIAL OR INCIDENTAL DAMAGES, ARISING OUT OF THE USE OF, OR OTHERWISE RELATED TO, THIS DOCUMENTATION OR ANY OTHER DOCUMENTATION. NOTWITHSTANDING ANYTHING TO THE CONTRARY, NOTHING CONTAINED IN THIS DOCUMENTATION OR ANY OTHER DOCUMENTATION IS INTENDED TO, NOR SHALL HAVE THE EFFECT OF, CREATING ANY WARRANTIES OR REPRESENTATIONS FROM LOTUS (OR ITS SUPPLIERS OR LICENSORS), OR ALTERING THE TERMS AND CONDITIONS OF THE APPLICABLE LICENSE AGREEMENT GOVERNING THE USE OF THIS SOFTWARE.
Preface This document provides information about the Lotus Connectors supplied with IBM Lotus Enterprise Integrator for Domino (LEI) and Domino Enterprise Connection Services (DECS). These Connectors can be used with LEI, DECS, Lotus Connector LotusScript Extensions (LC LSX), and Lotus Enterprise Solution Builder for Domino (ESB). Note The LC LSX is supplied with the Domino Server and Designer, Notes Client, LEI, and DECS. This manual also provides information about setting up and using Lotus Connectors, including information about required software and instructions for testing connectivity. This manual is a core component of both the LEI and DECS user documentation set. The following information is presented: •
Description of each Connector supplied with LEI and DECS, including properties and values on each Connection Document
•
Software requirements for connecting to external data sources and accessing the data in those external sources
•
Supplied connectivity testing programs DCTEST and CONTEST
Organization of this Manual This manual contains the following chapters. Chapter
Description
Preface
The preface provides information about the organization of this manual, related documentation, and Lotus support.
Chapter 1 DCTEST and CONTEST
This chapter provides information and instructions for running the connectivity test programs DCTEST and CONTEST.
Chapter 2 Connectivity
This chapter describes connectivity considerations for each of the supplied Connectors. continued
vii
Chapter
Description
Chapter 3 Introduction to Lotus Connectors
This chapter provides introductory information about each of the supplied Lotus Connectors.
Chapter 4 Lotus Connector for Notes
This chapter provides information about the Lotus Connector for Notes.
Chapter 5 Lotus Connector for DB2
This chapter provides information about the Lotus Connector for DB2.
Chapter 6 Lotus Connector for File System
This chapter provides information about the Lotus Connector for File System.
Chapter 7 Lotus Connector for ODBC
This chapter provides information about the Lotus Connector for ODBC.
Chapter 8 Lotus Connector for Oracle 7
This chapter provides information about the Lotus Connector for Oracle 7.
Chapter 9 Lotus Connector for Oracle 8
This chapter provides information about the Lotus Connector for Oracle 8.
Chapter 10 Lotus Connector for OLE DB
This chapter provides information about the Lotus Connector for OLE DB.
Chapter 11 Lotus Connector for Sybase
This chapter provides information about the Lotus Connector for Sybase.
Chapter 12 Lotus Connector for Text
This chapter provides information about the Lotus Connector for Text.
Chapter 13 Lotus Metaconnectors for LEI
This chapter provides information about the Lotus Metaconnectors for LEI.
Related Documentation This section lists documentation that you may find useful as you learn about and use the various Lotus Connectors. Note Two of the four LEI user documentation files (Lotus Connectors and Connectivity Guide - lccon6.nsf and Lotus Connector LotusScript Extensions Guide - lsxlc6.nsf) are also part of the DECS documentation set and are now supplied with Domino only, not LEI. To obtain these two needed documentation databases, you must either install DECS or perform a custom install of the Domino server and select the DECS User Assistance option. These two files are also available at http://www.notes.net. Their PDF equivalents are available only at http://www.notes.net.
viii Lotus Connectors and Connectivity Guide
LEI Documentation Documentation for LEI is available online with the product distribution and at http://www.notes.net. The LEI documentation set is listed below: •
IBM Lotus Enterprise Integrator for Domino (LEI) Activities and User Guide -- Provides information and instructions for using LEI and its Activities (leidoc.nsf and leidoc.pdf).
•
IBM Lotus Enterprise Integrator for Domino (LEI) Installation Guide -Provides installation, configuration, and migration instructions for LEI (leiig.nsf and leiig.pdf).
•
Lotus Connectors and Connectivity Guide -- Provides information on how to set up and use the supplied Lotus Connectors, including information about required software and instructions for testing connectivity (lccon6.nsf). This documentation file is installed with Domino, not LEI. The lccon6.pdf file is available for download at http://www.notes.net.
•
Lotus Connector LotusScript Extensions Guide -- Describes the Lotus Connector LotusScript Extensions, which can be used in writing scripted sessions for accessing enterprise data (lsxlc6.nsf). This documentation file is installed with Domino, not LEI. The lsxlc6.pdf file is available for download at http://www.notes.net.
•
IBM Lotus Enterprise Integrator for Domino (LEI) Release Notes -- The release notes (readme.txt) contain information about the current release of LEI that may not be included in the documentation set.
Current information about LEI can also be found at the following Web site: http://www.lotus.com/
DECS Documentation Documentation for DECS is available online with the product distribution and at http://www.notes.net. It is comprised of three separate manuals as follows: •
Domino Enterprise Connection Services User's Guide -- Provides information and instructions for using DECS (decsdoc6.nsf).
•
Lotus Connectors and Connectivity Guide -- Provides information on how to set up and use the supplied Lotus Connectors, including information about required software and instructions for testing connectivity (lccon6.nsf). This documentation file is installed with Domino, not LEI. The lccon6.pdf file is available for download at http://www.notes.net.
•
Lotus Connector LotusScript Extensions Guide -- Describes the Lotus Connector LotusScript Extensions, which can be used in writing scripted sessions for accessing enterprise data (lsxlc6.nsf). This documentation file is installed with Domino, not LEI. The lsxlc6.pdf file is available for download at http://www.notes.net. Preface ix
•
Domino Enterprise Connection Services (DECS) Release Notes -- The release notes for DECS are contained in the same database as the Domino Release notes. See Domino documentation for more information.
Current information about DECS can be found at the following Web site: http://www.lotus.com/ei
Other Documentation For more information about related tools, refer to the following documents:
Domino Administrator’s Guide -- Provides information for configuring and administering a Domino installation.
LotusScript Language Reference -- Provides information about writing LotusScript programs. This is useful when using the LSX to write customized Activities.
Additional Domino Connector Documentation -- Lotus Software, IBM Software Group sells additional Lotus connectors for enterprise systems including Enterprise Resource Planning (ERP) and Transaction Processing Systems. Specific documentation about these connectors is included with the connector software and package. You may need documentation for the specific databases, ERP, and transaction processing systems that you are using. •
The DB2 product editions are supplied with a library of online documentation. This contains excellent information, especially introductory, general terms, and error messaging descriptions. There are also many DB2 books available for download from IBM. The Quick Beginnings books are suggested reading for new users. For more information about DB2, see the following Web site: http://www.ibm.com/software/data/db2/library
x Lotus Connectors and Connectivity Guide
Contact and Support Information Lotus Software, IBM Software Group provides extensive support for its products. Enterprise Integrator Web Site To obtain the latest information about LEI and DECS, visit the following Web site: http://www.lotus.com/ei
Note Domino-related product updates for iSeries can be found at following Web site: http://www-1.ibm.com/servers/eserver/iseries/domino/support/qm u.htm
Technical Support To contact Customer Support with suggestions or questions regarding your Lotus Connector or LEI/DECS application, call 1-800-346-6388.
Preface xi
Chapter 1 DCTEST and CONTEST This chapter provides information about DCTEST and CONTEST. These programs test system and application connectivity to external data sources.
Overview After installing LEI or DECS, you should test your external system client connectivity using DCTEST. Once you have confirmed that your external system client connectivity is operational, you can begin the process of creating LEI or DECS Activities and Connections. However, before you execute an LEI Activity that uses one or more of these connections, you should test your connections using CONTEST. CONTEST tests that a specific Lotus connection can actually access the external system. For example, when you create a named connection using an LEI Connection Document, run CONTEST on that connection name before running any Activity that uses it. LEI and DECS are supplied with connectivity testing software. Both LEI and DECS supply the DCTEST utility, while LEI also supplies the CONTEST utility. DCTEST is a client-specific test program. It tests system connectivity to external data sources. For example, you could use DCTEST to test connectivity between your DB2 client and your DB2 server. CONTEST is a connector testing program, for use with LEI only, that tests specific LEI connections.
1
Supported Data Sources DCTEST and CONTEST test system connectivity to the following supported data sources: •
DB2
•
ODBC
•
Oracle 7
•
Oracle 8
•
OLE DB
•
Sybase
Testing Connectivity to External Data Sources with DCTEST DCTEST is a connectivity test that establishes whether the client data source access libraries are available and functional on the Domino server. DCTEST ensures that the communications and client software required to access a specific data source is available and properly configured. It does not test for specific product functionality. Before running DCTEST, you must install the appropriate external system client connectivity software (for example DB2, Sybase, and so on) onto the Domino server that hosts the LEI server and that also hosts the LEI Administrator. If your LEI server and Domino server are on two different machines, you must install the external system client connectivity software onto both of those machines. You do not need to install the external system client connectivity software onto your Notes client. On the iSeries, the appropriate connectivity software is automatically installed with LEI. Use DCTEST to test that your external system client connectivity software is operational. Once you have determined that it is working properly, use CONTEST (LEI only) to test specific Lotus connections prior to running LEI Activities that use them. Note LEI uses server-side browsing, not client-side browsing from the LEI Administrator. DECS uses server-side browsing, not client-side browsing from the DECS Administrator. Both LEI and DECS browse databases on the external system using client connectivity from the Domino server that hosts the LEI or DECS Administrator, not from the Notes client.
2 Lotus Connectors and Connectivity Guide
Syntax The syntax for using DCTEST is as follows: [n]dctest
Running DCTEST Follow the steps below to run DCTEST. 1. Locate the DCTEST program specific to your operating system platform in the Domino program directory. The DCTEST program has the following names for each of the associated operating system platforms: • Windows (Win32) platforms — ndctest.exe • UNIX platforms — dctest • iSeries platform — call Qnotes/dctest Note When working with a case-sensitive OS such as UNIX, enter the DCTEST program name using lowercase characters. Note When you use DCTEST on a UNIX or Linux platform, be sure that the shared library path points to the directory where the DCTEST utility resides. If you use the current directory as the shared library path, you will not be able to use DCTEST. Once you have completed your test with DCTEST, revert to the original shared library path setting. 2. Invoke the dctest program. The DCTEST screen appears, as shown below.
Chapter 1: DCTEST and CONTEST 3
3. Enter the number of the test you want to run and press Enter. 4. Depending on the type of external system you are testing, for example DB2, you are prompted to enter additional information as required to log in to the specified data source. After entering the external system database, user name, and password, the program attempts to connect to the external system server. For more information, refer to the chapter in this manual that discusses the specific external system for which you want to test connectivity. 5. A message appears indicating whether the test was successful or not. 6. You can retry a connection by entering “Y” at theTry Again? [N] prompt. This provides the opportunity to reenter the required information. Note Testing an ODBC connection with DCTEST can provide you with information regarding the minimum version and conformance level required of ODBC drivers so that they work with LEI or DECS. To obtain this information you must respond “Y” when DCTEST prompts you for a full report.
Testing LEI Connections with CONTEST CONTEST attempts to connect using LEI connections defined in the LEI Administrator. It tests the ability to make a connection using the information found in the LEI Connection Document. CONTEST must be run with an active LEI server.
Syntax The syntax for using CONTEST is as follows: [n]contest [Options] ...
[Options] n denotes the optional parameter: -p. This parameter displays the connector properties. ... denotes actual connection names (use quotation marks if spaces exist in the connection names). Typing [n]contest with no input parameters results in Help information being displayed.
4 Lotus Connectors and Connectivity Guide
Running CONTEST Follow the steps below to run CONTEST. 1. Open a Command Prompt/DOS window or a UNIX shell. 2. Locate the CONTEST program specific to your operating system in the Domino program directory. The CONTEST program has the following names for each of the associated operating system platforms: • Windows (Win32) platforms — ncontest.exe • UNIX platforms — contest • iSeries platform — call Qnotes/contest Note Because UNIX is case sensitive, be sure to enter the CONTEST program name using lower-case characters. 3. At the command line, type the command appropriate to your platform and press Enter. Note
CONTEST runs in a command window.
Note Information about the connection displays when you use the optional parameter -p. When you enter [n]contest without the parameter, only information about the successfulness of making the connection displays.
Examples Example 1 (Windows platform): C:\Lotus\Domino>ncontest "NotesDb on MyOracle"
Sample Output: Testing NotesDb on MyOracle NotesDb on MyOracle Connect Successful
Example 2 (UNIX Platform): C:lotus/domino>contest "Oracle on MyOracle" "Sybase 11 on MySQLServer"
Sample Output: Testing Oracle on MyOracle Oracle on MyOracle Connect Successful Testing Sybase 11 on MySQLServer Sybase 11 on MySQLServer Connect Successful
Chapter 1: DCTEST and CONTEST 5
Chapter 2 Connectivity This chapter provides instructions and information for setting up and testing connectivity to the following database systems: •
DB2
•
Notes
•
ODBC
•
Oracle 7
•
Oracle 8
•
OLE DB
•
Sybase
Client libraries of the external systems to be accessed must be installed on the LEI server and the Domino server. When running activities, if the LEI server that you want the activity to run on and the Domino server where the LEI Administrator resides are on separate machines, the client libraries must be installed on both machines. Note Access to other iSeries DB2/400 servers is integrated into OS/400. No additional software installation is required when using the Lotus Connector for DB2.
DB2 Connectivity This section lists supported platforms and configurations. It also lists specific LEI activities supported by the Lotus Connector for DB2.
Supported Activities The Lotus Connector for DB2 supports the following LEI activities: •
Direct Transfer • Source/destination connections • Destination metadata creation ("Create Target Metadata")
•
Command
•
Archive 7
•
Advanced RealTime (Virtual Documents and Virtual Agents), Virtual Fields, and DECS Real Time • Create, Open, Update, and Delete events
•
Replication • Master and Target connections
•
Scripted
•
Polling
•
Java
Connectivity to DB2 This section provides information about software required to connect to DB2. This information is provided to help you get started. You should refer to the documentation for the specific software you are using for complete instructions. The following DB2 product editions contain the Administration client and the Application Development client. These two items provide all the connectivity software you need for successfully connecting to a DB2 database server. The specific edition to use will depend on your environment. •
DB2 Universal Database (UDB) Workgroup Edition
•
DB2 Universal Database (UDB) Enterprise Edition
•
DB2 Universal Database (UDB) Personal Edition
•
DB2 Connect Enterprise Edition
•
DB2 Connect Personal Edition
For details about these Editions, see the appropriate DB2 user documentation. For the UDB Editions, see the manual entitled Road Map to DB2 Programming, Appendix A, "About DB2 Universal Database." See also the http://www-3.ibm.com/software/network/commserver for related information. Note Only the administration client is necessary for successful connectivity to a DB2 database server. On Solaris, due to similarities between the ODBC and DB2 application program interfaces, errors are seen when using concurrent connections to ODBC and DB2 in DECS. To avoid these errors, use the ODBC DB2 driver for DB2 connections rather than the DECS DB2 Connection.
8 Lotus Connectors and Connectivity Guide
Connectivity to DB2 on iSeries This section describes connectivity considerations between DB2 on a Windows workstation and DB2/400. None of the options described require the installation of software to the iSeries. When connecting to a DB2/400 server remotely, you must use DB2 Connect in order to specify OS/400 as the target DB2 database. The UDB Editions do not allow you to specify the target database operating system. DB2/400 is part of the base operating system on the iSeries and has support to be both a requester and server of remote DB2 requests. DB2/400 can be the target of DB2 connection requests from platforms such as NT, AIX, etc. It can also request DB2 connections to other DB2 databases in the network. DB2/400 supports both SNA and TCP/IP connections. See the "Connecting to Remote DB2 from iSeries" section for more details. Because DB2/400 is part of the base operating system, if you are running LEI native on the iSeries you do not need to install additional DB2 software on the iSeries. All DB2 databases being connected to, including the local DB2/400 database, must be registered in the Relational Database Directory (see WRKRDBDIRE). You can also connect to DB2 on an iSeries or mainframe using DDCS gateway. Connecting to a DB2 Data Source on iSeries All connections originating from the iSeries to DB2 databases (including the local DB2/400), require that the target DB2 database be registered in the Relational Database Directory on the requesting iSeries. Register DB2 data sources using the WRKRDBDIRE CL command. You can register your remote connections as either *SNA or *IP. If using SNA, communication configuration is required to connect to the remote database as described in the appropriate iSeries documentation. If using *IP, provide the target IP address or remote location name and verify that the target database is active on the designated port. The default IP port for *DRDA is 446. If the target database is another DB2/400 using a *IP connection, make sure that the DDM server job on the target iSeries is listening for the connection request. This occurs by entering a STRTCPSVR *DDM command on the target iSeries. The command starts the QRWTLSTN job on the iSeries in QSYSWRK subsystem. This job monitors the DRDA port. Note If you are connecting to a remote DB2/400, the password in the Connection Document should be in uppercase characters. Direct DB2/400 Connectivity This section describes direct DB2/400 connectivity considerations. Chapter 2: Connectivity 9
One Server Connecting to DB2/400 This configuration does not require the installation of software to the iSeries. You can use an *IP connection. If you are using SNA as your connection protocol, bundled with Connect Personal Edition is an SNA server. Install the SNA server with the SNA over APPC option. It must be over APPC; iSeries requires APPC for DB2 connectivity when using an SNA connection. Also, in this stand-alone environment, the SNA over APPC is self-sufficient; there is no general network need for APPC and SNA in the network. Refer to the IBM DB2 Connect Personal Edition Quick Beginnings document (numbered S10J-8162-00) as a means to begin the installation. Use a user name and password that exist also on the DB2/400. This will allow the installation to perform operations on the iSeries without intervention. Multiple Servers Connecting to DB2/400 This configuration does not require any software installed to the iSeries. This will install a gateway to DB2/400. A gateway allows access to the DB2/400 data from multiple servers. This software is only necessary if you plan to have more than one server. You can use an *IP connection. If using SNA as your connection protocol, the Connect Enterprise Edition does not come with bundled SNA software. You must install an SNA server, such as the Microsoft SNA server. If the DB2 Connect Enterprise Edition is not installed on the machine, then a DB2 client such as DB2 Administration Client needs to be installed on the machine. This client is needed to perform the direct connection from the Domino server to DB2. Server Connecting to DB2/400 with DDCS A Distributed Database Connection Services (DDCS) and SNA server are required. This configuration does not require the installation of software to the iSeries. This configuration is for customers with an existing DDCS installation. This option only exists for customers who have DDCS already in house, because at this time only the latest DB2 Connect Versions 6.1 and 7.1 software is available for purchase. DDCS Single User or Gateway can be used to connect to DB2/400. With DDCS, there is also a requirement for an SNA server over APPC. Therefore, you need SNA software such as Microsoft SNA.
10 Lotus Connectors and Connectivity Guide
If DDCS is not installed on the server machine, a DB2 Client such as DB2 Administration Client must be installed on the server machine. This client is needed to perform the direct connection from the server to DB2/400.
ODBC DB2/400 Connectivity ODBC DB2/400 connectivity is facilitated through the DB2 client. This gives the server the advantage of straight connectivity, speed, and data type access without the ODBC layer. However, if you install products such as IBM's Client Access for iSeries, then the connectivity is through the ODBC link. Be certain to verify the requirements of the individual packages; in most cases an SNA server is still a requirement. Note This option may require that additional software be installed on the iSeries.
Connection for DB2 CAE and DDCS LEI offers native connectivity to DB2. This provides a direct connection to DB2 on all DB2-supported platforms, and enhances the DB2 connectivity previously provided through ODBC. The native interface offers improvements in speed and support for native data types not accessible through ODBC. This section contains information on configuring native DB2 connectivity through Distributed Database Connection Services (DDCS).
Getting Started Network communications programs must be installed to the server and the DB2 system to establish a network connection for data transfer. Depending on the platform you are using to operate the server, and the operating system used to store DB2, your requirements are either to install the Administration Client or DDCS. These communications products are available from IBM. The Administration Client is also available on your DB2 Edition CD-ROM. The machines must have connectivity through the Administration Client or a DB2 run-time environment such as DB2 server. For DDCS for Windows NT to access DRDA Application servers such as DB2 for MVS/ESA, the APPC protocol support must also be installed on your system. The program required to do this is Microsoft SNA server Version 2.11 or later. Before attempting to connect, verify connectivity through the DB2 command line program (supplied with DB2) or the DCTEST connectivity test program.
Chapter 2: Connectivity 11
Sample Steps for DB2 Administration Client Configuration on NT The following illustrates some sample steps you may wish to follow when configuring your DB2 connectivity using the Administration Client on NT. For full details, refer to the DB2 manual Install/Use DB2 Clients for xxx where xxx is your operating system. The steps below assume you are installing the administration client for the server machine running on Windows NT and using TCP/IP. 1. Install the DB2 Administration Client software. 2. Using the DB2 Client Configuration Assistant, follow the steps to configure your client for connectivity to a DB2 server. 3. Verify connectivity to DB2 from Domino by running the ndctest.exe program found in the Domino program directory. This program will prompt you for the database name or database alias, userid, and password.
Sample Steps for DB2 Administration Client Configuration on UNIX The following illustrates some sample steps you may wish to follow when configuring your DB2 connectivity using the Administration Client on UNIX. For full details, refer to the DB2 manual Install/Use DB2 Clients for xxx where xxx is your UNIX operating system. The steps below assume you are installing the Administration Client for the server machine running on UNIX and using TCP/IP. 1. Install the DB2 Administration Client software. 2. Ensure the server machine can resolve the DB2 server TCP/IP host address. For example, you should be able to ping the server. If it can't, either update the Domain Name server to include the DB2 server name and address or add an entry to your server machine's /etc/hosts file. 3. Ensure the DB2 server has enabled the TCP/IP protocol through the DB2COMM environment variable. This variable may indicate multiple protocols. Make certain it includes TCPIP. This variable must be set at the time the DB2 server is started. 4. Ensure the services file on the DB2 server machine contains an entry for TCP/IP support for each database manager instance you plan on accessing. db2inst1c
3700/tcp
# DB2 connection service port db2inst1i
3701/tcp
# DB2 interrupt connection service port
12 Lotus Connectors and Connectivity Guide
In this example, db2inst1c is the value of the service_name parameter and db2inst1i is arbitrary. 3700 and 3701 are the port numbers for the connection and interrupt port, and TCP is the protocol. The port number 3700 is arbitrary, but must be unique within the file. The second port number must also be unique and be equal to the first number plus one. These same numbers must be used when configuring the services file on the server machine. 5. On the server machine, catalog the DB2 server and database. To catalog the server, use the DB2 command line processor on the server machine and enter the command: CATALOG TCPIP NODE nodename REMOTE hostname SERVER servicename
In this example, nodename is a name you use to refer to this connection, hostname is the TCP/IP name of the DB2 server machine, and servicename is the instance name you entered in the services file (you only need to do this once using the first port even if you also entered an interrupt connection service port in the services file). 6. Catalog the database using the following command: CATALOG DATABASE databasename AS local_database_alias AT NODE nodename
In this example, databasename is the name of the database on the DB2 server, local_database_alias is a name you choose when you wish to connect to the database from the server machine, and nodename is the name you used in the previous CATALOG TCP/IP command. 7. Exit and restart the DB2 command line processor. Connect to the DB2 database with the following command: CONNECT TO local_database_alias USER username USING password
In this example, local_database_alias is the alias you cataloged and username is a valid DB2 user name. 8. Verify connectivity to DB2 by running the DCTEST program found in the Domino program directory. This program will prompt you for the database name or database alias, userid, and password.
When to Use IBM Distributed Database Connection Services (DDCS) DDCS has been replaced by DB2 Connect Personal Edition and DB2 Connect Enterprise Edition. The following information is provided for environments which may not yet have acquired these connectivity packages.
Chapter 2: Connectivity 13
When connecting to DB2 for MVS/ESA, DB2 for VSE and VM(SQL/DS), or DB2 for OS/400, you can use DDCS. DDCS can also be used to connect to any other DB2 server but it is more direct and efficient to connect from the local machine using the Administration Client directly to the DB2 server. It does not matter where DDCS is installed as long as the Domino server machine can connect to the DDCS machine through TCP/IP, SPX, or any other DB2-supported protocol. Refer to the DDCS Install/Configuration document for instructions and software requirements. Connections to external systems may require additional communications software. Sample Steps for Using DDCS This example illustrates how DDCS works with the server. For this example, assume the following parameters: •
The server is running on a Windows NT machine named NP1.
•
The NP1 machine has the DB2 Administration Client for Windows NT installed and will connect to the DDCS workstation using TCP/IP.
•
DDCS is installed on an AIX machine named DB2GW. It has TCP/IP and the IBM Communications Server installed.
•
Connectivity to a DB2 database on the MVS machine MVS1 is desired and will be made through APPC.
1. The connectivity between DB2GW and MVS1 must be established though DB2GWs IBM Communications Server and MVS1's VTAM. The details of this configuration and configuration at the MVS host are not covered here; refer to the DDCS Install/Configuration manual for information. 2. MVS1s node and database is cataloged at the DDCS machine. The following commands are issued to catalog the remote node and database: CATALOG APPC NODE db2node REMOTE db2pic SECURITY PROGRAM
In this example, db2node is a name you pick to refer to this host, db2pic is the Symbolic Destination Name you defined when you configured MVS1 in the IBM Communications Server. CATALOG DATABASE db2db AS mydb AT NODE db2node AUTHENTICATION DCS
In this example, db2db is the MVS database name, mydb is the database alias, and db2node is the node defined in the previous command.
14 Lotus Connectors and Connectivity Guide
3. The services file on the DDCS machine (DB2GW) is modified to include an entry for a database instance (inst1c) and an interrupt connection (inst1i). The following DB2 command must be used. It tells the database manager to listen for connections to the instance from remote clients to the instance. UPDATE DATABASE MANAGER CONFIGURATION USING SVCENAME inst1c
4. The environment variable DB2COMM is set to TCPIP. DDCS is started with the operating system command DB2START. 5. Connectivity from NP1 is established through the DB2 Administration Client by defining the target database: CATALOG TCPIP NODE gw1 REMOTE db2gw SERVER inst1c CATALOG DATABASE mydb AS mvsdb2 AT NODE gw1
In this example, gw1 is the alias that will refer to the DDCS gateway and will be used by the server, db2gw is the TCP/IP name of the DDCS Gateway machine, and inst1c is the service name defined in step 3 above. The mydb alias is defined in step 2 above; mvsdb2 is the alias that will be used by LEI.
DB2 Connectivity Test To test for connectivity to DB2, complete the following steps: 1. Run the test program DCTEST, located in the Domino program directory, appropriate to your operating system. 2. Select DB2 from the program menu. 3. Enter the data source, user name, and password when the program prompts for them. 4. Choose (Y/N) whether or not you want detailed driver information. 5. You can produce a printed report for diagnostic purposes. When asked, you can choose to output to a file (Y) or not (N). If you do not choose output to a file, the results appear on your monitor. 6. If you chose file output, supply a name for the file, then press Enter. The program then attempts to connect to the DB2 data source. 7. You can retry a connection by entering "Y" when prompted for another data source.
Chapter 2: Connectivity 15
ODBC Connectivity This section provides information about setting up connectivity to an ODBC data source.
Requirements for ODBC Connectivity Connectivity software requirements depend on the operating system platform and the ODBC version you are using. You must have: •
The ODBC driver appropriate to the operating system. Lotus recommends DataDirect ODBC version 3.5.
•
The driver must be 32-bit on Windows NT.
•
The ODBC driver must be thread-safe.
•
The ODBC Administrator must be present.
•
The ODBC Administrator must contain correctly defined and configured ODBC data sources.
•
All client software required to connect to the ODBC data sources must be installed and configured correctly.
ODBC Connectivity Test To test for connectivity to ODBC, complete the following steps: 1. Run the test program DCTEST, located in the Domino program directory, appropriate to your operating system. 2. Select ODBC from the program menu. 3. Enter the data source, user name, and password when the program prompts for them. 4. Choose (Y/N) whether or not you want detailed driver information. Note Testing an ODBC connection with DCTEST can provide you with information regarding the minimum version and conformance level required of ODBC drivers so that they work with LEI, however, to get this information you must respond with Yes (Y) when DCTEST prompts you for this information. 5. You can produce a printed report for diagnostic purposes. When asked, you can choose to output to a file (Y) or not (N). If you do not choose output to a file, the results appear on your monitor. 6. If you chose file output, supply a name for the file, then press Enter. The program then attempts to connect to the ODBC data source. 7. You can retry a connection by entering "Y" when prompted for another data source.
16 Lotus Connectors and Connectivity Guide
Oracle 7 Connectivity This section provides information about setting up connectivity to an Oracle 7 server.
Requirements for Oracle 7 Connectivity Connectivity software requirements depend on the operating system platform and the Oracle 7 version you are using. You must have the following: •
With a Windows NT-based server: Oracle 7 SQL*Net version 1 or 2.
•
SQL*Net must be the same version as the SQL*Net installed on the Oracle 7 data server. A network connection must exist between the server machine and the Oracle 7 data server machine using SQL*Net.
•
Native Oracle 7 connectivity support requires Oracle version 7.2 or later.
•
LEI links with Oracle 7.2 libraries, which use SQL*Net for the communications layer. If you are using Oracle 7 with LEI, you must install Oracle 7 SQL*Net. You can use SQLNet Easy Config utility to configure SQL*Net.
Oracle 7 Connectivity Test To test for connectivity to an Oracle 7 server, complete the following steps: 1. Run the test program DCTEST, located in the Domino program directory, appropriate to your operating system. 2. Select Oracle 7 server from the program menu. 3. When the program prompts for an Oracle 7 user name, password, and connection string, enter a valid user name, password, and connection string. • The connection string can be for either SQL*Net V1 or SQL*Net V2, depending on what software you have configured on your Oracle 7 server and Domino server. • The general format for a V1 string is network_prefix:server_name:sid. • The format for V2 consists of a single identifier, service_name. • Refer to your Oracle 7 SQL*Net documentation for further information on the format of connection strings. 4. After entering a user name, password, and connection string, the program attempts to connect to the Oracle 7 server.
Chapter 2: Connectivity 17
A message appears telling whether the test was successful or not. You can retry a connection by entering "Y" at the Try Again? [N] prompt. This provides the opportunity to reenter all of the required information, for example if you misspelled an entry or entered the wrong user name, password, or connection string.
Oracle 8 Connectivity This section provides information about setting up connectivity to an Oracle 8 server.
Requirements for Oracle 8 Connectivity Connectivity software requirements depend on the operating system platform and the Oracle 8 version you are using. You must have Oracle client version 8.0.5 or 8i. Oracle connectivity on Solaris relies on the Oracle 8i client library found in ORACLE_HOME/lib. If you are using LEI and a pre-8i version of the Oracle client, you must create a symbolic link in ORACLE_HOME/lib using the command "ln -s libclntsh.so.1.0 libclntsh.so.8.0'". Note For best result, Lotus Software recommends matching your Oracle client and server versions.
Oracle 8 Connectivity Test To test for connectivity to an Oracle 8 server, complete the following steps. 1. Run the test program DCTEST, located in the Domino program directory, appropriate to your operating system. 2. Select Oracle 8 server from the program menu. 3. When the program prompts for an Oracle 8 user name, password, and service name, enter a valid user name, password, and service name. 4. After entering a user name, password, and service name, the program attempts to connect to the Oracle 8 server. A message appears telling whether the test was successful or not. You can retry a connection by entering "Y" at the Try Again? [N] prompt. This provides the opportunity to reenter all of the required information, for example if you misspelled an entry or entered the wrong user name, password or service name.
18 Lotus Connectors and Connectivity Guide
OLE DB Connectivity This section provides information about setting up connectivity to an OLE DB data source.
Requirements for OLE DB Connectivity Connectivity software requirements depend on the operating system platform and the OLE DB version that you are using. •
Microsoft Data Access Components (MDAC) 2.0 or higher is required. MDAC 2.5 is recommended; the latest version is available for download from . MDAC 2.5 can be installed on Windows NT 4.0 and is included in Windows 2000.
•
OLE DB supports connectivity to Microsoft SQL Server 7, SQL Server 2000, and Microsoft Access 2000. SQLOLEDB, the Microsoft SQL Server OLE DB provider, is currently the only supported OLE DB provider.
•
The preferred Net-Library can be set by the SQL Server Client Network Utility. Alternatively, the Net-Library can be specified in the Provider String when making a connection.
OLE DB Connectivity Test To test for connectivity to OLE DB, complete the following steps: 1. Run the test program DCTEST, located in the Domino program directory, appropriate to your operating system. 2. Select OLE DB from the program menu. 3. Enter the provider name, data source, provider string, authentication service, user name and password as prompted. The following is an example of the information that is returned when you have a successful connection.
Chapter 2: Connectivity 19
Sybase Connectivity This section provides information about setting up connectivity to a Sybase server.
Requirements for Sybase Connectivity Connectivity software requirements depend on the operating system platform that you are using. Operating System
Sybase Version
Windows NT
Sybase Adaptive Server 11.9.2
Solaris and AIX
Sybase Adaptive Server 11.1.1
A network connection between the Domino server and the Sybase SQL server is required. Note When DB2 and Sybase clients are installed on the same machine, the DB2 environment variable LC_ALL will adversely effect Sybase connectivity. To correct this problem, delete the environment variable.
20 Lotus Connectors and Connectivity Guide
Sybase Connectivity Test To test for connectivity to a Sybase SQL server, complete the following steps: 1. Run the test program DCTEST, located in the Domino program directory, appropriate to your operating system. 2. Select Sybase from the program menu. 3. Enter the server name, user name, and password as prompted. The test program then attempts to connect to the Sybase Adaptive Server machine. 4. A message appears telling whether the test was successful or not. You can retry a connection by entering "Y" at Try Again? [N]. This provides the opportunity to reenter all of the required information, in case a mistake was made in spelling or you gave the wrong user name, password or server name. 5. If problems persist, check to make sure that the client software is properly installed.
Chapter 2: Connectivity 21
Chapter 3 Introduction to Lotus Connectors This chapter provides introductory information about each of the supplied Lotus Connectors.
Connectors Overview A connection is a document that defines how a Lotus Connector will interact with a specific data source. The connection provides specific access parameters, such as server names, user IDs and passwords. The “connected” databases are the databases that LEI or DECS can access. Because the forms used with each connection type are different, each Connection Document is described separately. Before creating connections, you should verify that the LEI server (or Domino server if you are using DECS) can communicate with your system databases. Do this by running the data source-specific tests described earlier in this manual or in the specific manual for the Lotus Connector that you intend to use. After creating your connections, you should test them using the supplied utilities described in the “DCTEST and CONTEST” chapter in this manual.
Connectors and Supported Data Sources LEI and DECS provides the following standard Lotus Connectors for the associated data sources: •
DB2
•
Notes
•
File System (not used with Virtual Documents or Virtual Agents Activities)
•
ODBC
•
Oracle 7
•
Oracle 8
•
OLE DB
•
Sybase
•
Text (not used with Advanced RealTime or DECS Activities) 23
Additional Lotus Connectors are available and can be purchased separately. Client libraries of the external systems to be accessed must be installed on the LEI server and the Domino server. When running activities, if the LEI server that you want the activity to run on and the Domino server where the LEI Administrator resides are on separate machines, the client libraries must be installed on both machines. For more information about Lotus Connectors, visit http://www.lotus.com/ei.
Using Multiple Connections of the Same Type You can use multiple connections for the same types of databases as well as for the same databases. You can create multiple connections to the same database by making copies of a connection definition and then renaming the copies. You might do this is to access the same database but to set various permission levels for specific tables or to use a different username and password. Any number of Activities can use the same connection. Some connections are not supported by certain Activities. See the section entitled “Connections and Supported Activities” later in this chapter for more information.
LEI and Metaconnections: Specialized Intermediate Connections Metaconnections are specialized connections that perform an intermediary role in LEI when used with an Activity. Metaconnections enable specific actions to be performed on data. Supported Metaconnections include the following: •
Collapse/Expand
•
Metering
•
Order
•
Trace
Note Metaconnections are not used with LEI Advanced RealTime or DECS. The Metaconnection functionality is transparently integrated into LEI Advanced RealTime and DECS Activities. Once a Metaconnector is created, the Metaconnection Document can be found in the Connections views. You can use LEI browsing functionality within a Metaconnector. However, you must first select a metadata object (table, form, view, and/or 24 Lotus Connectors and Connectivity Guide
procedure) in every base Connector that is used with the Metaconnector. If base Connectors referenced by the Metaconnector do not have metadata selected, a message appears at which time you can return to the base connector, select metadata, and then rebuild the Metaconnection Document. This is a requirement only if you intend to browse the Metaconnectors.
Processing RTF Fields Between Notes and RDBMS Notes is primarily a document management system, not a relational database management system (RDBMS). Because of this, Notes performs special handling for attachments stored in rich text fields. Notes rich text fields are stored in a proprietary binary format. For example, Notes rich text data written to Oracle fields will result in the Oracle fields containing data in that proprietary format. Non-Notes applications will be unable to process this data. Notes rich text data is not the same as Rich Text Format data used for word processing documents. In order to use BLOBs or RAWs, they must first originate in Notes, be inserted into the Oracle table, and then be read back into Notes. Otherwise, the BLOB or RAW data will not be in a format that Notes can recognize. This is also true for LEI and DECS when a Notes database is one of the connected databases. For all non-Notes Connectors, if you move data into a Notes rich text field and then read it as type binary, that binary data will then be in Notes rich text format. Using a Notes Database as the Source Binary data transferred from a Notes source will act as shown in the following tables. Binary Data
Notes Destination
as binary
will be stored in Notes Rich Text format
as text
will be stored as Text
Binary Data
Non-Notes Destination
as binary
will be stored in Notes Rich Text format
as text
will be stored as Text
Non-binary Data
Notes Destination
as binary
will be stored in Notes Rich Text format
Non-binary Data
Non-Notes Destination
as binary
will be stored in Notes Rich Text format
Chapter 3: Introduction to Lotus Connectors 25
Using a Non-Notes Database as the Source Binary data transferred from a non-Notes source will act as shown in the following tables. Binary Data
Notes Destination
as binary
will be stored as Notes Rich Text format (but source may or may not be Notes Rich Text)
as text
will be stored as Text
Binary Data
Non-Notes Destination
as binary
will be stored as binary (in its original format)
Non-binary Data Notes Destination as binary
will be stored in Notes Rich Text format
Non-binary Data
Non-Notes Destination
as binary
will be stored as binary (in its original format)
Transferring Attachments Lotus Notes stores attachment data separately from rich text field data. Currently you can only transfer attachments from Notes to Notes; rich text fields with attachments do not store correctly in the target RDBMS such as DB2 and Oracle. To work around this constraint, you can use the Extract File Attachments option in the Lotus Connector for Notes to save attachments to files on disk. You can then use LotusScript to read the files, store their contents in LCFields, and save the LCFields to binary fields in a RDBMS. This level of scripting requires LotusScript expertise.
Processing Empty and NULL Values in LEI and DECS In DECS and in LEI, empty data in a Notes rich text or Text field is not set to NULL when it is transferred. It is transferred as “”. To set empty data to NULL requires that you write a LotusScript routine or a stored procedure. For LEI (but not for Advanced RealTime or DECS) NULL is not equivalent to an empty string or to an empty value such as zero. LEI regards a NULL as an undefined value, one that cannot be compared to other values. This is true for all LEI activities (except Advanced RealTime Activities), however, Replication is most sensitive to this issue. LEI Replication occurs whenever LEI performs a comparison between Database A and Database B and encounters mismatches in the comparison fields. For example, a replication will occur if LEI finds a NULL in one database matching a corresponding empty value in another. This can occur frequently with date specifications; 26 Lotus Connectors and Connectivity Guide
for example, if Database A specifies a date and Database B has no data specification. When this occurs, LEI uses SQL syntax to convert NULLS to values that are equivalent across databases.
Supported Connector Characteristics - List of Terms The following table defines the terms used in the “Supported Characteristics” section of each Connector chapter in this manual. Term
Definition
Writeback support
Indicates whether the connection supports writeback result sets. The term writeback is defined in RDBMS systems as an updateable cursor, which means that, using the result set, the most recently fetched record can be directly updated or deleted. A non-writeback update must first search the table using keys, however a writeback update can immediately locate the record to update. Writeback support saves time and is therefore more efficient.
Writeback index
Indicates the database index, if any, required to enable writeback support for a given metadata object. For example, some Connectors require that a unique index exist, while others do not.
Statement syntax
Refers to the statement type and format that this Connector accepts.
Condition syntax
Refers to the type and format of the condition statements that this Connector accepts.
Array transfer
Refers to the capability of this Connector to transfer many records at once. The benefit of transferring many records at once is that only one network transaction is needed, rather than many, for a given set of records — the data has the same number of bytes, but the transfer takes less time. Array transfers can be used for read or write operations, depending on the RDBMS and the Connector.
Actions supported
Refers to the Actions that this Connector is capable of supporting.
Catalog types
Refers to the Catalog types that this Connector supports for browsing-type operations.
Create types
Refers to the Object types that this Connector can create in the external system.
Drop types
Refers to the Object types that this Connector can drop from the external system.
Chapter 3: Introduction to Lotus Connectors 27
Connection Documents A Lotus Connection Document enables you to define connections to external data sources. Connection Documents contain access information for specific databases and users. When you create an activity, you make connection choices from the existing set of defined connections. The information required in a Connection Document may be different for different database products, so while the Connection Documents provide standard connection name fields, there are sections and fields specific to the external system. Refer to the specific Connector chapters in this manual for information about the type of connection you are creating. If you are using a premium Connector, refer to the documentation provided with the Connector. The Lotus Connectors use a series of properties. When defining a connection to LEI or DECS, values for these properties are specified in a Connection Document. When using a Lotus Connector with LSX classes, values for these properties are specified by setting properties of the LCConnection class. Note that fields which are browseable are not editable. Most Connection Document fields are browseable, enabling easy point and click access. For more information about the LCConnection class properties, see the Lotus Connector LotusScript Extensions Guide. Note In order to connect to a supported data source, you must have the required connectivity software for that data source installed on your server. Before attempting to create a Connection Document, you should verify that all of your external system software is installed and current with all available maintenance releases and fix packs.
Connection Pooling For optimum performance of a Connector, underlying connections to the external systems can be pooled. This pooling occurs in the Connector API and is automatic with subsequent connections. LotusScript provides a simple programmatic interface to connection pooling. The LCSession class exposes a property called “ConnectionPooling.” Setting this property to True enables connection pooling. For more information, see the “Connection Pooling” section in Chapter 1 of the Lotus Connector LotusScript Extensions Guide.
28 Lotus Connectors and Connectivity Guide
Creating a New Connection Document in LEI To create a new Connection Document in LEI, perform the following steps: 1. Open the LEI Administrator database, decsadm.nsf. 2. Click the Add Connection button on the LEI Administrator Action Bar. 3. Select a connection type from the resultant list. 4. Complete the Connection Document as needed. 5. Save and Close the Connection Document. 6. Test the connection as described in the companion document Lotus Connectors and Connectivity Guide.
Viewing or Editing Connection Documents in LEI Once you create a Connection Document, it is visible in the Connections view. To view or edit an existing Connection Document in LEI, do the following steps. 1. Open the LEI Administrator database, decsadm.nsf. 2. Select Connections from the LEI Administrator’s Navigator panel. 3. Select the desired Connection from the view display on the LEI Administrator. Note You can also edit connections used by a particular Activity by opening that Activity Document and clicking the Edit Connection button.
Creating a New Connection in DECS To create a new Connection Document in DECS, perform the following steps: 1. Click the Connection button on the DECS Administrator navigator. 2. Click the Add Connection button on the action bar. 3. Select the desired Connector type from the resultant display. 4. Enter the required information in the resultant Connection Document.
Viewing or Editing Connection Documents in DECS Once you create a Connection Document, it is visible in the Connection view. To view or edit an existing Connection Document in DECS, perform the following steps. 1. Select Connections from the Views area of the DECS Administrator. 2. Select the desired connection from the resultant display.
Chapter 3: Introduction to Lotus Connectors 29
Considerations This section lists general considerations for using a Lotus Connection Document. •
The “Rollback upon error” option, specified on a Connection Document, will not be effective when a transaction within an Activity must be closed to complete the next step of the operation. For example, a Direct Transfer Activity, with “Overwrite existing data enabled”, cannot restore the truncated data if the transfer portion fails.
•
When specifying view names on a Connection Document, only list views that will actually be used by all activities that use the Connection Document. Specifying a view name that is not needed by the calling Activity may cause that activity to fail.
Features Common to All Connection Documents The following sections describe the parts that are found in every Connection Document. For information about the unique parts of each Connection Document, refer to the appropriate Connector chapter. Pop-up Help Dark blue text in the section headings in a Connection Document indicates that pop-up help is available. To display pop-up help, place the cursor on the heading and press and hold the mouse button. LEI Connection Name This field provides a name that identifies the connection in LEI. Each connection requires a unique name. This feature is not part of DECS. The maximum number of characters is 127. Password Encryption (Not Available on All Connection Documents) Password encryption allows LEI users to encrypt password information using their own encryption keys. The LEI server is always able to read the passwords. Password encryption in LEI pertains specifically to the password as stored in the Notes database and as seen on the screen, not for communicating to the external system database. When data is sent to the external system database, encryption is removed. As the author of a Connection Document, you can encrypt passwords using Notes encryption keys. All encryption keys used to encrypt connections must be added to the LEI server’s Notes user ID. Once you have created encryption keys, you can enable encryption for a Connection Document by clicking the Password not Encrypted button in the Connection Document and then selecting the encryption key to use. This process is described below. 30 Lotus Connectors and Connectivity Guide
Creating and Using Password Encryption Keys This process attaches an encryption key on the LEI server ID. The encryption key is not for your Notes ID, it is for the Notes ID used by the LEI server. 1. Open a Connection Document. 2. Click File — Security — User Security from the Notes menu. 3. Enter your Notes password when prompted. 4. Click the Notes Data tab and then the Documents tab. 5. Click New Secret Key. 6. Enter a new encryption key in the resultant data entry field, for example abx459. Optionally add comments in the data entry field provided for comments. 7. Click OK. 8. The new encryption key, in this example abx459, appears in the Encryption keys field on the resultant User ID menu. 9. Click Export. 10. Specify a file name on the Domino server in which to store the new encryption key. 11. Shut down the Domino server where LEI is installed. 12. Select File — Tools — Switch ID and enter the Notes ID used on that Domino server. 13. Click the Notes Data tab and then the Documents tab. 14. Click Other Options and then select “Import Secret Key.” 15. Select the encryption key created above, in this example abx459. 16. Restart the Domino server where LEI is installed. Note See the Password Encryption section of the Notes online help for more information. 17. Create or open your Connection Document in Edit mode. 18. Click the Password Not Encrypted button on the Connection Document. 19. Click Yes in response to the password encryption prompt. 20. Click the key tab on the resultant Document property sheet. 21. Select the desired key, in this example abx459, from the Secrete Encryption keys field. 22. Save the Connection Document. You are now ready to run an LEI Activity with the Connection Document containing the encrypted key. Chapter 3: Introduction to Lotus Connectors 31
Common Connection Document Fields The tables below describe fields that are common to most Lotus Connection Documents. The number and title of these fields will vary depending on the external system and type of connection you select. For more information, see the chapter that describes the Connector that is specific to the type of external system you wish to connect to. Field
Description
Server/Provider/Oracle Version/SQL Server
Select Oracle version, enter the name of the Sybase SQL Server where the database is located, or relational database engine to use, or programmatic ID for OLE DB provider to use. Note This field is not available for all Connection Documents.
Database/Engine/Directory Path/Data Source/Host String Provider String Authentication Service
Enter the information required for the specific data source for which you are defining a connection. This information can vary according to the type of data source selected. Note Depending on the Connector, more than one field may be exposed to capture all of the required database information.
User Name
Enter the user name required to access the selected data source specified above.
Password
Enter the password associated with the User Name specified above.
Password Encryption Key Icon
Click the password encryption icon to encrypt your password for this Connection Document. You can click it again to turn encryption off.
Selection Type:
You can choose to connect to data in: Tables Views Procedures (stored procedures - see Note below) Select the desired option.
Note When you browse for a stored procedure in the Connection Document, you are presented with dialog box listing all the stored procedures in the external system database. When you choose a stored procedure, the parameters of the chosen stored procedure are automatically listed in the Parameters field (see the table below). If you do not specify a stored procedure in the Connection Document, you can select a stored procedure and its associated parameters from the Virtual Field or Virtual 32 Lotus Connectors and Connectivity Guide
Activity document. In either case, the stored procedure is entered as the default stored procedure in the Events section of the activity document. In most cases returned values are handled by the external system database, in the case of Oracle, the Oracle connector handles returned information. This is transparent to you, however the person responsible for writing Oracle stored procedures should be aware of it. See the Oracle example in Chapter 7 for a full explanation. Use the Table/View/Procedure/Subdirectory Selection section of the document to select the specific metadata that you want to access through this connection. Table/View/Procedure/Sub Description directory Selection Field Use the Manual button to select a table that does not appear in the current list of tables. After you enter a table all of the associated columns are displayed. See the section below, “Using the Manual Button,” for more information. Owner
This field allows you to select from tables by owner name. The default value is , allowing you to select from all tables in the database. Click the down-arrow button to see a list of existing owner names. This enables you to select only from tables belonging to the specified owner. You must enter a valid Owner name in this field. Note This field is not available for the Text Connection Document. Note For iSeries, the owner name corresponds to a library name or SQL collection in OS/400.
Name
This field shows the name of the specific table or view you select from the data source. Click the down-arrow button to access a list of the tables or views from which you can choose.
Column(s)/Parameters /File Attributes
This field lists the column names and their associated data types found in the selected table or view of the external data source. If you are working with stored procedures, this field displays the stored procedure parameters. See “Selection Type” in the table above. If you are connecting to a file system, use this field to list file attributes corresponding data types from the selected subdirectory.
Comments
Enter text in this field that may be helpful to you in organizing or keeping track of your Connection Documents. Chapter 3: Introduction to Lotus Connectors 33
Manual Button You can use the Manual button to specify a table that is not included in the list of tables or views shown when you select the down-arrow button next to the Name field. You must enter the owner name and the table name, except in the case of the Lotus Connector for File System. You must enter these items exactly as they are named in the data source or DECS/LEI will not be able to locate your table.
Below is an example of a completed Lotus Connection Document for a Sybase database.
34 Lotus Connectors and Connectivity Guide
Creating Connection Documents This example illustrates the process of creating a sample Connection Document in LEI. Note To create a Connection Document in DECS, see DECS User Guide (desdoc6.nsf). In order to connect to a supported data source, you must have the required connectivity software for that data source installed on your server. Verify that all of your database software is installed and current with all available maintenance releases and fix packs before attempting to create Connection Documents. For related requirements, see the first chapter of the Lotus Enterprise Integrator for Domino (LEI) Installation Guide. 1. From the LEI Administrator, click the Add Connection icon. 2. A list of supported external data sources appears. Note You can remove any of the supported data sources from the list that you do not intend to use. Refer to the Notes Application Developer’s Guide for more information on how to remove a form from a menu. 3. Select the needed data source type from the resultant list and click OK. The appropriate Lotus Connection Document appears.
Chapter 3: Introduction to Lotus Connectors 35
Below is an example of a Sybase Connection Document.
4. Enter the required information in the Connection Document. The Connection Document is divided in three sections: • User Assistant Help — This section of the Connection Document provides basic usage instructions. It only appears if you have enabled the User Assistant. • Connectivity — This section of the Connection Document specifies the database or data source and the connectivity information required to access that data source. • Table/View/Procedure/Subdirectory Selection — This section of the Connection Document enables you to select the specific metadata that you want to access through this connection. The title of this section varies depending on the type of data you want to access. 36 Lotus Connectors and Connectivity Guide
Calling External Procedures Procedures in external systems may be used in a number of forms-based Activities and from within LC LSX scripts. Some Connectors provide procedure functionality as an alternate method of performing data selection or modification operations, while for others it is the only method of communicating with an external system. In all cases, there are various contexts and requirements regarding the behavior and handling of parameters for procedures. Instructions for using procedures within a given LEI Activity or DECS operation can be found in the documentation for that Activity. Any special considerations for calling procedures within a specific Connector can be found in the documentation for that Connector. In general, parameters will be provided to procedures by name if named parameters are supported, otherwise by position. Output from procedures will be expected as returned result sets when supported, otherwise output parameters may be used. A procedure is generally used within three general contexts: •
Perform a black box action In this case, the caller is not concerned with the action being performed; inputs may be provided, but no specific behavior or output is expected. This context is generally used within an LC LSX script, as most forms-based LEI Activities expect specific behavior from a stored procedure. In this case, input parameters are provided as indicated in the script, and parameters of the corresponding name and data type will be supplied to the procedure. For Connectors that do not support named parameters, the parameter position becomes relevant.
•
Perform a modification In this case, the stored procedure is being used to alter data in the external database. This context is used in many situations; both from forms-based Activities and scripts. When called from a script, it is treated like the black box action described above. When used in forms-based Activities, the input parameters provided and the behavior expected is defined by the normal Activity behavior. For example, when using a stored procedure as the destination of a Direct Transfer Activity, the input parameters match the destination fields being stored, and the insertion of new data records is the expected behavior. The Activity in question will specify what parameters are provided for a given context. For example, a single Virtual Field Activity can perform inserts, updates, and deletes through different stored procedures, and the parameters provided are specific to the action being performed.
Chapter 3: Introduction to Lotus Connectors 37
•
Produce a result set In this case, a procedure is being used to return information from an external system, either to simulate a standard selection operation or as the only method of producing a result set, depending on the Connector. Input parameters may be provided, and a result set should be returned. The input parameters are supplied in the same manner as the other procedure contexts described above. The result set contents are generally determined by the procedure definition. In some systems, the fields being returned must be identified at the time of the procedure call by the caller. In this case, the output fields will be identified by the calling Activity, or manually within the script. An example of this behavior is Oracle procedures, which only return results in output parameters that must be identified at the time of the call.
Connectors and Supported Data Management Activities There are three LEI Advanced RealTime Activities - Virtual Fields, Virtual Documents, and Virtual Agents. All other Activities are referred to as Data Management Activities. For information regarding Connectors and supported Advanced RealTime Activities see “Connectors and Supported RealTime Activities” later in this chapter. The table below shows which Connectors work with each Data Management Activity. For more details, see specific Connector chapters in this manual. Lotus Connector
Archive
Command Direct Java Transfer
Polling Replication Scripted Activities
DB2
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Sybase
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Lotus Notes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
ODBC
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Text
Yes
Yes
Yes
Yes
No
No
Yes
File
Yes
No
Yes
Yes
Yes
Yes
Yes
OLE DB
Yes
Yes
Yes
No
Yes
Yes
Yes
Oracle 7
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Oracle 8
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes (for OS)
No
N/A No
No
N/A
No No Connector
38 Lotus Connectors and Connectivity Guide
Note The Command Activity is the only activity that does not require a connection. In such a case, the Command Activity would be executing an operating system command on the system on which the LEI server is running.
Connectors and Supported RealTime Activities Connectors that work with LEI Advanced RealTime Activities and DECS are listed below. For information regarding Connectors and supported Data Management Activities see “Connectors and Supported Data Management Activities” earlier in this chapter. Note A Virtual Fields Activity was previously known as a RealTime Notes Activity in LEI and DECS. Supported Connections in DECS The table below shows which Connectors work with a DECS Virtual Fields Activity. Lotus Connector
DECS Virtual Fields
DB2
Yes
Sybase
Yes
Lotus Notes
No
ODBC
Yes
Text
No
File
Yes
OLE DB
Yes
Oracle 7
Yes
Oracle 8
Yes
Chapter 3: Introduction to Lotus Connectors 39
Supported Connections in LEI Advanced RealTime The table below shows which Connectors work with each Advanced RealTime LEI Activity. Lotus Connector
Virtual Fields++
Virtual Documents++
Virtual Agents
DB2
Yes
Yes
Yes
Sybase
Yes
Yes
Yes
Lotus Notes
No
No
No
ODBC
Yes
Yes
Yes
Text
No
No
No
File
Yes
No
No
OLE DB
Yes
Yes
Yes
Oracle 7
Yes
Yes
Yes
Oracle 8
Yes
Yes
Yes
++Virtual Attachments and Integrated Credentials are options for these Activities.
Connector Data Type Conversion Tables This section describes how LEI handles data type conversions. It is provided as background information. This information may be particularly helpful if you are scripting with the LC LSX Classes. At the end of each Connector chapter is a section that includes documentation tables that define data type conversions for the specific data source defined by the Connector. These documentation tables arrange LEI or DECS actions into four sections — Execute, Fetch, Insert/Update, and Create. During activity execution, data is transferred from its native data type into an LEI or DECS field object, which is a component of a Fieldlist object. A Fieldlist is a collection of named fields which is temporarily stored (in memory only; not on disk) on the LEI server or Domino server in the case of DECS. The data is then transferred, replicated, copied, and so on, to the destination in the most compatible data type that LEI or DECS can determine. Data can undergo two changes — first into an LEI or DECS field and second into the compatible target format. Conversions such as character set are done at the last minute, and directly from source to target to avoid extra or unnecessary conversions.
40 Lotus Connectors and Connectivity Guide
The figure below illustrates the conversion process of data types. Note that this is meant to show how data types might be converted during an LEI Activity. DECS has a similar conversion process, but it is limited to conversion between a data source and Domino. For information about the specific conversions of data types for specific data sources, refer to the data type conversion tables in the specific Connector chapters of this manual.
The information below provides details on the data type conversions. •
Execute operations against a LEI or DECS connection produce a result set from the data source and a corresponding metadata structure called a Fieldlist in LEI or DECS. The Execute table defines what type of LEI or DECS field will be added to a Fieldlist based on the type of the field in the result set. In general, each data source type maps to a single LEI or DECS type. Any multiple choices indicate that certain attributes of the source data type can alter the LEI or DECS type used.
•
Fetch operations define what data transformations are valid in fetches from a data source result set into an LEI or DECS Fieldlist. In a Direct Transfer and most forms-based Activities, the Fieldlist produced by a Connector in Fetch is sent back to that Connector for Fetch, but from an LEI or DECS script there is no such restriction. For each LEI or DECS data type, the table indicates which data source columns may be fetched into that field. Multiple choices indicate that various data source types will be converted to the indicated LEI or DECS type. For an LEI or DECS binary field, the different formats allow for different type checking restrictions. For example, an LEI or DECS number list allows numbers to be fetched from Notes, but an LEI or DECS datetime list does not.
Chapter 3: Introduction to Lotus Connectors 41
•
Insert/Update operations are the opposite of a Fetch operation, and for each LEI or DECS data type the table defines the valid data target types which can be stored. Multiple values indicate that a single LEI or DECS type can map to multiple target types. Additional formatting information in a middle column has the same usage as for the Fetch operation above.
•
Create operations create metadata in the data target from an LEI or DECS Fieldlist. The table defines which data target type is created based on the LEI or DECS data type. Multiple values indicate that formatting information from the LEI or DECS field affects the choice. This is especially relevant for Create operations since LEI or DECS fields can hold additional formatting information specifically to refine creations. This is most apparent during an operation like Direct Transfer, but much of this is invisible to the LEI or DECS user except when using advanced scripts. Execute operations store additional formatting information in the LEI or DECS Fieldlist metadata, which is then used during creation to exactly reproduce (as best supported by the data target) the source. For example, a 2-byte unsigned integer in a data source will be represented by the LEI or DECS generic INT type. But the original information is still stored in LEI or DECS, and for a data target which supports such a type, this information will be used during Create operations.
To summarize, the Execute and Create tables define the default mapping performed by LEI or DECS when creating LEI metadata from a data source, or data target metadata from an LEI or DECS Fieldlist. The Fetch and Insert/Update tables define valid data type mapping between LEI or DECS and the data source/target.
42 Lotus Connectors and Connectivity Guide
Chapter 4 Lotus Connector for Notes This chapter provides information about the Lotus Connector for Notes, including descriptions of the fields in the Connection Document.
Introduction to the Lotus Connector for Notes This chapter provides information about the Lotus Connector for Notes. The Lotus Connector for Notes can be used with IBM Lotus Enterprise Integrator for Domino (LEI) and Lotus Connector LotusScript Extensions (LC LSX). The Lotus Connector for Notes allows you to define a connection to a Lotus Notes database. Notes Connection Documents are not available for DECS, nor are they available for Advanced RealTime Activities. Refer to Chapter 2, “Connectivity” for information about configuring and testing connectivity. Refer to Chapter 3, “Introduction to Lotus Connectors” for general information about Lotus Connectors.
Terminology The table below lists LEI terms and the corresponding terms in Notes. LEI
Notes/Domino
Server
Server
Database
Database
Metadata
Form
Index
View
Field
Field/Item
Record
Document
43
Supported Characteristics This section lists the supported characteristics of the Lotus Connector for Notes. For a definition of the terms used in this section, see “Supported Connector Characteristics — List of Terms” in Chapter 3 of this manual. If you are accessing the Connector using LotusScript, see the Lotus Connector LotusScript Extensions Guide for more information. •
Writeback support — Full
•
Writeback index — When an OrderList is provided, it uses an exiting view, creates a temporary or permanent view LEIIndexViewXXX, where XXX is the first available number. Lotus Connector for Notes properties are used to control view creation.
•
Statement syntax — Notes formula language. Excludes data modification statements but includes “execute ” where is a Notes agent that is not run on a view.
•
Condition syntax — Valid when placed in the following Notes formula: SELECT ...
•
Array transfer — None (Bulk Insert)
•
Actions supported — Clear, Reset, Truncate
•
Catalog types — Server, Database (no connection required), Metadata, Index, Field
•
Create types — Database (cannot be connected), Metadata, Index
•
Drop types — Database (cannot be connected), Metadata, Index
All connections have a set of properties with values that can be assigned and retrieved. See the Lotus Connector LotusScript Extensions Guide for a list of supported properties for each Connector. Also see sections “Common Connector Properties” and “LCConnection Properties” in the LCConnection Class chapter of that same manual.
Notes Connection Document for LEI The Notes Connection Document defines a Connection to a Notes database and specifies the Domino server on which the database can be found. Note The Notes Connection Document is not available for DECS or for LEI Advanced RealTime Activities. To create a new Notes Connection Document in LEI: 1. Open the LEI Administrator. 44 Lotus Connectors and Connectivity Guide
2. Click the Add Connection button in the Action bar. 3. Select Notes. To open an existing Notes Connection Document, select it from the Connection view on the LEI Administrator.
Common Features Each LEI Connection Document contains the following common features. User Assistant Help You can enable the User Assistant in order to open a Connection Document with explanatory text at the top of the document. To turn the User Assistant on or off, use the option in the Help portion of the LEI Administrator’s Navigator panel. Pop-up Help Dark blue text in the section headings in a Connection Document indicates that pop-up help is available. To display pop-up help, place the cursor on the heading and press and hold the mouse button.
Chapter 4: Lotus Connector for Notes 45
Name This field provides a name that identifies the connection. Each connection requires a unique name. The maximum number of characters is 255. The comma character is not allowed. Password Encryption This option enables the author of a Connection Document to encrypt passwords using Notes encryption keys. See the “Introduction to Connectors” chapter for details. Comment The Comment field provides space for you to annotate the Connection Document with meaningful descriptive text.
Fields in the Connection Document See the following tables for descriptions of the Connection Document fields.
46 Lotus Connectors and Connectivity Guide
Connectivity The Connectivity options are described below. Field
Description
Name
Specifies a unique name that identifies this Connection. The maximum number of characters allowed is 255. Commas are not allowed.
Domino Server Specifies the name of the server where the Notes database identified by this Connection is located. Leave this field blank if the database is to be accessed locally. Notes Database Specifies the file path and filename (*.nsf) of the Notes database identified by this connection, relative to the Notes data directory. For example, to access C:\notes\data\orders.nsf, enter orders.nsf in this field.
Connection Options These advanced options extend the capabilities of LEI to take advantage of specific Notes data structures and design elements. The options let you specify, for example, view-based selection criteria that manage the hierarchical structure of Notes. Connection Options also permit you to define data translation and manipulation. The options are divided into the following groups: •
General Options
•
Document Selection
•
Field Selection
•
Data Transformation
•
Data Creation
The fields in each of these sections are described below. General Options When you select the General Options tab, the following options appear. These options can apply to the source or destination database, depending on whether the connection is used by the Activity as the source or target connection.
Chapter 4: Lotus Connector for Notes 47
Field
Description
Binding Options: Do Not Enforce Form Design
Specifies that the Activity not execute any Notes form and field-related formulas. Computed fields, such as the current date, are not computed.
Binding Options: Enforce Field Flags Only
Specifies that the Activity set all field flags as defined in the form but not execute any formulas. As a result, special types, such as reader and author fields, are assigned in new documents as indicated in the form. This option avoids the overhead of computing field formulas.
Binding Options: Enforce Form Design
Calculates all field-related formulas (default value, input translation, and computed field) as part of the Activity. This option may cause slower data transfer as a result of formula calculations. This option does not execute @ function names that begin with Db. It does enable field flags.
Binding Options: Enforce Form Design and Perform Validation
Calculates all Notes field-related formulas (default value, input translation, and computed field), and invokes all Notes field validation formulas which ensure that the data is within the parameters for the field in the Notes form. Any field validation errors are recorded in the Activity log.
Server Port
Specifies the name of the port to use when dialing a server remotely.
File Path for File Attachments
Specifies the directory where file attachments are stored if the option “Extract File Attachments is selected” (see below). If no path is specified here, file attachments are copied to the current directory.
Use Computed Subforms
To support computed subforms, list all of the subforms to include here. All fields in these subforms will be considered to be part of the form and appear in the mapping dialog box in the activity. This field is disabled if anything other than “Do Not Enforce Form Design” is selected. For information about how to use computed subforms and enable form design, see the “Considerations” section later in this chapter.
Note Only Notes language formulas are executed by the above options. The above options do not execute LotusScript formulas. Document Selection When you select the Document Selection tab, the following options appear. The Document Selection section is used to configure the document level options used by the Activity. These are used to limit the documents that the Activity selects from the source. Several options can be combined, but the 48 Lotus Connectors and Connectivity Guide
filtering is cumulative. A document must satisfy all options to be selected. These options can apply to the source or destination database, depending on whether the connection is used by the Activity as the source or target connection, and apply to the creation of a result set.
Field
Description
Form To Use
Enables you to select a form from the database specified in the “Notes Database” field in the Connectivity section of the Connection Document. Fields To Use From Form — Once you select a form, the fields contained on that form are displayed. Check the field names that you wish to use. Note Any field selection here is ignored when this connection is used in a Replication Activity. To tailor field selection for replication, explicitly map the fields in the Mapping section of the Replication Activity Document.
Document Options: Include View Responses
Includes response documents of any parent document that is used in a view. This option cannot be used along with the option “Copy Response Hierarchies”. When used in a Notes to Notes transfer, the result in the destination database is not hierarchical and all documents are copied at the same level.
Document Options: Copy Response Hierarchies (Notes to Notes only)
This option ensures that response documents retain their hierarchical relations to the parent document. This option cannot be used with the option “Include View Responses.” To use this option from an Activity with manual field mapping, add a field LCXHIER to both field lists (this is not necessary for automatic field mapping by name or position). continued Chapter 4: Lotus Connector for Notes 49
Field
Description
Document Options: Include Documents of Other Forms
By default, the documents in a result set are restricted to those associated with the source form identified as the metadata in the Activity Document. Use this option to include documents of all forms in the result set, filtering them through the source form. Note If the option “Fetch View Column Data” is used for selection, this option is required and will be automatically selected.
Document Options: Delete Result Set
This option applies only when a Notes database is the source. Deletes documents from the source Notes database before transfer. As a result, the documents don’t show up on the destination database and are deleted from the source. To delete the source result set after a transfer, follow a regular transfer Activity with an Activity that deletes the result set. Identify the second Activity as a dependent Activity of the first. This option only affects document selection through an explicit Notes formula, such as a Direct Transfer Activity or the LC LSX Connection.Execute method. It does not affect generic selection such as done by Replication activities. This option applies only when a Notes database is the source. It has no effect when the connection document is used to connect to a destination.
Document Options: Case-insensitive View Searches
Makes view searches case-insensitive (they are case-sensitive by default). An example of where to use this is in timestamp replication with the case-insensitive string comparison option, where case-insensitive searches are needed in Notes.
Full Text Search Query to Execute
The full text query that you enter here is executed against the current result set and only the resulting documents (those that contain the searched text) are used by the Activity. The query is executed on the result set produced by either the command statement in the Activity or the View to Use for Selection entry, plus any defined agent to execute. The database selected in the Connection Document must be indexed and a view must be selected in “View to Use for Selection” to support this option. This option only affects document selection through an explicit Notes formula, such as a Direct Transfer Activity or the LC LSX Connection.Execute method. It does not affect generic selection such as those done by Replication Activities.
50 Lotus Connectors and Connectivity Guide
Field Selection When you select the Field Selection tab, the following options appear. The Field Selection section is used to limit the document fields (or view columns) used by the Activity to create the result set.
Chapter 4: Lotus Connector for Notes 51
The following table describes the Field Selection options. Field
Description
View to Use For If the name of a Notes view is entered, the documents appearing in that view will be selected by the Activity. This option replaces Selection and ignores any command statement specified in the Activity. By default, only top-level documents are included, although other options allow the view contents to be altered. Documents not in the view are ignored. When used with ordering or timestamps in Replication Activities, this field indicates the name of the view to use for these operations. When performing primary key replication, supplying a view name can improve performance by not requiring the database to be re-indexed with every Activity run. When no view is specified, a temporary view is still created and an event is logged suggesting use of a permanent view name. When the view is the wrong format or doesn’t exist, checking the Allow View Creation/Modification option (see below) allows the activity to create or overwrite that view in its own format. This option overwrites the view when modifying an existing view. Allow View Creation/Overwrite — Checking this option allows the activity to modify or create the view if it doesn’t already exist or doesn’t have the proper formatting. This option is required for timestamp replication when a view is specified. If the option “case insensitive view searches” is selected, then the view columns will be set to sort case-insensitive. Note When you use a permanent view to support keyed searches, such as those used by Replication Activities, and an existing view needs to be altered (as is always true for timestamp replication), that view will be deleted and a new view will be created. Agent to Execute
Enables you to choose an agent name from a resultant list. The agent specified will further refine the documents selected. The agent is executed on the result set produced by the command (or selection) statement in either a Direct Transfer Activity or a Command Activity. Note This option is only valid if the connection will be used in a Direct Transfer or Command Activity.
Special Fields Appends a virtual field named UNID to the result set. This field Options: will fetch the Universal Note ID for each document. Load Document Universal ID (UNID) continued
52 Lotus Connectors and Connectivity Guide
Field
Description
Special Fields Appends a virtual field named NOTEID to the result set. This Options: field will fetch the Note ID for each document. Load Document Notes ID (NOTEID) Special Fields Options: Load Parent Universal ID (REF)
Appends a virtual field named REF to the result set. This field will fetch each document’s parent Universal Note ID, which is used by Notes to maintain response hierarchies.
Special Fields Options: Load Last Modified Timestamp (@Modified)
Appends a field “@Modified” to the result set, which contains the Notes implicit document timestamp. Select this option on the relevant Notes Connection and specify it as a Timestamp in the Replication Activity to use Notes implicit timestamps in replication. This prevents having to use additional Notes Timestamp fields.
Special Fields Options: Extract File Attachments (FILE)
Appends a virtual field named FILE to the result set. FILE contains file names of all attachments in a document and extracts files to disk. The directory for file extraction is the current directory or the one specified in the “File Path for File Attachments” field in the General Options section of the Notes Connection document. While this option copies file attachments on a Notes to Notes transfer, the “Copy File Attachments” option is more efficient for this purpose because it does not write to files.
Fetch Selections Specifies how fetching is to be performed. Choose one of the following options. Fetch Document Items — Gets the field names from the form designated as source metadata. Fetch View Column Data — Gets data from the view designated at “View to Use for Selection.” The fields are automatically named column1, column2, and so on. The destination metadata must contain fields of this name, or use map by position or user defined mapping to prevent field mapping failures. Selecting this option automatically checks the option “Include Documents of Other Forms.” Note The Fetch View Column Data option retrieves text data only. Other Options: Translate Multivalue Types to Text
Transfers the contents of multivalue types Text List, Number List, and Datetime List as Text. This is useful when the destination database cannot accept a multivalue’s default binary type. continued
Chapter 4: Lotus Connector for Notes 53
Field
Description
Other Options: Copy File Attachments (Notes to Notes only)
Copies any file attachments associated with transferred documents. If this option is not selected, transferred file attachments will appear as icons only in the target. To use this option from an Activity with manual field mapping, add a field LCXFILE to both field lists (this is not necessary for automatic field mapping by name or position).
Other Options: Copy Special Composite Fields (Notes to Notes only)
Copies any composite support fields associated with transferred documents. This includes the fields, links, and fonts to return full fidelity of composed data. To use this option from an Activity with manual field mapping, add a field LCXCOMP to both field lists (this is not necessary for automatic field mapping by name or position).
Other Options: Maximum Length for Text Data
Signals LEI to use this length as the maximum for Text type fields. This option is often used when a metadata is being created in a relational database and text lengths and types are important. The default text length is slightly under 64KB. If the “Truncate Data When Necessary” option is set in the Activity Document, LEI truncates the text field to the maximum length indicated here before transfer. If the Truncate Data option is not checked, any record with one or more fields greater than this limit is not transferred, and LEI logs the error “Data overflow.”
Understanding Destination Column Data Types To use any of these options with transfers to a database other than Notes, you must already have columns available in the destination metadata. The columns are added as the last columns in the metadata (one for each of the fields in the order listed below). Some Notes Connection options add a special field to the result set. This field is automatically handled by a Notes target, but must be explicitly defined in a non-Notes target. When using LEI Replication between two Notes databases, these options must be selected in parallel, for both the source and target connections, to properly map within the Replication Activity. The destination database column types must reflect the following Notes data types: Database Column Type
Data Type
UNID
CHAR (32)
NOTEID
INT
REF
CHAR (32)
FILE
VARCHAR or BLOB
@Modified
DATETIME or TIMESTAMP equivalent
54 Lotus Connectors and Connectivity Guide
Note Since UNID, NOTEID, and REF are concepts found in Notes databases, but not in relational databases and other targets, pay special attention when you use these options and properties. When moving data from Notes to a non-Notes target, always check these options in the Connection Document (or in scripting, set these properties) when you require UNID, NOTEID, and/or REF to be transferred. Remember that these columns must be explicitly defined in a non-Notes external source. Transferring the UNID, NOTEID and REF data from a non-Notes external source back to Notes will not flow back to the UNID, NOTEID, and REF fields through a normal transfer. You must use scripting to do this kind of transfer. Data Transformation When you select the Data Transformation tab, the following options appear. The Data Transformation section provides options for executing formulas to transform data.
The following table describes the Data Transformation options. Field
Description
Formula to Execute During Select
Enter the Notes formula that will execute just after the data is fetched. The data is altered as part of the fetch/select operation. This applies when the connector is used to connect to the source database.
Formula to Execute Prior to Insert
Enter the Notes formula that will execute just before the selected data is inserted into the target. The data is changed as part of the insert operation. This applies when the connector is used to connect to the target database.
Formula to Execute Prior to Update
Enter the Notes formula that will execute before the data in the designated target is updated. The transformation will take place as part of the update operation. This applies when the connector is used to connect to the target database.
Transformation formulas should be prefixed with “select @all;”. For example, to assign a field value, enter the formula .
Chapter 4: Lotus Connector for Notes 55
Data Creation When you select the Data Creation tab, the following options appear. The Data Creation section provides options for managing data creation with the Notes database during processing of any Activities associated with the Connection.
The following table describes the Data Creation options. Field
Description
Notification Options: Sends inserted documents as mail rather than saving to a Notes database. The transferred records must contain a Send New Documents as Mail field named SendTo containing a valid address. For sources that support SQL, this field can be selected as part of the SQL SELECT clause in the statement of the Activity Document. Example syntax is shown below: select column1, column2 from table where SendTo=“[email protected]” Notification Options: Embeds the form in documents sent as a result of using the Embed Form in “Send New Documents as Mail” option. Use this option Mailed Documents when the recipients of the mail will not have the relevant form in their mail database. Notification Options: This option commits each change to the Notes database Commit Changes immediately. The default behavior is to commit all Immediately changes at database close. This option can slow down performance. continued
56 Lotus Connectors and Connectivity Guide
Field
Description
Notification Options: Reflects the database changes in the databases views at the end of the transfer or replication process when the Refresh Views as destination database is being closed. This option causes Database is Closed view refresh to occur as part of the transfer rather than to occur when the user next opens the view. Notification Options: Purge Deletion Stubs as Database is Closed
Use this option to clear all deletion stubs from the Notes database when disconnecting. It is strongly recommended that this only be used with the option to “Refresh Views as Database is Closed”, since once the stubs are deleted, they will not be properly removed from views. Selecting the “Refresh Views” option will remove them before purging. This option cannot be used on a Notes database with the Notes replication setting to “Delete documents not modified in the last N days.” Doing so will skip the purging and generate an error indicating the conflict. To use this option successfully, the LEI Notes ID must have sufficient access to the database to enable modification of Notes replication settings.
Encryption
Specifies how encryption should occur. Encrypt Enabled Fields — Encrypts all enabled fields in the form of the target document. Private Encyption Key(s) — To use private encryption keys (the default is to use the public key), provide one or more private encryption key names, separated by commas or semicolons in this field. These keys must be available on the LEI server. For more information on encryption, see Domino Designer Help.
Deletion: Delete Database upon Connection
Deletes the database specified in the Activity upon connection. This is used together with Creation (below) to delete and then recreate the database prior to population.
Creates a destination Notes database to receive the data if Creation: Create Database (if it a database does not exist. For database creation, you can optionally enter a template server and template file path. doesn’t exist) This option should not be selected when the target Domino server is part of a Domino cluster because the database may be created in an inconsistent state. When the target is a Domino cluster, create the database using a Notes client prior to running the LEI activity. Database Template Server
The Domino server containing the template file to be used to create the destination database.
Database Template File Name
The file path of the Notes .ntf template file to be used to create the destination database.
Chapter 4: Lotus Connector for Notes 57
Considerations when Working with the Lotus Connector for Notes This section addresses important issues in using a Notes Connection.
Activity Command Statements Aside from standard selection formulas using the Notes formula language, statements executed against Notes may also be of the following format: "execute agent name"
where “agent name” is the name of a Notes agent. This functionality can be used to modify data through a post-statement Polling Activity, where normally an update statement would be executed. By using this syntax, an agent that updates documents may be run. This is an LEI-specific formula language enhancement to account for the fact that non-selection formulas cannot be used as LEI statements. The “execute ” statement syntax requires a sufficient access level to perform the desired actions and access the agent. The agent must satisfy the following requirements: •
Uses a shared agent
•
Is run manually from actions menu or manually from agent list
•
Is run on all documents in database or run once
•
Does not use simple actions
•
Cannot be view-based, that is, specified as “run on selected documents in view” or “run on all documents in view”
LEI Replication of Notes When you make modifications to a client for Timestamp Replication, there is no way to obtain the server current datetime. Because of this, time differences between the Notes client and server are relevant. If the client is later than the server, then some changes may not be picked up until the next replication. If the client is earlier than the server, then some changes may be missed. If synchronization of time is not possible between client and server, then making the Domino server slightly earlier than the clients will prevent documents from being missed. When specifying a view to use (View property of Notes Connection Options), that view must be of a particular LEI format, and the keys indicated in the view are irrelevant (they are taken from the Activity view keys, regardless of the Activity). If the view is not of the correct format, then it will be modified by LEI, using the AlterView property of the Notes Connection Options. When a view is specified and the view is not of the 58 Lotus Connectors and Connectivity Guide
correct format, then it will be recreated for the proper result set. For this reason, do not use a view which is used for other purposes because it will be overwritten. When no view is specified, a temporary view is created for the duration of that Activity and a message is written to the log recommending that a permanent view be used. When using a view name with Timestamp Replication, the same view name is used between replications, but the view is still altered each time since it is categorized based on the last replication timestamp.
Notes Form Creation Notes form and field attributes, such as field formulas, help text, and formatting, will be set as defaults when LEI creates a new Notes form. Caution When you use the ’Create Target Metadata’ option on Direct Transfer, Archive, and Replication Activities to create a new form within a Notes target database, do not have the Notes target database open while the activity is running. The new form is not available until the database is closed and re-opened. Errors will result if you try to access the newly created records before the database has been closed and re-opened.
Notes @Functions The following @commands cannot be used in any Notes formula specified in an Activity. They are not supported except through the Notes interface: •
@DbLookup
•
@DbColumn
•
@Command
•
@MailSend
•
@Prompt
•
@DDEInitiate
•
@DDETerminate
•
@DDEExecute
•
@DDEPoke
Depositor Level Access When the LEI Server connects with Depositor level access, documents in the database are not visible. Any selection results in no documents. One effect is that overwriting or truncating data will not find any documents and therefore not remove them.
Chapter 4: Lotus Connector for Notes 59
Moving Text List Data over Different Platforms Notes databases store data in canonical format (byte ordering), which is platform-independent. LEI automatically converts data to the host platform’s byte ordering when read from Notes, and to canonical format when written to Notes. (Composite data is an exception: It is always left in canonical format.) As a result, all Notes-format data outside of Notes is considered to be in platform byte ordering native to the host format, allowing users to ignore the implications of canonical byte ordering. Moving data between Domino servers and Notes and other databases does not usually pose a problem. However, in the case where data is moved from one Domino server to another Domino server through another database, and using LEI server platforms with different host formats, list types (text list, number list, and datetime list) become corrupted. For example, you use a Windows NT LEI server to move a text list from Notes to DB2. If the data is moved from DB2 back to Notes through another NT server, there is no problem. But if the other LEI server is a UNIX server, then the data is corrupted.
Notes Data Types The following tables show the correspondences of Notes to LEI data types for various types of Activities. The following notes apply to the tables below: (p) — Indicates that if Allow Precision Loss is not enabled, then an error will be generated on the type match. Allowing precision loss is the default. (o) — Indicates that overflow checking will be performed when data is being transferred. If an overflow occurs and Truncate Data When Necessary is enabled, then the data is truncated; if not an error is generated. Text, Number, or Time indicates single-value unless otherwise specified. The Notes Connection Option “Maximum Length for Text Data” alters the default boundary of 64996 for LEI text. The Notes Connection Option “Translate Multivalue Types to Text” makes multiple-value Text, Data, and Time look like single-value Text. LEI evaluates the absence of a field in a Notes database as a NULL. Note For more information on the organization of these tables, see the section entitled “Note on Connection Data Type Conversion Tables” in Chapter 3.
60 Lotus Connectors and Connectivity Guide
Execute Notes Number
Time
LEI Single-value — Notes Number field contains a single value
Float
Allow multiple values
Binary (number list format, variable length, bound = 64996)
Single-value
Datetime
Allow multiple values
Binary (datetime list format, variable length, bound = 64996)
Keywords
Text (variable length, bound = 64996)
Names
Text (variable length, bound = 64996)
Author Names
Text (variable length, bound = 64996)
Reader Names
Text (variable length, bound = 64996)
Text
Single-value
Text (variable length, bound = 64996)
Allow multiple values
Binary (text list format, variable length, bound = 64996)
Rich Text
Binary (composite format, variable length, unbounded)
Fetch LEI
Notes
Int
Number (p, o)
Float
Number
Currency
Number (p, o)
Numeric
Number (p, o)
Datetime
Time
Text (o) Binary (o)
Text, Rich Text, Formula BLOB
Text, Number allow multi-values, Time allow multi-values, Rich Text, Formula
composite
Text (single-value), Rich Text
number list
Number, Text (single-value)
datetime list
Time, Text (single-value)
text list
Text
Chapter 4: Lotus Connector for Notes 61
Insert/Update LEI
Notes
Int
Number
Float
Number
Currency
Number (p)
Numeric
Number (p)
Datetime
Time
Text
Text, Rich Text, Formula
Binary
BLOB
Text (o), Number (allow multiple values) (o), Time (allow multiple values) (o), Rich Text, Formula (o)
composite Date from Notes Rich Text field
Text (single-value) (o), Rich Text
number list
Number (o), Text (single-value) (o)
datetime list
Time (o), Text (single-value) (o)
text list
Text (o)
Create LEI
Notes
Int
Number (single-value)
Float
Number (single-value)
Currency
Number (single-value)
Numeric
Number (single-value)
Datetime
Time (single-value)
Text Binary
bounded
Text (single-value)
unbounded
Rich Text
BLOB
Text (single-value)
composite
Rich Text
number list
Number (allow multiple values)
datetime list
Time (allow multiple values)
text list
Text (allow multiple values)
62 Lotus Connectors and Connectivity Guide
Virtual Fields The following virtual fields are supported by the Lotus Connector for Notes. For more information, see the “Field Virtual Codes in the LCField Class” section of the Lotus Connector LotusScript Extensions Guide. LEI
Notes
Int
Number (single-value)
Float
Number (single-value)
Currency
Number (single-value)
Numeric
Number (single-value)
Datetime Text Binary
Time (single-value) bounded
Text (single-value)
unbounded
Rich Text
BLOB
Text (single-value)
composite
Rich Text
number list
Number (allow multiple values)
datetime list
Time (allow multiple values)
text list
Text (allow multiple values)
Lotus Connector for Notes Properties See the Lotus Connector LotusScript Extensions Guide for a list of properties for the Lotus Connector for Notes.
Chapter 4: Lotus Connector for Notes 63
Chapter 5 Lotus Connector for DB2 This chapter provides information about the Lotus Connector for DB2, including descriptions of the fields in the Connection Document.
Introduction to the Lotus Connector for DB2 The Lotus Connector for DB2 delivers connectivity to IBM’s DB2 Universal Database (UDB), enabling LEI, DECS, and Domino applications written in LotusScript to access DB2 using the standard Lotus Connector API. The Lotus Connector for DB2 does not give access to all features of the DB2 UDB. The Lotus Connector for DB2 uses the DB2 Client Level Interface (CLI) to perform actions between the Lotus Connector API and DB2. Refer to Chapter 2, “Connectivity” for information about configuring and testing connectivity. Refer to Chapter 3, “Introduction to Lotus Connectors” for general information about Lotus Connectors. After creating your DB2 connections, you should test each of them using the Connection Document test utility provided with LEI.
Obtaining Updated DB2 Information Current information about DB2 can be found at the following Web site: http://www-4.ibm.com/software/data/db2/
65
Terminology The table below lists LEI terms and the corresponding terms in DB2. LEI Term
DB2 Term
Server
N/A
Database
Database
Metadata
Table
Index
Index
Field
Column
Record
Row
Procedure
Stored Procedure
Identity Columns With identity column support, DB2 version 7 can automatically generate unique values for new rows in a table, including primary keys, for DB2 data types INT, BIGINT, SMALLINT, and DECIMAL. In order to maintain a unique sequence of key values for a given table, DB2 generates identity column values upon Insert. For example, inserting a record with a NULL key (defined as an identity column) will yield a new row with the next unique and sequential key. The Lotus Connector for DB2 supports the use of DB2’s identity columns with the following limitation: When an activity’s key field is mapped to a DB2 Identity column, and the Activity or Create event uses a NULL value for its key field, the Activity or event will complete successfully. However, the key field value generated by DB2 is not returned to the source document or Advanced RealTime Virtual Fields key field. To obtain the newly generated key field values for subsequent operations or for Open, Update, and Delete events, the key documents must be replicated from the DB2 table or view or initialized again in LEI or DECS. A stored procedure can also be used to return the new identity column value as an output parameter. Note DB2/400 support of identity columns is being introduced with V5R2.
66 Lotus Connectors and Connectivity Guide
Supported Characteristics This section describes LotusScript functionality available for the Lotus Connector for DB2. For a definition of the terms used in this section, see “Supported Connector Characteristics — List of Terms” in Chapter 3 of this manual. If you are accessing the Connector using LotusScript, see the Lotus Connector LotusScript Extensions Guide for a detailed description of the LotusScript properties and methods supported by the Lotus Connector for DB2. Note The Lotus Connector for DB2 provides the standard set of Lotus Connector methods, or function calls, to control interaction with a DB2 connection. All methods are supported. However, certain methods only support a subset of functions. Unsupported functions will return the following error message: “Requested functionality is not available.” •
Connection properties — Database, UserID, and Password
•
Standard functionality — Full
•
Writeback support — Full except when the result set is ordered. In this case, writeback functionality is not available and is simulated with keyed operations. Make sure that the proper key settings and values are provided even when performing writeback update and remove operations.
•
Writeback index — Index strongly advised, but not required. Use the command “create index on (, , ..., )”. (Simulated by keyed operations when cursors are not supported.)
•
Statement syntax — Full DB2 SQL Syntax, including UDFs (User Defined Functions)
•
Condition syntax — Valid when placed in the following DB2 statement: SELECT ... WHERE ORDER BY ...
All connections have a set of properties with values that can be assigned and retrieved. See the Lotus Connector LotusScript Extensions Guide for a list Chapter 5: Lotus Connector for DB2 67
of supported properties for this Connector. Also see sections “Common Connector Properties” and “LCConnection Properties” in the LCConnection Class chapter of that same manual.
DB2 Connection Document for LEI The Connection Document for DB2 defines a connection to a DB2 database. Connection Documents enable you to define your system connections. They contain access information for specific databases and users. When you create an Activity, you make connection choices from your set of defined connections. To create a new DB2 Connection Document in LEI: 1. Open the LEI Administrator. 2. Click the Add Connection button in the Action bar. 3. Select DB2. To open an existing DB2 Connection Document, select it from the Connection view on the LEI Administrator.
Common Features Each LEI Connection Document contains the following common features. User Assistant Help You can enable the User Assistant in order to open a Connection Document with explanatory text at the top of the document. To turn the User Assistant on or off, use the option in the Help portion of the LEI Administrator’s Navigator panel.
68 Lotus Connectors and Connectivity Guide
Pop-up Help Dark blue text in the section headings in a Connection Document indicates that pop-up help is available. To display pop-up help, place the cursor on the heading and press and hold the mouse button. Name This field provides a name that identifies the connection. Each connection requires a unique name. The maximum number of characters is 255. The comma character is not allowed. Password Encryption This option enables the author of a Connection Document to encrypt passwords using Notes encryption keys. See the “Introduction to Lotus Connectors” chapter for details. Options Tabs Connection Document options are classified and displayed by logical tab naming and grouping. The Table Creation Options and Logging Options are common to all Connection Documents. Comment The Comment field provides space for you to annotate the Connection Document with meaningful descriptive text.
Fields in the LEI Connection Document See the following tables for descriptions of the Connection Document fields. Connectivity The Connectivity options are described below.
Chapter 5: Lotus Connector for DB2 69
Field
Description
Name
Specifies a unique name that identifies this connection. The maximum number of characters allowed is 255.
Database
Database property Specifies the name of the DB2 database.
User Name
Username property Specifies the user name required to log in to the DB2 database. This matches the DB2 Username property.
Password
Password property Specifies the password associated with the user name. This matches the DB2 Password property and displays as hidden text. Password encryption is described in the “Introduction to Lotus Connectors” chapter.
Data Journalling
NoJournal property Specifies whether or not journalling is enabled. Select this option to enable support for SQL queries against non-SQL data external to DB2. When the target is a non-journalled data source, SQL queries are not supported unless this option is selected. If your database does not have journalling enabled, set this to off. If your database has journalling enabled, set this to on. This option sets the access mode to read-only (transaction isolation level of uncommitted read), which enables SQL queries. The default access level is read-write (transaction isolation level committed read). The requirement for this option is most common when connecting to DB2/400 tables. It appears as a
in not valid for operation” error message. For non-DB2/400 users, this option disables all data insert and modification operations through this connection.
Connection Options The Connection Options section of the DB2 Connection Document provides options for adjusting the performance and actions of the connection.
70 Lotus Connectors and Connectivity Guide
Transaction Options When you select the Transaction Options tab, the following options appear. The Transaction Options apply to operations that create, modify, or delete data. These settings have no effect on Advanced RealTime Activities.
Field
Description
Rollback Rollback upon Error
RollbackOnError property Specifies what to do if an error happens during data transfer, specifically how Rollback actions should occur. When Rollback is enabled, and an Activity terminates in an error state, all changes in the current DB2 Connection’s transaction are rolled back at disconnect time.
Commit Options
CommitFrequency property Specifies how commit actions should occur. The choices are as follows: Commit At Disconnect: Enable this option to commit changes to the database as the database is being disconnected at the end of the operation. This is the default Commit option. Commit Every N Operations: Commits changes periodically after a specified number of changes are made. This number is specified as the Commit Frequency below. Commit After Every Option: When enabled, this option causes immediate commits for each change to the database. Note that this option reduces performance.
Commit Frequency
This is used with the option Commit Every N Operations to specify how many actions must occur before the changes are committed.
Chapter 5: Lotus Connector for DB2 71
Table Creation Options When you select the Table Creation Options tab, the following options appear.
Field
Description
Size Cutoff for Create NOT LOGGED COMPACT
CreateMaxLogged property Enables you to specify the data size past which columns are created without logging (DB2 syntax is “NOT LOGGED COMPACT”). When LEI or DECS creates a DB2 table, all columns are created with logging by default. Columns larger than 1GB cannot be logged by DB2. Specifying a value in this field allows for successful table creation with columns of this size. Text or Binary columns of unlimited length are always created using this option.
Logging Options When you select the Logging Options tab, the following options appear. The Logging Options section provides a feature for including SQL statements in the Activity log.
Field
Description
Output SQL Statements to Log
TraceSQL property Specifies that all SQL statements submitted to the external database and generated during the Activity be included in the Activity log. Note Selecting this option slows down performance. Use it only for troubleshooting.
72 Lotus Connectors and Connectivity Guide
Selection Type Regardless of which Options tab you select, the following option is available.
Field
Description
Selection Type
Enables you to specify the metadata type for a connection. Select Table to connect to a DB2 table. Select View to connect to a DB2 view. Select Procedure to connect to a DB2 stored procedure. Spaces in a table or column name are not permitted.
Table Selection These settings display a current list of tables and allow you to specify which tables will be accessed. You can also specify a table name not shown in the list by selecting the Manual button.
Field
Description
Owner
Lists the available owner names for the above table, view, or procedure selection type in the specified Database. On iSeries, this lists libraries by library name. A selection list displays all DB2 owners. Choose the owner of the table, view, or procedure being connected to from the list (Optional).
Name
Lists the available table, view, or procedure names defined for the specified Owner. A selection list displays all DB2 tables, views, or procedures for the selected Owner. Choose the table, view, or procedure to connect to. If an owner is not specified, all names are listed for the specified Selection Type. Spaces in a table or column name are not permitted.
Column(s)
Lists the columns or parameters (stored procedure) defined for the specified Name. Spaces in a table or column name are not permitted. Chapter 5: Lotus Connector for DB2 73
DB2 Connection Document for DECS The Connection Document for DB2 defines a connection to a DB2 database. Connection Documents enable you to define your system connections. They contain access information for specific databases and users. When you create an Activity, you make connection choices from your set of defined connections. To create a DB2 Connection Document in DECS: 1. Click Connections in the Navigator. 2. Click the Add Connection button in the Action bar. 3. Choose DB2 from the dialog box. 4. Click OK. To open an existing DB2 Connection Document, select the Connection Document you want from those displayed in the Connections View. Note You can optionally use the Connection Document Assistant to assist you in completing the Connection Document. If you use the Assistant, the Connection Document opens with explanatory text at the top of the document. To toggle the Assistant on or off, click the “Enable/Disable Assistant” text at the bottom of the DECS Administrator Navigator panel.
Common Features Each DECS Connection Document contains the following common features. User Assistant Help You can optionally use the User Assistant to assist you in creating the Connection Document. If you enable the User Assistant, the Connection Document opens with explanatory text at the top of the document. To toggle the Assistant on or off, click the “Enable/Disable Assistant” text at the bottom of the DECS Administrator Navigator panel. Pop-up Help Dark blue text in the section headings in a Connection Document indicates that pop-up help is available. To display pop-up help, place the cursor on the heading and press and hold the mouse button. Password Encryption This option enables the author of a Connection Document to encrypt passwords using Notes encryption keys. See the “Introduction to Lotus Connectors” chapter for details.
74 Lotus Connectors and Connectivity Guide
Comment The Comment field provides space for you to annotate the Connection Document with meaningful descriptive text.
Fields in the DECS Connection Document The DECS Connection Document provides values for Connectivity and Table Selections options. The fields in the DECS Connection Document are described below. Field
Description
Database
Database property Specifies the name of the DB2 database.
Userid
Username property Specifies the user name required to log in to the DB2 database. This matches the DB2 Username property.
Password
Password property Specifies the password associated with the user name. This matches the DB2 Password property and displays as hidden text.
NoJournal property Data Journalling Journalled/Non-Journ Enables support for SQL queries against non-SQL data external to DB2. When the target is a non-journalled data alled Data source SQL queries are not supported unless you enable this option. If your database does not have journalling enabled, set this to off. If your database has journalling enabled, set this to on. This option sets the access mode to read-only (transaction isolation level of uncommitted read), which enables SQL queries. The default access level is read-write (transaction isolation level committed read). The requirement for this option is most common when connecting to DB2/400 tables. For non-DB2/400 users, this option disables all data insert and modification operations through this connection. Selection Type
Specifies the metadata type for a connection. Select Table to connect to a DB2 table. Select View to connect to a DB2 view. Select Procedure to connect to a DB2 stored procedure. Spaces in a table or column name are not permitted. continued
Chapter 5: Lotus Connector for DB2 75
Field
Description
Owner
Lists the available owner names for the above table, view, or procedure selection type in the specified Database. On iSeries, this lists libraries by library name. A selection list displays all DB2 owners. Choose the owner of the table, view, or procedure being connected to from the list (Optional).
Name
Lists the available table, view, or procedure names defined for the specified Owner. A selection list displays all DB2 tables, views, or procedures for the selected Owner. Choose the table, view, or procedure to connect to. If an owner is not specified, all names are listed for the specified Selection Type. Spaces in a table or column name are not permitted.
Column(s)
Lists the columns or parameters (stored procedure) defined for the specified Name. Spaces in a table or column name are not permitted.
Comment
Enables you to add comments to the Connection Document that help describe its intent or usage. This is a rich text field. You can paste doclinks, as well as normal text characters here.
Stored Procedures A DB2 stored procedure may be used wherever procedures are allowed, such as the destination of a Direct Transfer, within an LSX script, or in an Advanced RealTime Activity such as Virtual Agents or Virtual Documents. The stored procedure being called must have its parameters set up correctly for the call. Input and output values are provided to DB2 procedures as named parameters. This requires that the parameters in DB2 use the same names as the fields being provided as the parameters unless explicitly mapped in the activity. The parameters being provided should include key values when being used in the context of a keyed operation (selection, update, or delete contexts), and data values when relevant (insert or update contexts). The DB2 parameter data types should be selected as the closest match to the data type in the LC API. See the “DB2 Data Types” section, later in this chapter, for more information. Note When using a stored procedure with the Delete event in LEI or DECS, the stored procedure need only declare the fields specified under “Key(s):” in the Activity. Since a Delete event will not return any output 76 Lotus Connectors and Connectivity Guide
parameters in any case, the Activity will only pass the key fields to the stored procedure. Furthermore, an Activity connecting to a Stored Procedure cannot support only the Delete event. Any result set output from a DB2 stored procedure must be returned through a DB2 cursor left open in the stored procedure. The result set produced by the stored procedure will be retrieved with this cursor. The Lotus Connector for DB2 supports the return of output parameters from stored procedures. The following scenarios describe what is returned from a stored procedure call: •
If the stored procedure returns a result set only, the Connector will return that result set fieldlist.
•
If the stored procedure returns multiple result sets, the Connector will return the first result set fieldlist only.
•
If the stored procedure returns output parameters only, the Connector will return a fieldlist of those output parameters.
•
If the stored procedure returns output parameters and a result set, the Connector will return a fieldlist of the output parameters only.
•
If the stored procedure returns output parameters and multiple result sets, the Connector will return a fieldlist of the output parameters only.
The Lotus Connector for DB2 will not return multiple fieldlists in any scenario and a fieldlist of output parameters will always have return precedence.
Considerations when Using Stored Procedures DB2/400 does not support stored procedure result sets from remote data sources. When using DB2 stored procedures and the Call method in LotusScript, the “Fieldnames” property must be set. The “Fieldnames” property must contain all of the parameters declared OUT or INOUT in the DB2 stored procedure. Stored procedure return values are not supported with the Lotus Connector for DB2. Stored procedures in DB2 can be written in Java, C, and C++. DB2 Universal Database version 6.1 and 7.1 provide a Stored Procedure Builder with which to create procedures more easily. The version 7.1 Stored Procedure Builder also allows stored procedures in SQL.
Chapter 5: Lotus Connector for DB2 77
Example: DB2 Stored Procedure in C The following is an example of a DB2 stored procedure written in C for the DB2 CLI preprocessor. This is the format that would be required for the Open event of an Advanced RealTime Virtual Fields Activity assuming that the key field is called NUMBER1 and the data fields are called NUMBER2, TEXT1, and TEXT2. In this context, the key field is the input parameter, and the result set is expected to include the data fields followed by the key field. Note that the input parameter data type is checked and handled for both integer and float types. SQL_API_RC SQL_API_FN sf_proc (void *reserved1, void *reserved2, struct sqlda *inout_sqlda, struct sqlca *ca) { /* Declare a local SQLCA */ EXEC SQL INCLUDE SQLCA;
/* Declare Host Variables */ EXEC SQL BEGIN DECLARE SECTION; char *select_stmt = “SELECT NUMBER2, TEXT1, TEXT2, NUMBER1 FROM TALBENAME WHERE NUMBER1 = ?”; long int number1; EXEC SQL END DECLARE SECTION;
if (inout_sqlda) { if ((inout_sqlda->sqlvar[0].sqltype == SQL_TYP_INTEGER) || (inout_sqlda->sqlvar[0].sqltype == SQL_TYP_NINTEGER)) number1 = *((long int *) (inout_sqlda->sqlvar[0].sqldata)); else if ((inout_sqlda->sqlvar[0].sqltype == SQL_TYP_FLOAT) || (inout_sqlda->sqlvar[0].sqltype == SQL_TYP_NFLOAT))
78 Lotus Connectors and Connectivity Guide
number1 = (long int) *((double *) (inout_sqlda->sqlvar[0].sqldata)); else number1 = 0; EXEC SQL WHENEVER SQLERROR GOTO err; EXEC SQL PREPARE stmt FROM :select_stmt; EXEC SQL DECLARE curs CURSOR FOR stmt; EXEC SQL OPEN curs using :number1; }
Example: DB2 Stored Procedure in SQL The following is an example of a simple SQL stored procedure. CREATE PROCEDURE DB2ADMIN.NEW_SALES_ORDER ( IN CUSTID int, IN ITEMID int, IN QTY int, OUT SONUM bigint) LANGUAGE SQL P1: BEGIN DECLARE CUSTVAR int; DECLARE ITEMVAR int; DECLARE QTYVAR int; DECLARE ITEMCOSTVAR dec(7,2);
Chapter 5: Lotus Connector for DB2 79
DECLARE AMTVAR dec(9,2); DECLARE STAMP timestamp; DECLARE cursor1 CURSOR FOR SELECT ITEMCOST FROM DB2ADMIN.ITEMS WHERE ITEMID = ITEMVAR; DECLARE cursor2 CURSOR FOR SELECT SONUM FROM DB2ADMIN.SALES_ORDERS WHERE DTEORD = STAMP; SET CUSTVAR = CUSTID; SET ITEMVAR = ITEMID; SET QTYVAR = QTY; SET STAMP = CURRENT TIMESTAMP; OPEN cursor1; FETCH FROM cursor1 INTO ITEMCOSTVAR; CLOSE cursor1; SET AMTVAR = QTY * ITEMCOSTVAR; INSERT INTO DB2ADMIN.SALES_ORDERS (CUSTID, ITEMID, QTY, AMT, DTEORD) VALUES (CUSTVAR, ITEMVAR, QTYVAR, AMTVAR, STAMP); OPEN cursor2; FETCH FROM cursor2 INTO SONUM; CLOSE cursor2;
END P1
Example: Sample LC LSX Agent to Call a DB2 Stored Procedure This example uses the SQL stored procedure shown in the previous example. Sample LS: [Options] Option Public Option Explicit Uselsx “*lsxlc” 80 Lotus Connectors and Connectivity Guide
[Initialize] Sub Initialize Dim sess As New LCSession Dim conn As New LCConnection (“db2”)
’set the stored procedure owner and stored procedure name... conn.Owner = “DB2ADMIN” conn.Procedure = “NEW_SALES_ORDER” ’set Fieldnames property with any output parameters declared in the stored procedure... conn.Fieldnames = “SONUM”
’declare any fields and fieldlists for input/output data... Dim input_fieldlist As New LCFieldList Dim output_parms As New LCFieldlist Dim in_field As New LCField (1, LCTYPE_INT) Dim sonum As New LCField (1, LCTYPE_NUMERIC) Dim out As Double ’set the input parameters of the stored procedure... Set in_field = input_fieldlist.Append (“CUSTID”, LCTYPE_INT) in_field.Value = 2146
Chapter 5: Lotus Connector for DB2 81
Set in_field = input_fieldlist.Append (“ITEMID”, LCTYPE_INT) in_field.Value = 196
Set in_field = input_fieldlist.Append (“QTY”, LCTYPE_INT) in_field.Value = 500
’with the input parameters set, call the stored procedure... ’the declared output_parms fieldlist will hold the output parameters of the stored procedure... out = conn.Call (input_fieldlist, 1, output_parms) ’fetch parameter(s) into the output_parms fieldlist... out = conn.Fetch (output_parms)
’retrieve the parameter(s) from the output_parms fieldlist... Set sonum = output_parms.GetField (1)
’use the output parameter value(s) in your script... Print “Your new sales order number is ” & sonum.Value(0)
conn.Disconnect
End Sub
DB2 Data Types The following tables show the correspondences of DB2 to LotusScript data types.
82 Lotus Connectors and Connectivity Guide
In DB2, the data type pairs DOUBLE and FLOAT and NUMERIC and DECIMAL are synonymous, and only the first of each type synonym (DOUBLE and NUMERIC) is indicated in these tables. •
(p) — Indicates that if Allow Precision Loss is not enabled, then an error will be generated on the type match. Allowing precision loss is the default.
•
(o) — Indicates that overflow checking will be performed when data is being transferred. If an overflow occurs and Truncate Data When Necessary is enabled, then the data is truncated; if not, an error is generated.
Note For more information on the organization of these tables, see the section entitled “Note on Connection Data Type Conversion Tables” in Chapter 3. These conversion tables may have changed since this printing. For the latest information about IBM’s DB2 data types, see the IBM Web site http://www-4.ibm.com/software/data/db2.
Data Type Considerations The following considerations pertain to use of DB2 data types. •
When you use the DB2 BIGINT data type as a keyfield on a Connection Document, a precision loss error occurs when you initialize keys. The error also occurs if you select “Leave all/Leave selected RealTime fields in Documents” and one of the field values is a BIGINT. To avoid this error, use a different data type in these instances.
•
The DB2 data type DATALINK and the Data Links Manager are not currently supported.
•
The DB2 column used as the timestamp field in timestamp replication or timestamp polling must be of type TIMESTAMP, not DATE.
•
DB2 allows the storage of the time value 12:00:00 AM as both 00:00:00 and 24:00:00. When transferring 24:00:00 from DB2, DECS and LEI consider this time to be invalid. If 12:00:00 AM times are inserted through DB2, and not through DECS or LEI, use 00:00:00 for 12:00:00 AM, not 24:00:00.
Chapter 5: Lotus Connector for DB2 83
Execute This table describes how the Execute method converts data types between LotusScript Connector Extensions and DB2. DB2 Data Type
