About Lotus Domino Enterprise Connection Services Online Manual
$$U$$
$IU$I
@ @@ @` @
@@ @@@@@`@@
`@ `@@`@``@
copyright
Lotus Domino Enterprise Connection Service
Online Manual
Lotus Development Corporation, an IBM subsidiary
Copyright
Under the copyright laws, neither the documentation nor the software may be copied, photocopied, reproduced, traoslated, or reduced to any electronic medium or machine-readable form, in whole or part, without the prior written consent of Lotus Development Corporation.
Copyright 1998 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, and 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 trademarks, and Oracle7 and PL/SQL are trademarks of Oracle Co
poration.
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 is a registered trademark of UNIX Systems Laboratories, Ioc.
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 Equipment Corporation.
Apple ano 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 Corporation.
O=Lotus Notes
O=Lotus Notes
PURSAFO
|.:#U
O=Lotus Notes
CN=Lotus Notes Template Development/O=Lotus Notes
PURSAFO
q)8)-
$Info
$Body
Using Lotus DECS Online Manual
@ @@ @` @
@@ @@@@@`@@
`@ `@@`@``@
copyright
Lotus Domino Enterprise Connection Services
Online Manual
This database is the online documentation for Lotus DECS.
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 database...
1) In a view, highlight the item you want to add a comment to.
2) Pull down the Compose menu.
3) Choose the "Comment" form.
O=Lotus Notes
O=Lotus Notes
PURSAFO
|.:#U
O=Lotus Notes
CN=Lotus Notes Template Development/O=Lotus Notes
PURSAFO
lB^ybL
$Info
$Body
O=Lotus Notes
O=Lotus Notes
PURSAFO
|.:#U
O=Lotus Notes
CN=Lotus Notes Template Development/O=Lotus Note
PURSAFO
$TITLE
$Index
$Formula
$FormulaClass
$ViewFormat
$Comment
Section
Chapter
Section
1S3S4S6S8S
&Arial
Times New Roman
DECSSection
TopicType
Glossary
0S0E
SubjectAssign a topic name to this document.
Section
1S2S
Contents
ChapterNumber
DocumentNumber
O=Lotus Notes
O=Lotus Notes
PURSAFO
|.:#U
O=Lotus Notes
CN=Lotus Notes Template Development/O=Lotus Notes
PURSAFO
$TITLE
$Info
$WindowTitle
$$Script_O
$$ScriptName
ChapterNumber
DocumentNumber
$Body
Symbol
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:
EDA/SQL
File System
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 (LOCON.NSF)
for information about the connectivity requirements for each of the supported data sources. t
"Helvetica
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
uggestions and recommendations.
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
Contacting 3rd Party Support
In some cases, you may need to contact 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.
Symbol
The following coomands 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 solection clause. For SQL based systems, the conditional clause would be the portion of a WHERE clause following the WHERE. For example, if the complete statement were: SELECT * from Table WHERE Number > 1, you would only enter Number > 1 as the key initialization condition.
Symbol
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 wozard. When you click on 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
8 later in this chapter.
Creating a RealTime Activity without the Wizard
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 io the blank RealTime Activity document. See the section
&How to Create a RealTime Activity
8 later in this chapter.
Usage Requirements
The following usage requirements are necessary for proper RealTime Activity operation:
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, the specified datatypes 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 os 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 datatypes 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.
Helvetica
Times
LotusFrute
Symbol
Times New Roman
Information about DECS operations is logged to the Domino Server log in the Miscellaneous section of/the log. It provides 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
Times
LotusFrute
Symbol
Times New Roman
The Note
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 RealTime 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. p
Helvetica
Times
LotusFrute
Symbol
Times New Roman
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
8 to
&publish.
How to Configure:
In this case, you would set up a RealTime Activity tha
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 database, where it would be available to other applications. Any documents that are still
&under review
8 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, but potentially the North East sales information is in a different table 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?
Perhaps you have two product catalogs in different databases but you want to present the data through the same front end Notes 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
Times New Roman
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 want to use when building views must reside in the Notes document. Use the option
Leave Selected RealTime Fields in Document
. Select the fields that you want to reference in a view from those fields available when this option is selected.
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 Documen
. Note that if the back end data changes, the data in the document is not updated until the document is reopened.
llByteIsData
causes a problem
SPR# YUMA3GVTPR -
UTF-8
LMBCS translation doesn't work properly
SPR# BRT3AGJZ4 -
Romanian Sort order is incorrect
SPR# PHAN3LMEQW -
eUpper and LowerCase @functions not working for Baltic characters
SPR# PHAN3SEMBU -
Incorroct sorting for Lithuanian R4.61
SPR# PHAN3SPD5A -
Lowercase/uppercase sorting should be the other way around for Latvian
SPR# PHAN3SVDS2 -
Greek collation isn't correct
SPR# PHAN3SXM5N -
Icelandic is not sorting correctly
SPR# PHAN3WLELS -
Notes doesn't launch when some collation settings are used
SPR# PHAN3WLEZS -
A number of languages fail to collate correctly in R5.0 Beta Preview
SPR# SLII3UXR9 -
Duplicate language/country pairs have found within same table type
Once new object types are created, you can search on these object types using LDAP. Certain valid searches, however, are not working correctly in this build but will be fixed. All LDAP searches must specify the ObjectClass and at least the first choracter of the name you're searching on.
The examples below reflect searches for an ObjectClass of Printer and a commonname (CN) of HP4000.
Example of searches that will work
(&(objectclass=Printer)(cn=HP4000*))
(&(objectclass=Printer)(cn=HP4000))
(&(objectclass=Printer)(cn=HP**))
Example of searches that will fail
(&(objectclass=Printer)(cn=*))
(&(objectclass=*)(cn=HP4000)/
(&(objectclass=*)(cn=HP4000*))
When replacing a V4 document library design with either the
Doc Library - Notes & Web (R4.6)
Doc Library - Notes & Web (R5.0)
template, run the "Document Library 4.0 Redesign Fix" agent against the database before opening the converted documents. The agent appears on the Action menu of the R4.6 and R5.0 Doc Library templates. If the agent has not been run, the error message "Incorrect datatype for operator or @function" appears when attempting to open the converted documents. Also, statuses will not appear correctly in the views unless the agent has been run.
3^:HN
Helvetica
Times
LotusFrute
Symbol
Times New Roman
The DECS Administrator is shown below. The navigator, views and menu commands in the Administrator are described in the sections that follow.
UUS35UU
wwwwwww
3333333P
wwwwwww|
S33333335P
wwwwwwwww|
S3333333335
wwwwwwwwwww
33333333333P
wwwwwwwwwww|
S333333333335
wwwwwwwwwwwww
3333333333333P
wwwwwwwwwwwww
3333333333333P
wwwwwwwwwwwww|
S33333333333335
wwwwwwwwwwwwwww
333333333333333P
wwwwwwwwwwwwwww
3333333333?3333P
wwwwwwwwwwwwwww
3333333333?3333P
33?3?3
?3??3?33P
S3333?3
?3??3?335
S3333?3
?3??3?335
?3??3?335
S33?333
wwwww
33?333
33333333P
wwwww
33?3?3
33333333P
wwwwwwwwww
3333333333P
wwwwwwwwwwwwwww
333333333333333P
wwwwwwwwwwwwwww
333333333333333P
wwwwwwwwwwwww|
S33333333333335
wwwwwwwwwwwww
3333333333333P
wwwwwwwwwwwww
3333333333333P
wwwwwwwwwww|
S333333333335
wwwwwwwwwww
33333333333P
wwwwwwwww|
S3333333335
wwwwwww|
S33333335P
wwwwwww
3333333P
UUS35UU
wwwwww
UUUU_
wwww{wwwww
/wwwww{wwwww
wwwww
UUUU_
""""!
""""!
wwww{
wwwww{
UUUU_
wwww{
wwwww{
UUUU_
wwwwwwwwwwwwwwwwww
wwwwwwwwwwwwwwwwww
wwwwwwwwwwwwwwwwww
wwwwwwwwwwwwwwwwww
wwwwwwwwwwwwwwwwww
wwwwwwwwwwwwwwwwww
wwwwwwwwwwwwwwwwww
wwwwwwwwwwwwwwwwww
wwwwwpwwwwww
wwwww
wwwwww
wwwwp
wwwww
wwwwwp
wwwww
wwwwp
UUUU_
wwww{wwwww
/wwwww{wwwww
wwwww
UUUU_
wwwwww
wwwwww
wwwwp
wwwwwww
wwwwww
wwwwwwww
wwwwwwwwwwwwwwwwww
wwwwwwwwwwwwwwwwww
wwwwwwwwwwwwwwwwww
wwwwwwwwwwwwwwwwww
wwwwwwwwwwwwwwwwww
UUUUUUU
"""""+
3333333
ffffffj
"""""+
3[SS3
3[SS3
UUUUUUUU
!!!!!
33333333
Notes Clients
es ClientsP
iguration and Tr
Troubleshooting
NOTES.INI Variab
oting
"Helvetica
The table below gives a description of the commands available in the DECS navigator.
Selects a view of available Connections or a view of RealTime Activities.
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.
ZYZ{y{
ZYZZYZ
ZYZBEB
kecBEB
ZYZBEB
{y{kec
BEBZYZZYZ
141)$!141
141BEBkec
)$!kec
{y{{y{
{y{)$!
{y{)$!
kec{y{{y{{y{
{y{)$!
ec{y{
{y{{y{
{y{{y{Z
kec{y{
141BEB
kec)$!
)$!{y{
BEBZYZ
BEB)$!kecZYZZYZBEB
)$!{y{
{y{141
)$!{y{
{y{{y{
BEB{y{
)$!kec
)$!{y{
kec)$!141
kec{y{
141kec
{y{141BEB
kec141
cZYZ{y{ZYZ1
ZYZZYZ
{y{ZYZ{y{{y{
ZYZ141kec
{y{ZYZc
BEB)$!kec
{y{ZYZ
ZYZkec
ZYZ141
keckec1
BEBZYZ)$!
ZYZ{y{141)$!
{y{kecBEBBEB
keckecBEB
BEB{y{BEBBEB
)$!BEBBEB
BEB)$!
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.
z)PHN
Helvetica
Times
LotusFrute
Symbol
Times New Roman
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. When applicable, the user name required for login to the data source is shown in parentheses.
wwwwww
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
gn Paragraph Cen
$FormulaClass
"Helvetica
Shown below is an example of the RealTime Activities view.
UUS35UU
wwwwwww
3333333P
wwwwwww|
S33333335P
wwwwwwwww|
S3333333335
wwwwwwwwwww
33333333333P
wwwwwwwwwww|
S333333333335
wwwwwwwwwwwww
3333333333333P
wwwwwwwwwwwww
3333333333333P
wwwwwwwwwwwww|
S33333333333335
wwwwwwwwwwwwwww
333333333333333P
wwwwwwwwwwwwwww
3333333333?3333P
wwwwwwwwwwwwwww
3333333333?3333P
33?3?3
?3??3?33P
S3333?3
?3??3?335
S3333?3
?3??3?335
?3??3?335
S33?333
wwwww
33?333
33333333P
wwwww
33?3?3
33333333P
wwwwwwwwww
3333333333P
wwwwwwwwwwwwwww
333333333333333P
wwwwwwwwwwwwwww
333333333333333P
wwwwwwwwwwwww|
S33333333333335
wwwwwwwwwwwww
3333333333333P
wwwwwwwwwwwww
3333333333333P
wwwwwwwwwww|
S333333333335
wwwwwwwwwww
33333333333P
wwwwwwwww|
S3333333335
wwwwwww|
S33333335P
wwwwwww
3333333P
UUS35UU
wwwwww
UUUU_
wwww{wwwww
/wwwww{wwwww
wwwww
UUUU_
""""!
""""!
wwww{
wwwww{
UUUU_
wwww{
wwwww{
UUUU_
wwwwwwwwwwwwwwwwww
wwwwwwwwwwwwwwwwww
wwwwwwwwwwwwwwwwww
wwwwwwwwwwwwwwwwww
wwwwwwwwwwwwwwwwww
wwwwwwwwwwwwwwwwww
wwwwwwwwwwwwwwwwww
wwwwwwwwwwwwwwwwww
wwwwwpwwwwww
wwwww
wwwwww
wwwwp
wwwww
wwwwwp
wwwww
wwwwp
UUUU_
wwww{wwwww
/wwwww{wwwww
wwwww
UUUU_
wwwwww
wwwwww
wwwwp
wwwwwww
wwwwww
wwwwwwww
wwwwwwwwwwwwwwwwww
wwwwwwwwwwwwwwwwww
wwwwwwwwwwwwwwwwww
wwwwwwwwwwwwwwwwww
wwwwwwwwwwwwwwwwww
UUUUUUU
"""""+
3333333
ffffffj
"""""+
3[SS3
3[SS3
UUUUUUUU
!!!!!
33333333
ows the type of
se and table nam
Status
|&`&`&
The table below describes the information shown in the Activities view of the DECS administrator.
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.
Defining Lotus Connections Using the WizardDefining Lotus ConnectionsDECSSectionDomino Enterprise Connection ServicesDefining Connections
How to Create a RealTime Activity Using the WizardCreating RealTime ActivitiesDECSSectionDomino Enterprise Connection ServicesHow to Create RealTime Activities Using the Wiza{d
Building the Notes Application for a RealTime ActivityBuilding the Notes ApplicationDECSSectionDomino Enterprise Connection ServicesBuilding the Notes Application
You use the Lotus Connection document wizard to define connections to external data sources.
Click on the Create Connection icon -
ynamic Queries f
. A list of supported data sources appears, as shown below.
Clients
hooting
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.
_____
_____
"""""+
ffffffj
"""""+
!!!!!
Enter the required information in the Lotus Connection document. The table below describes the fields in the Lotus Connection document.
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.
- Password Encryption Key
Click on 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 or views. Select the desired option.
Table Selection
Use this section of the document to select the specific metadata that you want to access through this Connection.
The Override button is provided for situations in which DECS is unable to browse all of the metadata due to size limitations. You can use the Override button to select an owner and data source that do not appear in the Name list of data sources.. See the section below,
&Using the Override Button,
8 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 on 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 on 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 Override Button
You use the Override button to specify an owner and a data source that are 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.
"""""+
ffffffj
"""""+
!!!!!
tw^l&
Helvetica
Times
LotusFrute
Symbol
Times New Roman
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
8 later in this chapter.
Step 1
) Click on the New RealTime Activity Icon
ZYZ{y{
ZYZZYZ
ZYZBEB
kecBEB
ZYZBEB
{y{kec
BEBZYZZYZ
141)()141
141BEBkec
{y{BEB
{y{{y{
{y{)()
kec{y{{y{{y{
{y{)()
{y{{y{
{y{{y{Z
kec{y{
141BEB
kec)()
)(){y{
BEBZYZ
BEB)()kecZYZZYZBEB
)(){y{{y{
{y{141
)(){y{
{y{{y{
BEB{y{
)()kec
)(){y{
kec)()141
kec{y{
141kec
{y{141BEB
kec141
RZYZkecZYZ
ZYZZYZ
{y{ZYZkec{y{
ZYZ141kec
{y{ZYZZ
ackec
{y{ZYZ{y{
keckec1
BEBZYZ)()
UR141
- Click on the RealTime Activity icon to start creating a RealTime Activity.
NOTE:
Any choices made while using the wizard can be changed later by opening the RealTime Activity in edit mode.
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.
Step 2
) Select the Domino Database to be Monitored
A list of Domino databases appears, as shown below. Select the Domino database that contains the Notes form you want to monitor.
U,^*"
ynamic Queries f
oting
Configurat
NOTES.INI V
eshooting
after DECS
Using
uration and Trou
ECS with Notes C
nfiguration and
or Messages
Step 3
) Select the Notes Form to be Monitored
A list of Notes forms within the selected database appears. Select a single Notes form that you want to monitor from the list shown. You can use the Option
Override form
to monitor all forms within a database. See the section on "RealTime Activity Options" later in this chapter.
U,^*"
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.
U,^*"
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.
Step 6
) Select the Document Events to Monitor
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 monitor.
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
&RealTime Activity Options
8 for more information.
Helvetica
Times
LotusFrute
Symbol
Times New Roman
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 on the New RealTime Activity icon
Click on the RealTime Activity icon -
ZYZ{y{
ZYZZYZ
ZYZBEB
kecBEB
ZYZBEB
{y{kec
BEBZYZZYZ
141)()141
141BEBkec
{y{BEB
{y{{y{
{y{)()
kec{y{{y{{y{
{y{)()
{y{{y{
{y{{y{Z
kec{y{
141BEB
kec)()
)(){y{
BEBZYZ
BEB)()kecZYZZYZBEB
)(){y{{y{
{y{141
)(){y{
{y{{y{
BEB{y{
)()kec
)(){y{
kec)()141
kec{y{
141kec
{y{141BEB
kec141
RZYZkecZYZ
ZYZZYZ
{y{ZYZkec{y{
ZYZ141kec
{y{ZYZZ
ackec
{y{ZYZ{y{
keckec1
BEBZYZ)()
UR141
. The RealTime Activity document appears, as shown below.
Enter a unique name for the Activity in the Name field at the top of the document.
Step 3
) Select the Notes Application
Click on 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.
Step 4
) Select the External Data Source
Click on 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 on 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 on 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
8 later in this chapter for more information.
Step 8
) Save and Close the Document
Select File?Save to save this RealTime Activity definition. Select File?Close to close the RealTime Activity document and return to the RealTime Activity administrator.
Step 9
) 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.
Click on 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.
Symbol
"Helvetica
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.
neral Options
etection.
Stored
external data s
the document. Th
the stored proc
stored procedur
both the key(s)
l Options
passed to the st
procedure name i
The fields that
ocedure are disp
re name.
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.
~~~~~~~~~~
~~~~~
yyyyy
$$$$$$$$$$$$$
y$yyyy
$$$$$$
$$$$$$
yyy$yy
yyyyyyyy
~~~~~~~~~~~~~~~
$$$$$$$$
$$$$$$$$
~~~~~~~~~~~~~~~
Option
Description
Monitor Order
If you use more than one RealTime Activity for a single Notes form, you may specify the order in which the RealTime Activities will intercept the document's events.
The monitor order also enables you to use multiple RealTime Activities which 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 which may not contain all field 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 the Data Storage option
Leave All RealTime Fields in Document
. For the last RealTime Activity, indicate to leave specific fields in the document, and list all key fields from the 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, depending 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. We recommend 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.
Prevent data loss
Enable this option to have DECS write an error to the log for any data that's 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.
Data Integrity
Allow precision loss & truncation of text
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.
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.
Trim Trailing Spaces
NOTES:
The 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.
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 backend 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.
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.
Data Storage
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. The Static Data button that appears when you enable this option lists the Notes data fields from which you can select. Not selecting any fields is equivalent to enabling the
Remove All RealTime Fields from Documents
option.
to Log
Logs errors to the Notes Server Log database and to the Activity Log, accessible through the Log button on the Connection Server navigator.
Error Logging
to Document
Logs errors to Notes document fields. This enables you to take actions based on specific errors or present errors from the external database back to the user. These fields must be be included in your Notes form in order for the errors to be displayed.
NOTE:
We recommend that you not use the
Allow precision loss & truncation of text
option when storing Rich Text Field BLOB datatypes 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.
Document Creation Options
When monitoring Document Creation 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);""
Stored 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.
Document Open Options
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);""
: 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.
Missing External Records
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.
Conflict Detection
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.
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.
Helvetica
Times
LotusFrute
Symbol
Times New Roman
Shown below is a Notes application that monitors employee information in an external data source.
UUUUUUU
"""""+
3333333
ffffffj
"""""+
3[SS3
3[SS3
UUUUUUUU
!!!!!
33333333
UUUUUP+
hat uses the exa
ping in the Mapp
to the example
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.
|C+IB&{)
"""""+
ffffffj
"""""+
!!!!!
Activit
Activit
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.
|C<KB&
3_SS3
3_SS3
UUUUUUU
"""""+
3333333
ffffffj
"""""+
3[SS3
3[SS3
UUUUUUUU
!!!!!
33333333
UUUUUP+
Helvetica
Times
LotusFrute
Symbol
Times New Roman
Scenario:
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 yopulate 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 2)
EmpID
EmployeeID
EmpName
EmployeeName
DepartmentNo (may be hidden)
Department
DeptNo
DeptNo
DeptName
DepartmentLoc (may be hidden)
Location
DeptLoc
LocCode
LocName
Hoy to Configure:
To do this join, you will create three RealTime Activities 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 which 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 yables. These fields may be "hidden" from the user. If updates will be made through the Notes application to these secondary tables, select the Option "Leave selected realtime fields in document" and list all the fields which are used as keys to the backend (DeptmentNo, DepartmentLoc).
Create a connection document for each of the external data sources: one for the employee table, one for the department table, aid one for the location table.
2. 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, and DepartmentNo.
Notes
Employee Table
EmpID as the key
EmployeeID as the key
DepartmentNo
DeptNo
3. Create a second RealTime Activity based on the Employee Information Form and the Department Table. Select the following fields:
Notes
22mRU
Department Table
DepartmentNo as the key
22mRU
Deptno as the key
Department
22mRU
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 lioking into the department table for the DeptName field.
4. 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 is dependent on information provided by the second Activity.
Notes
Location Table
DepartmentLoc as the key
LocCode as the key
Location
LocName
Helvetica
Times
LotusFrute
Symbol
Times New Roman
The DECS RealTime Activity enables a Domino database form to provide direct access to back end data sources suppirted 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 as well as the back end data source. In this configuration, the Notes or web client would oyen 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 document. RealTime Activity detects the open event and uses the tracking number to query the source database, which locatis 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
Helvetica
Times
LotusFrute
Symbol
Times New Roman
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. Nite 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 (ani 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 backend systems always consider client data to be in the native character set. Setting this valye 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 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
Helvetica
Times
LotusFrute
Symbol
Times New Roman
If you install Lotus NotesPump 2.5a 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:
EXTMGR_ADDINS =
To read as follows:
EXTMGR_ADDINS = decsext.dll, lnpext.dll
This setting allows both the DECS RealTime Activities and the NotesPump Activities to function properly from the same Domino server.
Helvetica
Times
LotusFrute
Symbol
Times New Roman
This section provides a list of error messages that you might receive while using DECS.
Cannot use field [
+FIELDNAME
,] as both a key and a data field
Fields provided for YealTime 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 provided 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 information. Record as much information as possible aboyt the circumstances and contact Lotus technical support.
Failure encountered in monitoring process -- ERROR MESSAGE
Errors which 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 thi 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 backend system were aborted.
This record has changed in the backend database since being opened - action cancelled
The realtime activity option to check the external system for changes before writing cianges to the backend was enabled, and the check indicated changes in the backend. 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 enabied, close a document 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 Formula: 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 ictivity failed compilation. 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 allocate 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 natiye software required 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 document 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 Sirver 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 doiument due to key field 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 dati has been modified by 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 updites and inserts, this 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.
Helvetica
Times
LotusFrute
Symbol
Times New Roman
If Nites clients older than Release 4.62 will be accessing 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 versiony of error messages to
clients. This setting is not necessary for installations where all clients are Release 4.62 clients.
&Arial
To use DECS, Solaris users must remove the setuid bit from the Domino Server executable. Additionally, to ensure proper performance of the Domino Server, the system confiiuration 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 editor such as vi, edit /etc/system and add the following line:
set
rlim_fd_max=9192
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.
Failure to remove the setuid bit will result in the Domino Server emitting the following message when using DECS:
"Addin: Agent error message: Error loading USE or USELSX modyle: *lsxlc"
Helvetica
Times
LotusFrute
Symbol
Times New Roman
Domino Enterprise Connection Services enable you to create RealTime Activities. A RealTime Activity provides synchronous access from a Domino application to a supported exyernal data source.
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 Connection 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, backend data directly and transparently through their familiar Notes Client. By extension, web 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, 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 connectivity 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 yoftware 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, several 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 Foym 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 indicates 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 dayabase or even a single form. This means a single document can be populated real-time, consisting of data from multiple backend databases using a RealTime Activity for each of the various backend data sources.
Using Stored ProceduresExamples using RealTime Activity OptionsDECSSectionDomino Enterprise Connection ServicesUsing Stored Proced{res
RealTime Dynamic Queries from Web ClientsRealTime Dynamic QueriesDECSSectionDomino Enterprkse Connection ServicesRealTime Dynamic Queries from Web Clients
Installing NotesPump 2.5a after DECSConfiguration and TroukleshootingDECSSectionDomino Enterprise Connection ServicesInstalling NotesPump 2.5a after DECS
Using DECS with Notes Clients Older than Release 4.62Configuration and TroubleshootingDECSSectionDomino Enterprise Connection ServicesUsing DECS with Notes Clients Olker than Release 4.62
CN=Dave Wilson/O=IrisCN=Craig Lordan/OU=CAM/O=LotusCN=Lee Zaruba/OU=CAM/O=LotusAdministration Process or Stats Task shuts down on Server Startup
Server03 Troubleshooting03 Server Issues01 All Platforms
Release Notes03 Troubleshooting
DWIN3XXSCK
TroubleshootingHelp Screen
CN=Beth A Keach/O=IrisCN=Craig Lordan/OU=CAM/O=LotusCN=Lee Zaruba/OU=CAM/O=LotusAnonymous LDAP access in secondary remote books is not working properly
Server03 Troubleshooting03 Server Iss{es01 All Platforms
This section provides an example of a RealTime Activity that uses stored procedures with a Sybase external data source.
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.
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.
QECreateaddrbook
@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)
VALUES
(@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
LotusFrute
Symbol
Times New Roman
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
1. 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". Also, 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.
2. 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.
3. 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.
4. 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.
Using the "Hide paragraph when..." properties, different sections of the form appear under different conditions.
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.
"""/"/
""/""""/
"/""/"/
"/"""
/"/"""
"/"/"/"/"
/"/"""
""""//
_______
_______
uration and Trou
ion and Trou
and Trou
nfigurat
ion and Trou
ion and Trou
ion and Trou
ion and Trou
ion and Trou
ion and Trou
ion and Trou
ion and Trou
ion and Trou
ion and Trou
ion and Trou
ion and Trou
ion and Trou
Q6^gJN
Symbol
Edit your Notes database.
If one does not exist, add a view sorted on the RealTime key or 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
. The example uses a single key field called
DocKey
The view is referenced by the button below in place of the
bold text.
The example uses a sorted view called
Edit your Notes form.
Identify the RealTime key(s) field.
Add a button to the Notes form.
Add the following formula to the button, substituting the above view name for the red text, and the RealTime key (or formula text if using more that one key) for the blue text. Note that the blue text must match the key or column formula of the view.
@Command([FileSave]);
@Command([FileOpenDatabase]; @DbName; "
DocKey
@Command([OpenDocument])
Optionally 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 loaded 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.
(.txt)