Transaction Object (TOs) in Broker ActiveX Control are selections of logical methods that are stored in a transaction object repository (TOR). These logical methods contain all the connection and interface details necessary to communicate with EntireX Broker. This document covers the following topics:
The advantages of using transaction objects are:
Services are defined once, in one place, and distributed as needed. They can then be used by anyone from many different applications to access back-end applications.
Transaction objects can encapsulate all connection and conversational information from the developer, which simplifies the implementation and administration of distributed applications.
The send buffer of a message is broken down into parameters, and the receive buffer is mapped to the return object. This means you do not have to worry about offsets, data types, repeating fields (arrays), or structures.
The Transaction Object Editor is a tool within Broker ActiveX Control
with which you can define and maintain transaction objects. It is invoked by
calling the method DefineTOMethods from a form that
includes an ActiveX control.
The Transaction Object Editor can be called directly using the
TORedit executable. The extension
".tor" is registered as a file type, so you can call
the Transaction Object Editor with a double click from the Windows
Explorer.
Notes:
regsvr32 ebx.dll.
If you later want to use a TOR Editor from a different installation directory, register the corresponding ebx.dll as above.
When a transaction object is loaded, the corresponding file name will be displayed in the title bar. If loading or saving fails, an error message will be displayed in the title bar.
The following functions are available for managing TOR files.
| Menu Item | Description |
|---|---|
| Resets the TOR Editor. | |
| Loads an existing TOR file. A standard Open File dialog will be displayed. This function is needed to modify an existing TOR file. | |
| Saves a TOR file. | |
| Saves a new or modified TOR file. A standard Save File dialog will be displayed. | |
| Closes the TOR Editor. |
| Menu Item | Description |
|---|---|
| Calls the Custom Data Types dialog. See Defining Custom Data Types. | |
| Calls Broker Connection Information dialog. See the Specifying Connection Information |
| Menu Item | Description |
|---|---|
| Displays the About box. |
The following buttons are available in the transaction method definition model:
The button causes the method name within the dialog box to be added to the store.
The button copies the currently selected method to a new method.
The button removes the selected method from the store.
Methods are logically grouped in a transaction object. Each method specified in the transaction object relates directly to a specific Broker service. To define a new method, therefore, you need to know which services are available. Each method requires the following information:
Connection information is specified using the Broker Connection Information dialog. Each TOR file has default connection information, and each method has its individual connection information. If a parameter is not defined in the connection information of a method, the default is taken. For a description of the parameters, see Specifying Connection Information.
The Call Type tab represents the call types that can be used for this method.
| Call Type | Description |
|---|---|
| Send Data | Used to define a method that accepts parameters but does not return data from the service. This could be used to notify a back-end application of some event without waiting for a response. |
| Send and Receive Data | Used to define a method that accepts parameters and returns data from that service. |
| Receive Data | Can be used to get information from a back-end application that requires no input, for example MOTD (message of the day) information. It is also used to wait for incoming requests if you are using Broker ActiveX Control to write Broker Server applications. |
| Logon | Logon to EntireX Broker. |
| Logoff | Logoff from EntireX Broker. |
| End of Conversation | Used to end a conversation. |
| Syncpoint | Used to commit, backout, or cancel a unit of work, obtain the status of a unit of work, or delete the persistent status of a unit of work. |
| Register | Informs EntireX Broker that a service is available. |
| Deregister | Removes previously registered services from EntireX Broker's active list. |
The Call Type tab is shown in the Transaction Object Editor screen above.
The Parameter tab exposes a multiline box containing individual parameter variables.
These parameters are placed into the SEND-BUFFER of the EntireX Broker call. Each parameter has a data type (Integer, Real, String etc.) and a length.
If data is sent, it is necessary to define a parameter list for this
method. The TO method parameter list serves as a "map"
between the types passed as parameters, and the data types and locations within
the method's send buffer. Items within the TO method
parameter list are ordered sequentially as they will be passed when the method
is invoked.
A list control is used for defining, removing and ordering parameters of the current method. The list control supports in-place editing of items names, and works together with the item configuration controls positioned below. When a particular item is selected, it can be moved up and down the list sequentially. The order of the list defines the order in which parameters are passed when the method is invoked. Note that offsets are automatically generated for each list item, relative to the start of the list, and the items (and their sizes) that precede it.
The Add function adds the field after the
selected position.
Data conversion is also supported between a type provided by the client and the type expected by the Broker service. For parameters, the user can specify the data type that will be provided, and the type that will be sent to the Broker service. For return objects, the data received by the Broker service can be set to the data type retrieved by the user. The important data types are those sent to and received from a Broker service. Broker ActiveX Control automatically converts between the data type received from the Broker and a data type specified by the user (see the Data is received as and Data is retrieved as fields in the screen below).
The scalar data types supported by the Broker ActiveX are a subset of the standard Automation VARIANT types and are listed below. In cases where the selected data type is of fixed length, the data length edit control is set to the appropriate length and grayed.
| Transaction Object Method Data Types | Description |
|---|---|
| 1-byte Integer | 1-byte Integer used for signed and unsigned. |
| 2-byte Integer | 2-byte Integer used for signed and unsigned. |
| 4-byte Integer | 4-byte Integer used for signed and unsigned. |
| 4-byte Real | 4-byte Real compatible with "C" float. |
| 8-byte Real | 8-byte Real compatible with "C" double. |
| Bool | Boolean variable. |
| String | String of specified length. |
| Blob | Generic byte block. |
| Padding | Used to separate types in the buffer. |
If the transaction object method is invoked with call type 'Send and Receive' or 'Receive', a Return Object is created. This is a logical object that enables you to retrieve multiple scalar values or records by referencing its properties.
The Return Object tab exposes the individual properties that are mapped onto the RECEIVE-BUFFER of the Broker call. When the data is returned from the Broker service, Broker ActiveX Control uses the types and lengths of the defined properties to populate the values of the properties. You can now access the contents of the receive buffer as ActiveX properties of the method that is created by loading the transaction object.
As with the parameters, Broker ActiveX Control calculates the offset in the RECEIVE-BUFFER for each property. For information on list control, data conversion and implemented data types, see Defining a Parameter List.
Custom Data Types are used for non-scalar data types such as arrays and structures. They are also used to assign aliases to parameters for consistent naming purposes.
The Manually set data offset check box allows the transaction object designer to override automatic offset calculation and specify offsets manually. This feature is powerful, but also potentially dangerous, because no base type checking can be performed.
Connection information relates directly to the Broker service that you want to communicate with when using this method.
Transaction methods are defined using the Transaction Object Editor.
Connection information is specified using the Broker Connection
Information dialog. Each TOR file has default connection
information, and each method has its individual connection information. If a
parameter is not specified in the connection information of a method, the
default is taken. The Broker parameters are part of this connection information
(with the exception of Function, which depends on the
Call Type).
The Broker Connection Information dialog box accepts all the parameters required for establishing the necessary Broker connection to execute the defined method/call type. Information in this dialog can be changed without affecting the application code. For example, if the BrokerID changed, you would change the connection information in the methods (services) affected and distribute the new transaction object file. The next time the application code loads the transaction object file and calls a method, the new connection information will be used.
| Parameter | Description | ||||||||
|---|---|---|---|---|---|---|---|---|---|
| ServerClass, ServerName, Service | These three parameters represent the unique "signature" of this method call. | ||||||||
| BrokerID | The unique name of the Broker node that the services are attached to. See Using the Broker ID in Applications in the ACI Programming documentation and details on TCP/IP under Transport Methods. | ||||||||
| Wait | The following values are set for this parameter, depending on
the operation:
|
See Properties for a description of the other parameters.
Calling a method of a transaction object results in a Broker call. The parameters for the Broker call are taken either
from the Broker Connection Information dialog, see above, or
from the properties (see Properties).
If a value is specified in the Connection Information dialog, this value is taken and overrides any value specified in the properties.
If no value is specified in the Connection Information dialog, the current setting of the properties is taken. Leaving these parameters blank in the Connection Information dialog enables you to change these parameters dynamically, and also enables Broker communication in conversational mode. See example below:
This example shows a possible usage of dynamic parameter assignment:
Set TransObject=BOCX.CreateTransObject ("...calc.tor")
BOCX.UserID = "USER1"
BOCX.BrokerID = "ETB121"
Set ReturnOb = TransObject.calc("+", "000000000001", "000000000002")
The Custom Data Types dialog allows you to define new data types that will appear in the Return Object tag. With the button you can embed a custom type within another custom type as long as this does not result in a recursive inclusion.
The following four classes of custom data types are supported:
Any custom data type can be used in transaction objects return objects. Custom data types are not supported as method parameters.
Note:
All custom data types can be used recursively. That is, any custom
data type can be used as a member or base type for any other custom type. This
allows for nested structures, as well as arrays within structures and
records.
An alias is a custom data type that allows an administrator to specify an alias for any defined data type - custom or not. Aliasing also allows the definition of data types with specific in and out data types (type translation).
An array consists of multiple serial elements of the same data types. Arrays can be made up of either scalar or custom data types. The number of elements in an array must be specified.
Array custom data types accept the same basic information as alias data types, with the addition of the number of elements in the array. Arrays allow elements of the specified base type to be accessed in a subscripted fashion.
Note:
Multidimensional arrays and arrays of structures can be implemented
by specifying a custom array or record data type as the base type of this
array.
A record is a repeating collection of data types - scalar or custom.
This custom data type allows you to define a collection of data types that can be accessed in a subscripted fashion. The order of defined types in the Record can be changed. Also, the number of records within the receive buffer can be specified if known.
A structure is a named collection of data types.
The controls for this custom data type are identical to those of the data type 'record', with the exception of a repetitive count, which is not applicable.