CICS for Windows NT link extra for Lotus Notes

Take Note!

Before using this User's Guide and the product it supports, be sure to read the general information under Notices.

Second Edition, December 1997

This edition applies to Version 1.1 of CA70: CICS for Windows NT link extra for Lotus Notes, and to all subsequent releases and modifications until otherwise indicated in new editions.

A form for reader's comments is provided at the back of this publication. If the form has been removed, address your comments to:

IBM United Kingdom Laboratories
Transaction Systems Marketing Support (MP207)
Hursley Park
Hursley
Hampshire, SO21 2JN, England

When you send information to IBM, you grant IBM a non-exclusive right to use or distribute the information in any way it believes appropriate without incurring any obligation to you. You may continue to use the information that you supply.

©Copyright International Business Machines Corporation 1996, 1997. All rights reserved.
Note to U.S. Government Users - Documentation related to restricted rights - Use, duplication or disclosure is subject to restrictions set forth in GSA ADP Schedule Contract with IBM Corporation.

Notices

The following paragraph does not apply in any country where such provisions are inconsistent with local law.

INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore this statement may not apply to you.

References in this publication to IBM products, programs, or services do not imply that IBM intends to make these available in all countries in which IBM operates.

Any reference to an IBM licensed program or other IBM product in this publication is not intended to state or imply that only IBM's program or other product may be used. Any functionally equivalent program that does not infringe any of the intellectual property rights may be used instead of the IBM product. Evaluation and verification of operation in conjunction with other products, except those expressly designated by IBM, is the user's responsibility.

IBM may have patents or pending patent applications covering subject matter in this document. The furnishing of this document does not give you any license to these patents. You can send license inquiries, in writing, to the IBM Director of Licensing, IBM Corporation, 500 Columbus Avenue, Thornwood, New York 10594, USA.

The following terms are trademarks of the International Business Machines Corporation in the United States and/or other countries:

CICS
OS/2
IBM

The following terms, used in this publication, are trademarks of other companies as follows:

Lotus Development Corporation: Lotus, Lotus Notes
Microsoft Corporation: Windows NT

What is CICS for Windows NT link extra for Lotus Notes?

CICS for Windows NT link extra provides CICS applications with a means of sending data to a Lotus Notes environment. This data can be used to update or add one or more documents to a Lotus Notes database. Document updates may span more than one database. The user specifies what action to take using a combination of key fields and rules.

The previous announcement of 'CICS for Windows NT link for Lotus Notes' allowed Lotus Notes users to initiate the interaction with a CICS application. The new function provided in 'CICS for Windows NT link extra for Lotus Notes' allows an application on any of the CICS platforms to initiate the sending of data to the Lotus Notes user. The CICS for Windows NT link extra allows data from non-Notes environments to be integrated into Lotus Notes. A link database provides mapping between the system application and fields defined in the Lotus Notes databases. The CICS for Windows NT link for Lotus Notes runs as a server add-in task, while the CICS for Windows NT link for Lotus Notes extra runs as an independent process.

If you install CICS in order to link to Lotus Notes, you should have Lotus Notes installed and have the documentation provided with Lotus Notes and CICS.

Note: CICS for Windows NT link for Lotus Notes is referred to as CICS link and CICS for Windows NT link extra for Lotus Notes is referred to as CICS link extra through this document.

The diagram below outlines the flow of data from a CICS application to a Lotus Notes application.

Figure 1: CICS for Windows NT link extra for Lotus Notes

Prerequisites

CICS for Windows NT link extra requires Lotus Notes Server Version 3.2 or later and CICS for Windows NT V2.0.1 or later.

CICS for Windows NT link extra requires Lotus Notes Server Version 4.1 or later when used with Transaction Server for Windows NT.

Please see the CICS for Windows NT link extra Overview Diagram for an explanation of how the components are integrated.

CICS for Windows NT link extra for Lotus Notes Overview Diagram:

Figure 2: CICS for Windows NT link extra for Lotus Notes Overview Diagram

CICS for Windows NT link for Lotus Notes Overview Diagram:

The diagram below shows how CICS for Windows NT link functions to highlight the difference between CICS for Windows NT link and CICS for Windows NT link extra.

Figure 3: CICS for Windows NT link for Lotus Notes Overview Diagram

CICS for Windows NT link extra for Lotus Notes Components

Lotus Notes Link-database

This is a Lotus Notes Database that needs to be populated with entries which describe how the message data maps to fields in a given Lotus Notes document. The entry name of the Link-database document corresponds to the QUEUE information passed from the calling CICS application via the CICS START. The logical processing rules (e.g. If found Insert, Insert always, etc.) for each message retrieved are also specified in the database. The CICS link extra for Lotus Notes Link-database definition is an extension of the CICS for Windows NT link for Lotus Notes Link-database. As a result the CICS for Windows NT link extra for Lotus Notes Link-database may be used to define entries for both CICS for Windows NT link and CICS link extra.

   dmdb.nsf     (CICS for Windows NT link extra Link-database)

Starting the process

CICS for Windows NT link extra for Lotus Notes runs as an independent process. The process is started when the calling CICS application issues an EXEC CICS START command that issues a START to the defined CICS link transaction on the Notes Server.

The syntax of CICS START command used for the CICS link extra is as follows.

EXEC CICS START TRANSID(tranid)        /* CICS Transaction to Start */
                DATA(data)	       /* Data to be processed into Notes */
                LENGTH(sizeof(data))   /* Size of passed data */
                TERMID(termid)         /* remote Term ID */
                QUEUE(qname) 	       /* link database entry field */

Note that the TERMID parameter is optional since the CICS link extra transaction may be run as a background task.

Lotus Notes Sample Applications

A sample Lotus Notes demonstration applications is provided with CICS for Windows NT link extra. The CICS link extra Link-database have entries that will allow for updating of documents contained in the application databases. If you create your own applications, a suitable Link-database entry must be created.

   cltest1.nsf     (Name Information)
   cltest2.nsf     (Address Information)

CICS application

The CICS application is a standard transaction application that passes data to the CICS system running on the Notes Server. The QUEUE data corresponds to the Link-database entry name.

CICS Sample Application

An CICS sample application is provided to help you get started. This sample application is a C program designed to read messages from a provided data file. When the sample application is run, data is passed to CICS link extra that then places into the Lotus Notes sample databases as documents.

   demo1.dll    (CICS sample application for Windows NT Version 2)
   demo4.dll    (CICS sample application for Transaction Server for Windows NT)
   demo1.dat    (Sample data file)

Setting up your system

Installing the files

The CICS for Windows NT link extra package is distributed as a zipped file called ca70.zip. Follow the steps below to setup the CICS for Windows NT link extra files on your hard drive.

Create a sub-directory called c:\ca70 to hold the CICS for Windows NT link extra files (if you prefer, you may choose a different drive/directory name.)
Copy the file ca70.zip into your newly created directory as ca70.zip
Unzip the file using Infozip's UNZIP utility. From the c:\ca70 directory enter the following command.
```
   unzip ca70.zip
```
Compare the directory contents with the CICS for Windows NT link extra directory listing provided in the document section called "Directory Contents."
Update your CONFIG.SYS LIBPATH, PATH and DPATH statements to include the newly created directory c:\ca70. Reboot the operating system to make the changes effective.

Lotus Notes Setup

CICS for Windows NT link extra includes three Lotus Notes database files which must be installed. There are two sample demonstration databases and a Link-database. The CICS for Windows NT link extra Link-database is an extension of the CICS for Windows NT link Link-database.

Start Lotus Notes
Copy the following CICS for Windows NT link extra Lotus Notes database files to your Notes sub-directory C:\NOTES\DATA\
```
      dmdb.nsf     - CICS link extra Link-database
      cltest1.nsf  - Name Information
      cltest2.nsf  - Address Information
```
To place the Link-database in a directory other than the Notes directory, specify the directory name on the PATH statement in your config.sys.
Add the CICS link extra databases by choosing FILE-OPEN DATABASE option. Create a Workspace icon by opening each of the Notes database files listed above or adding the icons.
Open a view on the CICS link extra Link-database by double mouse clicking on the CICS link extra icon.
CICS link extra supports multiple entries with the same ENTRY identifier, CICS link does not.

CICS Setup

Setup for CICS for Windows NT Version 2

Start CICS for Windows NT.
Enter the CEDA transaction.
1. The CICS link code needs to have a transaction defined to the PCT (Program Control Table). The following setup will show how to set this PCT entry up when using CICS for Windows NT link on the same machine as Notes. Knowledge of CICS and the environment you are using will come into play when setting this system up to use remote systems and CICS for Windows NT link.

Add the following transaction definitions to the PCT.

If you are going to be using the sample CICS for Windows NT link Demo program, you must setup the CLNK transaction. The demo application is passing that transaction on the CICS START command.

   Transaction Code. . . . . . .LNKX
   Group Name. . . . . . . . . .CCLINKX
   Program Name. . . . . . . . .DEMO1
   Task Class. . . . . . . . . .N
   Secure. . . . . . . . . . . .N
   Can Be Purged . . . . . . . .Y
   Use Alternate Screen Size . .N
   Priority. . . . . . . . . . .0
   System ID . . . . . . . . . .
   Remote Transaction Code . . .
   Description . . . . . . . . .CICS link extra DEMO transaction

   Transaction Code. . . . . . .CLNK
   Group Name. . . . . . . . . .CCLINKX
   Program Name. . . . . . . . .CCLINKX
   Task Class. . . . . . . . . .N
   Secure. . . . . . . . . . . .N
   Can Be Purged . . . . . . . .Y
   Use Alternate Screen Size . .N
   Priority. . . . . . . . . . .0
   System ID . . . . . . . . . .
   Remote Transaction Code . . .
   Description . . . . . . . . .CICS link extra transaction

Make sure you Exit and restart CICS Windows NT for the new PCT defintions to take affect.
Copy the following files from the ca70 directory to cics_dir\bin\ (where cics_dir is the directory into which you have installed CICS)
- cclinkx.dll
- scclmsg.msg
- demo1.dll
Copy the following file into c:\
- demo1.dat

Setup for Transaction Server for Windows NT

Start Transaction Server for Windows NT Administration application.
1. The CICS link code needs to have a transaction defined to CICS (Transaction Definition). The following setup will show how to set this TD entry up when using CICS for Windows NT link on the same Windows NT machine as Notes. Knowledge of CICS and the environment you are using will come into play when setting this system up to use remote systems and CICS for Windows NT link.

Add the following program definitions to the region database.

       Program name:  CCLINKX
        Description:  CICS link extra for Notes
              Group:  CCLINKX
       Program path:  pathname\cclinkx4.dll

       Program name:  CCLXDEMO
        Description:  CICS link extra demo
              Group:  CCLINKX
       Program path:  pathname\demo4.dll

where pathname is the full path of the directory in which you have placed the two executables.

Add the following transaction definitions to the region database.
1. If you are going to be using the sample CICS link Demo program, you must setup the CLNK transaction. The demo application is passing that transaction on the CICS START command.
```
   Transaction name:  CLNK
        Description:  CICS link extra for Notes
              Group:  CCLINKX
      First program:  CCLINKX
```
```
   Transaction name:  LNKX
        Description:  CICS link extra for Notes demo
              Group:  CCLINKX
      First program:  CCLXDEMO
```
Ensure that the purgeable attribute is checked for both transactions.

Add the following Transient Data Queue definition to the region database:

           TDQ name:  CLX3
        Description:  TD Queue for CICS link demo
              Group:  CCLINKX
         Queue type:  intrapartition
         Open queue:  on request

If the region is already started you should add the defintions to both the permanent and the runtime databases.
Copy the following file from the ca70 directory to opt\cics\bin\
- scclmsg.msg
Copy the following file from the ca70 directory to c:\
- demo.dat

Verifying CICS link extra can initiate updates to Lotus Notes

Now that you have completed the set up work for Lotus Notes and CICS, you are ready to run the sample demonstration CICS and Lotus Notes applications. Two sample demonstration Lotus Notes databases are provided with CICS for Windows NT link extra. Running the sample will demonstrate how putting messages on a single triggered queue, separate documents in two different Lotus Notes database can be updated.

Start Lotus Notes. You should have CICS link extra Workspace icons representing the Link-database and two sample application databases. If you do not, go back perform the Lotus Notes Setup procedure.
Start CICS for Windows NT. You can run the CEDA transaction (CICS V2) or start the Transaction Server Administration program to check the resource definitions which you have made.
The LNKX transaction in the group CCLINKX should be defined. If not, go back and perform the CICS Setup procedure.
Start the sample application by issuing the LNKX transaction from CICS for Windows NT
Open a view on the Names or Address database. You should now see new document entries reflecting the data processed.

Directory Contents

The CICS for Windows NT link extra package is distributed as a zipped binary file. The CICS for Windows NT link extra directory contents are as follows:

\cclinkx.dll    CICS link extra executable code for CICS Version 2

\cclinkx4.dll   CICS link extra executable code for Transaction Server Version 4

\scclmsg.msg    File containing messages used by CICS link extra

\dmdb.nsf       Lotus Link-Database
\cltest1.nsf    Lotus Demo database 1
\cltest2.nsf    Lotus Demo database 2

\demo1.dll      Demo executable to pass messages to the CCLINKX process (CICS V2)
\demo4.dll      Demo executable to pass messages to the CCLINKX process (Txn Svr V4)
\demo1.dat      Demo data for input into demo1.dll

\demo1.ccs      Demo source to load messages into CCLINKX process
\demo1.mak      Demo source make file for CICS Version 2
\demo4.mak      Demo source make file for Transaction Server Version 4

\ca70.ps        User's Guide (postscript format)
\ca70.nsf       User's Guide (Lotus Notes database)
\ca70.htm       User's Guide (html format)
\ca70fig1.gif   Diagram for html version of User's Guide
\ca70fig2.gif   Diagram for html version of User's Guide
\ca70fig3.gif   Diagram for html version of User's Guide

Link-Database Sample

The Link-Database, DMDB.NSF, needs to be placed in the database directory on the Lotus Notes server that the Lotus client application will access. CICS link extra will read the Link-database entries to determine the Lotus Notes Documents and fields to update.

Entry: CLX3         Description: CICS link extra - Employee Name Database

Database Information
  User Database Name: cltest1

Rule         3. If found Update, else Insert

Output Offsets
Map from external application to Notes
Syntax: FieldName <space> Start <space> End  <space>  CHAR / INTEL-BINARY   <KEY<Comparison>> CASE / NOCASE

  name         0   14  CHAR KEY CASE
  mname       20   34  CHAR
  lname       40   54  CHAR KEY CASE


Additional Selection Formula (CICS link extra Only)
  (example: Salary > 100)

Link-Database Entry Description of Fields

Entry : Entry Name to be used in the Request (Example, in the @MailSend in CICS link and the Queue name in the CICS link extra.)
Description : A description of the document
Database Information
- User Database Name: Database that CICS link / CICS link extra will update with response data
Rule
The Rule indicates how the data is processed given existing documents in the Lotus Notes database. There is not a default value for Rule and a Rule must be specified.

0. If found Insert, else Fail
When no documents are found, call the user exit.
1. If found Update, else Fail
When no document are found, call the user exit.
2. If found Fail, else Insert
When one or more documents are found, call the user exit.
3. If found Update, else Insert
When a matching document is not found, a new one is created, the user exit is not called.
4. If found Update, else Ignore
When no matching document is found, the message is ignored or discarded and the user exit is not called.
5. Insert Always
A new document is always created regardless of whether a matching document is found, the user exit is not called.
6. If found Ignore, else Fail
When no matching documents are found, call the user exit.
7. If found Insert, else Ignore
When no matching documents are found, the message is ignored or discarded and the user exit is not called.
8. If found Fail, else Ignore
When one or more matching documents are found, call the user exit.
9. If found Ignore, else Insert
When a matching document is found , the message is ignored or discarded and the user exit is not called.
Output Offsets
- Syntax: FieldName <space> Start <space> End <space> CHAR / INTEL-BINARY <space> KEY <Comparison> CASE / NOCASE
- Layout of data in the CICS Message. Note that the FieldName is the name of the field in the Lotus Notes form to be updated with the output data. (Optional)
- The KEY specification is for CICS link extra fields only. It is used to specify that this field is part of the selection criteria. (Optional)
- Case sensitivity may be specified as part of the key field search information. CASE indicates the search is case sensitive. NOCASE indicates the search is not case sensitive. NOCASE is the default. Case is only pertinent when associated with a KEY field. (Optional)
- When documents are inserted/updated the default form for the Lotus Notes Database is used. The Form may be specified here as part of the message when the default form is not the desired form. For example, Form 0 7 CHAR
- When KEY fields are not specified and the Additional Selection Formula is blank, then the default selection will return all documents in the database.
Additional Selection Formula
Specify search criteria to be used against the Notes database. This can be fields that are part of the database form. For example, salary > 1000. (Optional)
Note:When KEY fields are not specified and the Additional Selection Formula is blank, then the default selection will return all documents in the database.

Error Codes

All informational and error messages are displayed at the console or recorded in the CICS error log.

SCL9000I CICS for Windows NT link extra for Lotus Notes v1.1 started. Copyright(c) 1996 ISSC and IBM, All Rights reserved.

Explanation:

User Response: None.

SCL9001I Lotus notes API initialized OK.

Explanation:

User Response: None.

SCL9002I Reading the Lotus Notes Meta Database OK.

Explanation: The database specified could be opened.

User Response: the database is specified correctly and is available.

SCL9003E ERROR Reading the Lotus Notes Meta Database.

Explanation: The database specified could not be opened.

User Response: Confirm that the database is specified correctly and available.

SCL9004E future use

Explanation:

User Response: None.

SCL9005I Reading the Lotus Notes application Database.

Explanation: The database specified could be opened.

User Response: the database is specified correctly and is available.

SCL9006E ERROR Reading the Lotus Notes application Database.

Explanation: The database specified could not be opened.

User Response: Confirm that the database is specified correctly and available.

SCL9007I MainCICS Program processed OK.

Explanation:

User Response: None.

SCL9008E ERROR while initializing Lotus Notes API.

Explanation:

User Response: None.

SCL9009E ERROR while opening the Lotus Notes Meta Database.

Explanation: One of the link database documents cannot be opened. It may be corrupted.

User Response: Check that all documents in the link database are correct.

SCL9010E ERROR while compiling a Lotus Notes formula to select a entry in the Database.

Explanation: The formula was not able to be compiled by Lotus Notes.

User Response: Verify the KEY output offsets and Additional Selection Formula in the link database and retry the operation.

SCL9011E ERROR while searching Lotus Notes that meet your selection criteria.

Explanation: A document was not found in the specified database.

User Response: Confirm the database is available and the document exists or not as appropriate. If the problem persists, contact your IBM support center.

SCL9012E ERROR while closing the Lotus Notes Database.

Explanation: The CICS link extra database could not be closed.

User Response: Verify that the link database specified exists and is available to Lotus Notes.

SCL9013E ERROR while opening the Lotus Notes Meta Database when a match was found.

Explanation: The database specified could not be opened.

User Response: Confirm that the database is specified correctly and available.

SCL9014E ERROR the database name field was not found in the Lotus Notes Meta Database.

Explanation: The database specified could not be opened.

User Response: Confirm that the database is specified correctly and available.

SCL9015E ERROR with the field WIDTH definitions in your Lotus Notes Meta Database.

Explanation: The link database mapping entry for field was specified with a BINARY type, but the width was incorrect. Correct values include 2, 4 and 8.

User Response: Correct the problem in the link database.

SCL9016E ERROR with the field TYPE definitions in your Lotus Notes Meta Database.

Explanation: One Item type was expected (most likely TEXT), and another was detected.

User Response: Check the link database and correct the field.

SCL9017E ERROR NULL field OFFSETS in your Lotus Notes Meta Database.

Explanation: No field offset mappings were specified in a document in the link database.

User Response: Check the link database.

SCL9018E ERROR the OUTPUT OFFSET field was not found in the Lotus Notes Meta Database.

Explanation: No field offset mappings were specified in a document in the link database.

User Response: Check the link database and correct the field.

SCL9019E ERROR while opening the Lotus Notes application Database.

Explanation: The database specified could not be opened.

User Response: Confirm that the database is specified correctly and available.