Transaction Objects in Broker ActiveX Control

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:


Advantages of Transaction Objects

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.

Calling the Transaction Object Editor

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:

  1. After installation you will find the Transaction Object Editor in directory <inst_root>\EntireX\bin\x86 (32-bit).
  2. Before you start the TOR Editor for the first time, you need to register the required DLL ebx.dll to your Windows system manually. Simply open a Windows Command prompt in folder <inst_root>\EntireX\bin\x86 and run the command regsvr32 ebx.dll. If you later want to use a TOR Editor from a different installation directory, register the corresponding ebx.dll as above.

TOR Editor

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.

Managing TOR Files

The following functions are available for managing TOR files.

File Menu

Menu Item Description
New Resets the TOR Editor.
Open Loads an existing TOR file. A standard Open File dialog will be displayed. This function is needed to modify an existing TOR file.
Save Saves a TOR file.
Save as Saves a new or modified TOR file. A standard Save File dialog will be displayed.
Exit Closes the TOR Editor.

Edit Menu

Menu Item Description
Custom Types Calls the Custom Data Types dialog. See Defining Custom Data Types.
Connection Calls Broker Connection Information dialog. See the Specifying Connection Information

Help Menu

Menu Item Description
About Displays the About box.

Defining Methods

The following buttons are available in the transaction method definition model:

  • The New button causes the method name within the dialog box to be added to the store.

  • The Copy button copies the currently selected method to a new method.

  • The Delete 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

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.

Call Type

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.

Parameters

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.

TOR parameters

Defining a Parameter List

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.

List Control

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

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).

Implemented Data Types

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.

Return Object

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.

TOR Return 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.

Specifying Connection Information

Introduction

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.

Connection Information Parameters

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 EntireX Broker ACI Programming documentation and details on TCP/IP under Transport Methods.
Wait The following values are set for this parameter, depending on the operation:
Operation Wait Value (in seconds)
Send 0
Send and Receive 30 (*)
Receive 59 (*)
(*) if no value is specified in the Connection info.

See Properties for a description of the other parameters.

Setting the Broker Call 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:

Visual Basic Example

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")

Defining Custom Data Types

The Custom Data Types dialog allows you to define new data types that will appear in the Return Object tag. With the Apply 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.

Custom Data Type 'Alias'

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).

Custom Data Type 'Array '

Custom data type array

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.

Custom Data Type 'Record'

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.

Custom data type record

Custom Data Type 'Structure'

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.