COMTI, included with Microsoft Systems Network Architecture (SNA) Server 4.0 and later, is used to integrate Microsoft Windows DNA applications with transaction programs running under the Customer Information Control System (CICS) or Information Management Systems (IMS) on IBM Multiple Virtual Storage (MVS) mainframe computers. COMTI contains a Microsoft Management Console (MMC) snap-in for administering COMTI, the Component Builder for creating COMTI components, and the COMTI run-time proxy. These are installed when you select the COM Transaction Integrator option in the SNA Server setup program. SNA Server is used to provide LU 6.2 communications with the mainframe computer.
As we saw in Chapter 6, COMTI encapsulates CICS and IMS applications in Automation objects that can be accessed from PC-based client applications. The Automation objects are generated by the COMTI run-time proxy that runs within MTS. The run-time proxy uses a type library produced by the Component Builder to generate the Automation objects on-the-fly. The combination of the run-time proxy and the type library is called a COMTI component.
If you are not interested in interoperating with CICS or IMS, you can skip to the section "Developing Applications with MSMQ" later in this chapter.
The COMTI Component Builder is a stand-alone GUI application that lets you automatically create a type library from the COBOL declarations of an existing CICS or IMS application, or vice versa. In this section, you will learn how to use the Component Builder to create COMTI components from existing CICS or IMS applications.
To create a component, run the Component Builder by selecting Programs, then Microsoft SNA Server, then COM Transaction Integrator, and finally Component Builder from the Start menu. Choose the New command from the Component Builder File menu to display the New Component Library dialog box, shown in Figure 15-1. In this dialog box, you enter the name of the type library you want to create, the name of the interface to define, a version number, and an optional description. You also specify whether the component is communicating with a CICS LINK, a CICS (the nonlinked model using straight LU 6.2 communication), or an IMS environment. In addition, you specify the transactional requirements for the component. Once these values have been specified, click the OK button to close the dialog box and continue creating your component.
Figure 15-1. The COMTI Component Builder New Component Library dialog box.
Now you can use the COBOL wizard to import the COBOL data declarations from a transaction program and define methods on the interface exposed by your component. In the left-hand pane of the Component Builder, right-click your component, select Import, and then choose COBOL wizard from the pop-up menu. The COBOL wizard walks you through the process of importing data declarations, one method at a time. First you must specify a COBOL file to import, and then you can choose to create a method or a Recordset object. (If you run the wizard on an existing component, you can also update method or Recordset definitions.) Recordset objects are used to access arrays of COBOL tables, and can be accessed by clients as ADO Recordset objects. If you create a method from a COBOL program that includes a fixed-length or variable-length table in the data declarations, a Recordset type will be implicitly defined. If you create a Recordset object explicitly, you can specify the name of the Recordset type that will be defined.
Usually, you will choose to create a method. Choosing this option displays a wizard screen, on which you can specify the name of the method your COM clients will use as well as the information required to connect to the host program running on the mainframe. The wizard will provide reasonable default values for all these settings. After you have entered your own values, click Next to move to the next screen of the wizard, on which you specify the data declarations to use as parameters in the method call. Click Next to display a screen that lets you specify whether each parameter should be input only, output only, input and output, or a return value. As shown in Figure 15-2, the parameters NAME and ACCNUM have been specified as input only parameters and the parameter ACCBAL has been specified as a return value. When you click the Next button on this screen, the wizard indicates whether any errors have occurred while your selections were being processed. You can then click Finish to finalize the method definition.
Figure 15-2. Specifying parameters for a new COMTI component method.
Once you have added all the methods you want in your component, choose the Save command from the File menu to generate the type library for your component.
Not every CICS or IMS program can be used "as is" by COMTI. Three types of transaction programs are supported by COMTI: CICS LINK, CICS (nonlinked model), and IMS. COMTI normally expects that each transaction program contains a single request/reply sequence. (The one exception is a transaction program that returns tables of data.)
CICS programs with embedded terminal logic must be restructured to separate terminal logic from business logic. If a CICS transaction program has already been structured to use a distributed program link (DPL), it will probably work as is. COMTI supports CICS LINK model programs with fixed-size Recordset objects but not with unbounded Recordset objects.
CICS nonlink model programs can use both fixed-size and unbounded Recordset objects. However, nonlink model programs are more complicated than LINK model programs. The transaction program must issue Advanced Program-to-Program Communication (APPC) or Common Programming Interface for Communications (CPIC) verbs to send and receive parameters. Transaction programs that want to participate in distributed transactions must also issue the appropriate verbs to implement Sync Level 2 and two-phase commit protocols.
Most IMS applications will probably work as is. When COMTI invokes a method, a message is sent to the IMS message queue. The transaction program runs in a message processing region and must issue Get commands to retrieve the input parameters. After processing the inputs, the transaction program must issue Insert commands to place the output parameters and return values into the message queue to be returned to COMTI.
The Component Builder automatically maps COBOL types to Automation data types when COBOL data declarations are imported. COMTI provides default mappings for all the standard Automation data types. As mentioned, COMTI also supports mapping COBOL data tables to ADO Recordset objects. The developer can either accept the default mapping or override it with a compatible mapping. (The valid mappings are documented in the COMTI help file.) The mappings used are stored in the type library and are used by the run-time proxy to determine how to pass data to and from the mainframe transaction program. The run-time proxy also takes care of translating between Unicode and EBCDIC character sets.
COMTI can include only CICS transaction programs in MS DTC coordinated distributed transactions. IMS transaction programs can't be included in distributed transactions until IBM provides Sync Level 2 support for IMS. If you mark a COMTI component as "requires a transaction" or "requires a new transaction," the mainframe transaction program must support Sync Level 2. If you mark a COMTI component as "supports transactions," the transaction program must support both Sync Level 0 and Sync Level 2 requests. If the transaction program supports only Sync Level 0, you must mark the COMTI component as "does not support transactions."
You will normally use a COMTI component from another component that provides the root transaction. The COMTI run-time proxy will call SetComplete for interface methods that complete successfully. It calls SetAbort for methods that fail or when the transaction program indicates the transaction should not commit. However, the run-time proxy cannot detect application-specific conditions that might cause the transaction to abort. In this case, the client component must detect the abort condition and call SetAbort itself.
After you create a component, you use the COMTI Management Console to configure the component. The COMTI Management Console is an MMC application that includes both the COMTI and MTS snap-ins.
The first step in configuration is to add the component to an MTS package, following the procedures outlined in Chapter 10. The only file you need to insert into the package is the type library generated by the Component Builder; a COMTI snap-in extension ensures that the type library is recognized as a complete component. If you need to move the MTS package, the normal MTS package export facilities can be used.
You will also need to define a COMTI Remote Environment to specify what connection to use to communicate with the mainframe transaction program. From the COMTI Management Console, select the Remote Environment folder, choose New from the Action menu, and then choose Remote Environment. The Add Remote Environment dialog box lets you specify the type of environment to create: CICS, CICS LINK, IMS, Diagnostic Capture, or Diagnostic Playback. The diagnostic environments are used for testing your component without a real mainframe connection.
Before you define a Remote Environment as CICS or IMS, you must use the SNA Server Manager to configure Local and Remote APPC LU aliases and APPC modes. Once these settings are configured, you can continue with the Remote Environment definition. After you click OK in the Add Remote Environment dialog box, the Remote Environment wizard displays a screen that asks you for the SNA attributes for this environment, as shown in Figure 15-3. Select the Local LU alias, the Remote LU alias, and the APPC mode from the drop-down lists on this screen, and then click Next to continue. On the next screen of the wizard, you can enter a name for the new Remote Environment and, optionally, a comment describing the environment in more detail. Clicking Next takes you to the final screen of the wizard, on which you can click Finish to create the Remote Environment.
Figure 15-3. Specifying the SNA attributes using the Remote Environment wizard.
Every COMTI component must be assigned to a Remote Environment. When you install a component into MTS, the component will automatically be assigned to the default Remote Environment of the correct type (if one exists). If the component is not assigned to the correct Remote Environment, you can move the component from the COMTI Management Console. To do so, select the component you want to move, and then choose the Move command from the Action menu. In the Move Component dialog box, select the name of the destination Remote Environment from the drop-down list, and then click OK to close the dialog box.
Finally, you might need to configure the security settings for your COMTI component. COMTI components can be assigned security attributes just like any other MTS component. However, COMTI also needs to deal with security issues on the mainframe computer.
COMTI provides two security options: package-level and user-level. With the package-level security option, the Microsoft Windows NT identity of the MTS package is used to derive the correct mainframe security credentials, using the single sign-on support in SNA Server. With the user-level security option, the Windows NT identity of the client that invoked the COMTI component is used to derive the correct mainframe security credentials, again using the single sign-on support in SNA Server. An override can be used for either option to explicitly specify security credentials. In this case, no mapping is done; the specified security credentials are used directly.
To set package-level or user-level security on the Remote Environment, select Remote Environment in the COMTI Management Console and then choose the Properties command from the Action menu. Select the Securities tab, and then specify the security level. If you want to use explicit security, check the Allow Application Override check box.
If you use explicit security, your application must provide a callback object that can be used to retrieve security credentials. The requirements for this callback object are described in detail in the COMTI Online Guide.
Once security is configured, your component is ready for use.
See Angela Mills' excellent white paper "Using Microsoft Transaction Server 2.0 with COM Transaction Integrator 1.0" for further information about how COMTI works. This white paper is available from the COM home page at http://www.microsoft.com/com/.