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

• Calling the Transaction Object Editor

• Managing TOR Files

• Defining Methods

• Specifying Connection Information

• Defining Custom Data Types

• TOR Files in IDL Format

• TOR Files in XML Format

• Storing TOR Files in a Tamino Database

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.

When the Transaction Object Editor is started, a license check is performed. If there is no license file or if the license has expired, the editor will be closed.

Note:
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 DOS prompt in folder <drive>:\SoftwareAG\EntireX\bin 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.

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

• Edit Menu

• Options Menu

• Help Menu

File Menu

Edit Menu

Options Menu

Help Menu

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

• Call Type

• Parameters

• Return Object

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 Defining Connection Information.

Call Type

The Call Type tab represents the call types that can be used for this method.

The Call Type tab is shown in the 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.

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.

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.

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

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.

Connection Information Parameters

See Properties of Broker ActiveX Control 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 of Broker ActiveX Control).

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:

• Custom Data Type 'Alias'

• Custom Data Type 'Array '

• Custom Data Type 'Record'

• Custom Data Type 'Structure'

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 '

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

TOR Files in IDL Format

When a TOR file is saved in IDL format, a file with extension .idl is generated. (The file must have been saved as a TOR file before).

This IDL file can be used by other EntireX tools such as DCOM Wrapper or Java Wrapper. It can be modified with any editor like a regular IDL file.

Conversion Rules

List of the performed conversions:

TOR Files in XML Format

To use TOR files in XML format, Internet Explorer 5 or above is required.

Loading an XML File

When you load an XML file, the XML file is checked against the defined DTD (see The DTD File list below). When you use the XML file, it is not necessary to store the transaction object in TOR file format.

Saving an XML File

When a TOR file is saved in XML format, a file with the extension .xml is generated.

This XML file can be viewed with a browser that supports XML. It can also be viewed and edited with any XML notepad or any text editor.

The DTD File

The structure of the XML file is defined in the DTD file. When you use a tool that validates XML files, the XML file is checked against these definitions.

<!ELEMENT EntireXTorFile (DefaultConnection? , Method*, CDT*)>

<!ATTLIST EntireXTorFile Name CDATA #IMPLIED 
                  Version CDATA #IMPLIED>

<!ELEMENT DefaultConnection EMPTY>

<!ATTLIST DefaultConnection %Connection;>

<!ELEMENT Method (MethodConnection? , Parameter*)>

<!ATTLIST Method Name CDATA #REQUIRED 
     CallType (SEND | RECEIVE | SEND-RECEIVE |
       LOGON | LOGOFF |EOC | SYNCPOINT | 
       REGISTER | DEREGISTER | SUBSCRIBE | 
       UNSUBSCRIBE | SEND_PUB | RECEIVE_PUB | 
       CONTROL_PUB) #REQUIRED
     ManualOffset (YES | NO) #IMPLIED>

<!ELEMENT MethodConnection EMPTY>

<!ATTLIST MethodConnection %Connection;>

<!ELEMENT Parameter (InFormat, OutFormat, Length?)>

<!ATTLIST Parameter Name CDATA #IMPLIED
              Direction (IN | OUT | INOUT) #IMPLIED
              Offset CDATA #IMPLIED>

<!ELEMENT CDT (Alias | Array | Record | Structure) >

<!ATTLIST CDT Name ID #REQUIRED>

<!ELEMENT Alias (InFormat, OutFormat, Length?)>

<!ELEMENT Array (InFormat, OutFormat, Length?)>

<!ATTLIST Array NumberEle CDATA #IMPLIED>

<!ELEMENT Record (Parameter*)>

<!ATTLIST Record NumberEle CDATA #IMPLIED>

<!ELEMENT Structure (Parameter*) >

<!ELEMENT InFormat (Scalar | UsedCDT)>

<!ELEMENT Scalar EMPTY>

<!ATTLIST Scalar Format (I1 | I2 | I4 | F4 | F8 |
 Bool | String | Blob | Padding) #REQUIRED>

<!ELEMENT UsedCDT EMPTY>

<!ATTLIST UsedCDT Target IDREF #REQUIRED>

<!ELEMENT OutFormat (Scalar | UsedCDT)>

<!ELEMENT Length EMPTY>

<!ATTLIST Length Value CDATA #IMPLIED>

<!ENTITY % Connection
       'ServerClass CDATA #IMPLIED 
       ServerName CDATA #IMPLIED 
       Service CDATA #IMPLIED
       ConversationID (NONE | NEW | OLD | ANY)
       #IMPLIED 
       UOWTime CDATA #IMPLIED 
       BrokerID CDATA #IMPLIED 
       UserID CDATA #IMPLIED 
       Password CDATA #IMPLIED 
       Environment CDATA #IMPLIED 
       Wait CDATA #IMPLIED 
       UOWStatusPersist CDATA #IMPLIED 
       Option (NULL | MSG | HOLD | IMMED | QUIESCE
       | EOC | CANCEL | LAST | 
       NEXT | PREVIEW | COMMIT | BACKOUT |
       SYNC | ATTACH | DELETE |
       EOCCANCEL | QUERY | SETUSTATUS | ANY | 
       TERMINATE |DURABLE |CHECKSERVICE)
       #IMPLIED 
       Encryption (NONE | TO-BROKER | TO-TARGET )
       #IMPLIED
       ForceLogon (NO | YES)  #IMPLIED
       CompressLevel   CDATA  #IMPLIED
       Token           CDATA  #IMPLIED 
       Topic           CDATA  #IMPLIED 
       PublicationID   CDATA  #IMPLIED 
       UOWStatusLife   CDATA  #IMPLIED 
       BrokerSecurity  CDATA  #IMPLIED"   >

Defining the Location of the DTD and XSL File

A DTD file is used to check the XML file. An XSL file is used to view the XML file. To locate these files, enter a reference in the XML Options:

This reference can be a URL (like above) or a regular path (e.g., the default: the EntireX etc directory).

Using the XML Objects During Runtime

The XML file can also be used during runtime. It must be defined in the same way as the TOR file.

Visual Basic Example

Set TransObject=BOCX.CreateTransObject ("...\\calc.xml")

Storing TOR Files in a Tamino Database

To store and use TOR files in a Tamino database, Tamino 4.2.1 or higher and Internet Explorer 5 or higher are required.

Creating a Tamino Database for the TOR Files

In the EntireX etc directory an EntireXTorIno vrs.xml is provided. This file can be used to define the schema in Tamino (_define function). It is very close to the DTD file. The XML files generated can be directly stored in Tamino. The database prefix defined in Tamino must be defined in the XML Options screen as well as the server name of the Tamino database.

Loading Tamino Objects using the TOR Editor

When loading a Tamino object, the following dialog will be displayed:

If necessary, the Tamino server name and the Tamino database prefix can be changed here. The name of the desired object can be entered directly or selected from the drop-down menu Select by Object Name.

Storing Tamino Objects using the TOR Editor

When saving a Tamino object, the following dialog will be displayed:

If necessary, the Tamino server name and the Tamino DB prefix can be changed here. The name of the object must be entered in the Tamino Object Name field. If a Tamino object with this name already exists, you can overwrite the existing file or cancel the save operation.

Using Tamino Objects During Runtime

The Tamino object can also be used during runtime. It must be defined like the XML file:

Visual Basic Example

Set TransObject=BOCX.CreateTransObject ("Calc")

Note:
The name of the Tamino object is case-sensitive.

The Tamino server name and the Tamino DB prefix from the General XML Options screen are used.