Sample Programs for COMTI


Host Integration Server 2000
Microsoft Corporation

October 2001

Summary: This article describes the sample programs for application integration using COMTI (COM Transaction Integrator) for CICS and IMS included with the Host Integration Server 2000 Software Development Kit. (4 printed pages)


Bounded Recordsets Sample
Programming Specifics Sample
Sync Level 2 Sample


The source code for several sample programs that illustrate using features of the Microsoft® COM Transaction Integrator (COMTI) for CICS and IMS is included on the Microsoft® Host Integration Server 2000 CD-ROM as a part of the Host Integration Server Software Development Kit (SDK). COMTI allows developers to integrate component-based Microsoft Windows® applications using COM, distributed COM, and COM+ with CICS and IMS transactions on IBM mainframes.

In addition to the COMTI samples included in the Host Integration Server SDK, there is a basic COMTI sample titled CedarBank that is installed with COMTI when the COMTI feature option is selected during setup. The CedarBank sample is installed under the system\Tutorials\CedarBank subdirectory below where Host Integration Server is installed (the default location is C:\Program Files\Host Integration Server\system\Tutorials\CedarBank).

Note that documentation on COMTI is not included with the Host Integration Server SDK. Documentation on COMTI is included under Application Integration Services as part of the Host Integration Server 2000 user documentation. The documentation is also available in printable format on the Host Integration Server CD-ROM under the Documentation\Printable Books folder in the Application Integration Services.pdf file.

The COMTI sample programs are located in the \SDK\Samples\COMTI subdirectory on the Host Integration Server 2000 CD-ROM. These files are copied to your hard drive during Host Integration Server software or Host Integration Client software installation when the Host Integration Server Software Development Kit option is selected. These samples are installed in the Samples\COMTI subdirectory below where the Host Integration Server SDK software is installed (C:\Program Files\Host Integration Server SDK, by default).

When installed as part of the MSDN Platform SDK, these samples are located under the Samples\NetDS\HIS\COMTI subdirectory below where the MSDN Platform SDK has been installed (C:\Program Files\Microsoft SDK, by default).

These sample programs include the files in the following subdirectories:

Subdirectory Description
BoundedRecordsets\COBOL-CICS A sample program in COBOL using COMTI that illustrates the use of bounded recordsets. This subdirectory also contains a sample TLB file created using the COMTI Component Builder for this COBOL sample.
BoundedRecordsets\VB A sample class defined in Microsoft® Visual Basic® using COMTI that illustrates the use of bounded recordsets.
ProgrammingSpecifics This folder contains a comprehensive sample that includes Visual Basic client code as well as mainframe COBOL code and sample COMTI type libraries. This sample is intended to be a complete end-to-end sample demonstrating features of COMTI.
ProgrammingSpecifics\CICSNonlink A sample program in COBOL using COMTI that demonstrates how to receive a COMTI fixed-sized data area greater than 32767. This sample is not intended to be a complete end-to-end program, but it demonstrates the receiving-side logic of a CICS Non-Link server application program using COMTI.
ProgrammingSpecifics\TCP A set of several sample programs in COBOL using COMTI that demonstrate how to use a CICS TCP server application.
SyncLev2 A sample program in COBOL using COMTI that demonstrates how to use Sync Level 2.

These samples primarily use a remote environment of CICS using LU 6.2. These COMTI samples are designed to assist developers in creating code for specific COMTI features.

In order to first start working with COMTI, it is recommended that developers use the CedarBank tutorial that comes with the COMTI installation. The CedarBank tutorial illustrates how to use all of the COMTI Remote Environments and includes the COMTI type libraries and the COBOL code for the mainframe for all of the environments (IMS, CICS, APPC, and TCP/IP). The CedarBank sample also includes sample programs for the client-side code written in Microsoft Visual Basic and Microsoft Visual C++®.

Once connectivity has been established by working with the CedarBank tutorial, then the COMTI samples included with the Host Integration Server SDK can be used to gain an understanding of more advanced COMTI features not covered by the CedarBank tutorial.

Bounded Recordsets Sample

The Microsoft® COM Transaction Integrator (COMTI) for CICS and IMS can be used with Microsoft Visual Basic bounded recordsets. This sample includes Visual Basic code and CICS COBOL code showing how to use bounded recordsets by calling into a CICS transaction program via LU 6.2 (Remote Environment CICS using LU 6.2). The Visual Basic code is in the COMTI\BoundedRecorsdsets\VB folder and demonstrates how to create a recordset and populate it with data to send to the mainframe. Note that there is no code that actually displays the data that comes back from the mainframe. A developer can put a breakpoint in the VB code using the debugger and use the immediate window to look at the data or insert further code to examine the data that is returned.

In the COMTI\BoundedRecorsdsets\COBOL-CICS folder, there is a COMTI type library (TLB file) that can be used with this sample. The type library is set up for accessing a transaction named GETI on the host. There is also sample COBOL code that can be compiled and linked on the mainframe side. The compiled code should be set up to run on the host as a transaction named GETI or the COMTI type library must be changed to reflect the name of the transaction if it is different.

Programming Specifics Sample

The Microsoft® COM Transaction Integrator (COMTI) for CICS and IMS supports a number of powerful features that are illustrated by these samples. In the COMTI\ProgrammingSpecifics folder, there is a complete Microsoft Visual Basic project that demonstrates the following features of COMTI:

  • Returning a Recordset
  • Variable Length Tables
  • Handling REDEFINES Clauses
  • Variably Sized Strings
  • Handling FILLER
  • Unbounded Recordsets
  • In/Out Variable Length Table

The Visual Basic project contains comments with the Visual Basic source code that indicates which COBOL (*.cbl) file contains the associated COBOL code for the mainframe side. The sample type library is included for CICS using LU 6.2. There are seven methods defined in the type library. Check on the properties for each method and look at the Host Names tab to see what the Mainframe TP name is. The value of the mainframe TP name property can be changed to the name used when compiling the sample COBOL programs.

Programming Specifics CICSNonlink Sample

In the COMTI\ProgrammingSpecifics\CICSNonlink folder there is sample COBOL code showing how to receive more than 32K bytes of data in a single method call. This sample includes only the mainframe code (COBOL), and does not include the corresponding Visual Basic or Visual C++ code for the PC side. It is intended to demonstrate the receiving side logic of a COMTI Non-link server application. This COBOL program contains comments explaining what is being done in the code.

Programming Specifics TCP Sample

In the COMTI\ProgrammingSpecifics\TCP folder, there are sample COBOL Child Server programs that can be used for TCP/IP connections. The Cicscs.cbl code is a sample program for TCP using CICS with Concurrent Server (analogous to CICS using LU 6.2). The Mscmtics.cbl code is a sample program for CICS calling a Link-to program (using CICS DPL). The Imsexpl.cbl code is a sample program for using IMS in the Explicit mode. The Imsimpl.cbl code is a sample program for using IMS in the Implicit mode. There are similar sample programs included with the CedarBank tutorial, which directly reflect the CedarBank data being passed.

Sync Level 2 Sample

The Microsoft COM Transaction Integrator (COMTI) for CICS and IMS supports the use of Sync Level 2 transactions. This sample includes COBOL source code illustrating transactional support (Sync Level 2) on the mainframe with CICS using LU 6.2. This sample only includes COBOL source code, which contains comments describing each of the code sections. The sample code demonstrates executing a Commit and identifying that a Rollback has been requested from COMTI. Please note that there is also related documentation in Knowledge Base article Q220967, Explanation of COMTI Metadata Elements. This article explains COMTI Metadata elements so that developers can better understand how to use Metadata to allow the COBOL program to initiate a Rollback of a transaction.