TIBCO ActiveEnterprise(TM) Module 1.0

Module Reference Manual

David Nichols

V. 1.0

Revision History
Revision 1.0	5 September 2008	dn
split from qore documentation

tibae Module

The tibae module provides TIBCO ActiveEnterprise(TM) functionality; that is, the ability to use an adapter configuration decribing function and data classes to communicate safely with other TIBCO ActiveEnterprise(TM) components.

Note

ActiveEnterprise is a trademark of TIBCO, Inc.

Note that the code in this module is not available with the PO_NO_NETWORK parse option.

To use this module, include the following line in the qore program to load the module:

%requires tibae

Note

This module was previously called "tibco", however it was renamed to avoid confusion with the tibrv module

The following table describes how Qore data is converted to Tibae data. To serialize to other types, use the Tibae Type Constants with the tibae_type() function.

Table 1. Default Serialization of Qore Data -> Tibae Format

Qore Type	Tibae Type
`Type::Boolean`	`Boolean`
`Type::Int`	`i4`, unless the integer is > 32bit, then `i8`
`Type::Float`	`r8`
`Type::String`	`String`
`Type::Binary`	`Binary`
`Type::Date`	`DateTime`, unless the repository calls for a `Date`
`Type::Hash`	`Class` as expected by the repository or specified by the ^class^ key
`Type::List`	`Sequence` as expected by the repository, only when instantiating a class

Table 2. Deserialization of Tibae Message Data -> Qore Data Structures

Tibae Type	Qore Type
`Class`	`Type::Hash`
`Associative List`	`Type::Hash`
`Union`	`Type::Hash`
`Sequence`	`Type::List`
`String`	`Type::String`
`Integer`	`Type::Int`
`Real`	`Type::Float`
`DateTime`	absolute `Type::Date`; when compiled with qore 0.8.0+, microsecond resolution is maintained
`Date`	absolute `Type::Date`
`Time`	absolute `Type::Date`; the date portion is set to 1970-01-01; when compiled with qore 0.8.0+, microsecond resolution is maintained
`Interval`	relative `Type::Date`
`Boolean`	`Type::Boolean`
`Binary`	`Type::Binary`

Table 3. Tibae Type Constants

Constant
`TIBAE_BINARY`
`TIBAE_BOOLEAN`
`TIBAE_BYTE`
`TIBAE_CHAR`
`TIBAE_DATE`
`TIBAE_DATETIME`
`TIBAE_FIXED`
`TIBAE_I1`
`TIBAE_I2`
`TIBAE_I4`
`TIBAE_I8`
`TIBAE_INTERVAL`
`TIBAE_R4`
`TIBAE_R8`
`TIBAE_STRING`
`TIBAE_TIME`
`TIBAE_U1`
`TIBAE_U2`
`TIBAE_U4`
`TIBAE_U8`

tibae_type()

Synopsis

Creates a hash structure to ensure that qore data is serialized as a particular Tibae data type as specified by the first argument (use one of the constants in the Tibae Type Constant list).

Usage

tibae_type(integer, any)

Example

$val = tibae_type(TIBAE_INTERVAL, 5D + 3h + 2m + 25s);

Table 4. Arguments and Return Values for tibae_type()

Argument Types	Return Type	Description
Integer, Any	Hash	Creates a hash structure to ensure that qore data in the second argument is serialized as the Tibae type specified by the first argument.

Tibae::TibcoAdapter Class

TibcoAdapter objects allow Qore programs to communicate with other TIBCO Active Enterprise components over the TIBCO message bus.

Use of this class requires a valid TIBCO repository with an adapter configuration (can be empty) and any ActiveEnterprise class definitions for outgoing messages and responses.

String data is converted to UTF-8 format if necessary for transmission with TIBCO Rendezvous.

The TibcoAdapter::constructor() method takes an adapter property hash to give the location for the repository and tell the SDK how the adapter should be instantiated. The table below describes the recognized keys in the adapter property hash and how they are used to describe the repository and the adapter. Note that the Vars key in the property hash is used to override global variable values in the adapter.

When Qore data is serialized to TIBCO data format and you need to specify the class name for the data, use a hash and put the class name in the ^class^ key and the value in the ^value^ key.

Otherwise generally Qore data types are transformed to TIBCO data types. If the data type does not match what the repository has defined, then a run-time exception is raised.

Table 5. TIBCO Adapter Property Hash

Key	Description
`AppInfo`	Information for the adapter.
`AppName`	The name of the adapter.
`AppVersion`	The version of the adapter.
`RepoURL`	The locataion of the repository.
`ConfigURL`	The location of the adapter in the repository.
`Vars`	This key can be set to a hash to override global variable values.

Table 6. Method Overview

Method	Except?	Description
TibcoAdapter::constructor()	Y	Creates the adapter object based on the repository URL, class hash, and the connection parameters passed.
TibcoAdapter::destructor()	N	Destroys the TibcoAdapter object.
TibcoAdapter::copy()	Y	Throws an exception; objects of this class cannot be copied.
TibcoAdapter::receive()	Y	Creates a listener and receives data based on the subject and timeout values passed.
TibcoAdapter::sendSubject()	Y	Creates a publisher and transmits data.
TibcoAdapter::sendSubjectWithSyncReply()	Y	Creates a publisher, transmits data, and returns a data structure representing the reply.
TibcoAdapter::callOperationWithSyncReply()	Y	Calls a Tibco Adapter Operation and returns a data structure representing the reply.
TibcoAdapter::callOperationOneWay()	Y	Calls an one way (no reply sent) Tibco Operation.

TibcoAdapter::constructor()

Synopsis

Opens and parses a repository and instantiates an instance of an adapter based on the arguments passed.

Usage

new TibcoAdapter(session_name, properties, [classlist, service, network, daemon])

Table 7. Arguments for TibcoAdapter::constructor()

Argument	Type	Description
`session_name`	String	The name of the session in the adapter.
`properties`	Hash	Adapter properties, see Adapter Property Hash for more information.
`[classlist]`	Hash	Maps function class names to adapter positions.
`[service]`	String	Service for rendezvous daemon to connect to.
`[network]`	String	Network parameter for Rendezvous daemon to connect to.
`[daemon]`	String	Daemon IP address for Rendezvous daemon to connect to.

Table 8. Return Values for TibcoAdapter::constructor()

Return Type	Description
TibcoAdapter Object	The new object created.

Table 9. Exceptions Thrown by TibcoAdapter::constructor()

err	desc
`TIBCO-INVALID-PROPERTIES-HASH`	Non-string value found in properties hash.
`TIBCO-PARAMETER-ERROR`	Invalid parameters passed to constructor.
`TIBCO-EXCEPTION`	The TIBCO SDK raised an exception instantiating the adapter.

TibcoAdapter::destructor()

Synopsis

Destroys the object.

Usage

delete lvalue

TibcoAdapter::copy()

Synopsis: Throws an exception - copying TibcoAdapter objects is not supported.

Table 10. Exceptions Thrown by TibcoAdapter::copy()

err	desc
`TIBCO-ADAPTER-COPY-ERROR`	Objects of this class cannot be copied.

TibcoAdapter::receive()

Synopsis

Creates a listener and receives data based on the subject and timeout values passed.

Usage

TibcoAdapter::receive(subject, [timeout ms])

Table 11. Arguments for TibcoAdapter::receive()

Argument	Type	Description
`subject`	String	The subject to listen on.
`[timeout ms]`	Integer or Date/Time	The timeout in milliseconds (1/1000 second) or as relative date/time.

Table 12. Return Values for TibcoAdapter::receive()

Return Type	Description
Hash	The message received. If a timeout value was set and no message was sent within the timeout period, no value is returned.

Table 13. Exceptions Thrown by TibcoAdapter::receive()

err	desc
`MAP-ERROR`	Don't know how to map TIBCO data to Qore data (unsupported TIBCO data type).

TibcoAdapter::sendSubject()

Synopsis

Creates a publisher and transmits data.

Usage

TibcoAdapter::sendSubject(subject, function, message)

Table 14. Arguments for TibcoAdapter::sendSubject()

Argument	Type	Description
`subject`	String	The subject to use for the message.
`function`	String	The class to use for the message.
`message`	Hash	The message data, must match the class description or an exception will be thrown.

Table 15. Return Values for TibcoAdapter::sendSubject()

Return Type	Description
n/a	This method does not return any value.

Table 16. Exceptions Thrown by TibcoAdapter::sendSubject()

err	desc
`TIBCO-SENDSUBJECT-PARAMETER-ERROR`	Invalid parameters passed to the method.
`TIBCO-EXCEPTION`	The TIBCO SDK raised an exception instantiating the adapter.

TibcoAdapter::sendSubjectWithSyncReply()

Synopsis

Creates a publisher, transmits data with the given subject, and returns a data structure representing the synchronous reply.

Usage

TibcoAdapter::sendSubjectWithSyncReply(subject, function, message, [timeout ms])

Table 17. Arguments for TibcoAdapter::sendSubjectWithSyncReply()

Argument	Type	Description
`subject`	String	The subject to use for the message.
`function`	String	The class to use for the message.
`message`	Hash	The message data, must match the class description or an exception will be thrown.
`[timeout ms]`	Integer or Date/Time	The timeout in milliseconds (1/1000 second) or as relative date/time.

Table 18. Return Values for TibcoAdapter::sendSubjectWithSyncReply()

Return Type	Description
Hash	The reply message received. If a timeout value was set and no message was sent within the timeout period, no value is returned.

TibcoAdapter::callOperationWithSyncReply()

Synopsis

Calls an Tibco Operation, waits for the reply and converts the reply into returned data structure.

Usage

TibcoAdapter::callOperationWithSyncReply(class name, method name, call parameters, [timeout ms], [client name])

Table 19. Arguments for TibcoAdapter::callOperationWithSyncReply()

Argument	Type	Description
`class name`	String	Class name of the Operation, as defined in Tibco repository.
`method name`	String	Method name of the Operation, as defined in Tibco repository.
`call parameters`	Hash	Parameters passed to the Operation, must match the class description or an exception will be thrown.
`[timeout ms]`	Integer or Date/Time	Optional timeout. Default value is 60 seconds.
`[client name]`	String	Optional identification of the caller, as defined in Tibco repository. Default is empty string.

Table 20. Return Values for TibcoAdapter::callOperationWithSyncReply()

Return Type	Description
Hash	The reply from the Operation. If timeout expires an exception is thrown.

Table 21. Exceptions Thrown by TibcoAdapter::callOperationWithSyncReply()

err	desc
`TIBCO-EXCEPTION`	The TIBCO SDK raised an exception.
`TIBCO-REMOTE-EXCEPTION`	The TIBCO raised an exception on server side.
`TIBCO-CLASS-DESCRIPTION-NOT-FOUND`	Description of a class not found in adapter parameters.
`TIBCO-CLASS-NOT-FOUND`	Class not found in repository.
`TIBCO-MISSING-CLASS-NAME`	Missing entry for an instantiated type.
`TIBCO-MISSING-VALUE`	Missing value for an instantiated type.
`TIBCO-DATE-INSTANTIATION-ERROR`	Date type cannot be instantiated.
`TIBCO-UNSUPPORTED-TYPE`	A type currently not supported by the module.
`TIBCO-INVALID-TYPE-FOR-CLASS`	Hash data was expected.
`TIBCO-HASH-KEY-INVALID`	Invalid attribute of a class.

TibcoAdapter::callOperationOneWay()

Synopsis

Calls an oneway Tibco Operation, no reply is expected.

Usage

TibcoAdapter::callOperationOneWay(class name, method name, call parameters, [client name])

Table 22. Arguments for TibcoAdapter::callOperationOneWay()

Argument	Type	Description
`class name`	String	Class name of the oneway Operation, as defined in Tibco repository.
`method name`	String	Method name of the oneway Operation, as defined in Tibco repository.
`call parameters`	Hash	Parameters passed to the oneway Operation, must match the class description or an exception will be thrown.
`[client name]`	String	Optional identification of the caller, as defined in Tibco repository. Default is empty string.

Table 23. Exceptions Thrown by TibcoAdapter::callOperationOneWay()

err	desc
`TIBCO-EXCEPTION`	The TIBCO SDK raised an exception.
`TIBCO-REMOTE-EXCEPTION`	The TIBCO raised an exception on server side.
`TIBCO-CLASS-DESCRIPTION-NOT-FOUND`	Description of a class not found in adapter parameters.
`TIBCO-CLASS-NOT-FOUND`	Class not found in repository.
`TIBCO-MISSING-CLASS-NAME`	Missing entry for an instantiated type.
`TIBCO-MISSING-VALUE`	Missing value for an instantiated type.
`TIBCO-DATE-INSTANTIATION-ERROR`	Date type cannot be instantiated.
`TIBCO-UNSUPPORTED-TYPE`	A type currently not supported by the module.
`TIBCO-INVALID-TYPE-FOR-CLASS`	Hash data was expected.
`TIBCO-HASH-KEY-INVALID`	Invalid attribute of a class.