| Combination ActiveX/Java Classes | Interfacing with IBM WebSphere | |
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.
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.
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. |
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.
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.
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.
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.
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.
Example :
invoke Context "SetAbort"
Declares that the transaction in which the object is executing must be aborted.
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.
Example :
invoke Context "DisableCommit"
Declares that the component's transactional updates are inconsistent and cannot be committed in their present state.
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.
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.
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.
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.
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.
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.
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.
| Combination ActiveX/Java Classes | Interfacing with IBM WebSphere | |