PreviousCombination ActiveX/Java Classes Interfacing with IBM WebSphereNext

Chapter 10: Interfacing with Microsoft Transaction Server

Microsoft Transaction Server is a component-based transaction processing system for developing, deploying, and managing high performance, scaleable, and robust enterprise, Internet, and intranet server applications. Transaction Server defines an application programming model for developing distributed, component-based applications. It also provides a run-time infrastructure for deploying and managing these applications.

Transaction Server allows you to break down transactions into components that perform discrete functions. A component notifies Transaction Server whether it has completed successfully or not. If all the components in a transaction complete successfully, the transaction is committed. If not, the transaction is rolled back.

This chapter explains how to create Transaction Server components in COBOL using Net Express. It does not cover how to set up and administer Transaction Server or any of the more advanced features that are available to programmers. For further information, you should refer to the documentation supplied with Microsoft Transaction Server.

10.1 Creating a Transaction Server Component

Any component used with Microsoft Transaction Server must be compiled and linked as an in-process OLE server. This section describes the structure of a component and how to build it. You can generate the skeleton of a transaction server component with the Net Express Class Wizard (click Help Topics on the Net Express Help menu and look up Class Wizard using the Index tab). Refer to the chapter OLE Automation and DCOM for more information on creating OLE servers in COBOL.

10.1.1 The Structure of a Transaction Server Component

All components used with Transaction Server have the same basic structure :

 $set ooctrl(+P) 
     class-id.
         component-name inherits from olebase.

     object section.
     class-control.
         Olebase is class "olebase"
         objectcontext is class "objectcontext".

     object.

     method-id. "method-name".

     local-storage section.

     01 Context              object reference.

   << Any data items local to the method >>

     linkage section.

   << Definition of any parameters to the method >>

     procedure division using linkage-section-items.
    *    Get our object context. Context will be set to NULL
    *    if we are not running under the control of Transaction
    *    Server
         invoke objectcontext "GetObjectContext" returning Context

   << Do the processing required for this component >>

    *    If the processing is successful, issue the SetComplete call,
    *    otherwise issue SetAbort.
         if everything-ok 
             if Context not = NULL
                 invoke Context "setComplete"
             end-if
         else
             if Context NOT = NULL
                 invoke context "setAbort"
             end-if
         end-if

    *    Ensure that the component terminates cleanly
         if Context not = NULL
             invoke Context "finalize" returning context
         end-if
         exit method.
     end method "method-name".

     end object.
     end class component-name.
component-name The name that will be used for the component. This name will be used as the OLE prog-id and the name displayed in the Microsoft Transaction Server Explorer.
method-name The name used for the method to be invoked in the component. You can have multiple methods inside a component.

10.1.2 The objectcontext Class

The class objectcontext provides access to the functionality provided by Transaction Server. It should be included in the class-control section, for example :

     class-control.
         Olebase is class "olebase"
         objectcontext is class "objectcontext".


Note: The class objectcontext is provided in the file objectcontext.dll. This file should be included with your Transaction Server components when you distribute your application.


10.1.3 The Context Object

Each Microsoft Transaction Server component has an associated context object. A context object is an extensible Transaction Server object that provides context for the execution of an instance, including transaction, activity, and security properties. When a Transaction Server component is created, Transaction Server automatically creates a context object for it. When the Transaction Server component is released, Transaction Server automatically releases the context object.

To retrieve the context object for your component, use the class method GetObjectContext. This returns an object reference to the context object. For example:

   01 Context           object reference.

   invoke objectcontext "GetObjectContext" returning Context

This context object is specific to your component and should not be passed to other objects.

If your component is not running under the control of Transaction Server (that is, it has not been imported into a Transaction Server package), a value of NULL is returned in the object context.

10.1.4 Terminating a Transaction Server Component

Before your component terminates, you should release the object context. This is done using the finalize method. For example :

   invoke Context "finalize"
       returning context

This ensures that your component is correctly removed from memory when all references to it are released.

10.1.5 Methods Provided by Objectcontext

The following methods in the class objectcontext can be accessed once you have acquired the context for the component. Each of these methods maps directly on to the Transaction Server method of the same name. Refer to your Transaction Server Programmer's Guide for complete information on the functionality of each of these methods.

10.1.5.1 SetComplete

Example :

    invoke Context "SetComplete" 

Declares that the current component has completed its work. For objects that are executing within the scope of a transaction, it also indicates that the object's transactional updates can be committed.

10.1.5.2 SetAbort

Example :

    invoke Context "SetAbort" 

Declares that the transaction in which the object is executing must be aborted.

10.1.5.3 CreateInstance

Example :

    01 NewObject        object reference.
    invoke Context "CreateInstance"
        using z"Account"
        returning NewObject

Creates a new instance of an OLE component, using the current context. The name passed is the prog-id of the component. It must be null-terminated. CreateInstance returns an object reference to the new component. The new instance uses the context of the current component.

Once an instance of a component has been created using CreateInstance, it can be used as if it had been created using the "new" method on the component.

10.1.5.4 DisableCommit

Example :

    invoke Context "DisableCommit" 

Declares that the component's transactional updates are inconsistent and cannot be committed in their present state.

10.1.5.5 EnableCommit

Example :

    invoke Context "EnableCommit" 

Declares that the current component's work is not necessarily finished, but that its transactional updates are consistent and could be committed in their present form.

10.1.5.6 IsInTransaction

Example :

    01 ReturnValue        pic x(4) comp-5.
    invoke Context "IsInTransaction"
returning ReturnValue

Returns non-zero if the current component is executing in a transaction. A value of 0 is returned if the component is not executing inside a transaction.

10.1.5.7 IsCallerInRole

Example :

    01 ReturnValue        pic x(4) comp-5.
    invoke Context "IsCallerInRole"
           using z"Managers" ReturnValue

Indicates whether a component's direct caller is in a specified role (either individually or as part of a group). Returns 0 if the caller is not in the specified role. Returns non-zero if the caller is in the role or if security is not enabled. The role should be specified as a null-terminated string.

10.1.5.8 IsSecurityEnabled

Example :

    01 ReturnValue        pic x(4) comp-5.
    invoke Context "IsSecurityEnabled"
           returning ReturnValue

Returns 0 if security is not enabled for this component or returns non-zero if security is enabled.

10.1.6 Building a Transaction Server Component

You can generate the skeleton of a transaction server component with the Net Express Class Wizard (click Help Topics on the Net Express Help menu and look up Class Wizard using the Index tab). To build the component, follow the procedure described in the section Creating In-Process Servers in the chapter OLE Automation and DCOM.

10.2 Execution and Debugging of Transaction Server Components

Transaction Server components execute under the control of Transaction Server itself and so no assumptions can be made about the environment the component will be executing in or which users are logged on when the component is executed.

If you are runnig the component on a PC that does not have Net Express installed, you should add the directory that contains the COBOL run-time files to the system path. This will ensure that they can always be found by the component.

If you want to debug a component, the following line should be added to the component, at the start of the procedure division for the method you want to debug :

 call "cbl_debugbreak" 

This causes the Net Express debugger to be invoked when the component is executed. To ensure that the source and debug files can be found by Net Express, you should set the following environment variables in the system environment :

COBIDY - should be set to the directory containing the .idy file for the component.

COBCPY - should be set to the directory containing the source files for the component.

10.3 Example of a Complete Transaction Server Component

Net Express includes an example of a complete Transaction Server component, which is an implementation in COBOL of the Account object supplied with Transaction Server. The example is called account.cbl, and you can find it in directory \Program Files\MERANT\Net Express\base\demo\mtx.


Copyright © 2000 MERANT International Limited. All rights reserved.
This document and the proprietary marks and names used herein are protected by international law.

PreviousCombination ActiveX/Java Classes Interfacing with IBM WebSphereNext