This chapter explains how Net Express interfaces with Microsoft Component Services.
Microsoft COM+, also known as Component Services, provides a transaction processing system for developing, deploying, and managing high performance, scaleable, and robust enterprise, Internet, and intranet server applications. Component services define an application programming model for developing distributed applications. They also provide a run-time infrastructure for deploying and managing these applications.
Component services enable you to break down transactions into components that perform discrete functions. A component notifies the component 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 COM+ components in COBOL using Net Express. It does not cover how to set up and administer Component Services or any of the more advanced features that are available to programmers. For further information, you should refer to the documentation supplied with Microsoft COM+.
Any component used with Component Services must be compiled and linked as an in-process COM server. This section describes the structure of a component and how to build it. You can generate the skeleton of a COM+ 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 Creating COM Objects for more information on creating COM Automation servers in COBOL.
All components used with COM+ 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 COM prog-id and the name recognized by Component Services. |
| 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 Component Services. It should be included in the class-control section, for example:
class-control.
Combase is class "combase"
objectcontext is class "objectcontext".
Note: The class objectcontext is provided in the file objectcontext.dll. This file should be included with your COM+ components when you distribute your application.
Each COM+ component has an associated context object. A context object is an extensible COM+ object that provides context for the execution of an instance, including transaction, activity, and security properties. When a COM+ component is created, a context object is automatically created for it. When the COM+ component is released, Component Services 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 Component Services (that is, it has not been imported into a COM+ package), a value of NULL is returned in the object context.
A COM+ component can obtain the constructor string defined in the COM+ properties by implementing a receiveConstructorString instance method as detailed below.
Example:
method-id. "receiveConstructorString".
local-storage section.
linkage section.
01 arrayObject object reference.
procedure division using by value arrayObject.
*> add code to process the string here.
exit method.
end method "receiveConstructorString".
Provides an initialization string specified in the properties of the component. ReceiveContructorString returns an object reference to a CharacterArray object.
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 COM+ method of the same name. Refer to your Microsoft documentation for complete information on the functionality of each of these methods.
Example:
01 NewObject object reference.
invoke Context "CreateInstance"
using z"Account"
returning NewObject
Creates a new instance of a COM+ 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.
Example:
invoke Context "SetAbort"
Declares that the transaction in which the object is executing must be aborted.
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.
You can generate the skeleton of a COM+ 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 Distributing COM Components.
COM+ components execute under the control of COM+ 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, add the following line 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 Net Express can find the source and debug files, set the following environment variables in the system environment:
COBIDY - set to the directory containing the .idy file for the component.
COBCPY - set to the directory containing the source files for the component.
Net Express includes an example of a complete COM+ component, which is an implementation in COBOL of the Account object supplied with COM+. The example is called account.cbl, and you can find it in directory Examples\Net Express IDE\mtx.
Copyright © 2006 Micro Focus (IP) Ltd. All rights reserved.