decs installation and user guide - lotus softwarefile/decsdoc6.pdf · 2 decs installation and user...

COPYRIGHT

Under the copyright laws, neither the documentation nor the software may be copied, photocopied,reproduced, translated, or reduced to any electronic medium or machine-readable form, in whole or inpart, without the prior written consent of IBM Corporation, except in the manner described in thedocumentation or the applicable licensing agreement governing the use of the software.

©Copyright 1985 - 2002 Lotus Development Corporation

©Copyright 2002 IBM CorporationLotus Software, IBM Software GroupOne Rogers StreetCambridge, MA 02142

All Rights Reserved.

List of Trademarks

Domino, cc:Mail, Notes, NotesBench, Domino Connectors, Domino Enterprise Connection Services,IBM Lotus Enterprise Integrator for Domino (LEI), and Notes/FX are trademarks; and Freelance,Freelance Graphics, Lotus, Lotus Notes, LotusScript, Notes Mail, NotesSQL, NotesView, 1-2-3, Organizer, SmartIcons, and SmartSuite are registered trademarks of Lotus Development Corporationand/or IBM Corporation in the United States, other countries, or both. OS/2 Warp and PowerPC aretrademarks and IBM, AIX, DB2, OS390, iSeries, zSeries, and pSeries, OS/2 Presentation Manager, andSNA are registered trademarks, and DB2/2, DB2/400, and RS/6000 are trademarks of InternationalBusiness Machines Corporation. Tivoli/Courier is a trademark of Tivoli Systems and/or IBMCorporation in the United States, other countries, or both.

All other trademarks are the property of their respective owners.

Disclaimer

THIS DOCUMENTATION IS PROVIDED FOR REFERENCE PURPOSES ONLY. WHILE EFFORTSWERE MADE TO VERIFY THE COMPLETENESS AND ACCURACY OF THE INFORMATIONCONTAINED IN THIS DOCUMENTATION, THIS DOCUMENTATION IS PROVIDED “AS IS”WITHOUT ANY WARRANTY WHATSOEVER AND TO THE MAXIMUM EXTENT PERMITTED,LOTUS DISCLAIMS ALL IMPLIED WARRANTIES, INCLUDING WITHOUT LIMITATION THEIMPLIED WARRANTIES OF MERCHANTABILITY, NONINFRINGEMENT AND FITNESS FOR APARTICULAR PURPOSE, WITH RESPECT TO THE SAME. LOTUS SHALL NOT BE RESPONSIBLEFOR ANY DAMAGES, INCLUDING WITHOUT LIMITATION, DIRECT, INDIRECT,CONSEQUENTIAL OR INCIDENTAL DAMAGES, ARISING OUT OF THE USE OF, OR OTHERWISERELATED TO, THIS DOCUMENTATION OR ANY OTHER DOCUMENTATION.NOTWITHSTANDING ANYTHING TO THE CONTRARY, NOTHING CONTAINED IN THISDOCUMENTATION OR ANY OTHER DOCUMENTATION IS INTENDED TO, NOR SHALL HAVETHE EFFECT OF, CREATING ANY WARRANTIES OR REPRESENTATIONS FROM LOTUS (OR ITSSUPPLIERS OR LICENSORS), OR ALTERING THE TERMS AND CONDITIONS OF THEAPPLICABLE LICENSE AGREEMENT GOVERNING THE USE OF THIS SOFTWARE.

17Main Menu Commands . . . . . . . . . . . . . .15Favorites View . . . . . . . . . . . . . . . . . . . .12Activities View . . . . . . . . . . . . . . . . . . . .12Connections View . . . . . . . . . . . . . . . . .

9DECS Administrator Navigator . . . . . . . . .9The DECS Administrator . . . . . . . . . . . . . .93 DECS Administrator . . . . . . . . . . .

7Uninstalling DECS . . . . . . . . . . . . . . . . . .7Running Restricted LotusScript Agents . . .6DECS and Access Control List (ACL) Levels . .6Installation Considerations . . . . . . . . . . .6

DECS Virtual Fields Activities in aClustered Domino Server Environment .

6After Upgrading to DECS Replace

Administrator Design . . . . . . . . . . . .

5DECS Installation . . . . . . . . . . . . . . . . . . .52 Installing DECS . . . . . . . . . . . . . . .

4Security . . . . . . . . . . . . . . . . . . . . . . . . .3Accessibility . . . . . . . . . . . . . . . . . . . . . .3Supported Data Sources . . . . . . . . . . . . . .2Virtual Fields Activity . . . . . . . . . . . . . .2Introduction to DECS . . . . . . . . . . . . . . . .1Organization of this Manual . . . . . . . . . . . .11 Introduction . . . . . . . . . . . . . . . . . .

viContact and Support Information . . . . . . . .vRelated Documentation . . . . . . . . . . . . . . .vPreface . . . . . . . . . . . . . . . . . . . . . . . .

39Step 10 — Select Scheduling Options . . . .39Step 9 — Select Options . . . . . . . . . . . .39Step 8 — Enable Subforms . . . . . . . . . .38Step 7 — Name the Activity Document . .37

Step 6 — Virtual Fields Activity Events toMonitor Selection . . . . . . . . . . . . . .

36Step 5 — Map Data Field(s) . . . . . . . . . .34

Step 4 — Select the Lotus Connection forthe Data Source . . . . . . . . . . . . . . .

33Step 3 — Select the Domino Form to

Monitor . . . . . . . . . . . . . . . . . . . .

32Step 2 — Select the Domino Database . . .31Step 1 — Click the Add Activity Icon . . .31

Creating a Virtual Fields Activity with theUser Assistant . . . . . . . . . . . . . . . .

30Establishing Access Control in the Domino

Directory . . . . . . . . . . . . . . . . . . .

30Turning the User Assistant Off . . . . . . .29Turning the User Assistant On . . . . . . . .29

Using the Activity and Connection UserAssistant . . . . . . . . . . . . . . . . . . . .

28Usage Requirements for Virtual Fields

Activities . . . . . . . . . . . . . . . . . . .

25Introduction to Virtual Fields Activities . . . .255 Virtual Fields Activities . . . . . . .

24Completed Connection Document . . . . . . .23Using the Manual Button . . . . . . . . . . . . .21Connection Document Fields . . . . . . . . . . .19Defining Lotus Connections . . . . . . . . . . .194 Defining Lotus Connections . . .

iii

Contents

64Example Application . . . . . . . . . . . . . . .63

Building a Domino Application for a VirtualFields Activity . . . . . . . . . . . . . . . .

636 Building a Domino Application .

62Virtual Fields Activity Logging . . . . . . . . .61Scheduling . . . . . . . . . . . . . . . . . . . . . .59Document Delete Options . . . . . . . . . . .57Document Update Options . . . . . . . . . .55Document Open Options . . . . . . . . . . .53Document Create Options . . . . . . . . . .52Event Options . . . . . . . . . . . . . . . . . . . .50Multivalue Data in Virtual Fields . . . . . . . .49Initialize Keys . . . . . . . . . . . . . . . . . . . .45General Options . . . . . . . . . . . . . . . . . .44Options Overview . . . . . . . . . . . . . . . . .44Step 12 — Process the Activity . . . . . . . .43Step 11 — Initialize Keys . . . . . . . . . . .43Step 10 — Save and Close the Document .43Step 9 — Select Scheduling Options . . . .43Step 8 — Select Options and Initialize Keys

43Step 7 — Select Event(s) to Monitor . . . .43Step 6 — Mapping . . . . . . . . . . . . . . .42Step 5 — Enable Subforms . . . . . . . . . .42

Step 4 — Select the Lotus Connection forthe Data Source . . . . . . . . . . . . . . .

41Step 3 — Select the Domino Application

and the Form to Monitor . . . . . . . . .

41Step 2 — Enter a Name for the Activity . .40Step 1 — Click the Add Activity Icon . . .40

Creating an Activity without the UserAssistant . . . . . . . . . . . . . . . . . . .

40Step 13 — Process the Virtual Fields

Activity . . . . . . . . . . . . . . . . . . . .

40Step 12 — Initialize Keys . . . . . . . . . . .39Step 11 — Save and Close the Document .

103Index . . . . . . . . . . . . . . . . . . . . . . . . .

89Appendix A Configuration andTroubleshooting . . . . . . . . . . . . . . .

86Example of Virtual Fields Dynamic Queries

from Notes Clients . . . . . . . . . . . . .

84Overview of Steps . . . . . . . . . . . . . . . .84

Virtual Fields Dynamic Queries from WebClients . . . . . . . . . . . . . . . . . . . . .

83Overview of Virtual Fields Dynamic Queries

838 Virtual Fields and DynamicQueries . . . . . . . . . . . . . . . . . . . . . .

80Output Parameters . . . . . . . . . . . . . . .79Input Values and Named Parameters . . .79Using an Oracle Stored Procedure . . . . . . .77Using a DB2 Stored Procedure . . . . . . . . . .75Testing the Stored Procedures in Sybase/SQL

73Sybase/SQL Stored Procedure Example . .73Using Stored Procedures in Sybase/SQL . . .71Using the Monitor Orders Option . . . . . . . .71Storing a Static Copy of External Data . . .71Building Views . . . . . . . . . . . . . . . . .71Using Data Storage Options . . . . . . . . . . .70

Accessing Different External Sources usingthe Same Notes Application . . . . . . .

70Saving Data to an External Data System . .69Using Filter Formulas . . . . . . . . . . . . . . .69

Using the Options in a Virtual Fields ActivityDocument . . . . . . . . . . . . . . . . . . .

697 Using Virtual Fields ActivityOptions . . . . . . . . . . . . . . . . . . . . . .

67Running the Virtual Fields Activity . . . . . .66Virtual Fields Activity Example . . . . . . . . .65Example of the Application Design View . . .

iv DECS Installation and User Guide

Preface

This document provides information about installing and using the DominoEnterprise Connection Services™ (DECS) application. Information aboutLotus® Connectors and connectivity is described in the companiondocument entitled Lotus Connectors and Connectivity Guide (lccon6.nsf). Thisdocumentation file is installed with Domino™, not with LEI™. Thelccon6.pdf file is available for download at http://www.notes.net.

Related DocumentationThis section lists documentation that you may find useful as you learnabout and use LEI.

LEI Documentation SetDocumentation for DECS is available online with the product distributionand at http://www.notes.net. The DECS documentation set is listed below:

• Domino Enterprise Connection Services (DECS) Installation and User Guide— Provides information about configuring DECS and information onhow to set up and use DECS activities.

• Lotus Connectors and Connectivity Guide — Provides information on howto set up and use the supplied Lotus Connectors, including informationabout required software and instructions for testing connectivity(lccon6.nsf). This documentation file is installed with Domino, not withLEI. The lccon6.pdf file is available for download athttp://www.notes.net.

• Lotus Connector LotusScript Extensions Guide — Describes the LotusConnector LotusScript Extensions, which can be used in writingscripted sessions for accessing enterprise data (lsxlc6.nsf). Thisdocumentation file is installed with Domino, not with LEI. Thelsxlc6.pdf file is available for download at http://www.notes.net.

Current information about DECS can also be found athttp://www.lotus.com/ei.

Other Documentation For more information about related tools, refer to the following documents:

• Domino Administrator’s Guide — This manual provides information forconfiguring and administering a Notes installation.

v

• LotusScript Language Reference — This manual provides informationabout writing LotusScript programs. This could be useful if you want touse the Domino LotusScript Extensions (LSX) to write customActivities.

• Additional Lotus Connector Documentation — Lotus Software, IBMSoftware Group sells additional Lotus Connectors for enterprisesystems including Enterprise Resource Planning (ERP) and TransactionProcessing Systems. Specific documentation about those Connectors isincluded with the specific Connector software and package. You mayneed documentation for the specific databases, ERP, or transactionprocessing systems that you are using.

Contact and Support InformationLotus Software, IBM Software Group provides extensive support for itsproducts.

Enterprise Integrator Web SiteTo obtain the latest information about DECS, visit the following Web site:

http://www.lotus.com/ei

Note Domino-related product updates for iSeries can be found atfollowing Web site: http://www-1.ibm.com/servers/eserver/iseries/domino/support/qmu.htm

Technical SupportTo contact Customer Support with suggestions or questions regarding yourLotus Connector or DECS application, call 1-800-346-6388.

vi DECS Installation and User Guide

Chapter 1Introduction

Domino Enterprise Connection Services (DECS) is an optional feature ofDomino 6. This chapter provides information about the organization of thismanual and includes an overview of DECS Virtual Fields activities(previously known as DECS RealTime activities).

Organization of this ManualThis manual contains the sections described below.

continued

This chapter provides examples using VirtualFields options to refine the results of Virtual FieldsActivities.

Chapter 7Using Virtual Fields ActivityOptions

This chapter provides information for creating aDomino application for use with a Virtual FieldsActivity.

Chapter 6Building a DominoApplication

This chapter provides an overview of VirtualFields activities, information regardingpreparation of external system fields, andinstructions for creating Virtual Fields Activities.

Chapter 5Virtual Fields Activities

This chapter provides information and instructionsfor creating Connection Documents.

Chapter 4Defining Lotus Connections

This chapter provides information about the DECSnavigator, views, icons, and menu commands.

Chapter 3DECS Administrator

This chapter provides information about installingand configuring DECS.

Chapter 2Installing DECS

This chapter provides information about theorganization of this manual. It also includes anintroduction to DECS Virtual Fields activities, listssupported data sources, accessibility information,and contact and support information.

Chapter 1Introduction

DescriptionSection

1

This appendix provides information aboutnotes.ini variables, using DECS with clusteredDomino servers, error messages and knownproblems that you may encounter under certainconditions while using DECS.

Appendix AConfiguration andTroubleshooting

This chapter provides information on how to useVirtual Fields for on-demand, dynamic queries ofexternal data.

Chapter 8Virtual Fields and DynamicQueries

DescriptionSection

Introduction to DECS This release of DECS replaces RealTime activities with Virtual FieldsActivities. The functionality of Virtual Fields activities consists of all thefunctionality available in the earlier DECS RealTime activity as well asfeatures not available in the earlier RealTime activity:

• Support for computed subforms

• Options for new line delimiters

• Additional logging options

• Support for procedure return parameters following insert and updateoperations. Output from write operations allows results to be returnedto fields in the Notes document being monitored following insert andupdate operations.

Virtual Fields ActivityVirtual Fields Activities (previously known as DECS RealTime Activities)enhance Lotus Notes applications by allowing them to retrieve externaldata, such as data from DB2, and to integrate this external data with nativeNotes data on a single Notes document form. DECS, running on theDomino Server that is hosting the Notes application, intercepts and handlesthe Notes database events. For example, when Notes or Web client usersopen, create, update, or save Notes documents, these events triggerimmediate access from the Notes form to external data sources supportedby DECS.

Once a system administrator has created a Virtual Fields activity, Dominousers can open, create, update or delete external system data directly andtransparently through their Notes Client. By extension, Web clients mayopen the same Notes form that the activity monitors by accessing a DominoRelease 5.0.5 or Domino 6 server, obtaining access to supported externalsource data.

2 DECS Installation and User Guide

For example, if the external database is a DB2 database, Notes end-usersmay work with DB2 data as if it were in Notes. DB2 connectivity software isnot required on each user’s system; however, it must be installed on theDomino server machine. Access to the external data source is handled bythe Domino server machine, which uses DECS connectivity software toaccess the external data source, such as DB2.

Supported Data Sources Virtual Fields activities support a range of external data sources, calledConnectors. Additional data sources are continuously being added. AsLotus and other third parties create data source Connectors for Domino,they will all be manageable using the Domino Enterprise ConnectionServices (DECS) product. Currently supported data sources include:

• DB2

• OLEDB

• Open Database Connectivity (ODBC)

• Oracle 7

• Oracle 8

• Sybase

• File

Each of the data sources has specific software requirements for networkconnectivity that must be met by the Domino Server. Refer to the LotusConnectors and Connectivity Guide for information about the connectivityrequirements for each of the supported data sources.

Verify that all of your database software is up to date with all availablemaintenance releases and fix packs.

Note Other Enterprise Resource Planning connectors and TransactionSystem Connectors are also available. For more information, see theEnterprise Integrator Web site: www.lotus.com/welcome/ei.

AccessibilityAccessibility features help a user who has a physical disability, such asrestricted mobility or limited vision, to use software products successfully.DECS adheres to the IBM and Lotus Notes R5 Accessibility guidelines. For more information on Accessibility, seehttp://www-3.ibm.com/able/guidelines.htm

Chapter 1: Introduction 3

DECS provides keyboard access as an alternative or to augment itsgraphical user interface. You can tab from one field on a DECS ConnectionDocument or Activity Document to another. You can also use the up anddown arrow keys to move the cursor and change focus. You can use theReturn key, for example, to select an action such as an Activity choice fromthe DECS Administrator. You can then use the arrow keys to move thecursor to the desired activity name. You can then press the Return key toselect that activity and open the corresponding Activity Document. Once anActivity Document is open, you can enter Edit mode by pressing <Ctrl> E.When you are in Edit mode, field level help displays automatically forwhatever field has focus. Field level help appears at the bottom of the userinterface.

Note Pop-up help is available for all Connection Document and ActivityDocument options using the mouse, but it is not available with thekeyboard.

To simplify user interaction with the application, DECS supports theshortcut keys listed next to the menu options on the top bar, such as File,Edit, View, and so on. To use the keyboard to open a top bar menu and thendisplay help on any of its content, press <Alt> and the underlined character(for example, F for File, E for Edit). Keyboard equivalents are listed to theright of all pull-down menu choices.

You can use screen-reader software and a digital speech synthesizer to hearwhat is displayed on the screen. You can also use voice recognitionsoftware, such as IBM ViaVoice, to enter data and to navigate the userinterface.

SecuritySee Appendix A and review the Domino release notes for informationregarding security and access control.


Chapter 2Installing DECS

This chapter provides information about installing DECS on Domino 6 anddescribes current functional limitations.

DECS Installation Domino Enterprise Connection Services (DECS) is a forms-basedtechnology in Domino that provides the capability to integrate live datafrom enterprise systems natively into Domino applications. DECS isinstalled as part of all new Domino 6 installations and upgrades but youmust select the DECS option to activate its functionality when you installDomino 6.

DECS installation is a simple process, simply elect to install DECS whenyou install Domino. But please see the following section, “DECS and AccessControl List (ACL) Levels,” for additional suggestions and Name andAddress Book setting.

Note Make sure that all users who will be creating DECS activities haveentries in the Name and Address book and that the server is listed as part ofa group. For more information, see the pop-up help in the DominoDirectory (formerly referred to as the Server Name and Address book).

Note If after upgrading to DECS, you are unable to get data when runningVirtual Fields activities, open each Virtual Fields activity document andensure that the specified Domino Server is correct.

As part of the install process in Domino 6 and Notes 6, the following DECSdocumentation databases are installed:

For Domino server installations, the following three document databasesare installed:

• Domino Enterprise Connection Services (DECS) Installation and User Guide(decsdoc6.nsf)

• Lotus Connectors and Connectivity Guide (lccon6.nsf)

• Lotus Connector LotusScript Extensions Guide (lsxlc6.nsf)

5

For Notes client installations, the following two document databases areinstalled:

• Lotus Connectors and Connectivity Guide (lccon6.nsf)

• Lotus Connector LotusScript Extensions Guide (lsxlc6.nsf)

After Upgrading to DECS Replace Administrator DesignAfter a Domino 6 upgrade, you must manually replace the design on theDECS administrator prior to running any activities. When you replace a DECS administrator design, Domino has to be running. Any scheduledDECS activities will launch once Domino is started, these activities shouldbe stopped prior to replacing the design. Once the design replace iscomplete, the activities can be restarted.

Another approach is to disable DECS the first time you restart Domino 6after an upgrade, replace the design, re-enable DECS and restart the server.

Use the supplied decsadm.ntf database to replace the design. Designreplacement follows standard Domino procedures, see Dominodocumentation for more information.

DECS Virtual Fields Activities in a Clustered Domino ServerEnvironment

If you plan to use DECS in a clustered Domino server environment, see“Using DECS Virtual Fields Activities in a Clustered Domino ServerEnvironment” in Appendix A.

Installation ConsiderationsThe following should be considered before installing DECS:

• The DECS Virtual Fields activity does not work in true real-time withDomino clustering. Writing changes to the external system databasemay be delayed if not all databases within the cluster areDECS-enabled.

DECS and Access Control List (ACL) LevelsThe DECS administrator is shipped with a predefined Access Control List(ACL). In this ACL, “Default” is set to Manager because when DECS is firstinstalled and the addin task is loaded for the first time, DECS automaticallybuilds the initial administrator from the template — there is no opportunityfor a user to set themselves as the database administrator.


Managers and administrators are urged to change the ACL to best fit theirenvironment as soon as possible after installation so that only theappropriate people have the access they require.

Note Either a “Default” or “Lotus Notes Template Development/LotusNotes” ACL entry must exist and must have at least Editor access orbrowsing will fail. This is because the agent that is used for browsing is runon the server, therefore security is through the signer of the agent, which is“Lotus Notes Template Development/Lotus Notes.”

System administrators can further secure the system by specifying theTemplate development ID (that is, Lotus Notes Template Development/Lotus Notes) in the Server entry in the Name and Address book in the“Run Restricted LotusScript/Java agents” list. This will only allow that IDto run LotusScript agents on that server (this is very restrictive and may betoo excessive for most installations). For additional information, see thefollowing section, “Running Restricted LotusScript Agents.”

Running Restricted LotusScript AgentsTo execute unrestricted LotusScript agents you must grant permission to“*”. In addition, either “Default” or (more secure) the signer of the agentmust have Editor access to the DECS Administrator database withpermission to delete documents.

Uninstalling DECSWhen you elect to install DECS during a Domino installation, two entriesare added to the NOTES.INI file. If you need to disable DECS for anyreason, delete the following items (highlighted in italics) from the notes.inifile and restart the server.

ServerTasks=....., DECS

EXTRMGR_ADDINS=decsext

To re-enable DECS, simply add the two entries back into the notes.ini fileand restart the server.

Adding an Empty DECS AdministratorIf you want to start with an empty (fresh) DECS administrator, rename ordelete the existing Administrator (decsadm.nsf) in the server data directory.Restart the server with DECS enabled. A new administrator is automaticallycreated during the server startup.

Note Do not move or delete the DECS ntf file (decsadm.ntf) at any time.

Chapter 2: Installing DECS 7

Chapter 3DECS Administrator

This chapter provides information about the DECS Administrator,including its navigator, views, and menu commands.

The DECS AdministratorThe DECS Administrator provides an interface that makes it possible foryou to view connections and activity documents, create activities andconnections, and manage all of these components.

There are three distinct views available to you in the Administrator.

• Activities — This view displays all of the existing Activities and theirstate (running, disabled, what type of activity they are, and so on).

• Connections — This view displays all of the existing connections. It alsoshows which external database the connector is accessing and whichtable, view, or procedure is being used.

• Favorites — This is a folder that contains whatever activity andconnection documents you choose to drag into it. You can create moreviews of this type as you want. The Action bar options for these remainthe same.

An example of each view is illustrated below as well as the navigator,action bar, views, and menu commands in the Administrator. All aredescribed in the sections that follow.

DECS Administrator Navigator The Navigator panel on the left side of the Administrator is present in allviews. It contains these icons:

• Activity — Click this icon to see the Activities view.

• Connections — Click this icon to see the Connections view.

• Favorites — Click this icon to see the Favorites view.

• Info — Click this icon to open a document with an illustration and adescription of all of the icons used in the Administrator.

9

• Help — Click this icon to open the DECS Administrator helpdocumentation.

• Running — Click this icon to open a dialog box showing the currentlyrunning activities. Click again to close the dialog box.

• Assistant — Click this icon to turn the User Assistant on or off. Whenthe User Assistant is turned on the New Activity/Connectivity Wizardis enabled. The Wizard guides you through creating a Virtual Fieldsactivity document and provides information about creating and editingan activity document.


The following illustration shows the Navigator with the Running Activitieswindow open. To see the activity listed by Notes application, click “ByNotes App”; to see the activities listed by external system application, click“By External Sys.”

Chapter 3: DECS Administrator 11

Connections View Lotus Connection documents are named automatically by the DECS taskusing a convention that specifies the external system, the database, and thetable name; when applicable, the user name required for login to the datasource is shown in parentheses. For example, DB2, DB2V5_2, (using‘mylogin’) — QEPUMP.KLBVD_EXT.

The Connections view Action bar contains an icon that enables you to createa connection:

• Add Connection — Click this icon to create a new connection documentfor an external data source. When the User Assistant is active, thislaunches the Wizard, which steps you through the process of defining aConnection to an external data source.

Below is an illustration of the Connections view.

Activities ViewIn the Activities view, you can see all of the Virtual Fields activities thathave been created in the Administrator.

In the Activities view Action bar, the following icons enable you to createand work with Activities:


• Add Activity — Creates a new activity. When the User Assistant isactive, this launches a wizard that prompts you through the process ofdefining a Virtual Fields activity. When the User Assistant is turned off,this displays a blank activity document that you can edit directly.

• Start — Start the currently selected activity. This has no effect if thecurrent selection is already executing.

• Log — See the log for the highlighted activity. Displays the status of thecurrently selected activity. If the current selection is running, the starttime and other current status are displayed. If the current selection isnot running, this will display the results of the most recent execution.

• Stop — End execution of the currently selected activity. This has noeffect if the current selection is not running.

Activity ViewBelow is an illustration of an Activities view.


Activity IconsThe following table describes the information shown in the Activities viewof the DECS Administrator.

The user-specified name of the Activity. Name

Activity scheduled to start and stop at specifiedtimes.

Activity not scheduled.

Activity scheduled to AutoStart with server.

Activity disabled with an error.

Activity stopped with an error.

Starting / Stopping an activity.

Active activity.

New activity.

Shows the status of the activity, as indicated by the iconsbelow. Refresh the view periodically to update the status.

Status

Shows the type of external data source, the database and tablename or metadata.

External Source

Indicates the activity is a Virtual Fields activity.Activity

Indicates the activity will process documentdeletions.

Indicates the activity will process documentupdates (edit/save).

Indicates the activity will process document opens.

Indicates the activity will process documentcreations.

Events

Shows the name of the Notes NSF and the specific form beingmonitored.

DominoApplication

Description and IconColumn


Favorites ViewThe Favorites view is a view that you can use to show both connections andactivities (by dragging and dropping them into the Favorites folder on theNavigator).

In the Favorites view Action bar, the following icons enable you to createboth Connections and Activities and to work with Activities:

• Add Activity — When the User Assistant is active, this launches awizard that prompts you through the process of defining a VirtualFields activity. When the User Assistant is turned off, this displays ablank activity document that you can edit directly.

• Add Connection — Click this icon to create a new connection documentfor an external data source. When the User Assistant is active, thisopens a connection document with a detailed description of the stepsyou go through in the process of defining a connection to an externaldata source.

• Start — Start the currently selected activity. This has no effect if thecurrent selection is already executing.

• Log — Displays the status of the currently selected activity. If thecurrent selection is running, the start time and other current status aredisplayed. If the current selection is not running, displays the results ofthe most recent execution.

• Stop — End execution of the currently selected activity. This has noeffect if the current selection is not running.

• Remove from Folder — Select the activity or connection document thatyou want to remove from the folder then click “Remove from Folder.”


The following is an illustration of an empty Favorites view, no activities orconnections have been brought into it.

You can add additional views that are identical in function to the Favoritesview. You can name these Views whatever you want to. Use a name thatreflects the kind of information you are monitoring — for example, “SouthAmerican Sales.” Then move activities and connections that are unique tothis folder or shared by other folders into this folder. See the followingillustration.


Main Menu Commands In addition to the Notes commands found in the menus, the DECSAdministrator menus provide specific commands for working with DECS.

CreateThe following commands are available from the main menu under Create:

Opens a dialog box from which you can select the type ofconnection document that you want to create. Provides thesame functionality as clicking “Add Connection” in the Actionbar.

Other...

DescriptionCommand

ActionsThe following commands are available from the main menu under Actions:

Remove the selected activity and connection documents fromthe currently opened folder. This menu option is onlyavailable when the Favorites folder is open, or when a folderview you have created is open. Provides the samefunctionality as clicking “Remove from Folder” in the Actionbar.

Remove fromFolder

When this option is turned on all the selected activities startwhen Domino starts. Clicking “Off” turns off this option forthe selected activities.

Set Autostart

Restarts the currently selected activity. Reset Activity

DescriptionCommand


Chapter 4Defining Lotus Connections

This chapter provides information and instructions for creating LotusConnection documents.

Defining Lotus ConnectionsYou use the Lotus Connection document to define connections to externaldata sources. You can use the Wizard or you can fill out the fields in thedocument without using the Wizard. If you use the Wizard, the connectiondocument opens with explanatory text at the top of the document (see theillustration in step 3), if you do not use the Wizard, the connectiondocument opens without explanatory text. In either case, refer to the stepsbelow.

Note In order to connect to a supported data source, you must have therequired connectivity software for that data source installed on your server.Verify that all of your database software is up to date with all availablemaintanence releases and fix packs.

1. Click the Add Connection icon.

2. A list of supported data sources appears, as shown below.

19

Note You can remove any of the supported data sources that you donot intend to use from the list. Refer to the Notes Application Developer’sGuide for more information on how to remove a form from a menu.

3. Select the data source for which you want to define a connection fromthe list of available sources and click OK. The Lotus Connectiondocument appears. Below is an example of a Lotus Connection for aSybase document.

Note Note that the text in the top part of the document only appearswhen the Wizard is turned on.

4. Enter the required information in the Lotus Connection document.

The Connection document is divided in two sections:

• Connectivity — This section of the document specifies the databaseor data source and the connectivity information required to accessthat data source.


• Table/View/Procedure/Subdirectory Selection — Use this section ofthe document to select the specific metadata that you want to accessthrough this Connection. The title of this section varies depending onthe type of data you want to access.

Connection Document FieldsThe tables below describe the fields in each section of the Lotus Connectiondocument.

The number and title of these fields may change depending on the externalsystem and the type of connection you select.

Note For information about Connection documents for the variousexternal systems that DECS supports, see the Lotus Connectors andConnectivity Guide (lccon6.nsf).

continued

Click the password encryption icon to encrypt yourpassword for this Connection document. You canclick it again to turn encryption off.

Password Encryption KeyIcon

Enter the password associated with the User Namespecified above.

Password

Enter the User Name required to access the selecteddata source specified above.

User Name

Enter the information required for the specific datasource for which you are defining a connection. Thisinformation can vary according to the type of datasource selected.Note Depending on the connector, more than onefield may be exposed to capture all of the requireddatabase information.

Database/Engine/DirectoryPath/Data Source/HostStringProvider StringAuthentication Service

Select Oracle version, enter the name of the SybaseSQL Server where the database is located, orrelational database engine to use, or programmaticID for OLE DB provider to use.

Server/Provider/OracleVersion/SQL Server Note This field is notavailable for all Connectiondocuments.

DescriptionConnectivity Field

Chapter 4: Defining Lotus Connections 21

Select the desired option. You can choose to connectto data in: �� Tables�� Views �� Procedures (stored procedures)

Note When you browse for a Stored Procedure inthe Connection document, you are presented with adialog box listing all the Stored Procedures in theexternal system database. When you choose a StoredProcedure, the parameters of the chosen storedprocedure are automatically listed in the“Parameters” field (see the table below). If you donot specify a Stored Procedure in the Connectiondocument, you can select a Stored Procedure and itsassociated parameters from the Virtual Fielddocument. In either case, the stored procedure isentered as the default stored procedure in the Eventssection of the activity document. In most casesreturned values are handled by the external systemdatabase; in the case of Oracle, the Oracle connectorhandles returned information. This is transparent toyou, however the person responsible for writingOracle stored procedures should be aware of it. Seethe Oracle example in Chapter 7 for a fullexplanation.

Note At present, only the Lotus connector for DB2supports output parameters.

Caution Using the “procedures” option with Sybaseand OLE DB may cause errors, see “Error WhenAttempting to Use Stored Procedures in Sybase orOLE DB” in Appendix A for more information.

Selection Type:

DescriptionConnectivity Field


In the Table/View/Procedure/Subdirectory Selection section of thedocument you select the specific metadata that you want to access throughthis Connection.

Enter text in this field that may be helpful toyou in organizing or keeping track of yourconnectivity documents.

Comments

This field lists the column names and theirassociated data types found in the selectedtable or view of the external data source. If you are working with procedures, this fielddisplays the stored procedure parameters. See“Selection Type” in the table above.If connecting to a file system, use this field tolist file attributes corresponding to data typesfrom the selected subdirectory.

Column(s)/Parameters/FileAttributes

This field shows the name of the specific tableor view you select from the data source. Clickthe down-arrow button to access a list of thetables or views from which you can choose.

Name

This option allows you to select from tablesby owner name. The default value is <Any>,allowing you to select from all tables in thedatabase. Click the down-arrow button to seea list of existing owner names. This enablesyou to select only from tables belonging to thespecified owner.

Owner (Not available in Fileconnection documents)

Use the Manual button to select a table thatdoes not appear in the current list of tables.After you enter a table all of the associatedcolumns are displayed. See the section below,“Using the Manual Button,” for moreinformation.

Description Table/View/Procedure/SubdirectorySelection Field

Using the Manual ButtonUse the Manual button to specify a table that is not included in the list oftables/views/procedures/subdirectories shown when you select thedown-arrow button next to the Name field.

You must enter the owner name and the table name (note that in the case ofthe File connector, there is no owner). You must enter these items exactly asthey are named in the data source or DECS will not be able to locate them.

Chapter 4: Defining Lotus Connections 23

Completed Connection DocumentThis completes the steps needed to create a Connection document. Below isan example of a completed Lotus Connection document for a Sybasedatabase.


Chapter 5Virtual Fields Activities

This chapter provides an overview of Virtual Fields activities, informationregarding preparation of external system fields, and instructions forcreating these activities.

Introduction to Virtual Fields ActivitiesDECS activities monitor Notes forms. DECS connects these forms toexternal data sources (such as DB2) through Lotus connectors.

Once a system administrator has created a Virtual Fields activity(previously known as DECS RealTime), Domino users can open, create,update or delete external system data directly and transparently throughtheir Notes Client. By extension, Web clients may open the same Notes formthat the activity monitors by accessing a Domino Release 5.0.5 or DominoV6 server, and obtain access to supported external source data.

For example, if the external database to be queried or updated from theNotes form is a DB2 database, Notes end-users may work with DB2 data asif it were in Notes. DB2 connectivity software is not required on the clientsystem. Network access to the external data source is handled by theDomino server machine, which contains DECS connectivity software for theexternal data source, such as DB2. No programming is required toaccomplish this functionality.

Virtual Fields activity functionality includes features not available in theearlier DECS RealTime activity: support for computed subforms, optionsfor new line delimiters, additional logging support, and support forprocedure return parameters following insert and update operations.Output from write operations allows results of write operations to bereturned to fields in the Notes document being monitored following insertand update operations.

OverviewIn Virtual Fields activities, Note documents exist for every data setpresented to the user. Virtual Fields activities simply add external systemdata to an existing document.

25

In the simplest Virtual Field scenario, the Notes document contains only thekey value necessary to retrieve the external system data. These Notesdocuments are referred to as “key” documents (in previous documentationthese were referred to as “stub” documents). While the Notes document canbe a simple key document, it can also contain additional fields. Any fieldnot mapped to external system data is saved in the Notes document.

Each Virtual Fields activity monitors a specific Notes form where themetadata is defined. Metadata is the list of fields in the Notes form that aremapped to a list of fields in the external data source during data query orupdate. You must map the key fields in the external data source to thecorresponding fields in the Notes form using the Virtual Fields activity. TheVirtual Fields activity requires key documents (referred to as “stubdocuments” in previous releases) in the Notes database to function. Thesekey documents are initialized by the Virtual Fields activity. See below,“How Key Documents Work,” for more information.

In addition, Virtual Fields activities can invoke external system storedprocedures to produce the data to display in the form.

Multiple Virtual Fields Activities and Monitor OrderVirtual Fields activities operate at the field level. You can have multipleVirtual Fields activities monitoring the same form in a Notes document, buteach activity is responsible for a subset of the fields on a form. For example,if any of the Virtual Fields activities is not running, the document formcontains all the fields, but only the fields for the stopped Virtual Fieldsactivities will be blank. In brief, you can use one or more Virtual Fieldsactivities to monitor a form in a Notes document, as long as you makeproper use of monitor order where appropriate.

Using monitor order you can have one activity that uses, for example,empid as a key to retrieve employee data, including the job ID. The job IDcould in turn be used as a key in another activity to retrieve the job title,description, salary range, and so on.

In summary, one or more external sources may be accessed from the Notesform. A single external data source definition (Connection document)indicates the data source to connect to and the metadata to use. ManyVirtual Field activities can be used to monitor a single form; each of theseaccess data from multiple external data sources.

In addition, you have the option of storing retrieved data to the Notes form,or simply viewing the retrieved data (see Data Storage under “GeneralOptions” later in this document).


Using Key DocumentsWhen you initially create a Virtual Fields activity for a database which hasexisting records, DECS populates the Notes database with one “keydocument” for each external system record.

You, the user, must initialized the keys. It is a one time task that is used topopulate a new Notes database with the necessary key documents.

These “key documents” contain the key value(s) that are mapped to theexternal system table and that you specified in the activity document. Thesekey(s) are used to do the lookup into the external system table. When theNotes document is opened, the key(s) in the “key documents” are used tofetch external system data to populate the rest of the fields.

When you create a new document through a Notes client, a “keydocument” is created and saved with the key field value(s).

In the simplest case, all of the data resides in an external database and theNotes document only holds the lookup key; the document is really a placeholder, or key document. However, the “key document” can be much morethan just a container to hold the key(s). It can be used to contain other datain addition to the data stored in the external system. Any fields on the formwhich are not mapped to an external system field in the activity documentwill be stored in the “key document.” In addition, in the Virtual Fieldsactivity document, mapped fields can be specified as fields that should besaved in the “key document.” In any case, all mapped field values arestored in the external data source.

For example, you can construct a form, monitored by a Virtual Fieldsactivity, that displays employee history, payroll data, and personalinformation. In this situation, assume that the employee data and personalinformation is stored in a Notes Database (nsf), and the payroll departmentinformation is stored in a DB2 database. In this case, the “key document” isonly a “key” in the sense that the employee id, for example, is used to fetchthe payroll information when the employee’s information document isopened. If the Virtual Field activity were not running, or if the user did nothave privileges to the DB2 data, the user would still see all of theinformation about the employee, but the payroll fields would be blank.

Chapter 5: Virtual Fields Activities 27

Usage Requirements for Virtual Fields ActivitiesThere are three usage requirements to keep in mind:

• Indexing

• Key Field Datatypes

• HTTP Server

The Indexing requirement is necessary for proper Virtual Fields activityoperation, as well as Key Field Datatypes and HTTP Server.

IndexingFor Virtual Fields, the following fields should be indexed:

• Mapped key fields should be indexed. The column mapped as a keyfield must be indexed in the external system. See “Key Field Datatypes”below for more information.

Key Field DatatypesAny field used for a key field in a Virtual Fields activity must be usable as akey field in the external system data source. For each of the data sourceslisted below, the specified data types cannot be used as key fields in VirtualFields activity.

• 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 external system; refer to the databasedocumentation.

• OLE DB/SQL Server — IMAGE, TEXT, and NTEXT cannot be used askeys.

• Notes — RICH TEXT fields cannot be used as keys.

Note Refer to the data source documentation for more information aboutthe use of data types as key fields.

HTTP ServerWhen using the HTTP Server to access documents, you should not use theVirtual Fields update event option “Conflict Detection” because it relies onthe use of hidden fields and the HTTP Server does not save contextinformation.

Performance in Virtual FieldsTo maximize performance in Virtual Fields activities, when the externalConnector is an SQL database, make sure an SQL index exists on the keyfields. For example, if the key fields for a Virtual Fields activity monitoring


table “MyTable” are “FirstName” and “LastName,“ create an index in theSQL database as follows:

CREATE UNIQUE INDEX IndexName on MyTable (FirstName, LastName)

When the Virtual Fields activity is enabled, DECS opens the Connectionwhen the first event for that activity is processed. DECS closes theConnection as soon as possible after the activity has been scheduled to stop.By default, a single persistent Connection is shared by all users of the Notesdatabase. It is possible to set the maximum number of concurrent, openedConnections to increase performance (see Max. Connections options in theVirtual Fields General Options section).

Using the Activity and Connection User AssistantYou use the New Activity/Connection User Assistant to create a VirtualFields activity. The User Assistant prompts you through the steps ofcreating a Virtual Fields activity. If you choose not to use the User Assistanta blank activity document is displayed, which you can fill in to define theactivity. For information about how to fill out an activity document withoutthe aid of the New Activity User Assistant, see the section in this chapterentitled ”Creating an Activity without the User Assistant.“

• Assistant — Click the following icon on the Administrator to turn theUser Assistant on or off:

Turning the User Assistant OnWhen the User Assistant is turned on, it enables an automated step by stepprocess for filling in an activity document. In a Connection document a listof steps appears on the document. The navigator indicates when the UserAssistant is turned on or off by displaying the appropriate text:

When you click the Add Activity icon on the action bar, the NewActivity/Connection User Assistant starts and steps you through theprocess of creating an activity.


See the section “Creating a Virtual Fields Activity with the User Assistant”later in this chapter.

Turning the User Assistant OffWhen the User Assistant is turned off, clicking the Add Activity icon causesa blank activity document to appear. Fill in the fields and select appropriateoptions in the blank activity document. See the section “Creating a VirtualFields Activity without the User Assistant” later in this chapter.

The navigator indicates when the User Assistant is turned on or off bydisplaying the appropriate text, as illustrated below:

Establishing Access Control in the Domino DirectoryIn the server document for the DECS server’s Domino Directory (formerlyreferred to as the Name and Address Book), the “Only allow server accessto 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 userslisted in the directory” option to “No.” The alternative is to make sure thatall users who will be creating DECS activities have entries in the DominoDirectory and that the server is listed as part of a group. For moreinformation, see the pop-up help in the Domino Directory document.


Creating a Virtual Fields Activity with the User AssistantYou can use the User Assistant to create a Virtual Fields activity. When theUser Assistant is enabled, it steps you through the process of creating theactivity. If the User Assistant is not enabled, clicking the Add Activity iconcauses a blank activity document to appear. In that case, see the section“Creating an Activity without the User Assistant” later in this chapter.

Step 1 — Click the Add Activity IconClick the Add Activity icon.

In either the Activity view or the Favorites view (or a Folder view) click theAdd Activity icon in the Action bar. A message box opens containing textthat explains the steps the User Assistant will take you through.

If you have not made any selections from the User Assistant, clicking theCancel button on this message box closes the activity form and returns youto the DECS Administrator. Once you have made one or more selections


while you are in the User Assistant, clicking Cancel causes the UserAssistant to shut down, but the activity document stays open, in Edit mode,displaying the choices you have made up to that point. You can thenmanually complete the activity document or abandon it.

Note Any choices you make while using the User Assistant can bechanged later by opening the activity document in Edit mode.

Step 2 — Select the Domino DatabaseA list of Domino databases appears (see illustration below). Select theDomino database that contains the Notes form you want to monitor.

Note When the list is large, you can scroll down the list to find the Dominoapplication (nsf) you want to select. However, if the list is too large to becompletely accommodated by scrolling, an overflow message appears at thebottom of the list (<overflow...>) and a box appears under the list, whichyou use to type in the exact name of the table you want to use.

Note Immediate or “real-time” monitoring uses the Notes replication ID ofthe application database. A Virtual Fields activity does not distinguishbetween the databases that share the same replication ID. Databases havethe same replication ID when they are replicas of each other and when onedatabase is created using the operating system to copy an existing database.


Step 3 — Select the Domino Form to MonitorA list of forms within the selected database appears. (These are the formsyou will use to display external system data.) Select a single form that youwant to monitor from the list shown.

Note Use the “Form Override” check box in the “General Options” sectionof the Virtual Fields Activity document to indicate that the Virtual Fieldsactivity should monitor all forms within the database, regardless of theform it uses. See the section on “Virtual Fields Activity Options” later in thischapter for more information.


Step 4 — Select the Lotus Connection for the Data SourceSelect the Connection for external data source you want to monitor fromthose available in the Select Connection dialog box, shown below.

Note When the list of tables is large, you can scroll down the list to findthe table you want to select. However, if the list of tables is too large to becompletely accommodated by scrolling, an overflow message appears at thebottom of the list (<overflow...>) and a box appears under the list, whichyou use to type in the exact name of the table you want to use.


When you have selected a Connection and there is more than one table inthe external database, another dialog box opens asking you to select a tablein the external database.


Step 5 — Map Data Field(s)After specifying the external data source and providing any requiredconnectivity information, such as User Name and Password, the Data FieldMapping dialog box appears. Use this dialog box to map data field(s)between the Notes application and the external data source.

Note This dialog box also makes it possible for you to map key fields.

Virtual Fields and Mapping Key FieldsYou are prompted to map one or more key fields. The illustration belowshows the interface for mapping key fields in a Virtual Fields activity.

Caution When you create an activity with the OLE DB Connector, the keyfield should not be a TEXT, NTEXT or IMAGE datatype. These datatypescannot be used in an ORDER BY clause or in the WHERE, HAVING, or ONclause, except with the LIKE or IS NULL predicates.

Using the UNID as Key FieldDECS provides an option to use the Notes universal ID that is createdautomatically by Notes for each document when a document is created.This makes it unnecessary for you to include an extra field in your Notesfront end solely as a key field.


Step 6 — Virtual Fields Activity Events to Monitor SelectionAfter mapping key and data field(s), the Virtual Fields Activity EventSelection dialog box appears. The last required step is to select the event(s)(create, open, update, delete) that you want to monitor. You see thisinterface only when you are creating or editing a Virtual Fields activitydocument.

Note The events that you are monitoring are on the Notes Form youspecified in this activity document, however, when you update, you updateto the external system. The user name used to connect to the externalsystem requires read and write permission for that external system. If a userhas only read rights, that user can open a document, but cannot update thatdocument and save changes to the external system. The user receives anerror message.


Step 7 — Name the Activity DocumentNext, you are prompted to enter a unique name for this activity. Enter aunique name and click OK.

After you name the activity and click OK, the following informationalmessage box appears outlining your options.

Click OK. The Virtual Fields activity document appears, showing yourselections. The numbered User Assistant icons in the document correspondto the major steps the User Assistant uses to create the Virtual Fieldsactivity.


Step 8 — Enable Subforms At this point in the process you can select this option to allow the use ofsubforms that are controlled by a formula. Subforms that are not controlledby a formula are included by default. If you select this option, a dialog boxopens that lets you select the available computed subforms that you want touse. Include only subforms controlled by a formula.

Step 9 — Select OptionsYou can now select the specific options that you want for this Virtual Fieldsactivity. See “Virtual Fields — Options” in this document for a fulldescription. If you select Update, you must also select Open, otherwise theDECS Administrator will not save the activity. You must also perform a onetime initialization of keys, see ” Initialize Keys” later in this document forcomplete information.

Step 10 — Select Scheduling OptionsSelect how you want to control the scheduling of the Virtual Fields activity.The options are Manual, AutoStart, and Custom. See the “Scheduling”section later in this chapter for more information.

Step 11 — Save and Close the DocumentChoose File - Save to save this Virtual Fields activity definition. Choose File- Close to close the Virtual Fields Activity document and return to theAdministrator.


Step 12 — Initialize KeysYou must initialize keys once and only once. You must first save the file.Once the file is saved, the “Initialize Keys” button appears in the Actionbar. Click the “Initialize Keys” button, now you can close the Virtual FieldsActivity document. For more information about Initializing keys see,“Virtual Fields — Initialize Keys” later in this chapter.

Note If you have already created “key documents,” do not initialize keysagain.

Step 13 — Process the Virtual Fields ActivityYou can process the activity using the Start and Stop buttons in the Actionbar of the Activities view or the Favorites (Folders) view. (When you select“Auto Start” in the Scheduling section of the activity document, the VirtualFields activity is established each time that the server starts. See theScheduling section for more information.)

Click the Virtual Fields activity to select it and then click the Start button tobegin processing it.

To stop a Virtual Fields activity, select the Virtual Fields activity and clickthe Stop button.

Creating an Activity without the User Assistant This section provides information on how to create a Virtual Fields activitywithout using the User Assistant. In this case, the User Assistant must bedisabled in the navigator.

When the User Assistant is disabled, clicking the Add Activity icon causes ablank Virtual Fields activity document to appear. Follow the steps below tocreate a Virtual Fields activity using a blank Virtual Fields activitydocument.

Step 1 — Click the Add Activity Icon Click the Add Activity icon.

The Virtual Fields activity document appears. The illustration below showsa Virtual Fields activity document.


Step 2 — Enter a Name for the ActivityEnter a unique name for the activity in the Name field at the top of thedocument.

Step 3 — Select the Domino Application and the Form to MonitorClick the down-arrow icon in the “Domino Application” section. A list ofdatabases appears. Select the database that contains the Domino applicationthat you want to monitor. Once you select a database, you are prompted fora form name.

Note When the list is large, you can scroll down the list to find the dominoapplication (nsf) you want to select. However, if the list is too large to becompletely accommodated by scrolling, an overflow message appears at thebottom of the list (<overflow...>) and a box appears under the list, whichyou use to type in the exact name of the table you want to use.

Note Immediate or “real-time” monitoring uses the Notes replication ID ofthe application database. A Virtual Fields activity does not distinguish


between the databases that share the same replication ID. Databases havethe same replication ID when they are replicas of each other and when onedatabase is created using the operating system to copy an existing database.

Note Use the “Form Override” check box in the “General Options” sectionof the Virtual Fields Activity document to indicate that the Virtual FieldsActivity should monitor all forms within the database, regardless of theform it uses. This option is only applicable to Virtual Fields Activitydocuments. See the section on “Virtual Fields Activity Options” later in thischapter.

Step 4 — Select the Lotus Connection for the Data SourceClick the down-arrow icon in the External System section to select fromexisting Lotus Connection documents.

Note When the list is large, you can scroll down the list to find the dominoapplication (nsf) you want to select. However, if the list is too large to becompletely visible, an overflow message appears at the bottom of the list(<overflow...>) and a box appears under the list, which you use to type inthe name of the table you want to use.

Step 5 — Enable SubformsSelect this option to allow subforms controlled by a formula to be used.Subforms that are not controlled by a formula are included by default. Ifyou select this option, a dialog box opens that lets you select the availablecomputed subforms that you want to use. Include only subforms controlledby a formula.


Step 6 — MappingClick the down-arrow icon in the “Mapping” section. The field mappingdialog box appears. Use this dialog box to map the key and data fieldsbetween the Domino application and the external data source.

Note When you create an activity with the OLE DB Connector, the keyfield should not be a TEXT, NTEXT or IMAGE datatype. These datatypescannot be used in an ORDER BY clause or in the WHERE, HAVING, or ONclause, except with the LIKE or IS NULL predicates.

Step 7 — Select Event(s) to Monitor Select one or more events to monitor. Click the down-arrow icon in theEvents section. A dialog box appears. Select the document events that youwant to monitor.

Step 8 — Select Options and Initialize KeysSelect the options, multivalue data options, and the event options you wantto enable or specify under the “Options,” “Multivalue Data,” and “EventOptions” tabs in the document. See the section “Virtual Fields: Options,“”Multivalue Data,“ and ”Event Options: Create, Open, Update, and EventOptions“ later in this chapter for more information. You must also performa one time initialization of keys, see ” Initialize Keys“ later in this documentfor complete information. If you select Update, you must also select Open,otherwise the DECS Administrator will not save the activity.

Step 9 — Select Scheduling OptionsSelect how you want to control the scheduling of the Virtual Fields activity.The options are Manual, AutoStart, and Custom. See the “Scheduling”section later in this chapter for more information.

Step 10 — Save and Close the DocumentChoose File - Save to save this Virtual Fields activity definition. Choose File- Close to close the Virtual Fields activity document and return to the DECSactivity administrator.

Step 11 — Initialize KeysYou must initialize keys once and only once. Do this after you have savedand exited the Virtual Fields Activity document you have just created.Reopen the document and click the ”Initialize Keys“ button, which willnow have become available in the Action bar. Once you do this you canclose the Virtual Fields Activity document. For more information aboutInitializing keys see, ”Virtual Fields — Initialize Keys“ later in this chapter.


If you have already created ”key documents,“ do not initialize keys again.

Step 12 — Process the ActivityYou can process the activity using the Start and Stop buttons in the Actionbar of the Activities view or the Favorites (Folders) view. When you select“Auto Start” in the Scheduling section of the activity document, the VirtualFields activity is established each time that the server starts. See theScheduling section for more information.

Click the Virtual Fields activity to select it and then click the Start button tobegin processing it.

To stop a Virtual Fields activity, select the Virtual Fields activity and clickthe Stop button.

Options OverviewOnce you have specified the Domino application, the Connection you wantto use, and set up mapping, there are a number of options for you toconsider in setting up the activity.

In this document, these options are broken down into the followingcategories:

• General Options (includes Initializing keys)

• Multivalue Data

• Event Options

• Scheduling Options


General Options The General Options section of the Virtual Fields activity document,illustrated below, presents options that can be applied to an activityregardless of the type of Event the Virtual Fields activity monitors. Each ofthe General Options is described after the illustration.


continued

The default is to monitor only documents using the formspecified in the Notes Application section above.Selecting this option causes the Virtual Fields activity toprocess the selected events for all the documents in the Notesdatabase that have the same key(s) as the original metadata,regardless of the form.

Form Override

This option sets the maximum number of Connections to theexternal database that can be open to service concurrent userrequests simultaneously. DECS opens one Connection to theexternal data source when the first Notes application eventoccurs. If two or more events occur simultaneously, additionalConnections are made, up to the maximum number ofConnections specified by this option. When the maximum number of connections is reached,subsequent events are queued and occur when each precedingevent is serviced. Each Connection lasts only as long asnecessary to read from or write data to the external data source.While the Connection is persistent, the time required to serviceeach event is minimal and depends on the amount of databeing read or written. The maximum number of Connections,therefore, does not need to be that great in order to servicemultiple events. Set the maximum connections to 2 or 3 and ifusers experience significant delays, increase this number.

Max.Connections

If you use more than one Virtual Fields activity for a singleNotes form, you can specify the order in which the document’sevents are intercepted.The monitor order also enables you to use multiple activitiesthat connect to different tables and use values found by the firstVirtual Fields activity (monitor order 1) as keys for subsequentActivities (monitor order 2, 3, etc.).Activities with monitor orders of 2, 3, 4, and so on, mustmonitor an Open event. They may monitor other events too,but one of the events must be an Open event. Depending on thenature of the activity, the activity with monitor order 1 may berequired to monitor an Open event as well.When adding or updating data to a source from a documentthat is not the first in the monitor order, a row is created in thesource that may not contain all fields or key values. To includeall data and key fields, use one of the following methods:

Monitor Order

DescriptionGeneral Options


continued

Prevent data loss — Enable this option to have DECS write anerror to the log for any data that is lost as a result of the transferand terminate the transfer.Allow precision loss — Enable this option to have DECS notreport loss of numerical or datetime precision as a result of thetransfer. This allows some loss of precision without stoppingthe transfer. This option is the default.Allow precision loss & truncation of text — Enable this optionto have DECS allow precision loss and to truncate text datawhen necessary to conform to field lengths in the externaldatabase. Note that key fields are not truncated.

Data Integrity

An optional Notes formula defining the documents that theVirtual Fields activity will monitor. Use this option to cause theVirtual Fields activity to process only documents that satisfythe specified formula. Note When you set up a Filter Formula, the selected fieldmust also be defined in “Saved Fields” under the Data Storageoption (see below). If a document is created that does not match the filter criteria, itis not inserted into the external table (hence, it is not“processed”), instead, it is saved locally in the .nsf regardless ofthe “Data Storage” setting.

Filter Formula



continued

Remove all real-time fields from documents — Enable thisoption if you want to remove all the data fields mapped in theActivity from the Notes document before it is saved to disk.This is the default.Leave all real-time fields in documents — Enable this option ifyou 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 orupdating a document when the activity is active.Leave selected real-time fields in documents — Enable thisoption if you want to leave selected data fields in the Notesdocument. You may want to select this option in order toenable views of the forms.

Data Storage

Select the option you want to use to convert the Notes new-linedelimiter to a new-line delimiter in another system.

New LineDelimiter forConnection

This option affects any trailing spaces that exist in the Textfields of the external data. Text trimming only occurs when the fields are read from theexternal source.There are three choices:Trim spaces on all non key fields — Select this setting to trimtrailing spaces only from data fields, not from the key fields.(Default)Do not trim spaces on any fields — Select this option to leavetrailing spaces in all fields. Trailing spaces may be required to ensure matching of fieldsbetween Notes and the external data. Note When data is put into external system fields of fixed lengthand then retrieved, the Connection with the external system maybe lost because the back end has padded the data with spaces tofit the fixed length of the field. If this occurs, use either a variablelength field (VARCHAR) in the external system database, orenable the “Trim spaces on all non key fields” option. You willmost likely encounter this situation when you use data of typeCHAR as a key field for Oracle 7 or 8 systems. When you use aCHAR data type as a key field, Lotus recommends that you usethe default setting, “Trim spaces on non-key fields.”

Note When using a Virtual Fields Activity that monitors theCreate Event, key fields of type character (fixed length) are onlyeffected by the Activity’s trim options when keys are firstinitialized. While the activity is running, newly createdcharacter (fixed) key fields will remain exactly as they areentered when creating the new record in Notes.

Trim TrailingSpaces



This option is only visible if you have selected “Leave selectedreal-time fields in documents.” Click the down arrow to open alist of Notes data fields from which you can select the data fieldyou want. If you do not select any fields, it is equivalent toenabling the Remove all real-time fields from documentsoption. Note If you use the Filter Formula option, the selected fieldmust also be defined here in Saved Fields.

Saved Fields


Initialize KeysWhen you are working in a Virtual Fields activity document, there is abutton labeled ”Initalize Keys“ in the Action Bar. When you click thisbutton DECS populates the currently selected Virtual Fields activity keyfields with data from the external data source for that Connection. Thiscommand should be used only once after creating a Virtual Fields activity.Initializing keys again creates duplicates of existing documents.

If you have specified Leave Selected Virtual field Fields in Document or LeaveAll Virtual field Fields in Document, the associated fields are transferred to theNotes application.

When using Initialize Keys with a Virtual Fields activity that has a FilterFormula, you are asked if you want to use a conditional clause to restrictthe number of external records imported into Notes. If you choose Yes, youare prompted to enter the external conditional clause. The conditionalclause must be in the external system’s syntax for a keyed selection clause.For SQL based systems, the conditional clause is that part of a WHEREclause following the word ”WHERE.“ For example, if the completestatement were: SELECT * from Table WHERE Number > 1, you wouldonly enter Number > 1 as the key initialization condition.

Note When you create an activity with the OLE DB Connector, the keyfield should not be a TEXT, NTEXT or IMAGE datatype. These datatypescannot be used in an ORDER BY clause or in the WHERE, HAVING, or ONclause, except with the LIKE or IS NULL predicates.


Multivalue Data in Virtual FieldsThe Multivalue Data options allow you to consider non-key fields asmultivalue fields. Once selected, there are more options for sorting andordering for you to choose from. Each Multivalue Data option is describedafter the illustration.

continued

Enable this option to have the Virtual Fields activity considernon-key fields to be multivalues.Multivalue Data allows a single document in a Notes databaseto relate to multiple records in the Connection.When enabled, the Open event will read all records of theexternal system which match the key data field(s) and combinethe multiple fields data into Notes multi-data fields. The Createand Update events reverse the operation.

Multivalue Data

DescriptionMulti-Value DataOptions


Force data into the selected character set for the purpose ofsorting. By default the underlying Connection’s character set isused. To provide a character set, use the corresponding suffix.For example, for LCSTREAMFMT_IBMCP932, use “CP932.”See the appendix in the LSX User Guide for a list of charactersets.

Character set

Ascending – Sorting is done alphabetically from A to Z. Earlierdates are placed before more recent ones; smaller numbers areplaced before larger ones.Descending – Sorting is done alphabetically from Z to A. Recentdates are placed before more earlier ones; larger numbers areplaced before smaller ones.

Direction

Binary — Sort based on the binary order of the character codes.Recommended.Case Sensitivity — Lower case is sorted before upper case.Case Insensitivity — Case is ignored in the sorting process.

Text order

Sorting key fields that define the order of the data WITHIN acollapsed record. The individual values within the multivaluedata field are sorted according to the “Text order” and the“Direction” options.All remaining fields will have their multivalue dataappropriately sequenced to preserve their order with those ofthe sorting field or fields.

Sorting fields

Enable this option to have the Virtual Fields activity sort datawithin the non-key fields. When enabled, the values within the multivalue data fields willbe sorted according to the sequence of the indicated “Sortingfields” and their relationships based on the type of sorting (text,binary and ascending, or descending.

Sorting

This is an additional key field (for one or more fields) thatdefines the unique key within a collapsed record. If you choosemore than one field, you can order them in any way you wouldlike.For example, if four orders by single customers are collapsedinto one document with the customer number as the key, andone order is changed, then the order number is required toensure that the correct record is updated. In this example, theorder number is the subkey and provides a uniqueidentification across the individual external records for thiscustomer when it is expanded back to the external data source.

Subkey Fields

DescriptionMulti-Value DataOptions

Multivalue functionality allows activities to group multiple records with acommon key value into a single Notes document. By using multivaluefields, these records can appear, for example, as table data. All records with


the same grouping key field value(s) are combined (collapsed) until adifferent key is encountered. (As an example, to capture this information,you could use Designer to create a two-row table on a Notes form andadding multi-value enabled fields for multivalues, with separator optionsset to ”new line.“)

In all DECS activities, a key must be defined as one or more fields, forexample, ”JOB“ might be defined as the key field. In this case, the DECSactivity document would have ”Key“ value field that is not a unique field.

To enable a DECS activity to work with multivalue data, check the”Multivalue Data“ check box under the ”Options“ section of the DECSactivity document. This expands the section displaying additionalselections. An important option that allows changes to be written back to anexternal data source is the ”Subkey fields“ option. This option makes itpossible for you to select a unique key to identify this individual record inthe external system data.

For example, if six employees are combined (”collapsed“) into onedocument with the job title as the key, and data regarding one employee ischanged, then the employee number is required to ensure that the correctrecord is updated. In this example, the employee number is the sub key andprovides a unique identification across the individual external records forthis employee when it is expanded back to the external data source.

Also note that we have numerous sorting options as well. These optionsallow us to sort the data contained in our combined (”collapsed") records

Finally, be sure to initialize keys. This action (that is, Initializing keys)creates stub documents based on the key field(s) in the DECS activitydocument. These stub documents serve as data containers after the activityis enabled.

Event OptionsThe monitored events are events that occur in the monitored Notes formthat you specified in this activity document. The Create, Open, Update, andDelete sections of the Virtual Fields activity document, provide manyoptions that depend on the type of Event the Virtual Fields activity ismonitoring.

In a Virtual Fields activity document you must choose which events youwant to monitor. The options displayed are specific to the type of event orevents you choose to monitor. You must choose at least one event tomonitor. Each of the options is described in the illustrations and tables onthe following pages.


Note If you select Update, you must also select Open, otherwise the DECSAdministrator will not save the activity.

Document Create OptionsWhen monitoring Document Create Events, several options are availabledepending on the choices you make. A description of the options followsthe illustration.


continued

Enable Procedure Output — This option is available only if astored procedure has been specified in the “Stored Procedure”field. When this option is selected, it opens up the “StoredProcedure Output Mapping” section of the activity document,where you enter input and output field names.This option enables the return of data from a stored procedure inthe external system to the Domino Application (that is, the Notesdocument). The activity’s key(s) and field(s) are supplied to thestored procedure as input parameters. To see the arguments that will be passed to the storedprocedure, type the stored procedure name in this field and thenpress F9. The fields that will be passed to the stored procedureare displayed next to the stored procedure name.Note At present, only the Lotus connector for DB2 supportsoutput parameters.

StoredProcedureOutput

This option executes a stored procedure in the external datasource to store data that has been entered into the Notesdocument. The field(s) are supplied to the stored procedure asinput parameters. To specify the stored procedure and see the parameters that willbe passed to the stored procedure and their order, type thestored procedure name in this field and then press F9. The fieldsthat will be passed to the stored procedure are displayed next tothe stored procedure name. In a Virtual Fields activity this includes the specified key field(s).Note Domino/DECS supports stored procedure browsing.Note See Appendix A for error situations you may encounterusing Sybase or OLEDB stored procedures that return a resultset.

StoredProcedure

This option executes a Notes formula language statement beforethe document data is stored. You can use this option to modifyexisting fields or to compute values for additional fields. Forexample:FIELD LASTNAME:=@if(LASTNAME =“”;“NA”;LASTNAME);“”Note If you are connecting to an Oracle external system andyou must use a text field(s) of fixed length as a key field(s), use aformula filter to pad the specific field to the correct length. Seethe Oracle 7 or 8 connector information in Lotus Connectors andConnectivity Guide for more information.

Pre-CreateFormula

DescriptionCreate Options


Domino Application — Specify the fields in the DominoApplication (Notes document) that will receive the storedprocedure output.Lotus Connection — Specify the fields from the external systemthat contain the stored procedure output. The first field from theexternal system maps to the first destination field, the secondexternal system field to the second destination field, and so on.Note These fields must be specified in the “Mapping” section.

StoredProcedureOutputMapping

DescriptionCreate Options

Document Open OptionsWhen monitoring Document Open Events, several options are availabledepending on the choices you make. A description of the options followsthe illustration.

continued

This option executes a Notes formula immediately after data isretrieved from the external system. You can use this option tocompute additional fields or modify existing fields. For example:FIELD FIRSTNAME := @if(FIRSTNAME =“Al”;“Albert”;FIRSTNAME);“”Note You should not use Post-Open Formulas when usingconflict detection.

Post-OpenFormula

This option executes a Notes formula before the document datais retrieved from the external system. This option provide youwith an opportunity to compute additional fields or modifyexisting fields used as key information, thereby altering dataselection.

Pre-openFormula(Virtual Fieldsonly)

DescriptionOpen Options


These fields are visible only if “Stored Procedure Output” ineither a Create or an Update event has been selected, see eitherCreate or Update event for more information.


If no matching external record is found for a document on open,you can choose what the action should be:Create Record — this option creates a new record in the externaldatabase.Generate Error — this option generates a Notes error messagebox.Ignore — this option ignores the fact that there are no matchingrecord and opens the document even though it contains no data.

MissingExternalRecords(Virtual Fieldsonly)

This option executes a stored procedure in the external datasource to determine the data that will be retrieved into the Notesdocument. To see the arguments that will be passed to the stored procedure,type the name of the stored procedure in this field or select thestored procedure from the drop down list and then press F9. In Virtual Fields, the specified key fields are displayed next tothe stored procedure name. For connectors that support procedure output parameters, thekey fields (in Virtual Fields activities) are passed as input/outputparameters and the other fields are passed as output parameters.Note Domino/DECS supports stored procedure browsing.Note See Appendix A for error situations you may encounterusing Sybase or OLEDB stored procedures that return a resultset.

StoredProcedure

DescriptionOpen Options


Document Update OptionsWhen monitoring Document Update Events, several options are availabledepending on the choices you make. A description of the options followsthe illustration.

continued

When a document is updated, this option executes a storedprocedure in the external data source to update the data related tothe document. The field(s) are supplied to the stored procedure asinput parameters.To specify the stored procedure and see the parameters that willbe passed to the stored procedure and their order, type the storedprocedure name in this field and then press F9. The fields that willbe passed to the stored procedure are displayed next to the storedprocedure name. In a Virtual Fields activity this includes the specified key field(s).Note Domino/DECS supports stored procedure browsing.Note See Appendix A for error situations you may encounterusing Sybase or OLEDB stored procedures that return a result set.

StoredProcedure

When a Notes document is updated, this option executes a Notesformula statement before the data is saved in the externaldatabase.

Pre-UpdateFormula

DescriptionUpdate Options


continued

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 newrecord with the new key added.

�� Ignore — Do not update the key fields in the external datasource. If a key field is edited, the change will be stored withthe Notes document but the key field(s) in the external datasource will not change.

Key FieldUpdates

Only Update Changed Fields — This option causes the VirtualFields activity to not update fields in the external data sourceunless the corresponding fields in the Notes document have beenedited.Use this option if you have triggers in the external system thatmonitor updates to individual columns of a table.

Field LevelUpdates

Check External Data for Changes — This option ensures that theexternal data has not changed since the Notes document wasopened. If it has changed, an update to the external data sourcewill fail. If this option is enabled and if you make changes to data in aNotes document and then save the document, you must exit thedocument before making any more changes — even though youhave saved the document. Note When using an HTTP Server to access documents, “ConflictDetection” is not supported.

Note In a Virtual Fields activity, if you turn on “ConflictDetection” and you connect to a Sybase system, the Sybasedatabase table must be indexed.

ConflictDetection

Enable Procedure Output — This option is available only if astored procedure has been specified in the “Stored Procedure”field. When this option is selected, it opens up the “StoredProcedure Output Mapping” section of the activity document,where you enter input and output field names.This option enables the return of data from a stored procedure inthe external system to the Domino Application (that is, the Notesdocument). The activity’s key(s) and field(s) are supplied to thestored 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. Thefields that will be passed to the stored procedure are displayednext to the stored procedure name.Note Only the Lotus connector for DB2 supports outputparameters.

StoredProcedureOutput



Domino Application — Specify the fields in the DominoApplication (Notes document) that will receive the storedprocedure output.Lotus Connection — Specify the fields from the external systemthat contain the stored procedure output. The first field from theexternal system maps to the first destination field, the secondexternal system field to the second destination field, and so on.Note These fields must be specified in the “Mapping” section.



Document Delete OptionsWhen monitoring Document Deletion Events, several options are availabledepending on the choices you make. A description of the options followsthe illustration.


These fields are visible only if “Stored Procedure Output” ineither a Create or an Update event has been selected, see eitherCreate or Update event for more information.


When a document is deleted this option executes a storedprocedure in the external data source to remove the data relatedto the document. To see the arguments that will be passed to the storedprocedure, type the name of the stored procedure in this field orselect the stored procedure from the drop down list and thenpress F9. In Virtual Fields, the specified key fields are also displayed nextto the stored procedure name. For connectors that support procedure output parameters, thekey fields (in Virtual Fields activities) are passed asinput/output parameters and the other fields are passed asoutput parameters.Note Domino/DECS supports stored procedure browsing.Note See Appendix A for error situations you may encounterusing stored procedures that return a result set with Sybase orOLEDB.

StoredProcedure

Notes formula language statement to execute on the Notesdocument immediately prior to the deletion in the external datasource. Here is an example that sends an email containing informationabout a deleted document: FIELD LASTNAME:=LASTNAME;FIELD FIRSTNAME:=FIRSTNAME;@MailSend(“John Q Public”;“”;“”;“Doc Deleted”;“Doc deletedfrom MyDatabase w/ Firstname/Lastnameof:”;FIRSTNAME:LASTNAME);“”Note It may be necessary to specify that activity data be savedin the Notes document; otherwise, the specified formula mayaccess the field values after they’ve been deleted. If this were thecase for the example above, FIRSTNAME and LASTNAMEwould be empty. To specify that activity data be saved, in theGeneral Options section of the activity form go to “DataStorage,” choose one of the options “Leave all/selected realtimefields in document.”

Pre-DeleteFormula

DescriptionDeletion Options


SchedulingThis section of the document lets you chose what kind of scheduling youwill use for the Virtual Fields activity. A description of the options followsthe illustration.

Manual — Select this option to manually control the activityusing the Start/Stop action bar buttons (available only in theActivity and Folder — Favorites, and so on — views).Auto Start — Select this option to automatically establish thisVirtual Fields activity each time the server starts. The activitycontinues until the server is shut down. The activity’s runningstate can be overridden using the Start/Stop action bar buttons(available only in the Activity and Folder — Favorites, and soon — views).Custom — Select this option to specify at what time and onwhich days the activity should run. When you select thisoption, the “Run Time” and “Run on Days” fields areautomatically displayed (these fields are hidden for Manualand Auto Start). The activity starts at the beginning of thespecified run time and stops at the end of the specified runtime. This option can further be controlled by selecting the dayson which the activity should run. The activity’s running statecan be overridden using the Start/Stop action bar buttons(available only in the Activity and Folder — Favorites, and soon — views). Note If the activity is started with the action bar’s start button,the custom schedule is completely overridden, which is to say,it will not stop at the end of the specified run time.

SchedulingOption

DescriptionOption


Virtual Fields Activity Logging Logging information is available in DECS in the Activity and Folder —Favorites views.

Logged information about DECS operations is available to you when youhighlight the activity and click the Log button in the action bar.

The log lists the time and date when a Virtual Fields activity started andran, and information about any errors that occurred during processing ofthe activity.


Chapter 6Building a Domino Application

This chapter provides information about building a Domino application foruse with a Virtual Fields activity.

Building a Domino Application for a Virtual Fields ActivityThe Domino application being monitored by a Virtual Fields activity mustinclude data fields that map to data fields in the external data source.

In addition, the Virtual Fields activity must include at least one field thatmaps to a key field in the external data source. A key is one or more fieldsthat are used to uniquely identify the data. A Virtual Fields activity caninclude multiple key fields.

The next section gives an example of a Domino application that could beused with a Virtual Fields activity.

63

Example Application Shown below is an application that monitors employee information in anexternal data source.


Example of the Application Design ViewThe illustration below shows the Design view of the example application. Inthis application there are labels next to the data fields; these data fields mapto the data fields in the external data source, see the illustration below.

Note The Virtual Fields activity will map these fields to the fields orcolumns in the external database.

Chapter 6: Building a Domino Application 65

Virtual Fields Activity ExampleShown below is an example of a Virtual Fields activity that uses theexample application. The field mapping in the Mapping section of thedocument maps to the example Domino application above.

Note The key fields must be initialized in the Domino application in orderfor the Virtual Field activity to retrieve the associated information from theexternal database. You may choose to initialize key fields for the VirtualFields activity by selecting “Initialize Keys” from the Action menu orclicking the “Initialize Keys” icon.


Running the Virtual Fields ActivityOnce you have developed a Domino application form and created a VirtualFields activity, you are ready to run the activity.

Note Make certain you have initialized keys.

Select the activity and click on the “Start” icon. Press F9 until the activityicon shows that it is running.

• To view a document, open the Notes view that displays the key fordocuments whose form you are monitoring and click on one of them.When the document opens you should see data that is fetched from theexternal database.

• To update a document, open the Notes view that displays the key fordocuments whose form you are monitoring and click on the documentyou want to update and change the values as needed. Save thedocument. The changes will be reflected in the external database.

• To delete a document, open the Notes view that displays the key fordocuments whose form you are monitoring and select the documentyou want to delete and press Delete. The changes will be reflected inthe external database.

• To create a document, open the Notes view that displays the key fordocuments whose form you are monitoring and choose Create -<form_name> from the Main menu and fill in the fields. Then save thedocument. The changes will be reflected in the external database.

The next chapter describes options that you can use to refine a VirtualFields activity.

Chapter 6: Building a Domino Application 67

Chapter 7Using Virtual Fields Activity Options

This chapter provides examples of Virtual Fields Activities that utilize theoptions available in the Virtual Fields activity document. It covers thesetopics:

• Using Filter Formulas

• Using Data Storage Options

• Using the Monitor Orders Option

• Using Stored Procedures in Sybase/SQL

• Using a DB2 Stored Procedure

• Using an Oracle Stored Procedure

Using the Options in a Virtual Fields Activity DocumentThis section provides examples of Virtual Fields Activities that utilize theoptions available in the Virtual Fields activity document. It covers thesetopics:

• Using Filter Formulas

• Using Data Storage Options

• Using the Monitor Orders Option

• Using Stored Procedures in Sybase/SQL

• Using a DB2 Stored Procedure

• Using an Oracle Stored Procedure

Using Filter Formulas This section provides examples of how you would use the Filter Formulaoption in conjunction with the Monitor Order option to achieve specificresults.

Note If a document is created that does not match the filter criteria, it isnot inserted into the external table (hence, it is not “processed”). Instead, itis saved locally in the .nsf regardless of the “Data Storage” setting.

69

Saving Data to an External Data SystemScenario: Suppose you want to store data from a Notes document in anexternal data system, such as a DB2 or Oracle database, when the documentdata 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 Virtual Fields activitythat monitors the Notes application.

In the Virtual Fields activity, you would use a filter formula that includesonly documents that have been marked “Published.”

At that point the information from the Notes document will be written tothe DB2 database, where it would be available to other applications. Anydocuments that are still “under review” will not be stored in DB2.

Accessing Different External Sources using the Same NotesApplication

Scenario 1: Suppose you want to use a single Notes front end to interactwith information that is potentially in two different tables. For example, theNorth East sales information is in a different table than the South Westregion.

In this case, you would set up one Virtual Fields activity for each regionwith different external data sources, but using one Notes document as thefront end.

You could use a filter formula that would detect the region of informationand the account request and go to the appropriate external system data.

Scenario 2: Suppose that you have two product catalogs in differentdatabases, but you want to present the data through the same front endNotes application. You want to use a single Notes front end, but dependenton a field, you want to control where the data is coming from.

Set up identical Virtual Fields activities monitoring a single Notesapplication, but have each Virtual Fields activity use a filter formula tohandle part of the request.


Using Data Storage Options This section provides some examples of how and when you would use theData Storage options in Virtual Fields Activities.

Building ViewsAny data that you want to use when building views must reside in theNotes document. Use the option “Leave selected real-time fields indocuments.” When you select this option, you can choose the fields that youwant to reference in a view from the list of available fields.

Storing a Static Copy of External DataIf you want to store a static copy of the external data, you would select“Leave all real-time fields in documents.” Note that if the external datachanges, the data in the document is not updated until the document isreopened.

Using the Monitor Orders OptionIn this scenario, assume that the external data for your Notes HumanResources Information system is in multiple tables. A “join” of the data isrequired to tie these various tables together to populate the single EmployeeInformation form in the Notes application. In some cases, a join from thedatabase may not be possible, because the tables may reside in differentdatabases (one in Oracle, one in Sybase, for example). Information in theEmployee Information form includes Employee Name, Department Nameand Location Information. The following table explains which fields areused from which table and how they will relate to the Notes form.

Fields Used:

LocName…

Location

LocCodeDeptLocDepartmentLoc(may be hidden)

DeptNameDepartment

DeptNoDeptNoDepartmentNo(may be hidden)

EmployeeNameEmpName

EmployeeIDEmpID

LOCATION Table(access with monitororder 3)

DEPARTMENT Table(access with monitororder 2)

EMPLOYEETable

Employee InformationForm

Chapter 7: Using Virtual Fields Activity Options 71

How to Configure: To do this join, you will create three Virtual Fieldsactivities that each monitor separate tables: one to monitor the Employeetable, one to monitor the Department Table and one to monitor the LocationTable.

The first activity (using a Monitor Order of 1) will provide data that will beused by the other activities (with Monitor Orders of 2 and 3) as “keys” totheir tables. The Notes Form “Employee Information” will need to containthose fields that will act as “keys” to the secondary tables. These fields maybe “hidden” from the user. If you expect updates to be made through theNotes application to these secondary tables, select the Option “Leaveselected Virtual Fields fields in Documents” and list all the fields which areused as keys to the external system (DeptmentNo, DepartmentLoc).

Note Activities with monitor orders of 2, 3, 4, and so on, must monitor anOpen event. They may monitor other events too, but one of the events mustbe an Open event. Depending on the nature of the activity, the activity withmonitor order 1 may be required to monitor an Open event as well.

1. Create a Connection document for each of the external data sources:one for the employee table, one for the department table, one for thelocation table.

2. Create a Virtual Fields activity based on the Employee InformationForm and the Employee Table. Select all fields that will be used by theform and/or used as a key to another field. In this case, select at leastthe following: EmployeeName, DepartmentNo.

DeptNoDepartmentNo

EmployeeID as the keyEmpID as the key

Employee TableNotes

3. Create a second Virtual Fields activity based on the EmployeeInformation Form and the Department Table. Select the followingfields:

DeptNameDepartment

Deptno as the keyDepartmentNo as the key

Department TableNotes

Caution Set the Monitor Order for this activity to 2. This allows thefirst activity to retrieve the information from the employee table beforelooking into the department table for the DeptName field.


4. The third activity works like the second, except it monitors the LocationTable. It will use a monitor order of 3 because its lookup depends oninformation provided by the second Activity.

LocNameLocation

LocCode as the keyDepartmentLoc as the key

Location TableNotes

Using Stored Procedures in Sybase/SQLThis section provides an example of a Virtual Fields activity that uses storedprocedures with a Sybase external data source or a SQL (using Sybase)external data source.

Preliminary SetupSybase and OLEDB normally return a result set from a stored procedure,which DECS “sees” as if it were a result set from a table or view. Because ofthis, when setting up an Activity using a Stored Procedure, you must do thefollowing:

1. Create the DECS Sybase Connection Document by selecting table, notprocedure.

2. Use or create a table containing the exact column names returned by thestored procedure, and use this in the mapping process in the DECSActivity.

3. Identify the stored procedure to use in the Activity Options under theappropriate “When Intercepting a document” section.

There are separate sections for the Open, Create, Update, and Delete events,and separate stored procedures are needed for each event to performfunctions specific to that event. When DECS is activated, the storedprocedure is used, overriding the field mapping.

Note For additional information, see “Stored Procedures in Sybase orOLEDB” in the Appendix.

Sybase/SQL Stored Procedure ExampleIn this example there are four stored procedures for the table addrbook inSybase. When using these stored procedures, the key fields used must beFirstName then LastName, and the mapped fields must be (MailDomain,MailServer, MailAddress, CompanyName, and State). The storedprocedures, table name and fields must use the correct case since Sybase iscase sensitive.


To use a stored procedure, enter the name of the stored procedure in theoptions section for the appropriate event in the Virtual Fields activitydocument. In this example, these would be:

Create: QEInsertaddrbook Open: QESelectaddrbookUpdate: QEUpdateaddrbook Delete: QEDeleteaddrbook

The following illustration of a Virtual Fields activity document shows howthese stored procedures are entered in the Stored Procedure fields of thecorresponding document event options. The next section, “Testing theStored Procedures in Sybase/SQ,” contains an example of how you can testthe stored procedures directly in SQL through the database client.


If you use stored procedure output parameter mapping, be sure to fill in thefields on the activity form. The illustration below shows the outputparameters fields filled in.

Testing the Stored Procedures in Sybase/SQLThe examples below show how you would execute the stored procedures inSQL through the database client, in this case Sybase. You can test that thestored procedures work properly by executing them directly as shownbelow.

execute QEInsertaddrbook ’OurDomain’, ’ThisServer’, ’OurAddress’, ’OpenResearch’, ’NH’, ‘Adelino’, ’Fontes’

execute QESelectaddrbook ‘Adelino’, ’Fontes’

execute QEUpdateaddrbook ’OurDomain’, ’ThisServer’, ’OurAddress’,’Open Research’, ’NH’, ‘Adelino’, ’Fontes’

execute QEDeleteaddrbook ‘Adelino’,’Fontes’

Stored Procedure DefinitionsBelow are the actual stored procedure definitions used in the precedingexample. Note that these are Sybase procedures; stored procedures forother data sources may be different.

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)

)

as

INSERT INTO addrbook


(FirstName,LastName,

MailDomain, MailServer,

MailAddress, CompanyName,State)

VALUES

(@FirstName, @LastName,

@MailDomain, @MailServer,

@MailAddress, @CompanyName, @State)

create procedure dbo.QESelectaddrbook(


@LastName varchar(20)

)

as

select FirstName,LastName,

MailDomain, MailServer, MailAddress,

CompanyName,State from addrbook

WHERE FirstName = @FirstName and

LastName = @LastName

create procedure dbo.QEUpdateaddrbook(


@LastName varchar(20),

@MailDomain varchar(20),

@MailServer varchar(20),

@MailAddress varchar(20),

@CompanyName varchar(20),

@State varchar(20)

)

as

UPDATE addrbook SET

MailDomain=@MailDomain, MailServer=@MailServer,

MailAddress=@MailAddress,

CompanyName=@CompanyName, State=@State


WHERE

FirstName=@FirstName and LastName=@LastName

create procedure dbo.QEDeleteaddrbook(


@LastName varchar(20)

)

as

DELETE FROM addrbook

WHERE FirstName=@FirstName and LastName=@LastName

Using a DB2 Stored ProcedureA DB2 stored procedure may be used wherever procedures are allowed in aVirtual Field activity and within an LSX script. The stored procedure beingcalled must have its parameters set up correctly for the call. Input andoutput values are provided to DB2 procedures as named parameters. Thisrequires that the parameters in DB2 use the same names as the fields beingprovided as the parameters unless explicitly mapped in the activity. Theparameters being provided include key values when being used in thecontext of a keyed operation (selection, update, or delete contexts), and datavalues when relevant (insert or update contexts). The DB2 parameter datatypes should be selected as the closest match to the data type in the LC API.

Any result set output from a DB2 stored procedure must be returnedthrough a DB2 cursor left open in the stored procedure. The result set in thiscursor will become the result set produced by the stored procedure. TheDB2 Connector supports the return of output parameters from storedprocedures. The following scenarios describe what is returned from astored procedure call:

•If the stored procedure returns a result set only, the Connector will returnthat result set fieldlist.

• If the stored procedure returns multiple result sets, the Connector willreturn the first result set fieldlist only.

• If the stored procedure returns output parameters only, the Connectorwill return a fieldlist of those output parameters.

• If the stored procedure returns output parameters and a result set, theConnector will return a fieldlist of the output parameters only.


• If the stored procedure returns output parameters and multiple resultsets, the Connector will return a fieldlist of the output parameters only.

The DB2 Connector will not return multiple fieldlists in any scenario and afieldlist of output parameters will always have return precedence.

Stored procedure in DB2 can be written in Java, C, and C++. DB2 UniversalDatabase versions 6.1 and 7.1 provide a Stored Procedure Builder withwhich to create procedures easier. The version 7.1 Builder also allowsstored procedures in SQL. Below is an example of a simple SQL storedprocedure.

CREATE PROCEDURE DB2ADMIN.NEW_SALES_ORDER ( IN CUSTID int,

IN ITEMID int,

IN QTY int,

OUT SONUM bigint)

LANGUAGE SQL

P1: BEGIN

DECLARE CUSTVAR int;

DECLARE ITEMVAR int;

DECLARE QTYVAR int;

DECLARE ITEMCOSTVAR dec(7,2);

DECLARE AMTVAR dec(9,2);

DECLARE STAMP timestamp;

DECLARE cursor1 CURSOR FOR

SELECT ITEMCOST FROM DB2ADMIN.ITEMS

WHERE ITEMID = ITEMVAR;

DECLARE cursor2 CURSOR FOR

SELECT SONUM FROM DB2ADMIN.SALES_ORDERS

WHERE DTEORD = STAMP;

SET CUSTVAR = CUSTID;

SET ITEMVAR = ITEMID;

SET QTYVAR = QTY;

SET STAMP = CURRENT TIMESTAMP;

OPEN cursor1;

FETCH FROM cursor1 INTO ITEMCOSTVAR;


CLOSE cursor1;

SET AMTVAR = QTY * ITEMCOSTVAR;

INSERT INTO DB2ADMIN.SALES_ORDERS (CUSTID, ITEMID, QTY,AMT, DTEORD)

VALUES (CUSTVAR, ITEMVAR, QTYVAR, AMTVAR, STAMP);

OPEN cursor2;

FETCH FROM cursor2 INTO SONUM;

CLOSE cursor2;

END P1

Using an Oracle Stored ProcedureAn Oracle stored procedure can be used in a Virtual Fields Notes activity orwith an LC LSX script. However, the stored procedure being called musthave its parameters set up correctly for the call.

When you browse for a stored procedure in the Connection document, youare presented with dialog box listing all the stored procedures in theexternal system database. When you choose a stored procedure, theparameters of the chosen stored procedure are automatically listed in theConnection Document. If you do not specify a stored procedure in theConnection document, you can select a stored procedure and its associatedparameters from the Virtual Fields activity document. In either case, thestored procedure is entered as the default stored procedure in the ActivityEvents that you selected in the stored procedure field, followed by its list ofparameters. In most cases returned values are handled by the externalsystem database, in the case of Oracle, the Oracle connector handlesreturned information. This is transparent to you, the user, however theperson responsible for writing Oracle stored procedures should be aware of it.

Input Values and Named ParametersInput values are provided to Oracle procedures as named parameters. Thisrequires that the parameters in Oracle use the same names as the fieldsbeing provided as input values. The inputs being provided include keyvalues when they are used in the context of a keyed operation (selection,update, or delete context), and data values when relevant (insert or deletecontext). The input value data types provided by the Oracle connector areselected 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, aslong as the conversion is supported by Oracle.

Output ParametersOracle differs from other RDBMS connectors in that there is no way toreturn a result set from a procedure. Therefore, the Oracle connectorsupports output parameters as a way of returning results from a storedprocedure. This requires additional information to be available at the timethe procedure is called, specifically the context of the call and the outputparameter names. This information will be automatically provided byVirtual Fields activities, but must be manually specified when callingOracle procedures from an LC LSX script. The context indicates whether theprocedure should expect and specify output parameters, and the parameternames are provided as a property of the procedure call request to theOracle connector. The output parameters must be standard data types -rowsets may not be returned. This restricts the result set from an Oracleprocedure to a single row. Any parameters that are indicated as inputparameters and are also in the output parameter list will be provided asinput/output parameters.

The following is an example of an Oracle stored procedure body. This is theformat that would be required for the Open event of a Virtual Fields Notesactivity assuming that the key field is called NUMBER1 and the data fieldsare called NUMBER2, TEXT1, and TEXT2. In this context, the key field isthe input parameter, and the result set is expected to include the data fieldsand the key field. To accommodate the fact that one of the outputparameter names is the same as a key value in the select statement, theparameter keys should be copied to local variables to avoid scopingproblems in the procedure.

(NUMBER2 out tablename.number2%TYPE,

TEXT1 out tablename.text1%TYPE,

TEXT2 out tablename.text2%TYPE,

NUMBER1 in out tablename.number1%TYPE)

IS

BEGIN

DECLARE number1_request tablename.number1%TYPE := number1;

BEGIN

SELECT t.NUMBER2, t.TEXT1, t.TEXT2, t.NUMBER1

INTO number2, text1, text2, number1

FROM tablename t


WHERE t.NUMBER1 = number1_request;

END;

END;


Chapter 8Virtual Fields and Dynamic Queries

This chapter provides information on how to use DECS to create VirtualFields Activities that enable dynamic, on-demand queries to external datasources.

Overview of Virtual Fields Dynamic QueriesThe DECS Virtual Fields activity enables a Domino database form toprovide direct access to external data sources supported by DECS. TheVirtual Fields activity form requires that one or more key field values beheld in common with the Notes form (accessed by the Notes client or Webbrowser client) and the external system. It is the key field(s), entered intothe Notes form, that controls the query of the external data.

Normally, the Virtual Fields activity requires that the key field(s) exist inthe Notes key document (that is, a document containing nothing but a keyfield) as well as the external data source. In this configuration, the Notes orWeb client would open the form that has the appropriate key field valueyou want to use to query additional external data. There are, however,many situations where the key field value will not already be availablewithin a Notes document. In such cases, clients want to freely insert the keyvalue when they open the Notes forms.

The Virtual Fields activity can be set to allow Web and Notes client endusers to open Notes application forms and enter key values to Notes formfields then dynamically trigger DECS. These entries are then sent via theDomino DECS server to query the external data source. As an example, acustomer with a package tracking number opens a Notes form using a Webbrowser, enters the tracking number to the Domino server Web form, then,using a button on the form, submits the new document to the Dominoserver. The button causes the document to be saved and then reopens thenew document. Virtual Fields activity detects the open event and uses thetracking number to query the source database, which locates the packageinformation using the tracking number as a key. The matching recordresults are inserted into the Notes document and sent back to the client Webbrowser, which displays the status of the package, in real time.

83

The next sections provide information required for defining the VirtualFields activity and preparing Notes application forms to accept dynamicdata queries from Web clients and Notes clients.

Virtual Fields Dynamic Queries from Web Clients This section provides information about using your Web client to invoke aVirtual Fields activity that accepts a key value input for querying anexternal data source. This extends the functionality of the Virtual Fieldsactivity to provide a dynamic query capability.

Overview of Steps1. 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 tobe displayed to the user accessing the Domino server through a Webclient.) This form includes the fields that you want populated from theexternal system database. Also include one or more key fields, in whichthe user will enter values to be used to locate the correct external data.The appearance of the application form may be improved by using theNotes form design option of the “Hide paragraph when…” propertybox. In the example, the form is broken into three primary sections. Thetop of the form is always displayed. The input field, input help, and“Locate” button only display when the document is in Edit mode. Thedata fields only display when the document is in read mode. In ourexample, the key field is “PackageID”.

2. Next, include one hidden field in the form:

$$Return field - A computed for display only field of type “text” thatspecifies the URL for the new document returned once the query datahas been input and “Locate” button has been selected.

3. Within the overall Web application, create a URL link to the applicationform (for more information on specifying URLs to Notes databases andforms, see the Notes Application Developer’s Guide). In our example, weprovide an “About” page for the database that contains the URL linkfor the application form.

4. Define a DECS Virtual Fields activity that monitors the Notes databaseand the form defined in step 1 above. This form should include the keyand data fields you defined in step 1 above.


5. Access the Domino Lookup form from a Web browser. Type in atracking number (PackageID field). When the Locate button is selected,the document is saved in the database and the $$Return text is passedto the Domino HTTP process. This results in the new document beingre-opened. The Virtual Fields Notes Connection is activated, taking thekey value, from the PackageID field, submitted in the form. ThePackageID value is then sent to the external system, and the tablerecords are searched according to the PackageID value. Results of thesearch are sent back through DECS and inserted into the document. Thedocument is then sent from the Domino server to the Web client asdirected by the URL specified in the $$Return field.

What is visible in the formUsing the “Hide paragraph when…” properties, different sections of theform appear under different conditions. See the illustration below as youread the following bullets.

• Section 1 is always displayed.

• Section 2, including the input field, the button, and the help text, onlyappears 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 Readmode and, referencing the “status” field, when no data has beeninserted into the document from the Virtual Fields activity.

• Section 5 contains the data inserted by DECS and only displays in Readmode and, once again referencing the “status” field, when data exists.

Chapter 8: Virtual Fields and Dynamic Queries 85

Example of Virtual Fields Dynamic Queries from Notes Clients 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 Virtual Fields key (orthat there is a column formula if you use more than one key field). This keyor formula value will be used in place of the bold italicized text in step 4.This example uses a single key field called DocKey.

1. Edit your Notes form.

2. Identify the Virtual Fields key(s) field.

3. Add a button to the Notes form.

4. Add the following formula to the button.


@Command([FileSave]);

@Command([FileOpenDatabase]; @DbName; “Keys”; DocKey);

@Command([OpenDocument])

Note Substitute your view name for the “Keys” text in the aboveformula. Substitute the Virtual Fields key you are using for the“DocKey” text in the above formula (or formula text if you use morethat one key). Note that the text you use in place of the “DocKey” textmust match the key or column formula of the view. This button is usedto reference the view represented by the “Keys” text in this example.

5. Optionally, you can use hide formulas to make the button and keyfield(s) display when composing a new document and all fields displaywhen opening an existing document.

6. Save the form.

7. With Virtual Fields running, compose a document. Clicking the buttonwill save the document with the new key and reopen it, displaying theVirtual Fields data. This has an added side effect of allowing the user tojump back to compose the form and change the key. Pressing the buttonlocates a different document.

Chapter 8: Virtual Fields and Dynamic Queries 87

Appendix AConfiguration and Troubleshooting

This appendix provides information about INI variables, error messages,and known problems that you may encounter under certain conditionswhile using DECS.

NOTES.INI Variables The following entries may be added to the notes.ini file to control DECS:

DECSTranslation: This controls text translation, allowing the user toincrease performance in exchange for certain assumptions about the databeing accessed. Note that none of these settings affects translation betweenUnicode and other character sets, since it is always required. There are threevalid numeric settings:

0 Do not perform translation between character sets (except Unicode).This is valid when all data being accessed is compatible with the NotesLMBCS 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 forNotes 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 beoverridden. There are various situations when the native character set isused within DECS, and some back-end systems always consider client datato be in the native character set. Setting this value to a valid text formatstring replaces the character set obtained from the operating system byDECS with the indicated character set. Appendix D of the LSX LCdocumentation (LSXLCDOC.NSF) lists the supported character sets. Usethe text that remains after removing the “LCSTREAMFMT_” prefix. Forexample, Code Page 932, represented by the constantLCSTREAMFMT_IBMCP932, would be set as follows:

DECSNativeText=IBMCP932.

RTMaxEntries: This functionality has been added to DECS to allow supportfor more than 128 concurrent activities. To increase the maximum numberof realtime activities which can run concurrently, add “RTMaxEntries=” to

89

the notes.ini file and assign it an integer value to indicate the new upperlimit. If a line already exists, edit its value to the new setting. The lowerlimit is 128 active activities; a value less than 128 will not change the limitbelow 128. If the number of activities started exceeds the specified value inthe notes.ini file, DECS displays a warning message and subsequentactivities will not be started.

Configuration and TroubleshootingThis sections provides information about INI variables, error messages, andknown problems that you may encounter under certain conditions whileusing DECS.

It consists of the following topics:

• NOTES.INI Variables

• Security Issues

• Considerations When Domino/Notes is installed as an NT Service

• Using DECS Virtual Fields Activities in a Clustered Domino ServerEnvironment

• Error When Attempting to use Stored Procedures in Sybase or OLEDB

• Unable to Access Data After Upgrading

• Error Messages

Security IssuesBrowsing or running a LotusScript agent that makes use of the LotusConnectors extensions (lclsx), such as the Initialize Keys utility (run whenyou click “Initialize Keys”), requires use of operating system levelfunctions to access files and/or external database clients. To do this theagents must have permission to run as unrestricted agents.

SolutionsIf you are using DECS:

• Add the ID “Enterprise Connection Products/Notes CompanionProducts” to the “Run Unrestricted Agents” field in the DominoServer's entry in the Domino Directory containing that server. This fieldis found under the Security tab.


• Resign the DECS Administrator database with a Notes ID whichalready has permission to run unrestricted agents. Resign the DECSAdministrator through the Domino Administrator client, not throughthe normal Notes client.

If you are writing LotusScript code that uses the LC LSX (Lotus ConnectorLotusScript Extensions) against the Notes or File connectors

• Agents or other LotusScript code, which uses the Notes or Fileconnectors, must be signed with a Notes ID that has permission to rununrestricted agents. This also applies to any script libraries used by thiscode. Specifically, connections through these connectors will be blockedwith an error unless the signing Notes ID has permission to rununrestricted agents.

Considerations when Domino/Notes is Installed as an NT ServiceWhen a Notes/Domino Server is started as an NT Service, Notes/Dominousers cannot access Database/Directory Links which are at locations otherthan the local NT Server. Applications installed as a Service begin executionbefore the user is prompted to log in at the NT Server.

Therefore when Notes/Domino starts up and it is installed as a Service, anymapped drives that the NT Server may have set up are not yet reconnectedat the point when the Notes/Domino Server is started. Notes/DominoServer will only recognize drives that are available when it is first started,and any drives that are mapped after Notes/Domino server has started arenot recognized. Therefore any directory/database links that point tomapped drives on other computers will not function properly ifNotes/Domino Server is started as a Service.

The solution for this set of circumstance is to not install Notes/Domino as aService. When Notes/Domino is not installed as a Service, but is Launchedfrom the “Start Menu” or from a Desktop Shortcut, a user must bephysically logged in at the NT Server, because the user has to log in at theserver, all Network drives mappings will have been established be whenthe Notes/Domino server is launched and any directory/database linksthat are beyond the local server function correctly.

Appendix A: Configuration and Troubleshooting 91

Using DECS Virtual Fields Activities in a Clustered Domino ServerEnvironment

DECS Virtual Fields activities can be used to great advantage in a clusteredDomino server environment. This brief overview of how replication worksin a clustered Domino server environment will help you to understand howDECS Virtual Fields activities take advantage of a clustered configuration.Refer to Domino documentation for information on how to set up clusteredDomino servers.

When using DECS Virtual Fields activities with clustered Domino serversDECS must be installed on each server and identical RealTime connectionsand activities must exist in each DECS administrator and be enabled. DECSVirtual Fields will then intercept events in the monitored Domino formsand perform the requested read, write, updates or deletes on the externaldatabase.

Caution DECS is not currently supported on more than one server ofpartitioned Domino servers.

Domino ReplicationDomino replication keeps copies of a database up to date with one anotherwhen they reside on different servers. Domino Replication is managed by aprocess on one designated server which synchronizes the databases on theothers.

Domino Replication in a Clustered Environment Clustered replication works by a process on each of the Domino servers inthe cluster, monitoring databases on the server for changes, keeping aqueue of these changes in memory, and calling the replication routines topush those changes to other clustered servers with replication copies of thedatabase. If one or more of the target clustered servers is down, the sourceserver will retry at increasing intervals until it is successful. If the sourceserver crashes, the queue in memory is lost.

Lotus recommends that clustered replication be supplemented by periodicscheduled replication, so that the scheduled replication will pick upchanges that may be lost if a server crashes. Note that a cluster replicatormust be running on all servers to push changes in all directions. There is no“Pull” in cluster replication. The processes involved are pushing, receiving,and indexing.


DECS Virtual Fields Activities in a Clustered EnvironmentDECS Virtual Fields works by loading a management module for eachprocess through the ExtMgr_AddIn parameter in the notes.ini. Thisintercepts database operations and, when DECS Virtual Fields activitieshave been started, address real-time requests through operations on theexternal database. To operate correctly, DECS Virtual Fields activities mustbe started from the DECS administrator on all servers to intercept real-timeevents in all replicas. When this is done, DECS Virtual Fields intercepts boththe Domino database read on the source server and the database write onthe Domino target servers.

To prevent unwanted duplication of inserts, updates or deletes to theexternal database when the Domino databases are replicated from clusteredserver to clustered server, DECS Virtual Fields will add additionalinformation to the records as they are replicated to indicate that therequested action has already been done. This information does not alter thedocuments in anyway.

Note For DECS Virtual Fields to work as expected on clustered Dominoservers the DECS Virtual Fields activity and Connection documents must beidentical on all the servers. The least error-prone way to do this is to copyand paste from one to another. It is also recommended that after you pastethe documents, you should open the documents for editing and save themto ensure all computed fields are correct.

Stored Procedures in Sybase or OLE DBWhen attempting to create a DECS Activity that uses stored procedures inSybase or OLE DB, you may find that the fields cannot be mapped, and thefollowing error displays:

“Both the notes and connection data field list must contain at least onevalue.”

The Procedure can be selected, but the Activity cannot be completed orsaved.


SolutionSybase and OLE DB normally return a result set from a stored procedure,which DECS recognizes as if it were a result set from a table or view.Because of this, when setting up an Activity using a Stored Procedure, youmust do the following:

1. Create the DECS Sybase Connection Document by selecting Table, notProcedure.

2. Use or create a table containing the exact column names returned by thestored procedure, and use this in the mapping process in the DECSActivity.

3. Identify the stored procedure to use in the Activity Options under theappropriate “When intercepting a document” section.

There are separate sections for the Open, Create, Update, and Delete events,and separate stored procedures are needed for each event to performfunctions specific to that event. When DECS is activated, the storedprocedure is used, overriding the field mapping.

Example of how to set up an Activity with Sybase using StoredProcedures:In the following example, assume that you have a Notes form with twofields, Key1 and Lastname, and that you have Sybase table(s) with manyfields.

In addition, assume you have a stored procedure that accepts one inputparameter and returns a result set with Key1, Lastname columns.

Finally, assume that you have an activity that returns data based on theOpen event.

You will need to create a Sybase table, a stored procedure, and set up aDECS activity.

The Sybase TableFirst, create a Sybase table (for example dbo.proctable) that has columnsmade up of what you are ultimately mapping (the input parameter and theresult set that your procedure uses).

For instance, in this example the dummy table would contain the followingcolumns:

Key1 varchar(5)

Lastname varchar(25)

Or, if there is a table that already exists that has the exact fieldnames/datatypes, you can use that table.


The Stored ProcedureThe Procedure takes input (the same as what you selected for the DECSkey), and returns a result set, that includes the key and all mapped fields inthe DECS Activity:

CREATE PROCEDURE dbo.proc1

(@Key1 varchar(5) )

AS

BEGIN

select Key1, Lastname from debtest

where Key1 = @Key1

END

Note If you are working with Sybase, keep in mind that Sybase isgenerally case sensitive, but the @var (@Key1) in the Proc must have thesame name AND match case with your Sybase column and DECS mappedkey. Sybase will accept a different name/case if you execute the procedurefrom an SQL tool, using Execute <Procedure>, but DECS needs thename/case to be the same or it will return the error below:

03:48:27 PM DECS: Monitor failure — Error: Procedure proc1 expectsparameter @key1, which was not supplied., Connector 'sybase', Method-Call- (201): proctest

Sybase DocumentIn the Sybase Connection Document used in this example, Table wasselected, not Procedure. Procedure is valid only if you are returning allvalues using output parameters, as is done with Oracle, for example.

DECS ActivityIn the DECS Activity used in this example, dbo.proctable is a table createdspecifically with the fields required for mapping. Once the events areselected, specify the procedure to be used under the Options, as shown(proc1). After inputting the procedure name, if you press F9, it will refreshand show the input parameter that the procedure requires (Key1).

At this point, DECS returns the values in the mapped fields to the Formbeing monitored. To use other events, create procedures appropriate to theevent.

Note Since the stored procedure does not return all key values, “Initializekeys” does not work with this functionality — it does not “see” the contentsof a table or view. If key documents are required in Notes, create them viaan agent, or by a separate DECS Activity that pulls those key values intoNotes documents.


Unable to Access Data After UpgradingIf after upgrading DECS, you discover you are unable to get data when youare running Virtual Fields activities, you may have to open each VirtualFields activity document and ensure that the Domino Server chosen in theactivity document is correct.

Error Messages

Cannot use field [‘FIELDNAME’] as both a key and a data fieldFields provided for RealTime activities must be either key fields or datafields - a field cannot be used as both in a single Virtual Fields Activity(although one field can be used as a key in one activity, and data in anotheractivity). Remove any field that is used as both a key field and a data fieldfrom at least one of those lists.

Failure accessing shared RealTime Activities tableAn internal error was encountered when attempting to access activityinformation. Record as much information as possible about thecircumstances and contact Lotus technical support.

Failure encountered in monitoring process — ERROR MESSAGEErrors that are generated by the RealTime monitors in the Domino serverare logged with this prefix. The complete error text from the RealTime erroris appended.

Unexpected internal failure in RealTime monitoringAn internal error was encountered when attempting to access contextinformation. Record as much information as possible about thecircumstances and contact Lotus technical support.

Update of key field [‘FIELDNAME’] is not permittedKey values in a document were altered, but the Virtual Fields Activityindicated that changes to key fields should be blocked. Updates to bothNotes and the back-end system were aborted.


This record has changed in the back-end database since being opened— action cancelled

The Virtual Fields Activity option to check the external system for changesbefore writing changes to the back end was enabled, and the checkindicated changes in the back end. Since the document was opened, anothersystem or client changed the corresponding external record.

Cannot locate corresponding external recordThe key values in the opened document being monitored by a Virtual FieldsActivity did not correspond to a record in the external system. This errorcan be suppressed by selecting the Virtual Fields Activity option to createthe external record if it doesn’t exist — instead of the error, a new recordcorresponding to the current Notes document data will be created.

Failure compiling Filter Formula: FORMULA COMPILATION ERRORThe filter formula provided for the Virtual Fields Activity failedcompilation. The compilation error is generated with the error message. Fixor remove the filter formula to successfully run the Virtual Fields Activity.

Failure compiling Pre-Open Formula: FORMULA COMPILATIONERROR

The pre-open formula provided for the Virtual Fields Activity failedcompilation. The compilation error is generated with the error message. Fixor remove the pre-open formula to successfully run the Virtual FieldsActivity.

Failure compiling Post-Update Formula: FORMULA COMPILATIONERROR

The post-update formula provided for the Virtual Fields Activity failedcompilation. The compilation error is generated with the error message. Fixor remove the post-update formula to successfully run the Virtual FieldsActivity.

Failure compiling Post-Create Formula: FORMULA COMPILATIONERROR

The post-create formula provided for the Virtual Fields Activity failedcompilation. The compilation error is generated with the error message. Fixor remove the post-create formula to successfully run the Virtual FieldsActivity.


Failure compiling Post-Delete Formula: FORMULA COMPILATIONERROR

The post-delete formula provided for the Virtual Fields Activity failedcompilation. The compilation error is generated with the error message. Fixor remove the post-delete formula to successfully run the Virtual FieldsActivity.

Unknown OS error: libdecsext.*This is a Notes error reporting that Notes couldn’t load the DECS extensionmanager library. Check that you have properly installed and configuredDECS. If problems persist, contact technical support.

Realtime service addin task initialization failedThis indicates that the LEI addin task startup encountered an error. Checkthat you have properly installed and configured LEI. If problems persist,contact Lotus software technical support.

Realtime service is unable to allocate addin task resourcesThe Realtime Service is unable to allocate additional resources. Check thatyou have properly installed and configured LEI. If problems persist, contactLotus software technical support.

Realtime service cannot connect to external systemYou may not have the proper connectivity software installed that isrequired for accessing the external data system. Refer to the Lotus EnterpriseIntegrator Installation Guide for information about the native softwarerequired for connectivity to each of the LEI supported data sources.

Realtime service cannot find external table/metadataThe metadata selected for this activity does not exist in the back end datasource.

Realtime service cannot find external procedure/transactionThe document open event captured by LEI encountered an error. The errordetails are logged to the Domino server log.

Realtime service error retrieving external recordThe document open event captured by LEI encountered an error. The errordetails are logged to the Administrator activity log for this activity.


Realtime service error inserting external recordThe document creation event captured by LEI encountered an error. Theerror details are logged to the Administrator activity log for this activity.

Realtime service error updating external recordThe document update event captured by LEI encountered an error. Theerror details are logged to the Administrator activity log for this activity.

Realtime service error deleting external recordThe document deletion event captured by LEI encountered an error. Theerror details are logged to the Administrator activity log for this activity.

Realtime service cannot locate the corresponding record in theexternal system

The document key field values do not correspond to a record in the backend data source. The record in the external data system may have beendeleted.

Realtime service unable to update document due to key field changes;changes to key fields have been disabled

The key fields in the external data have been modified since the documenthas been opened. To allow key field changes, select the appropriate settingfor the option Key Field Updates in the Document Update options sectionof the Activity Document.

Realtime service is unable to update document due to conflict; theexternal record has been modified since being opened

The external data has been modified by another application since thedocument has been opened. Close and reopen the document.

Realtime service error storing external attachmentThere was a problem storing the attachment portion of the document to theexternal data store.

Realtime service error retrieving external attachmentThere was a problem retrieving the attachment portion of the documentfrom the external data store.

Realtime service cannot locate the attachment in the external systemThere was a problem locating the attachment portion of the document inthe external data store.


Realtime service data overflow accessing external recordFor document Open events, this indicates that data in an external field wastoo 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 Administratoractivity log for this activity for information on which field caused theoverflow.)

For document updates and inserts, this message indicates that thedocument data overflowed a back end field. You may need to change thedata type in the back end to store large amounts of data.

Realtime service encountered invalid or corrupt Notes data in theexternal system

Information not yet available.

Realtime service error deleting external attachmentThere was a problem deleting the attachment portion of the document fromthe external data store.

Realtime service error browsing the external systemThere was a problem retrieving information about the names of tables in thedatabase, or retrieving the datatype information about the columns in aparticular table.

Realtime service encountered an invalid external field configuration inform

Information not yet available.

Realtime service encountered a missing or invalid Data ConnectionResource

You get this message when you are using the Domino Designer DataConnection Resource (DCR). The Data Connection Resource that wasreferred to by one or more of the fields on the form is not valid, or could notbe located.

Realtime service error scanning the external system. Some externalrecords may have been ignored

During a view refresh, an error occurred when retrieving documentinformation from the external data store.

Realtime service error loading external agents/design elementsAn error occurred while accessing a virtual agent.


Realtime service error retrieving external agent/design elementInformation not yet available.

Realtime service error writing external agent/design elementInformation not yet available.

Realtime service error deleting external agent/design elementInformation not yet available.

This application uses a Realtime Service Activity which is currentlynot running. Contact your Notes administrator.

During an attempt to open or delete a document, a needed running VirtualFields Activity could not be found. Verify that the activity monitoring thisdatabase form is running. If so, fully refresh your view (SHIFT-F9) in thepossibility that the external data source record has been deleted. Also checkthe activity log for any additional error information.


AAccess Control List (ACL)

and DECS, 6Accessibility

in DECS, 3Accessing Different External

Sources, 70ACL

See Access Control ListAction bar

Activities view, 12Connections view, 12Favorites view, 15

ActivitiesView, 9, 12

Activityadd, 13log, 13start, 13stop, 13Virtual Fields, description, 2, 25

Activity Icons, 14, 31Activity Logging

in Virtual Fields and Documentsactivites, 62

Activity Wizardintroduction, 29

Addactivity, 13

AdministratorDECS, 9replacing design when

upgrading, 6

BBuilding a Notes Application

and using Virtual Attachments, 63

CClustered Domino Server

Environmentand DECS, 92

Computed Subformsin Virtual Fields, 39

Conflict detectiondo not use with HTTP server, 28limitations of this option, 58

Connectionadd, 12

Connection documentcreating, 19definition, 19fields, 21options, 21

ConnectionsView, 9, 12

CreateVirtual Fields or Virtual

Documents Activity using theWizard, 31

Virtual Fields or VirtualDocuments Activity withoutusing the Wizard, 40

Create optionsin Virtual Fields and Documents

activities, 53

DData sources

supported, 3Data Storage Options

in Virtual Fields, 71DECS

Administrator, 9Administrator navigator, 9and accessibility, 3and clustered Domino server

environment, 92and the Access Control List

(ACL), 6installing, 5uninstalling, 7

upgrading to DECS 6, 6DECS Administrator

adding an empty, 7menu commands, 17replacing design when

upgrading, 6DECS Name and Address Book

access, 30DECS Virtual Fields

introduction, 2Deletion Options

in Virtual Fields and Documentsactivities, 59

Disablinguser assistant, 30

Domino/Notesconsideration when installed as

an NT Sevice, 91Dynamic Queries

example using Notes client andVirtual Fields, 86

in Virtual Fields activities, 83overview of use in Virtual

Field, 83

EEnable Subforms

in Virtual Fields, 39, 42Error Messages

for Advanced RealTime activities,96

Event Optionsin Virtual Fields and Documents

activities, 52External Data System

saving data to using VirtualFields, 70

FFavorites

folder or view, 9View, 15

Filter Formulas

103

Index

example of using in VirtualFields, 69

Formto monitor, 33

Form Overridein Virtual Fields activities, 33, 42

GGeneral Options, Event Options,

Scheduling, and Loggingfor Virtual Fields or

Documents, 44

HHTTP Server

do not use with ConflictDetection, 28

in Virtual Fields Activities, 28

IIcon

activities view, 9activity, 14, 31Assistant (Wizard), 10connections view, 9favorites view, 9help, 10info, 9running, 10Wizard, 10

Indexingin Virtual Fields, 28key fields in Virtual Fields

activities, 28Initialize Keys

in Virtual Fields, 49Installing

DECS, 5

KKey documents, 26

how they work, 27Key field

datatypes in Virtual FieldsActivities, 28

LLimitations

current, 6Log

activity, 13LotusScript Agents

running unrestricted, 7

MManual button, 23Mapped key fields

indexing in Virtual Fieldsactivities, 28

Menu commandsDECS Administrator, 17

Monitorform, 33

Monitor all formsVirtual Fields option, 42

Monitor Orderand multiple Virtual Fields

activities, 26Monitor Orders Option

using in Virtual Fields, 71Multi-Value Data

in Virtual Fields, 50

NName and Address Book

access, 30of DECS server and access, 5

Navigator, 9Notes Clients

example of dynamic queriesusing Virtual Fields activities, 86

NOTRES.INI variables, 89NT Service

and Domino/Notes, 91

OOLE DB Connector

mapping key fields in VirtualFields activities, 36, 43

OLEDBissues when using stored

procedures, 93OLEDB Connection Document

select Table when using storedprocedures, 73, 94

Open optionsin Virtual Fields and Documents

activities, 55Options

connection document, 21

examples of using in a VirtualFields activity document, 69

Scheduling in Virtual Fields andDocuments activities, 61

Oracle Stored Procedureexample used with Virtual

Fields, 79input and named parameters, 79output parameters, 80

PPassword, 21Performance, 28, 29Privileges

lack of: results in not seeing data, 27

ProcessVirtual Fields or Documents

activity, 40, 44

RRealTime activity

See Virtual Fields activityReplication id

and Virtual Fields andDocuments, 32, 41

SScheduling


Selection Type, 21Start

activity, 13Stop

activity, 13Stored procedure, 23

Sybase/SQL example, 73using DB2 stored procedures in

Virtual Fields Activities, 77using Oracle stored procedures in

Virtual Fields Activities, 79Stored Procedure Definitions

examples used in Virtual Fields, 75

Stored procedureserrors when attempting to use

Sybase or OLEDB storedprocedures with VirtualFields, 93


testing DB2 in Virtual Fieldsactivities, 77

testing SQL in Virtual Fieldsactivities, 75

use table in Sybase/SQL, 73using Sybase and SQL stored

procedures in Virtual Fields, 73

Stub documentsSee key documents

Subformsenable, 39

Supported Data Sources, 3Sybase

issues when using storedprocedures, 93

Sybase Connection Documentselect Table when using stored

procedures, 73, 94

TTroubleshooting

Inability to get data after anupgrade, 96

UUNID

as key field, 36Uninstalling

DECS, 7Update options


Updatingneed for write permission, 37

Upgradingto DECS 6, 6troubleshooting inability to get

data, 96User assistant

disabling, 30turning on, 29

VView

Activities, 9, 12by Domino Application, 13Connections, 9, 12Favorites, 9, 15

Views, 9Virtual Documents

Activity Logging, 62building a Notes Application that

uses Virtual Attachments, 63delete options, 59document create options, 53document open options, 55Event Options, 52General Options, Event Options,

Scheduling, and Logging, 44update options, 57

Virtual FieldsActivity Logging, 62building a Notes Application that

uses Virtual Attachments, 63building views in, 71delete options, 59document create options, 53document open options, 55dynamic queries, 83dynamic queries Notes clients,

examples, 86dynamic queries from Web

clients, examples, 84dynamic queries, examples, 83Event Options, 52general options, 45General Options, Event Options,

Scheduling, and Logging, 44initialize keys, 49multi-value data, 50update options, 57

Virtual Fields Activitiesaccessing different external

sources, 70and clustered Domino server

environment, 92and monitor order, 26data storage options, 71description, 2, 25examples of using the activity

options, 69filter formula, example of

using, 69saving data to external system, 70storing a static copy of external

data, 71testing stored procedures in

SQL, 75using an Oracle Stored

Procedure, 79using Sybase and SQL stored

procedures, 73using the monitor orders

option, 71

WWeb sites

DECS, viLEI, viPTFs, vi

Wizardturning off, 30turning on, 29using to create a connection

document, 19using to create a Virtual Fields or

Documents activity, 31Write permission

needed when updating, 37

Index 105