HEI Tutorial

Applicable version

HCL Enterprise Integrator for Domino 9.x, 10.x, 11.x, 12.x

Foreword

Contains tutorials for creating some activities for HEI (HCL(R) Enterprise Integrator). Use
these tutorials to learn more about how to create HEI activities.

explanation

Tutorial overview

The tutorials in this appendix walk you through several HEI (HCL(R) Enterprise Integrator)
activities and how to create the connections that the activities use. Each tutorial uses the
sample HCL(R) Notes(R) database that comes with HEI.

It also uses an existing Notes database as a source connection. A target connection can be any
Lotus Connector in the specified environment. When transferring or replicating data from a
Notes database to a target database, HEI creates new metadata objects (tables or Notes
forms).

This appendix covers the following tasks:

Create a Command activity

Create an activity that sets up and executes a SQL statement to create the table you will use
later in the tutorial.

Create a Direct Transfer activity

Create an activity that transfers data from the sample Notes database to the specified target
database.

Create a Polling Activity

Create an activity that polls a sample Notes database and executes a Direct Transfer activity
when a condition is met.

Create a Replication Activity

Create an activity that replicates the sample Notes database to the specified database.
Create a Scripted Activity

Create an activity that uses the two agents provided with the HEI Script Vault in combination
with the leipackagetrack.nsf sample database.

The activity you create is an activity that executes LotusScript commands that extend the data
transfer functionality.

Creating Advanced RealTime Activities

Create activities that monitor data from external systems in real time from your Notes
application.

Create an activity that dynamically queries from Lotus Notes or a web browser.

Other Advanced RealTime Examples

Create a Virtual Fields or Virtual Documents activity that uses Virtual Attachments.

Virtual Fields activities use filter expressions, Data Storage options, Monitor Order options,
and stored procedures.

After creating the example above, the activity will continue to run as scheduled. After
completing the tutorial, disable or delete the activity schedule as needed.

prerequisite

These tutorials are intended for users with an introductory understanding of Lotus Notes. See
the Lotus Notes online help if needed.

We also assume that you have HEI installed on your system and have installed all the
software required to connect to your system's data sources.

Finally, the tutorials are step-by-step. Create the following activities based on the activities
and connections created at the beginning of this appendix.

Before you start

To begin the tutorial, you need an HEI (HCL(R) Enterprise Integrator) Administrator
database and a log database on the HCL(R) Notes(R) Client.

You also need to know on which server the HEI sample databases leiempsamp.nsf,
leipackagetrack.nsf, and HEI Script Vault are located. A sample database is installed with
HEI. These databases are installed on the HEI Server computer, but must be copied to the
Notes Server. Add these databases to your Lotus Notes desktop as well, as you will be
modifying them in the tutorial exercises.

Make sure the HEI Server is running and able to communicate with any external data sources
you use. See the IBM(R) HEI (Lotus(R) Enterprise Integrator) Installation Guide for
connection requirements and testing connections to data sources.
Create a Command activity

This section describes how to create a Command activity. It also sets up and executes the
SQL statements that create the tables used later in the tutorial and provides general
instructions. The main steps to execute a Command activity are:

1 Create a connection.

2 Create a Command activity.

3 Do this activity.

4 View logs.

Step 1: Create a Connection Document

Before creating an activity, you need to create the connection that the activity will use. A
connection defines access to a database that HEI (HCL(R) Enterprise Integrator) interacts
with. A Command activity only requires a source database connection.

Note Establish a connection to the database you want to use first. For instructions, see the
Lotus Connectors Connectivity Guide .

create a connection

The Connection Documents you create are determined by the target database you need. To
create a connection, follow these steps:

1 In HEI Administrator, click Add Connection. Select the target database type from the list
that appears.

Note Metadata is created in this target database to store the transferred data.

2 In the Name field, enter Sample 1 Destination.

3 Fill in the rest of the information as needed to complete the document. Be sure to enter the
database location. You may also be required to enter the username and password you use for
access.

4 Enter the category name Samples.

5 Save and close the document.

This Connection Document name now appears in the Connections view.

View connections

The Activities and Connections views display activities and connections by name. You can
also view these by category. To view your connections by category:
 1 In the HEI Administrator navigator panel, expand Activities by Type. Click By Category
to expand the Samples category type.

2 Expand the Link subcategory to see the Sample 1 Destination connection you created.

Note To edit a displayed connection, double-click the connection name to open the
corresponding Connection Document. Press Ctrl+E or double-click the connection document
to switch to edit mode.

Step 2: Create a Command Activity

After defining the connection, you can create a Command activity that executes a SQL
statement to create the target table. Follow these steps to create a Command activity:

1 If creating from the HEI Administrator, click [Add Activity] and select Command from
the displayed list.

2 Enter the activity name Sample Command in the Name field.

3 Select a connection by clicking the down arrow button in the Connection Name field and
using the list of available connections, or placing the cursor inside the Connection Name field
and pressing Enter. . Select Sample 1 Destination.

4 In the Command Statement field, specify the SQL statement to use. This statement can be
a SQL query or a file system command like "cp -p file.txt file2.txt". For example, enter the
following SQL statement that corresponds to your selected target:

For DB2(R) or Oracle(R). CREATE TABLE EMPLOYEES (EMPNO INT, ENAME

VARCHAR(32), JOB VARCHAR(32), MGR INT, HIREDATE DATE, SAL INT, COMM
INT, DEPTNO INT)

For SQL Server, Microsoft(R)Access, or Sybase(R). CREATE TABLE EMPLOYEES

(EMPNO INT, ENAME VARCHAR(32), JOB VARCHAR(32), MGR INT, HIREDATE
DATETIME, SAL INT, COMM INT, DEPTNO INT)

5 The SQL statement creates a table related to the Notes form Emps with the same
documents as this statement.

6 Enter the category name Samples.

7 Save and close the Command Activity document.

Since we didn't enable scheduling the activity when we save and close the document, this
activity must be launched manually.

Step 3: Run the Activity

Start an activity and use the Active view to view activity status. To start an activity and view
the list of running activities, follow these steps:
 1 From the HEI Administrator, expand Activities by Type. Choose By Category and expand
the Samples category type in the view.

2 Expand the Activity subcategory to view the activities you created.

3 Select the Sample Command activity created in step 2 and click Start.

You can also run an activity by clicking Start at the top of an open Activity document.

View activity status

You can view the activity status in one of the following ways:

In the Navigator panel of the HEI Administrator, click By Type under Activities. All existing
activity names and current status are displayed.

From the HEI Administrator navigator panel, expand Activities by Type. Click Data
Management to see a detailed list of all activities and status.

From the HEI Administrator navigator panel, expand Activities by Type. Click By
Category. Click a category type. For example, click Command to see only the status of
Command activities.

If you don't see the list for a particular activity, press F9 periodically to refresh the view until
you see the activity name. If you don't see a list of activities when you press F9, it's likely that
the activity has completed. If so, view the log to see information about the activity that has
been performed.

Step 4: View Logs

The HEI log records the processing status and results of each activity. You can view activity
logs in one of the following ways:

Click View Log in an open Activity Document.

Select an activity in the Activity view and click Log in the action bar.

From the HEI Administrator navigator, click [Log].

When you open a log from an activity document, you see log entries from the last time you
ran that activity. In this example, the activity is complete, so with the Sample Command
activity selected in the Activities view, click Log in the action bar at the top of the Activities
view.

Create a Direct Transfer activity

This section describes how to create a Direct Transfer activity. Provides general instructions
for setting up and performing data transfer from one Notes database to another.
The main steps to perform a Direct Transfer activity are:

1 Create a connection.

2 Create a Direct Transfer activity.

3 Do this activity.

4 View logs.

Step 1: Create a Connection Document

Before creating an activity, you need to create the connection that the activity will use. A
connection defines access to a database that HEI (HCL(R) Enterprise Integrator) interacts
with. A Direct Transfer activity requires a source database connection and a target database
connection.

Note Establish a connection to the database you want to use first. For instructions, see the
Lotus Connectors Connectivity Guide .

Create a source connection

In this example, the source connection is the sample HCLR) Notes(R) database
leiempsamp.nsf in the help directory. Follow these steps to create a source connection:

1 Start Notes and open the HEI Administrator database, decsadm.nsf.

2 In HEI Administrator, click Add Connection > Connection to Notes.

3 In the Name field, enter a name to identify the connection. When creating a Direct
Transfer activity, select a connection by this name. Here, enter Sample 1 Source.

4 Enter the name of the Notes Server where the Notes database leiempsamp.nsf is
located. Leave this field blank if the database is local.

5 Enter leiempsamp.nsf for the Notes database name.

6 Enter the category name Samples. By assigning this category to the sample documents,
you can manage the documents by category. Familiarity with the use of category names here
will be helpful when working with HEI.

7 Save and close the document.

Create a target connection

Depending on which database you choose to output to, you create different Target
Connection Documents. To create a connection, follow these steps:

1 In HEI Administrator, click Add Connection. Select the target database type from the list
that appears.
Note Metadata is created in this database to store the transferred data.

2 In the Name field, enter Sample 1 Destination.

3 Fill in the rest of the information as needed to complete the document. Be sure to enter the
database location. You may also be required to enter the username and password you use for
access.

4 Enter the category name Samples.

5 Save and close the document.

You have now created two Connection Documents. Verify in the Connections view that the
document has been created.

View connections

The Activities and Connections views display activities and connections by name. You can
also view these by category. To view your connections by category:

1 From the HEI Administrator navigator, expand Activities by Type. Click By Category to
expand the Samples category type.

2 Expand the Link subcategory to reveal the Sample 1 Source and Sample 1 Destination
connections you created.

Note To edit a displayed connection, double-click the document name in the view, then
press Ctrl+E or double-click within the document to enter edit mode.

Step 2: Create a Direct Transfer Activity

After defining the source and target connections, you can create Direct Transfer activities that
transfer data from one database to another. Follow these steps to create a Direct Transfer
activity:

1 In the HEI Administrator, click Add Activity and select Direct Transfer from the
displayed list.

2 Enter the activity name Sample Transfer in the Name field.

3 Specify source and target connections.

Click the arrow button in the Connection Name field, or place your cursor inside the field and
press Enter.

From the list of connections displayed, select Sample 1 Source.

Do the same for the Target Connection Name field and select Sample 1 Destination.

4 In the Source Form field, enter the Notes form name Emps.
 5 In the Target Table field, enter the table name Employees.

6 In the Select Statement field, enter the statement that selects the data to transfer. The
statement can be a SQL query or a selection formula (for Notes source databases).

For example, enter the following Lotus Notes formula: SELECT @ALL

This formula creates a result set with the same documents as the Notes form Emps.

7 In the Field Mapping section, select Automatic and make sure By Name is selected.

8 Click the Target Data Options tab.

9 In the Existing Data Options section, enable the Create Target Metadata option to create a
new table to store the transferred data. Leave the other options as is.

Enter the category name 10 Samples.

11 Save and close the document.

You have now completed creating a Direct Transfer activity.

Since we did not enable scheduling the activity when the document is closed, this activity
must be launched manually.

Step 3: Run the Activity

Then manually start the activity and use the Active view to view the status of the activity. To
launch an activity and view a list of running activities, follow these steps:

1 From the HEI Administrator, expand Activities by Type. Click By Category and expand
the Samples category type in the view.

2 Expand the Activity subcategory to view the activities you created.

3 Select the Sample Transfer activity created in step 2 and click Start.

You can also run the activity by clicking Start at the top of the actual Activity document.

View activity status

There are three main ways to view activity status:

In the HEI Administrator navigator, click By Type under Activities. All existing activity
names and current status are displayed.

From the HEI Administrator navigator panel, expand Activities by Type. Click Data
Management to see a detailed list of all existing activities and their current status.
From the HEI Administrator navigator panel, expand Activities by Type. Click By
Category. Click a category type (such as Direct Transfer) to view the current status of Direct
Transfer activities only.

If you don't see the list for a particular activity, press F9 periodically to refresh the view until
you see the activity name. If you don't see a list of activities when you press F9, it's likely that
the activity has completed. If so, view the log to see information about the activity that has
been performed.

Step 4: View Logs

The HEI log records the processing status and results of each activity.

There are three ways to view logs:

By clicking the View Log button on an individual Activity Document.

Select an activity in the Activity view and click Log in the action bar.

From the HEI Administrator navigator, click [Log].

Note When you open a log from an activity document, you see log entries from the last time
you ran that activity.

In this example, the activity has completed, so with the Sample Transfer Direct Transfer
activity selected in the Activities view, click the Log button in the action bar at the top of the
Activities view.

Create a Polling Activity

This section describes how to create a Polling activity. Polling is a method of starting one or
more activities based on some condition. The Polling Activity periodically checks the
specified database to see if certain conditions are met. If the conditions are met, the Polling
activity will execute the other activities. A Polling activity acts as a trigger for other
activities.

This tutorial uses the Polling activity as a trigger for the Direct Transfer activity.

Step 1: Create a Polling Activity

A Polling Activity requires a connection that specifies the database to poll. Here we will use
the existing connection Sample 1 Source instead of creating a new connection.

Schedule the Polling activity to run every day from 8:00 am to 5:00 pm. Polls the database
every minutes during this time.

Follow these steps to create a Polling Activity:

 1 In the HEI Administrator, click Add Activity. Select Polling from the displayed list.

2 Enter the activity name Sample Polling in the Name field.

3 Select the connection named Sample 1 Source to specify the database to poll.

Note This connection was created in the previous section called "Creating a Direct Transfer
Activity". If you haven't created one yet, follow the steps in the previous section to create
one.

4 Enter Emps in the Table or Form Name section directly below the Connection Name field.

5 Enter SELECT HIREDATE=@TODAY in the Trigger Statement. There are currently no

records that meet this criteria, but we will add records that meet this criteria after creating the
activity.

6 Leave the polling frequency unchanged to poll every 10 seconds.

Note This value does not specify when the Polling activity will actually run. You set when it
runs like any other activity with a schedule.

7 Under Activities to Execute, select the activity named Sample Transfer. Under Activities
to Execute, select the activity named Sample Transfer.

Note This activity was created in the previous section called "Creating a Direct Transfer
Activity". If you haven't created one yet, follow the steps in the previous section to create
one.

8 For this example, leave the Reset Trigger as is.

9 Click the Error Handling Options tab and enter 1 for Maximum Event Count. Do not
change any other options.

Note This value specifies the maximum number of times the activity will be executed if the
specified condition is met before the activity ends. If the condition is met and the activity is
executed as one event, there is no upper limit to the number of times the event can be
executed.

10 Optionally, click the Activity Execution Options tab and specify the HEI Server on which
to run the activity. Do not change any other options.

11 Click the Scheduling tab and set the Schedule field to Schedule Enabled.

Note For Polling activities, schedules work a little differently than for other activities. Other
activities end when they are done processing. A Polling Activity will continue to run (and
poll) once started unless otherwise configured. So you don't need to set the Repeat Interval
(how often you want the activity to run) value to be shorter than the duration of the
schedule. For this example, we will define the schedule period as 8:00 am to 5:00 pm every
day by following these steps:
12 By default, the Repeat Interval is set to 60 minutes. Change this to 1 day.

13 Enter 8:00 AM - 5:00 PM in the Run at Times field. The activity will run at this time. If
you set the Repeat Interval to 1 day, the activity will start polling at 8:00 am and finish at
5:00 pm. Also, polling is done every minute according to the Polling Frequency set earlier.

Note If you specify a time other than the above, use a range that includes the current time.

14 Enter the category name Samples.

15 Save and close the document.

16 View the Samples Polling activity using the By Category display option.

In the next section we will create a new record. This record satisfies the polling conditions
and executes the Sample Transfer.

Step 2: Meet Polling Conditions

To satisfy polling conditions and have a Polling activity launch another activity, follow these
steps:

1 Open the sample database leiempsamp.nsf in the help directory.

2 Create a new document in the sample database by selecting Create - Emps from the Lotus
Notes menu.

3 Enter the following information into the form.

EMPNO 7790

ENAME NNOTES

JOB ENGINEER

MGR 7791

HIREDATE 9/12/01 (enter today's date)

SAL 1000

COMM

DEPTNO 72

Note Creating this document satisfies the following polling conditions: SELECT
HIREDATE = @TODAY.
4 Save and close the form.

5 Start an activity.

6 Check in the HEI Administrator that the activity successfully started the Sample
Transfer. Also view the logs to check the status of the activity.

Note Polling activities are stopped manually and continue to run until the schedule is
disabled.

Step 3: Clean up the sample

The created connections and activities can be deleted after exhausting the above
examples. You can also disable activities and reuse them later.

Delete Connection Documents and Activity Documents in the Samples category

1 In the HEI Administrator, click By Category.

2 Click the Samples arrow to view its contents. Continue viewing subcategories until you
see the name of a sample activity.

3 Select the document you want to delete and press Delete or press Ctrl+X.

4 Exiting the view deletes the document.

Disable the Sample Activity Document

1 In the HEI (HCL(R) Enterprise Integrator) Administrator, display [By Category].

2 Click the Samples arrow to view its contents. Continue viewing subcategories until you
see the name of a sample activity.

3 Select the first activity to disable.

4 Press Ctrl+E to edit the document.

5 On the Scheduling tab, change the Schedule field to Schedule Disabled.

6 Save and close the activity.

Create a Replication Activity

This section provides instructions for setting up and running database replication. We will use
the HEI (HCL(R) Enterprise Integrator) sample database leiempsamp.nsf and another
database of your choice.

The type of replication in this example is called Next Key. This replication method
compares one or more key fields in the source database (source) with key fields in the
destination (target). This replication uses key fields to compare records and determine
whether to perform an update, insert, or delete operation during replication. If the primary
keys of both records match, the record will be updated (assuming the data in the other fields
do not match) If the primary key exists only on the source side, the insert will be performed
on the row If it is only on the target side, it will be deleted.

Step 1: Prepare the database

This example uses the same database as the previous tutorial (Creating a Polling
Activity). Add a document to the sample HCL(R) Notes(R) database to see how replication
works. Records are replicated to the other database.

1 Using the Lotus Notes desktop, open the supplied sample database leiempsamp.nsf.

2 Create a new document in the sample database by selecting Create - Emps from the Lotus
Notes menu.

3 Enter the following information into the form.

EMPNO 6627

ENAME JNOTES
JOB ENGINEER

MGR 6628

HIREDATE Today's date

SAL 1000

COMM 0.05

DEPTNO 70

4 Save and close the form.

Step 2: Create a connection

Create a connection to a Notes database and another database. Specifies the source database
(replicate this database) when creating a Replication activity.

Create a source connection

This first connection is to the source database. To create a connection, follow these steps:

1 In HEI Administrator, click Add Connection > Connection to Notes.

2 Enter Sample 2 Master in the Name field.

3 Enter the Domino Server name where the sample database is located.

4 Enter the name of the sample Notes database leiempsamp.nsf located in the help directory.

5 Enter Samples in the Category field.

6 Leave all other options at their default values.

7 Save and close the document.

Create a target connection

This second connection identifies the target database. In this example, the data in the target is
updated as a result of replication. To create a connection, follow these steps:

1 In HEI Administrator, click Add Connection.

2 From the list that appears, select the type of database you want to use and click OK.

3 Enter Sample 2 Updated DB in the Name field.

4 Enter the name of the database to update with information from the source database. In
our example, this database will be named CurrentEmployeeData.nsf. This database was
created as a copy of the included sample database leiempsamp.nsf and resides on the local
HEI Server.

5 Enter Samples in the Category field.

6 Leave all other options at their default values.

7 Save and close the document.

Step 3: Create a Replication Activity

After creating the two connections, create an activity that replicates the source database. Data
is replicated at the table level (form level in Lotus Notes).

In this example, we set the activity to run every hour during a limited time period.

Follow these steps to create a Replication activity:

1 In the HEI Administrator, click Add Activity. Select Replication from the displayed list.

2 Enter Sample Replication in the Name field.

3 Specify Sample 2 Master in the Source Connection field.

4 Enter Sample 2 Updated DB in the Target Connection field.

5 Specify a form name for both connections. Enter Emps for the source connection and
Sample1 for the target connection.

6 Enable the option for automatic field mapping.

7 Enter Empno as the Source key value.

8 Enter Empno as the target key value.

 9 Enable mapping in the Name option.

10 If the specified database stores the modification time of records in a timestamp field, you
can identify that field to perform Next Key/Timestamp replication. For this example, leave
Timestamp Replication unselected.

11 Click the Data Options tab and select Reduced-precision Comparison.

Note If the precision of datetime or floating-point values differs between the source and
target databases, the comparison may not be correct. When this option is selected,
comparisons are made using only the common parts of precision. That is, dates are compared
down to the second, and floating point values are compared up to 10 digits.

12. For Conditional Clause for Source, enter a Lotus Notes expression or SQL WHERE
clause that filters the result set. For this example, leave this field blank. Do not enter a
conditional clause.

13 Optionally, click the Activity Execution Options tab and specify the HEI Server on which
to run the activity. If not specified, leave these options at their default values.

14 Click the Scheduling tab and select Run Activity Once and Disable. If you select this
option, replication runs only once and is automatically disabled after that.

15 Change the Schedule field to Schedule Enabled.

16 Specify the date and time for the activity to run. For example:

Enter 7:00 AM - 5:00 PM in the Run at Times field. The activity will run at this time.

Set replication to run every hour. Enter 60 in the Repeat Interval field and select Minutes.

Deselect the days of the week for today and tomorrow by clicking the arrow buttons in the
Days of Week field.

With this setting, the activity will not run until 7:00 AM the day after tomorrow.

17 Enter Samples in the Category field.

18 Leave all other options at their default values.

19 Save and close the document.

Check Activity Status and Run Activities

Check the activity status in the HEI Administrator.

1 In the HEI Administrator navigator, click Active.

2 Search for the activity you created (Sample Replication).

3 Select that activity.

4 Select Start in the HEI Administrator.

Note You can test the activity and the specified scheduling settings before actually running
the activity by selecting Trial Run Replication within the activity document.

5 Press F9 periodically to refresh the view until the activity is complete.

Once the note activity is complete, it is scheduled to run the day after tomorrow (Thursday
in this example) at 7:00 am. The Run Activity Once and Disable option is only relevant for
scheduled runs.
 6 Open the target database to see the changed data based on the contents of the source
database.

Create a Scripted Activity

This section describes how to create Scripted activities. Describes how to configure and run
activities that run LotusScript(R) agents.

Agents can be composed of one or more simple actions or expressions that manipulate data in
a database, custom LotusScript commands that perform various functions, Java(R)
statements, and advanced functionality to HEI (HCLR) Enterprise Integrator) activities that
you create. functions can be added.

Example 1

This example demonstrates how to access, edit, and use two supplied scripts (agents) stored
in the HEI (HCL(R) Enterprise Integrator) Script Vault. Both scripts access the Package
Tracking sample database (leipackagetrack.nsf) shipped with HEI.

The first script does a direct transfer from the DATA form in leipackagetrack.nsf, creates this
data and inserts it into a new form or table (depending on the target).

The second script performs keyed replication between the two tables in the Direct Transfer
activity.

There are two ways to access the included scripted agent:

Open HEI Script Vault from HCL(R) Notes(R).

Right-click and select Open from the menu that appears. Select your server and select HEI
Script Vault. An icon will appear on your desktop. Right-click that icon and select Open in
Designer.

Select File - Open - Lotus Notes Application from the Lotus Notes top bar. In the menu that
appears, specify the server name and name of the .nsf file (or database icon) and click
Open. Once the database is open, select View - Design to open the HCL Domino(R)
Designer. Select Agent in the Domino Designer navigator.

Launch Domino Designer and open the HEI Script Vault.

Select File - Open - Lotus Notes Application from the Domino Designer top bar. In the menu
that appears, specify the server name and the name of the .nsf file (or database icon) and click
Open. Expand the Shared Code section in the Domino Designer navigator and select Agent.

To see the agent's code, double-click the agent name in Domino Designer. Codes fall into the
categories Options, Declarations, Initialize, and Terminate.

Step 1: Create a Connection Document

In this step, you will create Connection Documents to the source and target databases. In this
case, the source database is the Package Tracking database (leipackagetrack.nsf) and the
target database is the sample Employee database (leiempsamp.nsf).

Create a source connection

1 In HEI Administrator, click Add Connection > Connection to Notes.

2 Enter Packagetracking in the Name field.

3 If desired, enter the name of your server in the Notes Server field. Leave blank to use a
local server.

4 Specify leipackagetrack.nsf for the Notes database file name.

5 Leave all other options at their default values.

6 Save and close the document.

Create a target connection

1 In HEI Administrator, click Activities > Add Connection > Connection to Notes > OK.

2 Enter myNotes in the Name field.

3 If desired, enter the name of your server in the Notes Server field. Leave blank to use a
local server.

4 Enter leiempsamp.nsf for the Notes database file name.

5 Save and close the document.

Step 2: Create a Direct Transfer Activity

1 Select File - Open - Lotus Notes Application from the Lotus Notes top bar to open the
Package Tracking database. Specify the server name and leipackagetrack.nsf file name from
the menu that appears and click Open.
 2 Click the All Documents view. Use the information in the "data" key.

3 Open the HEI Script Vault in Domino Designer.

4 Double-click the PackageTrack Direct Transfer agent.

Note Code for the specified agent falls into the categories Options, Declarations, Initialize,
and Terminate. The [Declarations] section contains all relevant information required for the
agent to run properly (such as the name of the source connection document). The script itself
is written in the [Initialize] section. Comments can be added if necessary.

5 Now create a Scripted activity to call the LSX agent. In the HEI Administrator, click [Add
Activity] - [Scripted].

6 In the Name field, enter Direct Transfer.

7 In the Agent Server field, enter the name of your server. Leave this field blank if the
server is local.

8 In the Agent Database field, enter HEIvlt6.nsf. HEIvlt6.nsf is the HEI Script Vault
database.

9 In the Agent Name field, enter Package Tracking Direct Transfer.

10 Enter Samples in the Category field.

11 Leave all other options at their default values.

12 Save and close the document.

13 Start the activity.

14 Check the HEI log to see that 8 records were fetched from all connections (source) and 8
records were inserted into all connections (target).
Step 3: Perform primary key replication

This script replicates from the leipackagetrack.nsf database to the leiempsamp.nsf

database. The script used in this procedure is called "PackageTrack Primary Key Replication"
and can be viewed in Domino Designer.

1 Open the leipackagetrack.nsf database in your Notes client.

2 Click Create>Package.

The following form will appear.

3 Add information to the Package Tracking Data input form.

4 Save and close the document.

5 Click [Add Activity] - [Scripted] in the HEI Administrator to create a Scripted activity
that calls this script.

6 Enter Replication in the Name field.

 7 In the Agent Server field, enter the name of your server. Leave this field blank if the
server is local.

8 In the Agent Database field, enter HEIvlt6.nsf.

9 In the Agent Name field, enter Package Tracking Primary Key Replication.

10 Enter Samples in the Category field.

11 Leave all other options at their default values.

12 Save and close the document.

13 Start the activity.

14 Check the HEI log. Observe that 17 records were fetched from all connections (source
and target) and 1 record was inserted into all connections (target).
Example 2

This example demonstrates how to use the Scripted activity to perform simple actions on data
in the sample database leiempsamp.nsf.

Step 1: Create an Agent

There are ways to create an agent in the database leiempsamp.nsf. In leiempsamp.nsf, click
Create - Agent from the Lotus Notes menu, or click the Create Agent button when creating a
Scripted Activity Document. Here we create the agent when creating the activity.

1 Create a new Scripted activity using the HEI Administrator.

2 Enter Scripted ActivityA in the Name field.

3 Click the Create Agent button at the top of the document.

4 If the default server name has been deleted, a dialog box will appear. In this dialog box
enter the name of the server where the database leiempsamp.nsf is located.

5 A dialog box appears prompting you to enter the database name in which to create the
agent. Enter leiempsamp.nsf.

6 A new agent window will appear.

7 Enter Job Script in the Name field.

 8 In the Runtime Target field, specify all documents in the database.

9 Close the properties box.

10 Click the Add Action button at the bottom of the window. An Add Action box appears.

11 Specify Modify Field in the Action field.

12 In the Field field, specify JOB.

13 In the Value field, specify ENGINEER.

14 Select Replace value.

This will change the value of the JOB field for each document in the leiempsamp.nsf
database.

15 Click OK.

16 Save and close the agent. The leiempsamp.nsf database remains open.

Step 2: Complete the Scripted Activity Document

1 Press Esc to return to the Scripted Activity you are creating.

2 Click the button in the Agent Name field and select Job Script from the list.

Note If you want a specific HEI Server to run this activity, specify the server under
Designated Server on the Activity Execution Options tab.

3 Enter Samples in the Category field .

 4 Leave all other options at their default values.

5 Save and close the document.

Step 3: Start the Activity

To run the activity and see it in the view, follow these steps:

1 View the Activity Samples category in the HEI Administrator.

2 Select the Scripted activity you created (Scripted ActivityA).

3 Click Start in the HEI Administrator.

4 You can confirm that the execution of Scripted ActivityA has started.

Step 4: View Logs and Activity Results

1 After the activity completes, select the activity's name in the HEI Administrator and click
Log. Activity is logged as "Started" and "Finished".

2 Open the leiempsamp.nsf database and check the Job field. Each instance has been
replaced with the value 'ENGINEER'.

Create an Advanced RealTime Virtual Fields Activity

The primary use of the Advanced RealTime Virtual Fields activity is to enable Lotus(R)
Notes(R) users to access databases on external systems (DB2(R), Oracle(R), Sybase(R), etc.)
. Here is an example of how to provide employee information to Lotus Notes
users. Employee information is stored in an external system database, similar to the
leiempsamp.nsf sample database shipped with HEI. This example uses the EMPNO key field
and ENAME, HIREDATE, SAL, JOB, and DEPTNO data fields.

If you have not already transferred your Notes data to an external system database, you can
use the Direct Transfer activity to transfer it and follow this tutorial. For instructions on
creating a Direct Transfer activity, see the Creating a Direct Transfer Activity section earlier
in this chapter.

Note To perform Advanced RealTime Activities, you must add HEI (HCL( R) Enterprise
Integrator) Server must be installed.

Follow these steps to create a simple Advanced RealTime Virtual Fields application.

Step 1. Collect information

Check the external system database table name, description (metadata), required username
and password. If you followed the Direct Transfer tutorial above, the table name is
Employees and the field names are above. Also, check the username and password required
for the external system database.

Step 2. Create a Lotus Notes Form

Create a form in your Notes database with fields corresponding to the key and data
fields. The field names do not have to match those used in the external system's database, but
the data types must match.

Enter a form name of your choice.

Create a view for selecting documents later. Here we use a view called Employee Lookup.

Step 3. Create a Connection Document

Create a connection document to the external system database using the information gathered
in step 1. Or reuse the Sample 1 Destination created in the tutorial earlier in this appendix.

Step 4. Create a Virtual Fields Activity

Create a Virtual Fields activity in the HEI Administrator using the above Connector. Map the
corresponding key and data fields. This Virtual Fields activity monitors the Document Open
event. When an end-user opens an EMPS form with only the key field EMPNO created, this
activity references the DB2 table EMPLOYEE.
Step 5. Initialize Notes Database Keys

Click the Initialize Keys button in the Virtual Fields Activity document. You must initialize
the above Notes database by creating a key document containing keys that refer to records in
the external system database. For that, we initialize the key.

Step 6. Launch the Virtual Fields Activity

1 Return to the HEI Administrator database and use the Activities view to discover
activities.

2 Select Start or open an activity and set the time for Notes users to use the Virtual Fields
activity.

3 Activate this schedule and save the document.

Note Virtual Fields activities continue to run until you click Stop to stop them or until the
schedule ends.

4 Refresh the Activities view until the activity's status icon changes. This icon indicates that
the activity is running.
Step 7. Use the Virtual Fields Activity

Open the monitored Notes database, open one of the documents containing the key values,
and use the application.

The first time you open it, it will take some time, because it needs to establish a connection
with the external system database. The data field data is then pulled from the external system
database by a Virtual Fields activity.

This completes the Virtual Fields Advanced RealTime Activity tutorial.

Create dynamic queries with Advanced RealTime Virtual Fields in Notes or web
clients

This section describes how to launch a Virtual Fields activity that receives user-entered key
values and query an external data source from the HCL(R) Notes(R) Client or web
browser. This example shows how to add dynamic query functionality to an Advanced
RealTime Activity.

Sample content and setup

The HEI (HCL(R) Enterprise Integrator) installation disk contains a sample database
leipackagetrack.nsf. This database provides the Lookup and Status forms used in the
examples. It also contains sample data to populate the external system database for use in the
examples.

Overview

Creating a Lotus Notes-based or Web-based query for Advanced RealTime Virtual Fields
requires the following elements:

An external system database that contains information to provide to Lotus Notes users

A Lotus Notes database (such as leipackagetrack.nsf) on the HCL Domino(R) Server

Connected Virtual Fields (or Virtual Documents) activities on the same Domino Server

To follow this tutorial, copy the sample data to an external system database and create two
forms and one view in your Notes database. Next, create a Virtual Fields activity that
monitors your Notes database. Use the forms and views provided with this sample database
so you don't have to create them yourself.

Step 1. Setup

Copy the leipackagetrack.nsf database to the Domino server directory where HEI is installed.

To modify the memo form, open leipackagetrack.nsf in Domino Designer.

Step 2. Create or Select an External System Database to Monitor

The leipackagetrack.nsf database contains data in packages that can be transferred to external
system databases. These documents or records were created in the Package form and can be
viewed in the Packages view. You can use HEI to move this data to an external system
database, choose your own similar table, or create a table. The key field named "CODE" is
important here. If you use your own table, specify the key field to use for reference and use it
where indicated in later steps. Field names do not have to be the same in both databases. To
denote this, we use PackageID on the Lotus Notes side.

If you want to transfer this data to Oracle using the Direct Transfer activity, select the No
Long Column option in the Connection Document. If this is not selected, the th text column
will be of type LONG on the Oracle side.

Step 3. Create a Notes Database Lookup Form

If you use leipackagetrack.nsf, you can use the Lookup form included in this database. The
key field HEI uses for lookup is an important item. In this example, it is PackageID. You can
add information to this form for instructional purposes to the user.

Note After completing the Lookup form, you must create the Query view.

The "Lookup Package" form has a button with the following expression:

@PostedCommand ([FileSave]);

@PostedCommand ([FileCloseWindow]);

@PostedCommand ([FileOpenDatabase]; @DbName; "Query"; @Text(PackageID));

@PostedCommand ([OpenDocument])

This code is used when running the application from Lotus Notes, but is ignored when
running from the Web.

Note You cannot monitor document creation events when running dynamic queries . This
can result in unwanted data being injected into the external system or a "duplicate key value
specified" error.

1 Enter the PackageID and save the document.

2 Close the window.

If you do not close the note window, you will be left with an orphaned "Untitled"
document.

3 In the Query view, find the document whose indexed key field PackageID is the same as
the one you just saved.

4 Open your document. The view's selection formula displays the Status form.
Operation description

Over the Web, Domino treats the button as a POST command to create the document in the
database and respond to the formula in the $$Return field (normally hidden). The $$Return
field generates a URL that opens the newly created document in a view called Query, just
like through the Notes Client.

In this example, the $$Return field contains the following syntax:

@If (PackageID="";

"Please supply a tracking number before pressing the LOCATE button";

"[/" + @Subset (@DbName; -1) + "/Query/" + PackageID + "?OpenDocument]"

Step 4. Create the Notes Database Status Form

Create a form to return information to the user. In this example, it is Status. This form should
also use a key field called PackageID. If you select Monitor Any Forms in the Virtual Fields
activity, this Status form will open when you open the original user-created document in
Query view. Using a form filter expression (described in step 7) ensures that only one critical
form triggers a Virtual Fields activity.
Step 5. Create a Query view in your Notes database

To find the documents created in the last step, we need to create a view. This view should
create an index on the key field (PackageID in the example).

The view selection formula is:

SELECT (@Contains(Form; "Lookup"))

In the View Properties Advanced tab, enter the following formula:

@If(@IsNewDoc;"Lookup"; "Status")

This formula will switch the form being used to the Status form when a document saved
using the Lookup form is opened.

Step 6. Create Connectors to Source Databases and External System Databases

Two HEI connections are required. Use the first connection to the external database as
follows.
Connections used for Notes databases are monitored by Advanced RealTime as follows:

Step 7. Create a Virtual Fields Activity

1 In the HEI Administrator, create a Virtual Fields activity that monitors the Notes database
Open event.

This activity links an external system database to a Notes document using key fields specified
in the Connection Document. This Connection Document was created in step 3 of the
previous tutorial, Creating an Advanced RealTime Virtual Fields Activity.

In this case, the key field on the Lotus Notes side is PackageID and on the external system
database side is CODE.

2 Select the Status form to map the data fields.

3 Select Monitor Any Forms because we need to monitor Lookup forms to monitor the
Open event.
 4 There are forms in the sample database that are irrelevant to the functionality of this
application, so filter them out by entering FORM = "Lookup" | "Status" in the filter
expression. See the illustration below.
5 Specify the Post-Open Formula as follows:

Select @ALL;

FIELD Form := "Status"

Step 8. Do the final steps

1 Ensure that the external system source is populated with the leipackagetrack.nsf sample
data as described above. Use the Direct Transfer activity for this.

2 Enable the Advanced RealTime Activity schedule you created to run at regular intervals,
or click the Start! button in the Activity document to keep it running until you manually close
it.

3 Verify that the activity is active by refreshing the view to see the Active icon. If you see
an Error icon, go back and check your steps.

4 Create a Lookup document from the Notes client Actions menu and enter the tracking
number in the PackageID field. See the leipackagetrack.nsf database for sample tracking
numbers.

5 Click the Locate button to save the Lookup document to the database.

The same document reopens in view. The view's selection formula switches the form to
Status when it determines that the document was previously saved.

6 From a web browser, access the Lookup form using a URL similar to the following.

http://servername/leipackagetrack.nsf/Lookup?OpenForm

Note This URL will require customization to reflect your Domino server name and any
changes you may have made to the name used by your application.

7 Enter your tracking number in the PackageID field. See the leipackagetrack.nsf database
for sample tracking numbers.

8 Click the Locate button.

Clicking the Locate button saves the Lookup document to the database and passes the
$$Return text to the Domino HTTP process. This will reopen a new document. The
Advanced RealTime Activity fires and takes the values submitted to the Lookup form and
maps them to the Advanced RealTime Activity definition and the Status form. The
PackageID value is then sent to the external system source and the record in the table is
searched based on this value. Search results are returned to the web application indicated by
the URL specified in the Lookup form.

Other Advanced RealTime Examples

This section covers the following items:

Create a Virtual Fields or Virtual Documents activity that uses Virtual Attachments

Using Filter Expressions, Data Storage Options, Monitor Order Options, and Stored
Procedures in Virtual Fields Activities

Create a Lotus Notes application for Virtual Fields or Virtual Documents activities

HCL(R) Notes(R) applications monitored by Virtual Fields or Virtual Documents activities

require data fields that map to data fields in the external data source.

Also, the Virtual Fields activity must have at least one field that maps to a key field in the
external data source. A key field is one or more fields that uniquely identify data. A Virtual
Fields activity can contain multiple key fields.

The following sections provide examples of applications that can be used in Virtual Fields or
Virtual Documents activities.

Sample application

Below is a Notes application that monitors employee information in an external data

source. See the next section for a design view of this application.
Design view of the sample application

The following figure shows the design view of the sample application. This application has
labels next to the data fields. These data fields map to data fields in external data sources
monitored by this application. A Virtual Fields or Virtual Documents activity that uses this
application also defines field mappings in the mapping section of the activity document.
Virtual Fields activity example

Below is an example of a Virtual Fields activity using the sample application. The field
mappings in the [Mapping] section of the document map to the example application above.

To populate the Notes application that created the note, you must initialize the fields in the
Virtual Fields activity. Fields are initialized by opening the Virtual Fields activity and
clicking the Initialize Keys button.
Virtual Documents activity example

For Virtual Documents to work, you need to add four fields to your external system's
database. These fields should be mapped to the Notes ID information fields. For more
information, see Required External System Fields for Virtual Documents Activities in
Chapter 13, Virtual Documents Activities.

Note These fields can be created automatically using the Create Table Utility action
button. See Chapter 13, Virtual Documents Activities for more information .

Below is an example of a Virtual Documents activity that uses the sample application created
earlier in this chapter. The field mappings in the [Mapping] section of the document map to
the sample application.

Note Virtual Documents do not require key initialization. Initialization is automatic.

Use Virtual Attachments

Virtual Attachments is a feature for adding attachments to external system databases using
Notes. Attached files can be accessed from a virtual view.

To use the Virtual Attachments feature, you need to create a table and create a field in the
external system that accepts Virtual Attachments. Fields that you create in the external
system must be located in tables that are explicitly created to hold only those fields.

Note You can use the Table Creation Utility button to automatically create the attachments
table. For more information, see Chapter 12 or Chapter 13, "Creating a Virtual Attachments
Table."

The required field names for Virtual Attachment are:

EIDBID

EFFICIENCY

EIFILESIZE
EIUNID (previously called EINOTEID)

EIFILENAME

CONTENTS

The data type of each field varies by external system, as described in the following table.

Note Sybase(R) requires column names to be uppercase (eg EIUNID).

Note This information is relevant in DB2(R) for data types consisting of attachments up to
1MB.

External system EIDBID data type

Oracle VARCHAR2 (16) or CHAR (16)
Informix CHAR (16)
Sybase CHAR (16)
DB2 CHARACTER (16)
SQL Server CHAR (16)
MS Access NUMBER、INTEGER

If your memo table supports multiple databases, create indexes on these fields for efficient
performance.

External system EIFIHEID data type

Oracle NUMBER
Informix INT
Sybase INT
DB2 INTEGER
SQL Server INT
MS Access TEXT (16)

Create an index on these fields for efficient memo performance.

External system Data type of EIFILESIZE

Oracle NUMBER (8)
Informix INT
Sybase INT
DB2 INTEGER
SQL Server INT
MS Access NUMBER、LONG、INTEGER

Note The EIFILESIZE column length is adjustable, but must remain an integer (X,0).

External system EIUNID data type

Oracle NUMBER (10)
Informix INT
Sybase INT
DB2 INTEGER
SQL Server INT
MS Access TEXT (32)

Note EIUNID is a DWORD or 32-bit unsigned integer. The maximum EIUNID calculated
by the formula 2^n - 1 is 4,294,967,295, so a total of 10 digits are required.

External system Data type of EIFILENAME

Oracle VARCHAR2 (255)
Informix VARCHAR2 (255)
Sybase VARCHAR2 (255)
DB2 VARCHAR2 (255)
SQL Server VARCHAR2 (255)
MS Access TEXT (255)

External system EICONTENTS data type

Oracle BLOB
Informix BYTE
Sybase IMAGE
DB2 BLOB (1048576)
SQL Server IMAGE
MS Access OLE OBJECT

Specifying the table where the Virtual Attachments field resides

Specify the table with the above fields by entering the name of the table in the Attachment
table field of the Activity Document. In the following diagram, the name of the table used for
attachments is MY_ATTACH.

Note You can create tables using SQL commands.

Note Attachments that have not been added to the external system by processing with
Virtual Attachments are not accessible from Activity Documents in Virtual Fields and Virtual
Documents. For example, if you add attachments to an external system database using other
methods, such as SQL commands, you cannot access those attachments from Activity
Documents in Virtual Fields and Virtual Documents.

Using Virtual Fields Options

This section provides examples of using filter expressions, Data Storage options, Monitor
Order options, and stored procedures in Virtual Fields activities.

Use filter expressions

This section describes how to use the Filter Formula option in conjunction with the Monitor
Order option to obtain specific results.

Storing data in external data systems

Scenario: Now that the document data has been finalized, you want to store the Notes
document data in an external data system such as a DB2(R) or Oracle(R) database.

Once each document is finalized and ready to be saved to an external system, change the
document's status from 'under review' to 'publish'.

How to configure: In this case, configure a Virtual Fields activity to monitor the HCL(R)
Notes(R) application.

In the Virtual Fields activity, use a filter expression to select only documents marked as
"Published".

The Notes document information is now written to the DB2 database. This database can also
be used by other applications. "under review" documents are not stored in DB2.

Access different external sources using the same Lotus Notes application

Scenario 1: Manipulating information in two different tables using a single Notes front
end. For example, sales information for the Northeast region is stored in a different table than
for the Southwest region.

In this case, you would set up one Virtual Fields activity for each region using a single Notes
document as a front end, even if they had different external data sources.
You can search for relevant external source data using filter expressions that detect
geographic information or account claims.

Scenario 2: Suppose you have two product catalogs in different databases and use the same
front-end Notes application to present the data. Suppose you use a single Notes front end, but
want to verify the origin of the data for some fields.

Set up identical Virtual Fields activities to monitor a single Notes application, each with a
filter expression that processes a portion of the request.

Using the Data Storage option

This section provides an example of using the Data Storage option in a Virtual Fields activity.

create a view

All data used to create a view must exist in a Notes document. Use the Leave Selected real-
time Fields in Document option. If you select this option, you can select the field to reference
in the view from the list of available fields.

Store static copies of external data

Select Leave All real-time Fields in Document if you want to save a static copy of the
external data. Note that the data in the saved document will not be updated when the data in
the external source changes until the document is reopened.

Using the Monitor Order option

In this scenario, external data from a Lotus Notes human resources information system is
stored in multiple tables. Concatenating these tables together to populate the single Employee
Information form in the Notes application requires a "join" of data. In some cases, a join from
the database is not possible. This is because the tables are in different databases (one in
Oracle, one in Sybase, etc.). The Employee Information form stores employee name,
department name, and location information. The following table shows the relationship
between fields and each table and how they relate to Notes forms.

Employee information EMPLOYEE DEPARTMENT table LOCATION table

form table
(accessed with (accessed with
monitoring order 2) monitoring order 3)
EmpID EmployeeID
EmpName EmployeeName
DepartmentNo DeptNo DeptNo
(normally hidden)
Department DeptName
DepartmentLoc Dept. Place LocCode
(normally hidden)
Location LocName…

To do this join, create three Virtual Fields activities, each monitoring a separate table. These
activities monitor the Employee, Department, and Location tables respectively. The first
activity (using watch order 1) provides the data that the other activities (using watch orders 2
and 3) use as a "key" to the table. Thus, the Notes form "Employee Information" needs a field
to act as the "key" to the second table. These fields are normally "hidden". If you are updating
these second tables from your Notes application, select the "Leave selected real-time fields in
Documents" option and list any fields (DeptmentNo, DepartmentLoc) that will be used as
keys to the external source. increase.

Note Any activity with a monitoring order of or later should monitor the Open
event. Other events can be monitored, but one of them must be the Open event. Depending on
what the activity does, an activity with a monitoring order of should monitor the Open
event.

1 Create a Connection Document for each external data source for the Employee table,
Department table, and Location table.

2 Create a Virtual Fields activity based on the Employee Information form and the
Employee table. Select all the fields that are used in the form and/or that are used as keys to
other fields. In this case, select at least EmployeeName and DepartmentNo.

Lotus Notes Employee table

EmpID (key) EmployeeID (key)
DepartmentNo DeptNo

3 Create a second Virtual Fields activity based on the Employee Information form and the
Department table. Select the following fields:

Lotus Notes Department table

DepartmentNo Deptno (key)
(key)
Department DeptName

Set the monitoring order for this activity to 2. As a result, the first activity
will retrieve information from the Employee table and then look at the
DeptName field in the Department table.

4 The third activity has the same functionality as the second activity, except that it monitors
the Location table. Set the monitoring order to 3, because the reference for this activity
depends on the information provided by the first activity.
Lotus Notes Location table
DepartmentLoc (キー) LocCode (key)
Location LocName

Using stored procedures in Sybase/SQL

This section provides examples of Virtual Fields activities that use stored procedures with
Sybase external data sources or SQL (using Sybase) external data sources.

This example provides four stored procedures for the Sybase addrbook table. When using
these stored procedures, the key fields used should be FirstName followed by LastName and
the mapping fields should be (MailDomain, MailServer, MailAddress, CompanyName,
State). Enter stored procedures, table names, and fields exactly as Sybase is case-sensitive.

To use a stored procedure, enter the name of the stored procedure in the options section of the
relevant event in the Virtual Fields Activity document. This example uses the following
stored procedure names:

Create:QEInsertaddrbook

Open:QESelectaddrbook

Update:QEUpdateaddrbook

Delete:QEDeleteaddrbook

The image below shows a stored procedure entered in the Stored Procedure field of each
event option in the Virtual Fields activity. The next section provides an example of how to
test a SQL stored procedure directly from a database client.
Test SQL stored procedures

The following example shows how to execute a SQL stored procedure from a database client
(Sybase in this case). You can run the stored procedure directly as follows to test if it works
correctly.

Note This example assumes the existence of an "addrbook" table with the following
columns:

execute QEInsertaddrbook 'OurDomain', 'ThisServer', 'OurAddress', 'Open Research', 'NH',

'Adelino', 'Fontes'
run QESelectaddrbook 'Adelino', 'Fonts'

execute QEUpdateaddrbook 'OurDomain', 'ThisServer', 'OurAddress', 'Open Research', 'NH',

'Adelino', 'Fontes'

run QEDeleteaddrbook 'Adelino','Fonts'

stored procedure definition

Here is the actual stored procedure definition used in the previous example. This procedure is
a Sybase procedure. This is different for other data sources.

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(

@FirstName varchar(20),

@LastName varchar(20)

as

select FirstName,LastName,

MailDomain, MailServer, MailAddress,

CompanyName,State from addrbook

WHERE FirstName = @FirstName and

LastName = @LastName

create procedure dbo.QEUpdateaddrbook(

@FirstName varchar(20),

@LastName varchar(20),

@MailDomain varchar(20),

@MailServer varchar(20),

@MailAddress varchar(20),

@CompanyName varchar(20),

@State varchar(20)

as

UPDATE addrbook SET

MailDomain=@MailDomain, MailServer=@MailServer,

MailAddress=@MailAddress,

CompanyName=@CompanyName, State=@State
WHERE

FirstName=@FirstName and LastName=@LastName

create procedure dbo.QEDeleteaddrbook(

@FirstName varchar(20),

@LastName varchar(20)

as

DELETE FROM addrbook

WHERE FirstName=@FirstName and LastName=@LastName

Use DB2 stored procedures

DB2 converts Lotus Notes data types to parameter types. For example, if the Lotus Notes key
field is numeric, the DB2 parameter type will be DOUBLE. The stored procedure should
distinguish between input types (or at least check the input types).

Create your own stored procedure based on the following sample.

/* Stored procedure Example */

#include <memory.h>

#include <string.h>

#include <c:\sqllib\include\sql.h>

#include <c:\sqllib\include\sqlda.h>

SQL_API_RC SQL_API_FN sf_proc (void *reserved1,

void *reserved2,

struct sqlda *inout_sqlda,

struct sqlca *ca)

{

/* Declare a local SQLCA */

EXEC SQL INCLUDE SQLCA;

/* Declare Host Variables */

EXEC SQL BEGIN DECLARE SECTION;

char *select_stmt = "SELECT NUMBER2, TEXT1, TEXT2, MODIFIED, NUMBER1

FROM SIMPLE WHERE NUMBER1 = ?";

long int number1;

EXEC SQL END DECLARE SECTION;

if (inout_sqlda)

if ((inout_sqlda->sqlvar[0].sqltype == SQL_TYP_INTEGER) ||

(inout_sqlda->sqlvar[0].sqltype == SQL_TYP_NINTEGER))

number1 = *((long int *) (inout_sqlda->sqlvar[0].sqldata));

else if ((inout_sqlda->sqlvar[0].sqltype == SQL_TYP_FLOAT) ||

(inout_sqlda->sqlvar[0].sqltype == SQL_TYP_NFLOAT))

number1 = (long int) *((double *) (inout_sqlda->sqlvar[0].sqldata));

else

number1 = 0;

EXEC SQL WHENEVER SQLERROR GOTO ext;

EXEC SQL PREPARE stmt FROM :select_stmt;

exec sql DECLARE curs CURSOR FOR stmt;

exec sql OPEN curs using :number1;

 }

ext:

memcpy(ca, &sqlca, sizeof(struct sqlca));

if (inout_sqlda)

*(inout_sqlda->sqlvar[0].sqlind) = -128;

return(SQLZ_DISCONNECT_PROC);

Use Oracle stored procedures

Oracle stored procedures can be used in Virtual Fields activities or LC LSX scripts. However,
when calling the stored procedure, the parameters must be set correctly.

If you reference stored procedures in your connection document, a dialog box appears listing
all stored procedures in the external system database. When you select a stored procedure
from among them, the parameters for that stored procedure are automatically listed in the
connection document. If you do not specify a stored procedure in the Connection Document,
you can select the stored procedure and parameters associated with this procedure from the
Virtual Fields Activity Document. In either case, the stored procedure is entered as the
default stored procedure in the activity's event in the stored procedure field, followed by a list
of parameters. Return values are often handled on the external system database side. For
Oracle, the information returned is processed by the Lotus Connector for Oracle. This is
irrelevant to normal users, but should be understood by anyone writing Oracle stored
procedures.

Input values and named parameters

Input values are passed to Oracle procedures as named parameters. Therefore, in Oracle you
must use a parameter with the same name as the field passed as input. For keyed operations
(select, update, delete), the input specifies the key value and, if required (insert or delete), the
data value. The data type of the input value provided by the Lotus connection is chosen to be
the closest match to the HEI (HCL(R) Enterprise Integrator) data type and, if Oracle supports
the conversion, the procedure parameter definition data by Oracle. converted to type.

Return results using output parameters

Oracle doesn't have a way to return a result set from a procedure, unlike other RDBMS
Connectors. For this reason, Lotus Connector for Oracle supports output parameters as a way
to return stored procedure results. This requires additional information such as the context
and names of output parameters when calling the procedure. This information is provided
automatically by the Virtual Fields activity, but must be specified manually when calling the
Oracle procedure from an LC LSX script. The context indicates whether the procedure
requires output parameters, which are given as properties of the procedure call request to the
Oracle connection. Output parameters must be of standard data types (cannot return a set of
rows). This limits the result set from the Oracle procedure to one row. Parameters indicated
as input parameters and included in the output parameter list are passed as input and output
parameters.

Sample Oracle stored procedure

Below is a sample body of an Oracle stored procedure. This shows the format required to use
the Open event in a Virtual Fields Notes activity when the key field is NUMBER1 and the
data fields are NUMBER2, TEXT1, TEXT2 (three). In this example the key field is the input
parameter and the result set contains both the data field and the key field. Note that one of the
names of the output parameters must match the key value in the select statement, so we copy
the key of the parameter to a local variable inside the procedure to avoid scope issues.

(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;