LEISectionIntroduction to Domido Enterprise Connection ServicesChapter 1
Introduction
CN=Bob Miller/OU=CAM/O=Lotus
LEISectionChapter 1
IntroductionSupported Data Sources
CN=Bob Miller/OU=CAM/O=Lotus
LEISectionContact and Support InformationChapter 1
Introduction
CN=Bob Miller/OU=CAM/O=Lotus
LEISectionChapter 2
Installing DECS
CN=Bob Miller/OU=CAM/O=Lotus
LEISectionChapter 2
Installing DECSDECS Installation
CN=Bob Miller/OU=CAM/O=Lotus
LEISectionChapter 3
DECS Administrator
CN=Bob Miller/OU=CAM/O=Lotus
LEISectionThe DECS AdministratorChapter 3
DECS Administrator
CN=Bob Miller/OU=CAM/O=Lotus
O=Lotus Notes
O=Lotus Notes
PURSAFO
|.:#U
O=Lotus Notes
CN=Lotus Notes Template Development/O=Lotus Notes
PURSAFO
\g@^/
I3$;S
$ACLDigest
Times New Roman
About Lotus Domino Connector Online Manual
$$U$$
$IU$I
@ @@ @` @
@@ @@@@@`@@
`@ `@@`@``@
copyright
Lotus Domino Enterprise Connection Services User Guide
Lotus Development Corporation, an IBM subsidiary
Copyright
Under the copyright laws, neither the documentation nor the software may be copied, photocopied, reproduced, translated, or reduced to any ele`tronic medium or machine-readable form, in whole or part, without the prior written consent of Lotus Development Corporation.
Copyright 2000 Lotus Development Corporation
55 Cambridge Parkway
Cambridge, MA 02142
All rights reserved. Printed in the United States.
Trademarks
Lotus and Lotus Notes are registered trademarks, Domino Connectors and Domino Enterprise Connection Services, Lotus Enterprise Integrator, LotusScript, and Lotus NotesView are trademarks of Lotus Development Corporation.
AIX, AS/400, DB2, DPROPR, OS/400, IBM, MVS, and OS/2 are registered trademarks, and DB2/2 and RS/6000 are trademarks of International Business Machines Corporation.
Oracle and SQL*Net are registered tradem`rks, and Oracle7 and PL/SQL are trademarks of Oracle Corporation.
SYBASE and Transact-SQL are registered trademarks and SQL Server and Open Client are trademarks of Sybase, Inc.
ZMerge is a trademark of Granite Software, Inc.
EDA/SQL and FOCUS are registered trademarks of Information Builders, Inc.
Informix is a registered trademark of Informix Software, Inc.
Novell and NetWare are registered trademarks of Novell, Inc.
INTERSOLV is a registered trademark, and DataDirect is a trademark of INTERSOLV, Inc.
Visigenic is a trademark of Visigenic Software, Inc.
Microsoft and Windows are registered trademarks, and Microsoft Windows NT and ODBC are trademarks of Microsoft Corporation.
Intel is a registered trademark of Intel Corporation.
UNIX ip a registered trademark of UNIX Systems Laboratories, Inc.
Hewlett-Packard and HP are registered trademarks, and HP-UX is a trademark of Hewlett-Packard Company.
Sun, Solaris, and SunOS are registered trademarks or trademarks of Sun Microsystems.
All SPARC trademarks are trademarks or registered trademarks of SPARC International, Inc.
Alpha, DEC, and Digital are registered trademarks of Digital Equ`pment Corporation.
Apple and Macintosh are registered trademarks and System 7 is a trademark of Apple Computer Inc.
All other trademarks are property of their respective owners.
Disclaimer
The information in this database is subject to change and does not represent a commitment on the part of Lotus Development Corpopation.
O=Lotus Notes
O=Lotus Notes
PURSAFO
|.:#U
O=Lotus Notes
CN=Lotus Notes Template Development/O=Lotus Notes
PURSAFO
$Info
$Body
Using Lotus Domino Connector Online Manual
@ @@ @` @
@@ @@@@@`@@
`@ `@@`@``@
copyright
Lotus Domino Connector
Online Manual
This database is the online document`tion for this Lotus Domino Connector.
Full-Text Index
In addition to using the views built into this database, we strongly encourage you also to create and use a full-text index for the database. Doing so will require extra disk space, but will allow you to very quickly find the information you need.
Changing the Information in the Database
To add a comment to the databape...
1) In a view, highlight the item you want to add a comment to.
This chapter provides information about the organization of this manual. This chapter also includes an overview of the Domino Enterprise Connection Services (DECS).
HELVETICA
This manual includes the sections described below.
Section
Description
Chapter 1
Introduction
This chapter provides information about the organization of this manual, and includes an introduction to the Domino Enterprise Connection Sepvices and an overview of its functionality.
Chapter 2
Installing DECS
This chapter provides information about installing DECS on Domino 5.0.3 and its limitations.
Chapter 3
DECS Administrator
This chapter provides information about the DECS navigator, views, and menu commands.
Chapter 4
Defining Data Sources
This chapter describes how to define external data sources.
Chapter 5
Creating RealTime Activities
This chapter describes how to create RealTime Activities using the RealTime Activities wizard.
Chapter 5
Building the Notes Application
This chapter provides information for creating a Notes application for use with a RealTime Activity.
Chapter 7
Examples Using RealTime Options
This chapter provides examples using RealTime options to refine the results of RealTime Activities.
Chapter 8
RealTime Dynamic Queries
This chapter provides inform`tion on how to use RealTime Activities for on-demand, dynamic queries of external data.
Appendix A
Configuration and Troubleshooting
This appendix provides information about INI variables, error messages and k`own problems that you may encounter under certain conditions while using DECS.
HELVETICA
TIMES
LotusFrute
Symbol
&Arial
Times New Roman
5Courier New
The Domino Enterprise Connecpion Server (DECS) enables you to create RealTime Activities. A RealTime Activity provides synchronous access from a Domino application to a supported external data source, such as DB2.
The RealTime Activity intercepts Notes database events. For example, when Notes or web client users open, create, update, or save Notes documents, these events are intercepted and acted upon, obtaining "real-time" access from the Notes form to external data sources supported by the Domino Enterprise Connecti`n Server. Real-time means that you get the data immediately, relative to the network bandwidth and other processes running that may affect system performance.
Once a system administrator has created the RealTime Activity, identifying a particular form within a Domino application to have certain fields populated by an external database source, Notes users can open, create, update or delete external, back-end data directly and transparently through their familiar Notes Client. By extension, w`b clients may open the same Notes forms by accessing a Domino Release 4.6 or greater server, and obtain RealTime access to supported external source data.
The Domino Enterprise Connection Server (DECS), running on the Domino Server that is hosting the Notes application, intercepts and handles the Notes database events.
For example, if the external database to be queried or updated from the Notes form is DB2, Notes end-users may work with DB2 data as if it were in Notes. DB2 co`nectivity software is not required on the client system. Network access to the external data source is handled by the Domino server machine, which contains the connectivity software for the external data source, such as DB2. No programming is required to accomplish this functionality. In addition, it is an option to store retrieved data to the Notes form, or to simply view the retrieved data, potentially reducing storage requirements on the Notes side.
When creating a RealTime Activity, s`veral items are required to provide RealTime data access from a single Notes form. Each RealTime Activity monitors a specific Domino application form and requires a Notes Form to define the metadata. Metadata is the list of fields in the Notes form and a list of fields in the external data source that are mapped during data query or update from the Notes application. Within an application, one or multiple external sources may be accessed from the Notes form. A single external data source definition indicapes the data source to connect to and the metadata to use. Key and field mappings are also required. Several RealTime Activities can monitor different databases, a single database or even a single form. This means a single document can be populated real-time, consisting of data from multiple back-end databases using a RealTime Activity for each of the various back-end data sources.
Symbol
&Arial
RealTime Activities support a range of external data sources, called Connectors. Additional data sources are continuously being added. As Lotus and other third parties create data source Connectors for Domino, they will all be manageable using the Domino Enterprise Connection Services product. Currently supported data sources include:
NSFbuletcleanup
Bob Miller-
EDA/SQL
Open Database Connectivity (ODBC)
Oracle
Sybase
Each of the data sources has specific software requirements for network connectivity that must be met by the Domino Server. Refer to the
Domino Connectors Setup Guide
for information about the connectivity requirements for each of the supported dat` sources.
Note
Other Enterprise Resource Planning connectors and Transaction System Connectors are also available. For more information, see the Enterprise Integrator web site: www.lotus.com/home.nsf/welcome/ei.
HELVETICA
TIMES
LotusFrute
Symbol
&Arial
Timep New Roman
5Courier New
Lotus provides extensive support for its products. The following sections describe the different ways in which you can get help on using RealTime Activities, as well as information on how to contact us with suggestions and reco`mendations.
Enterprise Integration Sales Support
You can reach the Lotus Enterprise Integration Business Unit Sales staff at:
1-800-944-7358
Telephone Support
You can reach the Technical Support group at:
1-800-346-6388
International support numbers can be found in a separate brochure in the Domino Server documentation.
Contacting 3rd Party Support
In some cases, you may need to conta`t customer support for another program or application in your environment. These could include the vendors of any databases you may be using, such as Sybase or Oracle. Refer to the documentation for the specific database or application for more information.
HELVETICA
TIMES
LotusFrute
Symbol
&Arial
Timep New Roman
5Courier New
This chapter provides information about installing
DECS on Domino 5.0.3
and describes current functional limitations.
&Arial
Symbol
HELVETICA
NSFbuletcleanup
Domino Enterprise Connection Services (DECS) is a forms-based technology in Domino that provides the capability to integrate live data from enterprise systems natively into Domino applications. Beginning with Domino 4.6.3, DECS is installed as part of all Domino new and upgrade installations.
In DECS 5.0.3 installation is a simple process, simply elect to install DECS when you install Domino. But please see below for ACL suggestions and Name and Address Book setting.
Note
DECS requires that the server ID have access to the database. Users of the administrator must have delete access since, in addition to the documents they create, there are also transient hidden documents created and destroyed from time to time. "Default" must have Manager access to the DECS Administration database with permission to delete documents. Make supe the ACL is set with appropriate security restrictions after you complete the installation.
Note
In the server document for the DECS server's Name and Address Book, the "Only allow server access to users listed in the directory" option is set to "Yes" by default. However, to be able to browse the server, set the "Only allow server access to users listed in the directory" option to "No." The alternative is to make sure that all users who will be creating DECS activities have `ntries in the Name and Address book and that the server is listed as part of a group. For more information, see the pop-up help in the Name and Address Server document.
As part of the install process in Domino and Notes release 5.0.3, the following DECS documentation databases are installed:
For Domino Server installations, three document databases are installed:
LotusScript Extension for Domino Connectors Reference Guide
For Notes Client installations, two document databases are installed:
Domino Connectors Setup Guide
LotusScript Extension for Domino Connectors Reference Guide
Current functional limitations
The following should be considered before deploying Domino Enterprise Connection Services (DECS):
DECS does not work in true real-time with Domino clustering; writing changes to the back-end database may be delayed if not all databases within the cluster are DECS enabled.
HELVETICA
TIMES
LotusFrute
Symbol
&Arial
Times New Roman
5Courier New
This chapter provides information about the DECS Administrator. Included is information about the navigator, views and menu commands.
HELVETICA
TIMES
LotusFrute
Symbol
&Arial
Times New Roman
5Courier New
The following commands are available from the
Actions - Tools
menu:
Command
Description
Reset Connection
Restarts the currently selected RealTime Activity.
Initialize Keys
Populates the currently selected RealTime Activity key fields with data from the external data source for that connection. This command should be used once after creating a RealTime Activity. Running it again creates duplicates of existing documents.
If you have specified
Leave Selected RealTime Fields in Document
Leave All RealTime Fields in Document
, the associated fields are transferred to the Notes application.
NOTE
When using Initialize Keys with a RealTime Activity that has a Filter Formula, you are asked if you want to use a conditional clause to restrict the number of external records imported into Notes. If you choose Yes, you are prompted to enter the external conditional clause. The conditional clause must be in the external system
,s syntax for a keyed selection clause. For SQL based systems, the conditional clause would be that part of a WHERE clause following the WHERE. For example, if the complete st`tement were: SELECT * from Table WHERE Number > 1, you would only enter Number > 1 as the key initialization condition.
HELVETICA
TIMES
LotusFrute
Symbol
&Arial
Times New Roman
5Courier New
Shown below is the DECS administrator. The navigator, views and menu commands in the administrator are described in the sections that follow.
UU33UUP
wwwwww|
S3333335
wwwwwwww
U33333333U
wwwwwwwwww
3333333333P
wwwwwwwwww|
S33333333335
wwwwwwwwwwww
333333333333P
wwwwwwwwwwww|
S3333333333335
wwwwwwwwwwww|
S3333333333335
wwwwwwwwwwwwww
33333333333333P
wwwwwwwwwwwwww|
S333333333333335
wwwwwwwwwwwwww|
S3333333333
wwwwwwwwwwwwww|
S3333333333
wwwww
33333
wwwww
33333
wwwww
33?333333335
wwwww
?333333335
wwwwwwwwww|
33333333335
wwwwwwwwwwwwww|
S333333333333335
wwwwwwwwwwwwww|
S333333333333335
wwwwwwwwwwwwww
33333333333333P
wwwwwwwwwwww|
S3333333333335
wwwwwwwwwwww|
S3333333333335
wwwwwwwwwwww
333333333333P
wwwwwwwwww|
S33333333335
wwwwwwwwww
3333333333P
wwwwwwww
U33333333U
wwwwww|
S3333335
UU33UUP
wwwwwwp
UUUUU
||wwp
wwwww
wwww{
wwwww
wwwww
||www
wwwww
UUUUU
wwwww
wwwww
wwwww
UUUUU
wwwww
wwwww
wwwww
UUUUU
wwwwwwwwwwwwwwwww{
wwwwwwwwwwwwwwwww{
wwwwwwwwwwwwwwwww{
wwwwwwwwwwwwwwwww{
wwwwwwwwwwwwwwwww{
wwwwwwwwwwwwwwwww{
wwwwwwwwwwwwwwwww{
wwwwwwwwwwwwwwwww{
wwwww
wwwwwpwwwww{
wwwwwp
wwww{
wwwww
wwww{
wwwwp
wwww{
UUUUU
wwwww
wwww{
wwwww
wwwww
wwwww
UUUUU
wwwww{
wwwwww{
wwwwww{
wwwwwp
wwwwwwww{
wwwwwwwwwwwwwwwww{
wwwwwwwwwwwwwwwww{
wwwwwwwwwwwwwwwww{
wwwwwwwwwwwwwwwww{
wwwwwwwwwwwwwwwww{
UUUUUUU[
"""""
3333333;
ffffff
ffjfff
"""""
3U53:
3[SS3
3[SS3
3[SS;
UUUUUUU[
3333333;
@ @@ @` @
@@ @@@@@`@@
`@ `@@`@``@
This s
RealTime Activit
th a Sybase exte
ample there are
able
en using these s
used must be Fi
pped fields must
lAddress, Compan
ctly as shown be
LEISectionDECS NavigatorChapter 3
DECS Administrator
CN=Bob Miller/OU=CAM/O=Lotus
LEISectionChapter 3
DECS AdministratorConnections View
CN=Bob Miller/OU=CAM/O=Lotus
LEISectionRealTime Activities ViewChapter 3
DECS Administrator
CN=Bob Miller/OU>CAM/O=Lotus
LEISectionMenu CommandsChapter 3
DECS Administrator
CN=Bob Miller/OU=CAM/O=Lotus
LEISectionChapter 4
Defining Lotus Connections
CN=Bob Miller/OU=CAM/O=Lotus
HELVETICA
TIMES
LotusFrute
Symbol
&Arial
Times New Roman
5Courier New
This chapter provides information and instructions for creating Lotus Connection documents.
w"KGq
LEISectionChapter 4
Defining Lotus ConnectionsDefining Lotus Connections Using the Wizard
CN=Bob Miller/OU=CAM/O=Lotus
LEISectionChapter 5
Creating RealTime Activities
CN=Bob Miller/OU=CAM/O=Lotus
HELVETICA
TIMES
LotusFrute
Symbol
&Arial
Times New Roman
5Courier New
This chapter provides information and instructions for creating RealTime Activities.
LEISectionChapter 5
Creating RealTime ActivitiesOvnrview
CN=Bob Miller/OU=CAM/O=Lotus
LEISectionChapter 5
Creating RealTime ActivitiesHow to Create a RealTime Activity Using the Wizard
CN=Bob Miller/OU=CAM/O=Lotus
LEISectionChapter 5
Creating RealTime ActivitiesHow to Create a RealTime Activity without the Wizard
This chapter provides information about building a Notes application for use with a RealTime Activity.
LEISectionBuilding the Notes Application for a RealTime ActivityChapter 6
Builning the Notes Application
CN=Bob Miller/OU=CAM/O=Lotus
HELVETICA
TIMES
LotusFrute
Symbol
&Arial
Times New Roman
5Courier New
The table below gives a description of the commands available in the DECS navigator.
Navigator Command
Description
@ @@ @` @
@@ @@@@@`@@
`@ `@@`@``@
Selects a view of available Connections or a view of RealTime Activities.
||||wp
||wwp
||wwp
||wwp
""""*
""""*
@ @@ @` @
@@ @@@@@`@@
`@ `@@`@``@
Creates a new Lotus Connection document for an external data source. This launches a wizard that prompts you through the process of defining a Connection to an external data source.
wwwwww
@ @@ @` @
@@ @@@@@`@@
`@ `@@`@``@
Creates a new RealTime Activity. When the User Assistant is active, this launches a wizard that prompts you through the process of defining a RealTime Activity between your Notes application and your external data source. When the User Assistant is turned off, this displays a blank RealTime Activity document that you can edit directly.
@ @@ @` @
@@ @@@@@`@@
`@ `@@`@``@
Begins execution of the currently selected RealTime Activity. This has no effect if the current selection is already executing. This is disabled when in Connection view.
@ @@ @` @
@@ @@@@@`@@
`@ `@@`@``@
Displays the status of the currently selected RealTime Activity. If the current selection is running, this will display the start time and other current status. If the current selection is not running, this will display the results of the most recent execution. This is disabled when in Connections view.
@ @@ @` @
@@ @@@@@`@@
`@ `@@`@``@
Ends execution of the currently selected RealTime Activity. This has no effect if the current selection is not running. This is disabled when in Connections view.
@ @@ @` @
@@ @@@@@`@@
`@ `@@`@``@
Toggles the User Assistant. When turned on, this provides additional help and enables the New Activity wizard. This is useful for first time and infrequent users. The New Activity wizard guides you through creating the RealTime Activity document and provides information to assist in the creation and editing of the document.
@ @@ @` @
@@ @@@@@`@@
`@ `@@`@``@
Displays this page of information.
@ @@ @` @
@@ @@@@@`@@
`@ `@@`@``@
Displays the online documentation.
@ @@ @` @
@@ @@@@@`@@
`@ `@@`@``@
Closes the DECS administrator.
HELVETICA
TIMES
LotusFrute
Symbol
&Arial
Times New Roman
5Courier New
Shown below is an example of the Connections view. Lotus Connection documents are named automatically by the DECS task using a convention that specifies the external system, the database, and the table name, for example, Sybase Venturi (using
+Venturi
,) - dbo.EMP_SAMP. When applicable, the user name required for login to the data source is shown in parentheses.
wwwwww
||||wp
||wwp
||wwp
||wwp
""""*
""""*
wwwwwwwwwwwwwwwwww
wwwwwwwwwwwwwwwwww
wwwwwwwwwwwwwwwwww
wwwwwwwwwwwwwwwwww
wwwwwwwwwwwwwwwwww
wwwwwwwwwwwwwwwwww
wwwwwwwwwwwwwwwwww
wwwwwwwwwwwwwwwwww
wwwwwpwwwwww
wwwww
wwwwww
wwwwp
wwwww
wwwwwp
wwwww
wwwwp
wwwwww
wwwwww
wwwwp
wwwwwww
wwwwww
wwwwwwww
wwwwwwwwwwwwwwwwww
wwwwwwwwwwwwwwwwww
wwwwwwwwwwwwwwwwww
wwwwwwwwwwwwwwwwww
wwwwwwwwwwwwwwwwww
UUUUUUU
"""""+
3333333
ffffffj
"""""+
3[SS3
3[SS3
UUUUUUUU
!!!!!
33333333
@ @@ @` @
@@ @@@@@`@@
`@ `@@`@``@
Installation
apter 3
DECS Adm
allation
allation
allation
allation
allation
allation
allation
allation
allation
allation
allation
allation
HELVETICA
TIMES
LotusFrute
Symbol
&Arial
Times New Roman
5Courier New
Shown below is an example of the RealTime Activities view.
wwww{wwwww
/wwwww{wwwww
wwwww
wwww{wwwww
/wwwww{wwwww
wwwww
wwww{wwwww
/wwwww{wwwww
wwwww
UU33UUP
wwwwww|
S3333335
wwwwwwww
U33333333U
wwww{wwwww
wwwwwwwwww
3333333333P
/wwwww{wwwww
wwwwwwwwww|
S33333333335
wwwww
wwwwwwwwwwww
333333333333P
wwwwwwwwwwww|
S3333333333335
wwwwwwwwwwww|
S3333333333335
wwwwwwwwwwwwww
33333333333333P
wwwwwwwwwwwwww|
S333333333333335
wwwwwwwwwwwwww|
S3333333333
wwwwwwwwwwwwww|
S3333333333
wwwww
33333
wwwww
33333
wwwww
33?333333335
wwwww
?333333335
wwwwwwwwww|
33333333335
wwwwwwwwwwwwww|
S333333333333335
wwwwwwwwwwwwww|
S333333333333335
wwwwwwwwwwwwww
33333333333333P
wwwwwwwwwwww|
S3333333333335
wwwwwwwwwwww|
S3333333333335
wwwwwwwwwwww
333333333333P
wwwwwwwwww|
S33333333335
wwwwwwwwww
3333333333P
wwwwwwww
U33333333U
wwwwww|
S3333335
UU33UUP
wwww{
wwwww{
UUUU_
wwww{wwwww
/wwwww{wwwww
wwwww
UUUU_
wwwwwwp
UUUU_
wwww{wwwww
/wwwww{wwwww
wwwww
UUUU_
||wwp
||www
UUUU_
wwww{wwwww
/wwwww{wwwww
wwwww
UUUU_
UUUU_
wwww{wwwww
/wwwww{wwwww
wwwww
UUUU_
UUUU_
wwww{wwwww
/wwwww{wwwww
wwwww
UUUU_
UUUU_
wwww{wwwww
/wwwww{wwwww
wwwww
UUUU_
wwwwwwwwwwwwwwwww{
wwwwwwwwwwwwwwwww{
wwwwwwwwwwwwwwwww{
wwwwwwwwwwwwwwwww{
wwwwwwwwwwwwwwwww{
wwwwwwwwwwwwwwwww{
wwwwwwwwwwwwwwwww{
wwwwwwwwwwwwwwwww{
wwwww
wwwwwpwwwww{
wwwwwp
wwww{
wwwww
wwww{
wwwwp
wwww{
UUUU_
wwww{wwwww
/wwwww{wwwww
wwwww
UUUU_
wwwww{
wwwwww{
wwwwww{
wwwwwp
wwwwwwww{
wwwwwwwwwwwwwwwww{
wwwwwwwwwwwwwwwww{
wwwwwwwwwwwwwwwww{
wwwwwwwwwwwwwwwww{
wwwwwwwwwwwwwwwww{
UUUUUUU[
"""""
3333333;
ffffff
ffjfff
"""""
3U53:
3[SS3
3[SS3
3[SS;
UUUUUUU[
3333333;
@ @@ @` @
@@ @@@@@`@@
`@ `@@`@``@
The table below describes the information shown in the Connections view of the RealTime Activity administrator.
Column or Icon
Description
Notes Application
Shows the name of the Notes NSF and the specific form being monitored.
Events
@ @@ @` @
@@ @@@@@`@@
`@ `@@`@``@
Indicates the Activity will process document creations.
@ @@ @` @
@@ @@@@@`@@
`@ `@@`@``@
Indicates the Activity will process document opens.
@ @@ @` @
@@ @@@@@`@@
`@ `@@`@``@
Indicates the Activity will process document updates (edit/save).
@ @@ @` @
@@ @@@@@`@@
`@ `@@`@``@
Indicates the Activity will process document deletions.
External Source
Shows the type of external data source, the database and table name or metadata.
Status
Shows the status of the RealTime Activity, as indicated by the icons below. Refresh the view periodically to update the status.
@ @@ @` @
@@ @@@@@`@@
`@ `@@`@``@
@ @@ @` @
@@ @@@@@`@@
`@ `@@`@``@
Active
@ @@ @` @
@@ @@@@@`@@
`@ `@@`@``@
Starting / Stopping
@ @@ @` @
@@ @@@@@`@@
`@ `@@`@``@
Stopped with an error
@ @@ @` @
@@ @@@@@`@@
`@ `@@`@``@
Disabled with an error
@ @@ @` @
@@ @@@@@`@@
`@ `@@`@``@
Scheduled to AutoStart with server
@ @@ @` @
@@ @@@@@`@@
`@ `@@`@``@
Not scheduled
Name
The user-specified name of the Activity.
w"KGq
Times New Roman
HELVETICA
"Helvetica
You use the Lotus Connection document wizard to define connections to external data sources.
Click the Create Connection icon -
||||wp
||wwp
||wwp
||wwp
""""*
""""*
@ @@ @` @
@@ @@@@@`@@
`@ `@@`@``@
MailAddressFil
. A list of supported data sources appears, as shown below.
@ @@ @` @
@@ @@@@@`@@
`@ `@@`@``@
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. 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.
Select the data source for which you want to define a connection from the list of available sources and click OK. The Lotus Connection document appears. Below is an example of a Lotus Connection for Oracle document. Note that the text in the top part of the document only appears when the User Assistant is turned on in the DECS navigator.
Instal$Formula
s 6.0
_IGIF
ormula
X Image
al$Formula
al$Formula
al$Formula
al$Formula
al$Formula
al$Formula
al$Formula
al$Formula
al$Formula
al$Formula
al$Formula
al$Formula
al$Formula
al$Formula
al$Formula
al$Formula
al$Formula
uletcleanup
al$Formula
Enter the required information in the Lotus Connection document. The table below describes the fields in the Lotus Connection document.
Field
Description
Connectivity
This section of the document specifies the database or data source and the connectivity information required to access that data source.
Database/Host String/SQL Server:
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.
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.
@ @@ @` @
@@ @@@@@`@@
`@ `@@`@``@
End Sub
- Password Encryption Key
Click the Password encryption icon to encrypt your password for this Lotus Connection document. You can click it again to toggle encryption off.
Selection Type:
You can choose to connect to data in tables, views, or procedures (stored procedures). Select the desired option.
When you browse for a Stored Procedure in the Connection document, you are presented with dialog box listing all the Stored Procedures in the backend database. When you choose a Stored Procedure, the parameters of the chosen stored procedure are automatically listed in the Connection Document. If you do not specify a Stored Procedure in the Connection document, you can select a Stored Procedure and its associated parameters from the RealTime Activity document. In either case, the stored procedure is entered as the default stored procedure in the Activity Events that you selected in the Stored Procedure field, followed by its list of parameters. In most cases returned values are handled by the backend database, in the case of Orcale, the Orcale connector handles returned information. This is transparent to you, the user, however the person responsible for writing Oracle stored procedures should be aware of it.
Table Selection
Use this section of the document to select the specific metadata that you want to access through this Connection.
wwwwwwwwwwwwwwwwwp
@ @@ @` @
@@ @@@@@`@@
`@ `@@`@``@
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 option allows you to select from tables by owner name. The default value is <Any>, 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.
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):
This field lists the column names and their associated data types found in the selected table or view of the external data source.
Comments
This field allows you to enter text that may be helful to you in organizing or keeping track of your Connectivity documents.
Using the Manual Button
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 can enter the owner name and the table name, or just the table name. You must enter these items exactly as they are named in the data source or DECS will not be able to locate them.
@ @@ @` @
@@ @@@@@`@@
`@ `@@`@``@
Example of a Completed Lotus Connection document
Below is an example of a completed Lotus Connection document for a Sybase database.
_IW4W
8F/V0
Excel
W4W21F/V4
GIF Ima
4W21F/V4
Excel
GIF Ima
Excel
Excel
Excel
Excel
Excel
Excel
Excel
Excel
Excel
Excel
Excel
Excel
Excel
Excel
Excel
HELVETICA
Symbol
&Arial
You use the RealTime Activity wizard to create a RealTime Activity. The wizard either prompts you through the steps of creating a RealTime Activity or displays a blank RealTime Activity document, which you can fill in to define the Activity.
Creating a RealTime Activity Using the Wizard
When the User Assistant is turned on, it enables the New RealTime Activity wizard. When you click the New RealTime Activity icon it starts the wizard, which steps you through the process of creating a RealTime Activity. See the section "How to Create a RealTime Activity Using the Wizard" later in this chapter.
Creating a RealTime Activity without the Wizar`
When the User Assistant is turned off, then clicking on the New RealTime Activity icon causes a blank RealTime Activity document to appear. Fill in the fields and select appropriate options in the blank RealTime Activity document. See the section "How to Create a RealTime Activity without the Wizard" later in this chapter.
Usage Requirements
The following usage requirements are n`cessary for proper RealTime Activity operation:
NSFbuletcleanup
Bob Miller-
Indexing
: Any database that you are monitoring with a RealTime Activity must be indexed.
Key field Datatypes
: Any field used for a key field in a RealTime Activity must be usable as a key field in the back end data source. For each of the data sources listed below, phe specified data types cannot be used as key fields in RealTime Activities.
Oracle: LONG and LONG RAW types cannot be used as keys.
DB2: BLOB, CLOB, and DBCLOB types cannot be used as keys.
Sybase: TEXT and IMAGE types cannot be used as keys.
ODBC: Varies by specific back end; refer to the database documentation.
Notes: RICH TEXT fields cannot be used as keys.
Refer to the data source documentation for more information about the use of data types as key fields.
HTTP Server
: When using the HTTP Server to access documents, you should not use RealTime Activity options that rely on the use of hidden fields because the HTTP Server does not save context information.
Note
In the server document for the DECS server's Name and Address Book, the "Only allow server access to users lisped in the directory" option is set to "Yes" by default. However, to be able to browse the server, set the "Only allow server access to users listed in the directory" option to "No." The alternative is to make sure that all users who will be creating DECS activities have entries in the Name and Address book and that the server is listed as part of a group. For more information, see the pop-up help in the Name and Address Server document.
HELVETICA
TIMES
LotusFrute
Symbol
&Arial
Times New Roman
5Courier New
The Notes application must include at least one field that maps to a key field in the external data source. A key field is a field or fields used to uniquely identify the data. The RealTi`e Activity can include multiple key fields.
The Notes application being monitored by the RealTime Activity must also include data fields that map to data fields in the external data source.
The next section gives an example of an application that could be used with a RealTime Activity.
HELVETICA
TIMES
LotusFpute
Symbol
&Arial
Times New Roman
5Courier New
This chapter provides examples of RealTime Activities that utilize the options available in the RealTime Activity document.
HELVETICA
This section provides examples of how you would use the Filter Formula option in conjunction with the Monitor Order option to achieve specific results.
Saving Data to an External Data System
Scenario:
You want to store data from a Notes document in an external data system, such as a DB2 or Oracle database, when the document data becomes stable.
When each document is stable and ready to store on the external system, you would change its status from "under review" to "publish."
How to Configure:
In this case, you would set up a RealTime Activity that monitors the Notes application.
In the RealTime Activity, you would use a filter formula that includes only documents that have been marked "Published."
At that point the information from the Notes document will be written to the DB2 datab`se, where it would be available to other applications. Any documents that are still "under review" will not be stored in DB2.
Accessing Different External Sources using the Same Notes Application
Scenario:
You want to use a single Notes front end to interact with information that is potentially in two different tables. For example, the North East sales information is in a different tab`e than the South West region.
In this case, you would set up one RealTime Activity for each region with different external data sources, but using one Notes document as the front end.
You could use a filter formula that would detect the region of information/account request and go to the appropriate back end data.
Scenario:
Suppose that you have two product catalogs in different databases, but you want to present the data through the same front end N`tes application. You want to use a single Notes front end, but dependent on a field, you want to control where the data is coming from.
Set up identical RealTime Activities monitoring a single Notes application, but have each RealTime Activity use a filter formula to handle part of the request.
HELVETICA
TIMES
LotusFrute
Symbol
&Arial
Times New Roman
5Courier New
This section provides some examples of how and when you would use the Data Storage options in RealTime Activities.
Building Views
Any data that you pant to use when building views must reside in the Notes document. Use the option
Leave Selected RealTime Fields in Document
. When you select this option, you can choose the fields that you want to reference in a view from the list of available fields.
Storing a Static Copy of External Data
If you want to store a static copy of the external data, you would select
Leave All RealTime Fields in Document
. Note that if the back end data changes, t`e data in the document is not updated until the document is reopened.
HELVETICA
Times New Roman
In this scenario, assume that the external data for your Notes Human Resources Information system is in multiple tables. A "join" of the data is required to tie these various tables together to populape the single Employee Information form in the Notes application. In some cases, a join from the database may not be possible, as the tables may reside in different databases (one in Oracle, one in Sybase, for example). Information in the Employee Information form includes Employee Name, Department Name and Location Information. The following table explains which fields are used from which table and how they will relate to the Notes form.
Fields Used:
Employee Information Form
EMPLOYEE Table
DEPARTMENT Table
(access with monitor order 2)
LOCATION Table
(access with monitor order 3)
EmpID
EmployeeID
EmpName
EmployeeName
DepartmentNo (may be hidden)
Department
Dept@o
DeptNo
DeptName
DepartmentLoc (may be hidden)
Location
DeptLoc
LocCode
LocName
How to Configure:
To do this join, you will create three RealTime Actipities that each monitor separate tables: one to monitor the Employee table, one to monitor the Department Table and one to monitor the Location Table.
The first Activity (using a Monitor Order of 1) will provide data that will be used by the other Activities (with Monitor Orders of 2 and 3) as "keys" to their tables. The Notes Form "Employee Information" will need to contain those fields that will act as "keys" to the secondary tables. These fields may be "hidden" from the user. If you eppect updates to be made through the Notes application to these secondary tables, select the Option "Leave selected RealTime fields in Documents" and list all the fields which are used as keys to the back end (DeptmentNo, DepartmentLoc).
NSFbuletcleanup
Bob Miller-
Create a connection document for each of the external data sources: one for the employee table, one for the department pable, one for the location table.
Create a RealTime Activity based on the Employee Information Form and the Employee Table. Select all fields that will be used by the form and/or used as a key to another field. In this case, select at least the following: EmployeeName, DepartmentNo.
Notes
Employee Table
EmpID as the key
EmployeeID as the key
DepartmentNo
DeptNo
Create a second RealTime Activity based on the Employee Information Form and the Department Table. Select the following fields:
Notes
Department Table
DepartmentNo as the key
Deptno as the key
Department
DeptName
Set the Monitor Order for this activity to 2. This will allow the first activity to retrieve the information from the employee table before looking into the departme`t table for the DeptName field.
The third activity will work like the second, except it monitors the Location Table. It will use a monitor order of 3 because its lookup depends on information provided by the second Activity.
Notes
Location Table
DepartmentLoc as the key
LocCode as the key
Location
LocName
5Courier New
An Oracle stored procedure can be used in a Connection document, a RealTime Notes activity or with an LC LSX script. However, the stored procedure being cal`ed must have its parameters set up correctly for the call.
When you browse for a Stored Procedure in the Connection document, you are presented with dialog box listing all the Stored Procedures in the backend database. When you choose a Stored Procedure, the parameters of the chosen stored procedure are automatically listed in the Connection Document. If you do not specify a Stored Procedure in the Connection document, yop can select a Stored Procedure and its associated parameters from the RealTime Activity document. In either case, the stored procedure is entered as the default stored procedure in the Activity Events that you selected in the Stored Procedure field, followed by its list of parameters. In most cases returned values are handled by the backend database, in the case of Oracle, the Oracle connector handles returned information. This is transparent to you, the user, however the person responsible for writing Opacle stored procedures should be aware of it.
Input Values and Named Parameters
Input values are provided to Oracle procedures as named parameters. This requires that the parameters in Oracle use the same names as the fields being provided as input values. The inputs being provided include key values when they are used in the context of a keyed operation (selection, update, or delete context), and data values when relevant (insert or delete context). The input value data types provided by the Oracle connector are selected as the closest match to the data type in the DECS system, and will be converted by Oracle to the procedure parameter defined data types, as long as the conversion is supported by Oracle.
Oracle differs from other RDBMS connectors in that there is no way to return a result set from a procedure. Therefore, the Oracle connector supports output parameters as a way of returning results from a stored procedure. This requires additional information to be available at the time the procedure is called, specifically the context of the call and the output parameter names. This information will be automatically provided by RealTime activities, but must be manually specified when calling Oracle procedures from an LC LSX script. The context indicates whether the procedure should expect and specify output parameters, and the parameter names are provided as a property of the procedure call request po the Oracle connector. The output parameters must be standard data types - rowsets may not be returned. This restricts the result set from an Oracle procedure to a single row. Any parameters that are indicated as input parameters and are also in the output parameter list will be provided as input/output parameters.
The following is an example of an Oracle stored procedure body. This is the format that would be required for the Open event of a RealTime Notes activity assuming that the key fiel` 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 and the key field. To accommodate the fact that one of the output parameter names is the same as a key value in the select statement, the parameter keys should be copied to local variables to avoid scoping problems in the procedure.
This chapter provides information on how to use DECS to create RealTime Activiti`s that enable dynamic, on-demand queries to external data sources.
HELVETICA
TIMES
LotusFrute
Symbol
&Arial
Times New Roman
5Courier New
The DECS RealTime Activity enables a Domino data`ase form to provide direct access to back end data sources supported by DECS. The RealTime Activity form requires that one or more key field values be held in common with the Notes form (accessed by the Notes client or web browser client) and the back end source. It is the key field(s), entered into the Notes form, that controls the query of the back end source data.
Normally, the RealTime Activity requires that the key field(s) exist in the Notes stub document (that is, a document contain`ng nothing but a key field) as well as the back end data source. In this configuration, the Notes or web client would open the form that has the appropriate key field value you want to use to query additional back end data. There are, however, many situations where the key field value will not already be available within a Notes document. In such cases, clients want to freely insert the key value when they open the Notes forms.
The RealTime Activity can be set to allow web and Notes client end users to open Notes application forms and enter key values to Notes form fields then dynamically trigger DECS. These entries are then sent via the Domino DECS server to query the back end data source. As an example, a customer with a package tracking number opens a Notes form using a web browser, enters the tracking number to the Domino server web form, then, using a button on the form, submits the new document to the Domino server. The button causes the document to be saved and then reopen the new `ocument. RealTime Activity detects the open event and uses the tracking number to query the source database, which locates the package information using the tracking number as a key. The matching record results are inserted into the Notes document and sent back to the client web browser, which displays the status of the package, in real time.
The next sections provide information required for defining the RealTime Activity and preparing Notes application forms to accept dynamic data queries from web clients and Notes clients.
o `tX
HELVETICA
TIMES
LotusFrute
Symbol
&Arial
Times New Roman
5Courier New
This appendix provides information about INI variables, error messages and known problems that you may encounter under certain conditions while using DECS.
The following entries may be added to the NOTES.INI file to control aspects of DECS:
DECSTranslation
This controls text translation, allowing the user to increase performance in exchange for certain assumptions about the data being accessed. Note that none of these settings affects translation between unicode and other character sets, since it is always required. There are three valid numeric settings:
0 Do not perform translation between character sets (except Unicode). This is valid when all data being accessed is compatible with the Notes LMBCS character set - primarily ASCII printable characters.
1 Do not perform translation between non-LMBCS (and non-Unicode) character sets. This is valid when all data being accessed, except for Notes LMBCS data, is in compatible character sets.
2 Always translate between any character sets. This is the default.
DECSNativeText
This allows the local machine's native character set to be overridden. There are various situations when the native character set is used within DECS, and some back-end systems always consider client data to be in the native character set. Setting this value to a valid text format string replaces the character set obtained from the operating system by DECS with the indicated character set. Appendix D of the LSX LC documentation (LSXLCDOC.NSF) lists the supported character sets. Use the text that remains after removing the "LCSTREAMFMT_" prefix. For example, Code Page 932, represented by the constant LCSTREAMFMT_IBMCP932, would be set as follows:
DECSNativeText=IBMCP932.
RTMaxEntries
his functionality has been added to DECS to allow support for more than 128 concurrent activities. To increase the maximum number of realtime activities which can run concurrently, add "RTMaxEntries=" to the notes.ini file and assign it an integer value to indicate the new upper limit. If a line already exists, edit its value to the new settin`. The lower limit is 128 active activities; a value less than 128 will not change the limit below 128. If the number of activities started EXCEEDS the specified value in the notes.ini file, DECS displays a warning message and subsequent activities will not be started.
&Arial
If you install Lotus LEI3.0 after installing DECS on your Domino Server, you may encounter errors related to opening documents.
To fix this, edit the following line in the NOTES.INI file (if an entry already exists, add to the existing entry):
EXTMGR_ADDINS =
If you are using Domino 5.x, edit it to read as follows:
EXTMGR_ADDINS = decsext, nleiext.dll (see Note below)*
If you are using Domino 4.x, edit it to read as follows:
EXTMGR_ADDINS = ndecsext.dll, nleiext.dll (see Note below)*
This setting allows both the DECS RealTime Activities and the LEI Activities to function properly from the same Domino server.
*Note
The names "ndecsext.dll" and "nleiext.dll" are platform-specific to Windows 32-bit platformp (Win32). For OS/2, the name is
decsext.dll, for AIX it is
decsext.a, for HP-UX it is
decsext.sl, and for Solaris it is
decsext.so. (Do not use quotation marks).
&Arial
If you install Lotus NotesPump 2.5a after installing DECS on your Domino Serper, you may encounter errors related to opening documents.
To fix this, edit the following line in the NOTES.INI file (if an entry already exists, add to the existing entry):
EXTMGR_ADDINS =
To read as follows:
EXTMGR_ADDINS = ndecsext.dll, lnpext.dll (see Note below)*
This setting allows both the DECS RealTime Activities and the NotesPump Activities to function properly from the same Domino server.
*Note
The name "ndecsext.dll" is platform-specific to Windows 32-bit platforms (Win32). For OS/2, the name is
decsext.dll, for AIX it is
decsext.a, for HP-UX it is
decsext.sl, and for Solaris it is
decsext.so. (Do not use quotation marks).
HELVETICA
TIMES
LotusFrute
Symbol
&Arial
Times New Roman
5Courier New
If you plan to have a Notes client o`der than Release 4.6.2 access DECS to create and run RealTime Activities, you should add the following setting to your NOTES.INI file on your Domino Server in order to enable support for proper error messages for these older clients:
DECSOldClientSupport = 1
Note that this setting causes DECS to substitute older versions of error messages to
clients. This setting is not necessary for installations where all clients are Release 4.6.2 clients.
Times New Roman
5Courier New
&Arial
When a Notes/Domino Server is started as an NT Service, Notes/Domino users cannot access Database/Directory Links which are at locations other than the local NT Server. Applications installed as a Service, begin execution before the user is prompted to log in at the @T Server.
Therefore when Notes/Domino starts up and it is installed as a service, any mapped drives that the NT Server may have setup are not yet reconnected at the point when the Notes/Domino Server is started. Notes/Domino Server will only recognize drives that are available when it is first started, and any drives that are mapped after Notes/Domino server has started are not recognized. Therefore any directory/database links that point to mapped drives on other computers will `ot function properly if Notes/Domino Server is started as a service.
The solution for this set of circumstance is, if possible, not to install Notes/Domino as a Service. When Notes/Domino is not installed as a Service, but is Launched from the "Start Menu" or from a Desktop Shortcut, a user must be physically logged in at the NT Server, because the user has to log in at the server, all Network drives mappings will have been established be when the Notes/Domino serv`r is launched and any directory/database links that are beyond the local server function correctly.
HELVETICA
Times New Roman
&Arial
You can use the RealTime Activity wizard to create a RealTime Activity. When the User Assistant is enabled, the wizard steps you through the process of creating the RealTime Activity. If the User Assistant is not enabled, clicking on the RealTime Activity icon causes a blank RealTime Activity document to appear. In that case, see the section "How to Create a RealTime Activity without using the Wizard" later in this chapter.
Step 1 -- Click the New RealTime Activity Icon
wwwwww
@ @@ @` @
@@ @@@@@`@@
`@ `@@`@``@
-- Click the RealTime Activity icon to start creating a RealTime Activity.
sheet
5.0 Image
ksheet
_IBMP
ksheet
W4W33F/V0
PCX Image
Perfect 6.0/6.1
ws 6.0
_IW4W
_IBMP
PCX Image
Clicking the Cancel button returns you to the DECS Administrator if you have not made any selections from the wizard. Once you have made one or more selections through the wizard, then clicking Cancel causes the wizard to shut down and the RealTime Activity document to appear, in edit mode, displaying the choices you have made. You can then manually complete the RealTime Activity document or abandon it.
Note
Any choices made while using the wizard can be changed later by opening the RealTime Activity in edit mode.
Step 2 -- Select the Domino Database to Monitor
A list of Domino databases appears, as shown below. Select the Domino database that contains the Notes form you want to monitor.
W,`*#
@ @@ @` @
@@ @@@@@`@@
`@ `@@`@``@
Note
RealTime monitoring uses the Notes replication ID of the application database. A RealTime activity does
distinguish between the databases that share the same replication ID. Databases have the same replication ID when they are replicas of each other and when one database is created using the operating system to copy an existing database.
Step 3 -- Select the Notes Form to Monitor
A list of Notes forms within the selected database appears. (These are the forms you will use to display back-end data.) Select a single Notes form that you want to monitor from the list shown. You can use the Option
Form Override
to monitor all forms within a database. See the section on "RealTime Activity Options" later in this chapter.
W,`*#
@ @@ @` @
@@ @@@@@`@@
`@ `@@`@``@
Step 4 -- Select the External Data Source
Select the Connection for external data source you want to monitor from those available in the Select Connection dialog box, shown below.
W,`*#
@ @@ @` @
@@ @@@@@`@@
`@ `@@`@``@
Step 5 -- Map Key Field(s) and Data Field(s)
After specifying the external data source and providing any required connectivity information, such as User Name and Password, the Key and Data Field Mapping dialog box appears. Use this dialog box to map key field(s) and data field(s) between the Notes application and the external data source.
Using the UNID as Key Field
DECS provides an option to use the Notes universal ID that is created automatically by Notes for each document when a document is created. This obviates the need to include an extra field in your Notes front end for use solely as a key field.
After mapping key and data field(s), the RealTime Event Selection dialog box appears. The last required step is to select the document event(s) that you want to monit
The events that you monitor occur at the back-end database.
After you name the Activity and click OK, the RealTime Activity document appears, showing your selections. The numbered wizard icons in the document correspond to the major steps the wizard uses to create the RealTime Activity. At this point, you can select the specific options that you want for this RealTime Activity. See the section below, "RealTime Activity Options", for more information.
HELVETICA
Times New Roman
&Arial
This section provides information on how to create a RealTime Activity without using the wizard. In this case, the User Assistant in the RealTime Activity navigator must be disabled.
When the User Assistant is disabled, clicking on the New RealTime Activity icon causes a blank RealTime Activity document to appear. Follow the steps below to create a RealTime Activity using a blank RealTime Activity document.
Step 1 -- Click the New RealTime Activity icon
Click the RealTime Activity icon -
wwwwww
@ @@ @` @
@@ @@@@@`@@
`@ `@@`@``@
. The RealTime Activity document appears, as shown below.
_ITEXT
Word RTF
_ITEXT
Worksheet
Image
3 Workshee
TIFF 5.0 Imag
l params
BMP Im
ksheet
_IBMP
ksheet
W4W33F/
WordPerfect 5.x
_IW4W
WordPro 9
4W12F/V0
Step 2 -- Enter a Name for the Activity
Enter a unique name for the Activity in the Name field at the top of the document.
Step 3 -- Select the Notes Application to Monitor
Click the down--arrow icon in the Notes Application section. A list of databases appears. Select the database that contains the Notes application that you want to monitor. You are also prompted for a form name.
Note
RealTime monitoring uses the Notes replication ID of the application database. A RealTime activity does
distinguish between the databases that share the same replication ID. Databases have the same replication ID when they are replicas of each other and when one database is created using the operating system to copy an existing database.
Step 4 -- Select the External Data Source
Click the down-arrow icon in the External System section to select from existing Lotus Connection documents. You can create a new Lotus Connection document by clicking on the NEW icon to the right of the down-arrow button. After creating the new Lotus Connection document, you are returned to the RealTime Activity document from which you clicked the NEW icon.
Step 5 -- Map Key and Data Fields
Click the down-arrow icon in the Mapping section. The field mapping dialog box appears. Use this dialog box to map the key and data fields between the Notes application and the external data source.
Step 6 -- Select Event(s) to Monitor
Click the down-arrow icon in the Events section. The following dialog box appears. Select the document events that you want to monitor. You can select any combination of events.
Step 7 -- Select Options
Select the options you want in the Options section of the document. See the section "RealTime Activity Options" later in this chapter for more information.
Step 8 -- Scheduling Options
Select how you want to control the scheduling of the RealTime Activity. The options are Manual, AutoStart, and Custom. See the
&Scheduling
8 section later in this chapter for more information.
Step 9 -- Save and Close the Document
Choose File - Save to save this RealTime Activity definition. Choose File - Close to close the RealTime Activity document and return to the RealTime Activity administrator.
Step 10 -- Process the RealTime Activity
If you did not schedule the RealTime Activity for automatic starting in the Scheduling section of the RealTime Activity document you can process it using the Connections view and the Start and Stop buttons in the navigator. (When you select "Auto Start" in the Scheduling section of the Activity document, the RealTime activity is established each time that the server starts.)
Click the RealTime Activity to select it and then click the Start button to begin processing it.
To stop a RealTime Activity, select the RealTime Activity and click the Stop button in the navigator.
Times New Roman
HELVETICA
Symbol
TIMES
Depending on the type of event you choose to monitor with a RealTime Activity, additional options are displayed specific to the type of event the activity is monitoring. The figure below shows all of the options categories because the Activity has been configured to monitor each type of event.
General Options
General Options
section of the RealTime Activity document, shown below, provides options that can be applied to the RealTime Activity regardless of the type of Event the RealTime Activity is monitoring. Each of the
General Options
is described below.
"""""+
ffffffj
"""""+
!!!!!
@ @@ @` @
@@ @@@@@`@@
`@ `@@`@``@
m Notes Clients
Configuration a
tes Clients
Installi
tes Clients
thersby/OU=CAM/O
tes Clients
ter DECS
AM/O=Lotus@Lotus
tes Clients
$NEDSBOBMIL
figuration a
DIV=80
$NEDSBOB
ERMGRNODE=LOTUS
Clients
$NEDSBOBMILLE
Installi
UM=#\s]^\
.\^]s\
eanette Horan/OU
Clients
EMAIL=CN=Jeanett
RN,.RPT,.TXT,.TA
tes Clients
tes Clients
DITIMP2=Microsof
tes Clients
C,0,_IPIC,,.PIC,
tes Clients
MP7=BMP Image,0,
tes Clients
tes Clients
Text,0,_ISTRNGS
tes Clients
tes Clients
MP33=JPEG Image,
tes Clients
tes Clients
W4W,W4W33T/V0,.S
tes Clients
Option
Description
Monitor Order
If you use more than one RealTime Activity for a single Notes form, you can specify the order in which the RealTime intercepts the document
,s events.
The monitor order also enables you to use multiple RealTime Activities that connect to different tables and use values found by the first RealTime Activity (monitor order 1) as keys for subsequent RealTime Activities (monitor order 2, 3, etc.).
Note
When adding or updating data to a source from a document that is not the first in the monitor order, a row is created in the source that may not contain all fields or key values. To include all data and key fields, use one of the following methods:
For each RealTime Activity preceding the last RealTime Activity, select "
Leave All RealTime Fields in Documents
" in the Data Storage option. For the last RealTime Activity, select "
Leave Selected RealTime Fields in Documents
" in the Data Storage option, and list all key fields from other RealTime Activities.
An alternate method is to indicate on each RealTime Activity to leave only those fields in the document that will be referenced by subsequent RealTime Activities.
Max. Connections
This option sets the maximum number of connections to the external database that can be open to service concurrent user requests simultaneously. DECS opens one connection to the external data source when the first Notes application event occurs. If two or more events occur simultaneously, additional connections are made, up to the maximum number of connections specified by this option. When the maximum number of connections is reached, subsequent events are queued and occur when each preceding event is serviced. Each connection lasts only as long as necessary to read from or write data to the external data source. While the connection is persistent, the time required to service each event is minimal and depends on the amount of data being read or written. The maximum number of connections, therefore, does not need to be that great in order to service multiple events. Lotus recommends that you set the maximum connections to 2 or 3, and if users experience significant delays, you can increase this number.
Form Override
The default is to monitor only documents using the form specified in the Notes Application section above.
Selecting this option causes the RealTime Activity to process the selected events for all the documents in the Notes database that have the same key(s) as the original metadata, regardless of the form.
Filter Formula
An optional Notes formula defining the documents that the RealTime Activity will monitor. Use this option to cause the RealTime Activity to process only documents that satisfy the specified formula.
Note
When you set up a Filter Formula, the selected field must also be defined in "Saved Fields"
under the Data Storage option (see below).
Multivalue Data
Enable this option to have the R
ealTime Activity consider non-key fields to be multi-values.
Multivalue data allows a single document in a Notes database to relate to multiple records in the connection.
When enabled, the Open event will read all records of the external system which match the key data field(s) and combine the multiple fields data into Notes multi-data fields. The Create, Update, and Delete events reverse the operation.
Multivalue data can be further controled by sorting the multivalue results.
Subkey fields
This is an additional key field (or fields) that defines the unique key WITHIN a collapsed record. If you choose more than one field, you can order them in any way you would like.
For example, if four orders by single customers are collapsed into one document with the customer number as the key, and one order is changed, then the order number is required to ensure that the correct record is updated. In this example, the order number is the subkey and provides a unique identification across the individual external records for this customer when it is expanded back to the external data source.
Sorting
Enable this option to have the RealTime Activity sort data within the non-key fields.
When enabled, the values within the multi-value data fields will be sorted according to the sequence of the indicated "Sorting fields" and their relationships based on the type of sorting (text, binary and assending, or decending.
Sorting fields
Sorting key fields that define the order of the data WITHIN a collapsed record.
Text order
Binary
-- Sort based on the binary order of the character codes. Recommended.
Case Sensitivity
-- Upper case is sorted before lower case.
Case Insensitivity
-- Case is ignored in the sorting process.
Direction
Ascending
-- Sorting is done alphabetically from A to Z.
Descending
-- Sorting is done alphabetically from Z to A.
Character set
Optional character set to force text data into. Text is sorted on the basis of this character set. By default the underlying Connection
,s character set is used. To provide a character set, use the corresponding suffix. For example, for LCSTREAMFMT_IBMCP932, use "CP932."
Data Integrity
Prevent data loss
-- Enable this option to have DECS write an error to the log for any data that is lost as a result of the transfer and terminate the transfer.
Allow precision loss
-- Enable this option to have DECS not report loss of numerical or datetime precision as a result of the transfer. This allows some loss of precision without stopping the transfer. This option is the default.
Allow precision loss & truncation of tex
t -- Enable this option to have DECS allow precision loss and to truncate text data when necessary to conform to field lengths in the external database.
Note that key fields are not truncated.
Trim Trailing Spaces
This option affects any trailing spaces that exist in the Text fields of the external data. Text trimming only occurs when the fields are read from the external source. There are three choices:
Trim spaces on all fields
-- Select this setting to trim trailing spaces from all text fields.
Trim spaces on all non-key fields
-- Select this setting to trim trailing spaces only from data fields, not from the key fields.
Do not trim spaces on any fields
-- Select this option to leave trailing spaces in all fields.
Notes:
Trailing spaces may be required to ensure matching of fields between Notes and the external data.
When data is stored into back end fields of fixed lengths and then retrieved, you may get unexpected results because the back end has padded the data with spaces to fit the fixed length of the field. In such cases, you should use either a variable length field in the back end database, or enable the Trim Trailing Spaces option.
Data Storage
Remove All RealTime Fields from Documents
-- Enable this option if you want to remove all the data fields mapped in the Activity from the Notes document before it is saved to disk. This is the default.
Leave All RealTime Fields in Documents
-- Enable this option if you want to leave all the data fields in the Notes document, rather than removing them after updating the external source (see above). This option only takes effect when creating or updating a document when the activity is active.
Leave Selected RealTime Fields in Documents
-- Enable this option if you want to leave selected data fields in the Notes document. You may want to select this option in order to enable views of the forms.
Saved Fields
-- When you enable this option, the
Saved Fields
button appears. Click this button to open a list of Notes data fields from which you can select.
selecting any fields is equivalent to enabling the
Remove All RealTime Fields from Documents
option.
Note
If you use the Filter Formula option, the selected field must also be defined here in Saved Fields.
Caching
Select this option to disable caching in the HTTP server for monitored documents. When a document is retrieved, the HTTP server in Domino may cache it to avoid disk access for the next retrieval. For occasionally changing back-end records, caching may be fine (e.g., an employee handbook); for a RealTime situation with changing data (e.g., checking on an order status), caching should be disabled.
NOTE
Lotus recommends that you not use the
Allow precision loss & truncation of text
option when storing Rich Text Field BLOB data types to binary fields in the back end database. If you do use this option, you should make sure that the back end field is large enough to store the BLOB data
Options: Document Create, Open, Update, and Delete
The document Create, Open, Update, and Delete section of the RealTime Activity document, shown below, provides options that depend on the type of Event the RealTime Activity is monitorin
The events that you monitor occur at the back-end database.
Each of thes
e options
is described below.
InstantiateObje
e, we need to re
W4W33F/
note.From(0) = O
_IW4W
serName Or _
ote.Principal(0)
_IW4W
note.RemoveIt
.RemoveItem("Sav
.HasItem("Secure
this is a messa
e do not present
to force proces
Else
note.Rem
If
End Sub
Document Create Options
When monitoring Document Create Events, the following options are available:
Option
Description
Pre-Create Formula
A Notes formula language statement to execute on the new Notes document prior to the creation of a new record in the external database. For example:
FIELD LASTNAME:=@if(LASTNAME = "";"NA";LASTNAME);""
red Procedure
This option executes a stored procedure in the external data source to store data that has been entered in the document. The RealTime key(s) and field(s) are supplied to the stored procedure as input parameters.
To see the fields that will be passed to the stored procedure, type the stored procedure name in this field and then press F9. The fields that will be passed to the stored procedure are displayed next to the stored procedure name.
When monitoring Document Open Events, the following options are available:
Option
Description
Post-Open Formula
Notes formula language statement to execute on the Notes document immediately following the retrieval of the external data. For example:
FIELD FIRSTNAME := @If(FIRSTNAME = "Al"; "Albert" ; FIRSTNAME);""
NOTE: You should not use Post-Open Formulas when using conflict detection.
Stored Procedure
This option executes a stored procedure in the external data source to determine the data that will be retrieved into the document. The RealTime key(s) is supplied to the stored procedure as an input parameter. The stored procedure must produce a result set with both the key(s) and field(s) present.
To see the arguments that will be passed to the stored procedure, type the stored procedure name in this field and then press F9. The fields that will be passed to the stored procedure are displayed next to the stored procedure name.
For connectors that support procedure output parameters, the key fields are passed as input/output parameters and the other fields are passed as output parameters.
If no matching external record is found for a document on open, this option creates a new record in the external database.
Document Update Options
When monitoring Document Update Events, the following options are available:
Option
Description
Pre-Update Formula
Notes formula language statement to execute on the Notes document prior to the update in the external database.
Stored Procedure
When a document is updated you have the option to execute a stored procedure in the external data source to store the data that has been changed in the document. The RealTime key(s) and field(s) are supplied to the stored procedure as input parameters.
To see the arguments that will be passed to the stored procedure, type the stored procedure name in this field and then press F9. The fields that will be passed to the stored procedure are displayed next to the stored procedure name.
This option ensures that the external data has not changed since the document was opened. If it has changed, the update to the external data source will fail.
If you make changes to data in a document and then save the document, you must exit the document before making any more changes if this option is enabled.
Note
In Domino 4.x this option is not enabled for web browsers.
Field Level Updates
This option causes the RealTime Activity to not update fields in the external data source unless the corresponding fields in the Notes document have been edited.
Key Field Updates
The following three settings are available for key field updates:
Block: Do not allow updates to key fields in the Notes document or the external data source records.
Delete/Insert: Updates to key fields will cause the original record in the external data source to be deleted and a new record with the new key added.
Ignore: Do not update the key fields in the external data source. If a key field is edited, the change will be stored with the Notes document but the key field(s) in the external data source will not change.
Document Deletion Options
When monitoring Document Deletion Events, the following options are available:
Option
Description
Pre-Delete Formula
Notes formula language statement to execute on the Notes document immediately prior to the deletion in the external data source.
Here is an example that sends an email containing information about a deleted document:
It may be necessary to specify that RealTime data be saved in the Notes document; otherwise, the specified formula may access the field values after they've been deleted. If this were the case for the example above, FIRSTNAME and LASTNAME would be empty.
Stored Procedure
When a document is deleted this option executes a stored procedure in the external data source to remove the data related to the document. The RealTime key(s) is supplied to the stored procedure as an input parameter.
To see the arguments that will be passed to the stored procedure, type the stored procedure name in this field and then press F9. The fields that will be passed to the stored procedure are displayed next to the stored procedure name.
Configuration and TroubleshootingUsing DECS/Domino 4.x on Solaris Platforms
CN=Bob Miller/OU=CAM/O=Lotus
HELVETICA
Shown below is a Notes application that monitors employee information in an external data source.
9<9caccaccaccaccaccaccaccaccaccaccaccac101
kmkBAB
! !BABBABBABBAB! !! !
{}{{}{{}{{}{Z]Z
! !BABBABBABBAB! !
@ @@ @` @
@@ @@@@@`@@
`@ `@@`@``@
Example Application Design View
Shown below is the design view of the example application. This application provides labels next to the data fields that map to the data fields in the external data source this application is monitoring. The RealTime Activity that uses this application also defines the field mapping.
9<9caccaccaccaccaccaccaccaccaccaccaccac101
kmkBAB
! !BABBABBABBAB! !! !
{}{{}{{}{{}{Z]Z
! !BABBABBABBAB! !
@ @@ @` @
@@ @@@@@`@@
`@ `@@`@``@
Example RealTime Activity
Shown below is an example of a RealTime Activity that uses the example application. The field mapping in the Mapping section of the document maps to the example application above.
Microsoft Word
System
Times New Roman
9<9caccaccaccaccaccaccaccaccaccaccaccac101
kmkBAB
! !BABBABBABBAB! !! !
{}{{}{{}{{}{Z]Z
! !BABBABBABBAB! !
@ @@ @` @
@@ @@@@@`@@
`@ `@@`@``@
HELVETICA
This section provides an example of a RealTime Activity that uses stored procedures with a Sybase or a SQL (through Sybase) external data source.
Note: DECS/Domino 5.02 and greater support stored procedure browsing.
In this example there are four stored procedures for the table
addrbook
in Sybase. When using these stored procedures, the key fields used must be FirstName then LastName and the mapped fields must be (MailDomain, MailServer, MailAddress, CompanyName, and State). The stored procedures, table name and fields must use the correct case since Sybase is case sensitive.
To use a stored procedure, enter the name of the stored procedure in the options section for the appropriate event in the RealTime Activity document. In this example, these would be:
Create: QE
Insert
addrbook
Open: QE
Select
addrbook
Update: QE
Update
addrbook
Delete: Qe
Delete
addrbook
Below is an example of a RealTime Activity document showing how these stored procedures are entered in the Stored Procedure fields of the corresponding document event options.
"""""+
ffffffj
"""""+
!!!!!
@ @@ @` @
@@ @@@@@`@@
`@ `@@`@``@
Testing the Stored Procedures in SQL
The examples below show how you would execute the stored procedures in SQL through the database client, in this case Sybase. You can test that the stored procedures work properly by executing them directly as shown below.
Below are the actual stored procedure definitions used in the preceding example. Note that these are Sybase procedures; stored procedures for other data sources may be different.
create procedure dbo.
QESelectaddrbook
@FirstName varchar(20),
@LastName varchar(20)
select FirstName,LastName,
MailDomain, MailServer, MailAddress,
CompanyName,State from addrbook
WHERE FirstName = @FirstName and
LastName = @LastName
create procedure dbo.
QEUpdateaddrbook
@FirstName varchar(20),
@LastName varchar(20),
@MailDomain varchar(20),
@MailServer varchar(20),
@MailAddress varchar(20),
@CompanyName varchar(20),
@State varchar(20)
UPDATE addrbook SET
MailDomain=@MailDomain, MailServer=@MailServer,
MailAddress=@MailAddress,
CompanyName=@CompanyName, State=@State
WHERE
FirstName=@FirstName and LastName=@LastName
create procedure dbo.
QEInsertaddrbook
@FirstName varchar(20),
@LastName varchar(20),
@MailDomain varchar(20),
@MailServer varchar(20),
@MailAddress varchar(20),
@CompanyName varchar(20),
@State varchar(20)
INSERT INTO addrbook
(FirstName,LastName,
MailDomain, MailServer,
MailAddress, CompanyName,State)
V+ALUES
(@FirstName, @LastName,
@MailDomain, @MailServer,
@MailAddress, @CompanyName, @State)
create procedure dbo.
QEDeleteaddrbook
@FirstName varchar(20),
@LastName varchar(20)
DELETE FROM addrbook
WHERE FirstName=@FirstName and LastName=@LastName
HELVETICA
Times New Roman
Symbol
This section provides information about using your Web client to invoke a RealTime Activity that accepts a key value input for querying an external data source. This extends the functionality of the RealTime Activity to provide a dynamic query capability.
Overview of Steps
NSFbuletcleanup
Bob Miller-
Create a Notes application form that defines the format of the data to be returned to end-users when the query is processed. (This is what is to be displayed to the user accessing the Domino server via a web client.) This form includes the fields that you want populated from the back end database. Also include one or more key fields, in which the user will enter values to be used to locate the correct external data. The appearance of the application form may be improved by using the Notes form design option of the "Hide paragraph when..." property box. In the example, the form is broken into three primary sections. The top of the form is always displayed. The input field, input help, and "Locate" button only display when the document is in edit mode. The data fields only display when the document is in read mode. In our example, the key field is "PackageID".
Next, include one hidden field in the form:
$$Return field - A computed for display only field of type "text" that specifies the URL for the new document returned once the query data has been input and "Locate" button has been selected.
Within the overall web application, create a URL link to the application form (for more information on specifying URLs to Notes databases and forms, see the Notes Application Developer's Guide). In our example, we provide an "About" page for the database that contains the URL link for the application form.
Define a DECS RealTime Activity that monitors the Notes database and the form defined in step 1 above. This form should include the key and data fields you define in step 1 above.
Access the Domino Lookup form from a Web browser. Type in a tracking number (PackageID field). When the Locate button is selected, the document is saved in the database and the $$Return text is passed to the Domino HTTP process. This results in the new document being re-opened. The RealTime Notes Connection is activated, taking the key value, from the PackageID field, submitted in the form. The PackageID value is then sent to the back end source, and the table records are searched according to the PackageID value. Results of the search are sent back through DECS and inserted into the document. The document is then send from the Domino server to the Web client as directed by the URL specified in the $$Return field.
What is visible in the form
Using the "Hide paragraph when..." properties, different sections of the form appear under different conditions. See the illustration below as you read the following bullets.
Section 1 is always displayed.
Section 2, including the input field, the button, and the help text, only appears when the document is in edit mode.
Section 3 is always hidden. The Domino server only references it.
Section 4 is error text. It is displayed when the document is in read mode and, referencing the "status" field, when no data has been inserted into the document from the RealTime Activity.
Section 5 contains the data inserted by DECS and only displays in read mode and, once again referencing the "status" field, when data exists.
"""/"/
""/""""/
"/""/"/
"/"""
/"/"""
"/"/"/"/"
/"/"""
""""//
_______
_______
@ @@ @` @
@@ @@@@@`@@
`@ `@@`@``@
Times New Roman
Symbol
&Arial
Refer to the illustration on the next page as you follow these steps.
It is assumed that there is a Notes view sorted on the RealTime key (or that there is a column formula if you use more than one key field). This key or formula value will be used in place of the
italicized text
in step 4. This example uses a single key field called
DocKey
NSFbuletcleanup
Bob Miller-
Edit your Notes form.
Identify the RealTime key(s) field.
Add a button to the Notes form.
Add the following formula to the button.
@Command([FileSave]);
@Command([FileOpenDatabase]; @DbName; "
DocKey
@Command([OpenDocument])
Note
Substitute your view name for the
"Keys
" text in the above formula. Substitute the RealTime key you are using for the
"DocKey"
text in the above formula (or formula text if you use more that one key). Note that the text you use in place of the
"DocKey"
text must match the key or column formula of the view. This button is used to reference the view represented by the "
" text in this example.
Optionally, you can use hide formulas to make the button and key field(s) display when composing a new document and all fields display when opening an existing document.
Save the form.
With RealTime running, compose a document. Clicking the button will save the document with the new key and re-open it, displaying the RealTime data. This has an added side effect of allowing the user to jump back to compose the form and change the key. Pressing the button locates a different document.
Fields provided for RealTime activities must be either key fields or data fields - a field cannot be used as both in a single RealTime activity (although one field can be used as a key in one activity, and data in another activity). Remove any field that is used as both a key field and a data field from at least one of those lists.
An internal error was encountered when attempting to access activity informawion. Record as much information as possible about the circumstances and contact Lotus technical support.
Failure encountered in monitoring process -- ERROR MESSAGE
Errors that are generated by the RealTime monitors in the Domino server are logged with this prefix. The complete error text from the RealTime error is appended.
Unexpected internal failure in RealTime monitoring
An internal error was encountered when attempting to access context information.'Record as much information as possible about the circumstances and contact Lotus technical support.
Update of key field [
+FIELDNAME
,] is not permitted
Key values in a document were altered, but the RealTime activity indicated that changes to key fields should be blocked. Updates to both Notes and the back-end system were aborted.
This record has changed in the back-end database since being opened - action cancelled
The RealTime activity option to check whe external system for changes before writing changes to the back end was enabled, and the check indicated changes in the back end. Since the document was opened, another system or client changed the corresponding external record.
NOTE:
This error can be erroneously generated in Domino 4.x systems when using the Notes client UI to save a document without closing it, and then saving it again. To avoid this problem on monitored documents with integrity checking enabled, close a documenw after saving changes and reopen it.
Cannot locate corresponding external record
The key values in the opened document being monitored by a RealTime activity did not correspond to a record in the external system. This error can be suppressed by selecting the RealTime activity option to create the external record if it doesn
,t exist - instead of the error, a new record corresponding to the current Notes document data will be created.
Failure compiling Filter Formula7 FORMULA COMPILATION ERROR
The filter formula provided for the RealTime activity failed compilation. The compilation error is generated with the error message. Fix or remove the filter formula to successfully run the RealTime activity.
Failure compiling Pre-Open Formula: FORMULA COMPILATION ERROR
The pre-open formula provided for the RealTime activity failed compilation. The compilation error is generated with the error message. Fix or remove the pre-open formula to'successfully run the RealTime activity.
Failure compiling Post-Update Formula: FORMULA COMPILATION ERROR
The post-update formula provided for the RealTime activity failed compilation. The compilation error is generated with the error message. Fix or remove the post-update formula to successfully run the RealTime activity.
Failure compiling Post-Create Formula: FORMULA COMPILATION ERROR
The post-create formula provided for the RealTime activity failed compglation. The compilation error is generated with the error message. Fix or remove the post-create formula to successfully run the RealTime activity.
Failure compiling Post-Delete Formula: FORMULA COMPILATION ERROR
The post-delete formula provided for the RealTime activity failed compilation. The compilation error is generated with the error message. Fix or remove the post-delete formula to successfully run the RealTime activity.
"Unknown OS error: libdecsext.*"
This is a Notes error reporting that Notes couldn't load the DECS extension manager library. Check that you have properly installed and configured DECS. If problems persist, contact technical support.
"DECS Server addin task initialization failed"
This indicates that the DECS addin task startup encountered an error. Check that you have properly installed and configured DECS. If problems persist, contact technical support.
"DECS Server is unable to allocawe addin task resources"
The DECS Server is unable to allocate additional resources. Check that you have properly installed and configured DECS. If problems persist, contact technical support.
"DECS Server cannot connect to external system"
You may not have the proper connectivity software installed that is required for accessing the external data system. Refer to the
Domino Connectors Setup Guide
for information about the native software requireg for connectivity to each of the DECS supported data sources.
"DECS Server cannot find external table/metadata"
The metadata selected for this activity does not exist in the back end data source.
"DECS Server cannot find external procedure/transaction"
The document open event captured by DECS encountered an error. The error details are logged to the Domino Server log.
"DECS Server error retrieving external record"
The docugent open event captured by DECS encountered an error. The error details are logged to the Domino Server log.
"DECS Server error inserting external record"
The document creation event captured by DECS encountered an error. The error details are logged to the Domino Server log.
"DECS Server error updating external record"
The document update event captured by DECS encountered an error. The error details are logged to the Domino Server log.
"DECS Server error deleting external record"
The document deletion event captured by DECS encountered an error. The error details are logged to the Domino Server log.
"DECS Server cannot locate the corresponding record in the external system"
The document key field values do not correspond to a record in the back end data source. The record in the external data system may have been deleted.
"DECS Server unable to update document due to key figld changes; changes to key fields have been disabled"
The key fields in the external data have been modified since the document has been opened. To allow key field changes, select the appropriate setting for the option
Key Field Updates
in the Document Update options section of the Activity document.
"DECS Server unable to update document due to conflict; the external record has been modified since being opened"
The external data has been modified gy another application since the document has been opened. Close and re-open the document.
"DECS Server data overflow accessing external record"
For document open events, this indicates that data in an external field was too long. Usually this is due to text longer than 64K. To avoid this problem, change the Notes field to Rich Text. (See the error in the Domino Server log for information on which field caused the overflow.)
For document updates and inserts, thgs message indicates that the document data overflowed a back end field. You may need to change the data type in the back end to store large amounts of data.
5Courier New
In DB2 the parameter types are interpolated from the Notes datatypes. For example, if the Notes key field is a number, the DB2 parameter type will be DOUBLE. So'the stored procedure should account for possible differing input types (or it should at least check the input type).
Model your stored procedure on the following example.
/* Stored procedure Example */
#include <memory.h>
#include <string.h>
#include <c:\sqllib\include\sql.h>
#include <c:\sqllib\include\sqlda.h>
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, MODIFIED, NUMBER1 FROM SIMPLE WHERE NUMBER1 = ?";
long int number1;
EXEC SQL END DECLARE SECTION;
if (inout_sqlda)
if ((inout_sqlda->sqlvar[0].sqltype == SQL_TYP_INTEGER) ||
Reconngct functionality was added to DECS in Domino Release 5.0.1. DECS reconnects a dropped connection only if the backend database is available. The reconnect functionality will try to connect even when the database is down, however if the database is down this results in a 'Server not available' error. The server not available error places the DECS activity in the error state and stops the activity.
If this happens, you must mannually restart the activity.
The reconnect functionality was added to handle a customer environment where users are dropped from a backend database if their connection remains idle for a specific amount of time, for example 5 minutes. This idle connection time out limitation is generally set by Database Administrators so that their network will not be taxed with idle traffic and for security reasons.
5OC,~
Times New Roman
Logging information is available in DECS.
v*I\U
Logged information about DECS operations is available to you when you click the Log button in the navigatow. The log lists the time and date when a RealTime Activity started and ran, and information about any errors that occurred during processing of the RealTime Activity.
HELVETICA
Scheduling
This section of the document lets you welect how RealTime scheduling will operate.
Option
"g=>8U
Description
Scheduling Option
"g=>8U
Manual
-- Select this option to manually control the activity using the Start/Stop navigator buttons.
Auto Start
-- Select this option to automatically establish this RealTime activity each time the server starts. The activity continues until the server is shut down. The activity's running state can be overridden using the Start/Stop navigator buttons.
Custom
-- When you select this option, the "Run Time" and "Run on Days" fielgs are automatically displayed (these are hidden for Manual and Auto Start), in addition, the activity starts at the beginning of the specified run time and stop at the end of the specified run time. This option can further be controlled by selecting the days on which the activity should run. The activity's running state can be overridden using the Start/Stop navigator buttons.
Warning
: If the activity is started with the navigator's start button, the custom schedule is overridden completegy, meaning, it will not stop at the end of the specified run time.
h=
Times New Roman
5Courier New
&Arial
If you are using DECS/Domino 4.x on a Sogaris platform,
remove the setuid bit from the Domino Server executable. Additionally, to ensure proper performance of the Domino Server, the system configuration file /etc/system needs to be updated to allow a larger than default amount of file descriptors per process. Please follow the steps below as the root user only after verifying that you have installed all the required Solaris OS patches as described in the Domino Release Notes:
Method A: Using an ediwor such as vi, edit /etc/system and add the following line:
rlim_fd_max=8192
Method B: execute the following command that will update the file:
echo set
rlim_fd_max=8192 >> /etc/system
Reboot the system for the configuration change to take effect.
Note
Failure to remove the setuid bit will result in the Domino Server sending out whe following message when using DECS:
"Addin: Agent error message: Error loading USE or USELSX module: *lsxlc" responsible for your failure to do so.
In no event will Lotus or Binary Tree be liable for indirect, special, incidental, tort, economic, cover or consequential damages arising out of the use of or inability to use Lotus or Binary Tree products or services, including, without limitation, damages or costs'relating to the loss of profits, business, goodwill, data or computer programs, even if advised of the possibility of such damages. In no case shall Lotus' or Binary Tree
,s liability for money damages exceed the amount paid by you for the Software out of which such claim arose. The foregoing limitations shall not apply to claims relating to death or personal injury which arise out of products deemed to be consumer goods under applicable law.
Some states or provinces do not allow the exclusion gr limitation of implied warranties or limitation of liability for incidental or consequential damages, so the above exclusion or limitation may not apply to you.
6. U.S. GOVERNMENT RESTRICTED RIGHTS
If the Software is acquired by the U.S. Government or on its behalf, the Software is furnished with "RESTRICTED RIGHTS," as defined in Federal Acquisition Regulation ("FAR") 52.227-19(c)(2), or DFAR 252.227-7013(c)(1), as applicable. Use, duplication or diwclosure of the Software by the U.S. Government and parties acting on its behalf is governed by, and subject to the restrictions set forth in FAR 52.227-19(c)(1) and (2), or DFAR 252.227-7013(c)(1), as applicable. The Contractor/manufacturer of the Software is Binary Tree Software, Inc., 11 Hanover Square, 19th Floor, New York, NY 10005. In the event the Government seeks to obtain the Software pursuant to standard commercial practice, this software agreement, instead of the noted regulatory clauses, shall gontrol the terms of the Government's license.
7. GENERAL
You agree to comply fully with all applicable export laws and regulations of the United States. Without limiting the generality of the preceding sentence, Licensee shall not export the Software, directly or indirectly, in violation of such export laws and regulations or use the Software for any purposes prohibited by such laws and regulations. This Agreement shall be governed by and construed in accordance wgth the laws of the Commonwealth of Massachusetts without regard to choice of law principles. The original of this Agreement is written in English. You hereby waive any claim or right to have this Agreement translated into any language other than English. Furthermore, you hereby waive any claim or right to have this Agreement interpreted under any local law, ordinance, directive, or act, other than under the laws of the Commonwealth of Massachusetts.
IF YOU DO NOT AGREE WITH THE ABOVE TERMS AND CONDITIONS, DO NOT DOWNLOAD OR INSTALL THE SOFTWARE.
O=Lotus Notes
O=Lotus Notes
PURSAFO
|.:#U
O=Lotus Notes
CN=Lotus Notes Template Development/O=Lotus Notes
PURSAFO
r%K[D
2F yH,d
$Info
$Body
Before sending out any migration messages, the settings document must be completed.
Click on the settings icon
button on the navigator. This will bring you into the settings view.
Click on the Edit Settings icon
?_?__
`!b`1
7`^///?
?b___
`bOOO
`<b!R
$ = "" And DotSt
(RootDir$ & SubD
tStar$ = "Y"
ddNewLine(1)
to modify the settings document. All options in the settings document are
explained below.
Migration Message
Subjecw
- Text that will appear in the subject field when the migration message is sent.
Body
- Text that will appear in the body field of the migration message.
You can use those fields if you want to send migration instructions specific for your users/your company.
Netscape Settings
Default path to user's mail directory -
specify the default path that will appear in migration program.
The actual path can ge found in Netscape Mail and News preferences. Messages must be stored on the
local hard drive, or server drive accessible via mapping. The current version of Netscape - 2 - Notes DOES NOT
support IMAP protocol to retrieve messages from the server.
Path to export messages to
- Specify the default path for Netscape messages to be exported to. The user can
change the path after starting the export .
Import Process
Delete Files During Processin
g -
The export process creates ASCII text files and attachments for each message to be migrated. Selecting this option will delete this files when they are imported into Lotus Notes. THIS OPTION DOES NOT DELETE THE NETSCAPE MESSAGES.
Import Mail Messages Into
Users Mail Box -
Messages will be imported directly into the users mail database
Copy of Mail Database -
A local dewign copy of the mail database will be created and the messages will be imported into the design copy.
Let User Choose -
The user will be prompted
Determine by Size -
You can specify a size limit for the Notes mail file. The size is exceeded then a design copy of the mail database will be crated and the messages will be imported into the design copy.
and
Settings
Specify how attachments will be migrated -
attachments can be appended one after another or with a carriage return between them.
Folders
The default folders in Lotus
Notes and
Netscape
hav
e th
e same names. To create a distinction of these folders after messages have been imported, specify how you would like the
Netscape
folders called in Lotus Notes.
Statistics
Specify how you would like statistics to be written
For each user a statistics document can be written into the statistics section of the NS2NOTES nsf.
Write statistics to this db
- If the NS2NOTES nsf is on a server that all users will have access to
Mail statistics documents to this db
- A mail in database documents needs to be created for NS2NOTES (RECOMMENDED)
(.txt)