Tuxedo Module 0.1

Module Reference

Pavel Vozenilek

V. 0.1

Revision History
Revision 0.15 Sep 2008dn
separated from qore documentation

1. tuxedo Module

The "tuxedo" module provides a Qore-language client API to BEA Tuxedo services.

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 tuxedo

1.1. TuxedoAdapter Class

The TuxedoAdapter class is used to communicate with Tuxedo servers. Detailed description of Tuxedo interface can be found on Tuxedo 9.1 reference and related pages. TuxedoAdapter class provides multithread safe wrapper over messaging part of Tuxedo API. Constants from Tuxedo API (like TPAPPAUTH) are all exposed in Tuxedo namespace.

Table 1. TuxedoAdapter Class Method Overview

Method

Except?

Description

TuxedoAdapter::constructor()

Y

Creates the Tuxedo adapter based on parameters passed as a hash.

TuxedoAdapter::destructor()

N

Destroys the TuxedoAdapter object.

TuxedoAdapter::copy()

Y

Copying objects of this class is not supported, an exception will be thrown.

TuxedoAdapter::call()

Y

Calls a Tuxedo service, returns the reply.

TuxedoAdapter::asyncCall()

Y

Calls an Tuxedo service and returns immediatelly The reply can be retrieved later.

TuxedoAdapter::waitForAsyncReply()

Y

Waits for a reply for an asynchronous call.

TuxedoAdapter::cancelAsyncCall()

Y

Cancels reply from an asynchonous call.

TuxedoAdapter::enqueue()

Y

Puts data into a Tuxedo queue.

TuxedoAdapter::dequeue()

Y

Retrieves data from a Tuxedo queue.

TuxedoAdapter::joinConversation()

Y

Opens new communication with a Tuxedo service in conversational mode.

TuxedoAdapter::breakConversation()

Y

Forcibly closes a communication in conversational mode.

TuxedoAdapter::sendConversationData()

Y

Sends data to a Tuxedo service in conversational mode.

TuxedoAdapter::receiveConversationData()

Y

Retrieves data from a Tuxedo service in conversational mode.

TuxedoAdapter::openResourceManager()

Y

Connects with the Tuxedo (not TX) resource manager.

TuxedoAdapter::closeResourceManager()

Y

Disconnects from the Tuxedo (not TX) resource manager.

TuxedoAdapter::openTxResourceManager()

Y

Connects with the X/Open (TX) compatible resource manager.

TuxedoAdapter::closeTxResourceManager()

Y

Disconnects from the X/Open (TX) compatible resource manager.

TuxedoAdapter::beginTransaction()

Y

Starts a Tuxedo transaction.

TuxedoAdapter::commitTransaction()

Y

Commits a Tuxedo transaction.

TuxedoAdapter::abortTransaction()

Y

Rolls back a Tuxedo transaction.

TuxedoAdapter::suspendTransaction()

Y

Temporarily suspends a Tuxedo transaction.

TuxedoAdapter::resumeTransaction()

Y

Resumes suspended Tuxedo transaction.

TuxedoAdapter::isTransactionRunning()

N

Returns information whether a Tuxedo transaction is currently active.

TuxedoAdapter::finishCommitAfterDataLogged()

Y

Sets a commit protocol used by the Tuxedo transaction.

TuxedoAdapter::finishCommitAfterTwoPhaseCompletes()

Y

Sets a commit protocol used by the Tuxedo transaction.

TuxedoAdapter::beginTxTransaction()

Y

Starts a X/Open compatible transaction.

TuxedoAdapter::commitTxTransaction()

Y

Commits a X/Open compatible transaction.

TuxedoAdapter::abortTxTransaction()

Y

Rolls back a X/Open compatible transaction.

TuxedoAdapter::finishTxCommitAfterDataLogged()

Y

Sets a commit protocol used by the X/Open compatible transaction.

TuxedoAdapter::finishTxCommitAfterTwoPhaseCompletes()

Y

Sets a commit protocol used by the X/Open compatible transaction.

TuxedoAdapter::setChainedTxTransactions()

Y

Finishing one X/Open compatible transaction will automatically start the next one.

TuxedoAdapter::setUnchainedTxTransactions()

Y

Each X/Open compatible transaction needs to be started explicitly.

TuxedoAdapter::setTxTransactionTimeout()

Y

Sets timeout for X/Open compatible transaction commit.

TuxedoAdapter::setStringEncoding()

Y

Sets the string encoding for the object; any strings serialized and deserialized with this object will be tagged with this character encoding.

TuxedoAdapter::error2string()

N

Converts numeric Tuxedo error code into a descriptive text.

TuxedoAdapter::writeToLog()

N

Writes a message into Tuxedo log file.

TuxedoAdapter::lastErrorDetails()

N

Returns details (an error code) for the last failed Tuxedo call.

TuxedoAdapter::getPriority()

Y

Returns numeric priority used by Tuxedo.

TuxedoAdapter::setPriority()

Y

Sets numeric priority used by Tuxedo.

TuxedoAdapter::postEvent()

Y

Generates a Tuxedo event.


1.1.1. TuxedoAdapter::constructor()

Synopsis

Creates the TuxedoAdapter instance based on the passed settings.

Usage
TuxedoAdapter::constructor(settings)

Table 2. Arguments for TuxedoAdapter::constructor()

Argument

Type

Description

Tuxedo connection settings

Hash

The passed settings (Hash) could and should to set up all relevant parameters to connect a Tuxedo server. The environment variables, used by Tuxedo C API don't need to be set explicitly. They will be examined if and only if their equivalent is not present among the settings. See tpinit() documentation for details. All recognized settings are listed in the table TuxedoAdapter::constructor settings bellow. The settings names are case insensitive. Unrecognized settings result in the exception TUXEDO-ADAPTER-CONSTRUCTOR. At least TUXDIR and TUXCONFIG settings need to be specified explicitly (either through the hash or with environment variables). For settings not set explicitly defaults are used.


Table 3. Return Values for TuxedoAdapter::constructor()

Return Type

Description

Object

The newly create TuxedoAdapter object


Table 4. Exceptions thrown by TuxedoAdapter::constructor()

err

desc

TUXEDO-ADAPTER-CONSTRUCTOR

Invalid or unrecognized value of settings

TUXEDO-ERROR

A Tuxedo call failed. Hash exception parameter has member 'error' with Tuxedo error code.


Table 5. Settings for TuxedoAdapter::constructor()

Value

Type

Description

Default

TUXDIR

String

Full path to the directory where Tuxedo is installed. Environment variable TUXDIR is used if this value is not present among the settings

required explicitly

TUXCONFIG

String

Full path to the configuration file used by this TuxedoAdapter instance. Environment variable TUXCONFIG is used if this value is not present among the settings

required explicitly

UserName

String

User name to connect the Tuxedo server. See tpinit() documentation for details.

empty string

Password

String

Password required to connect the Tuxedo server. See tpinit() documentation for details.

empty string

ClientName

String

Client name to connect the Tuxedo server. See tpinit() documentation for details.

empty string

GroupName

String

Group name to connect the Tuxedo server. See tpinit() documentation for details.

empty string

BinaryConnectionData

Binary

Binary data that are passed to the Tuxedo server during connection. See tpinit() documentation for details.

no data passed

ConnectionFlags

Integer

Flags passed to the tpinit(). The flag TPMULTICONTEXT (the application may have several connection at the same time) is set automatically

TPMULTICONTEXT (always set)

StringEncoding

String

Encoding used for all sent and retrieved strings.

'UTF8'

DefaultFlagsForCall

Integer

Flags used as a default when the TuxedoAdapter::call() does not specify them explicitly. If this settings is not present the TuxedoAdapter::call() requires the 'flags' parameter. See tpcall() documentation for details.

n/a

DefaultFlagsForAsyncCall

Integer

Flags used as a default when the TuxedoAdapter::asyncCall() does not specify them explicitly. If this settings is not present the TuxedoAdapter::asyncCall() requires the 'flags' parameter. See tpacall() documentation for details.

n/a

DefaultFlagsForWaitForAsyncReply

Integer

Flags used as a default when the TuxedoAdapter::waitForAsyncReply() does not specify them explicitly. If this settings is not present the TuxedoAdapter::waitForAsyncReply() requires the 'flags' parameter. See tpgetrply() documentation for details.

n/a

DefaultFlagsForPostEvent

Integer

Flags used as a default when the TuxedoAdapter::postEvent() does not specify them explicitly. If this settings is not present the TuxedoAdapter::postEvent() requires the 'flags' parameter. See tppost() documentation for details.

n/a

DefaultFlagsForJoinConversation

Integer

Flags used as a default when the TuxedoAdapter::joinConversation() does not specify them explicitly. If this settings is not present the TuxedoAdapter::joinConversation() requires the 'flags' parameter. See tpconnect() documentation for details.

n/a

DefaultFlagsForSendConversationData

Integer

Flags used as a default when the TuxedoAdapter::sendConversationData() does not specify them explicitly. If this settings is not present the TuxedoAdapter::sendConversationData() requires the 'flags' parameter. See tpsend() documentation for details.

n/a

DefaultFlagsForReceiveConversationData

Integer

Flags used as a default when the TuxedoAdapter::receiveConversationData() does not specify them explicitly. If this settings is not present the TuxedoAdapter::receiveConversationData() requires the 'flags' parameter. See tprecv() documentation for details.

n/a

DefaultFlagsForEnqueue

Integer

Flags used as a default when the TuxedoAdapter::enqueue() does not specify them explicitly. If this settings is not present the TuxedoAdapter::enqueue() requires the 'flags' parameter. See tpenqueue() documentation for details.

n/a

DefaultFlagsForDequeue

Integer

Flags used as a default when the TuxedoAdapter::dequeue() does not specify them explicitly. If this settings is not present the TuxedoAdapter::dequeue() requires the 'flags' parameter. See tpdequeue() documentation for details.

n/a

DefaultFmlType

String (either 'FML' or 'FML32')

Selects into which FML type Hash data will be serialized if no direct hint is given. If this settings is not present then any function serializing Hash data requires explicit hint about the result FML type.

'FML32'

DefaultFmlDescriptionFile

String

If used it should be full file path to a text file formatted according to FML description file specification. This file should describe all FML data used by this instance of TuxedoAdapter. The file is read only during construction of the adapter. This settings is mutually exclusive with DefaultFmlDescription (description provided in a Hash).

n/a

DefaultFmlDescription

Hash

Description of all FML data used by this instance of TuxedoAdapter. The key is FML item name, the value is integer (e.g. FLD_STRING) specifying the type. This settings is mutually exclusive with DefaultFmlDescriptionFile (decsription provided in a file). See FML description file specification for details.

n/a

DefaultFmlDescriptionBase

Integer

Base offset of the FML items specified by the DefaultFmlDescription. Used only when DefaultFmlDescription is also specified. For details see FML description file specification.

0

DefaultFml32DescriptionFile

String

If used it should be full file path to a text file formatted according to FML32 description file specification. This file should describe all FML32 data used by this instance of TuxedoAdapter. The file is read only during construction of the adapter. This settings is mutually exclusive with DefaultFml32Description (description provided in a Hash).

n/a

DefaultFml32Description

Hash

Description of all FML32 data used by this instance of TuxedoAdapter. The key is FML32 item name, the value is integer (e.g. FLD_STRING) specifying the type. This settings is mutually exclusive with DefaultFml32DescriptionFile (decsription provided in a file). See FML32 description file specification for details.

n/a

DefaultFml32DescriptionBase

Integer

Base offset of the FML32 items specified by the DefaultFmlDescription. Used only when DefaultFml32Description is also specified. For details see FML32 description file specification.

0

Priority

Integer (1..100)

Default Priority used for communication with Tuxedo servers. TuxedoAdapter::setPriority() can be used later to change the priority again. See tpspprio() documentation for details.

set in configuration file

WhenCommitFinishes

String 'AfterDataAreLogged' or 'AfterTwoPhaseCompletes'

Specifies which mechanism is used when Tuxedo transaction (NOT TX transaction) commits. The settings could be changed later by TuxedoAdapter::finishCommitAfterDataLogged() or TuxedoAdapter::finishCommitAfterTwoPhaseCompletes(). See tpscmt() documentation for details.

set in configuration file

WhenTxCommitFinishes

String 'AfterDataAreLogged' or 'AfterTwoPhaseCompletes'

Specifies which mechanism is used when X/Open (TX) transaction commits. The settings could be changed later by TuxedoAdapter::finishTxCommitAfterDataLogged() or TuxedoAdapter::finishTxCommitAfterTwoPhaseCompletes(). See tx_set_commit_return() documentation for details.

'AfterTwoPhaseCompletes'

AreTxTransactionsChained

Boolean

Specifies whether a new X/Open (TX) transaction starts automatically after commit or rollback (when value is True) or whether it needs to be started explicitly by TuxedoAdapter::beginTxTransaction() (when value is False). See tx_set_transaction_control() documentation for details.

False

WSENVFILE

String

Equivalent of WSENVFILE environment variable described in tpinit() documentation.

empty string

WSNADDR

String

Equivalent of WSNADDR environment variable described in tpinit() documentation.

empty string

WSFADDR

String

Equivalent of WSFADDR environment variable described in tpinit() documentation.

empty string

WSFRANGE

String

Equivalent of WSFRANGE environment variable described in tpinit() documentation.

empty string

WSDEVICE

String

Equivalent of WSDEVICE environment variable described in tpinit() documentation.

empty string

WSTYPE

String

Equivalent of WSTYPE environment variable described in tpinit() documentation.

empty string

WSRPLYMAX

String

Equivalent of WSRPLYMAX environment variable described in tpinit() documentation.

empty string

TMMINENCRYPTBITS

String

Equivalent of TMMINENCRYPTBITS environment variable described in tpinit() documentation.

empty string

TMMAXENCRYPTBITS

String

Equivalent of TMMAXENCRYPTBITS environment variable described in tpinit() documentation.

empty string


1.1.2. TuxedoAdapter::destructor()

Synopsis

Destroys the TuxedoAdapter object. All pending asynchronous calls are cancelled, all opened conversations are forcibly stopped, the connection to Tuxedo is terminated.

Usage
TuxedoAdapter::destructor()

Table 6. Arguments for TuxedoAdapter::destructor()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 7. Return Values for TuxedoAdapter::destructor()

Return Type

Description

n/a

This method returns no value


1.1.3. TuxedoAdapter::copy()

Synopsis

Copying objects of this class is not supported, an exception will be thrown.

Usage
TuxedoAdapter::copy()

Table 8. Arguments for TuxedoAdapter::copy()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 9. Return Values for TuxedoAdapter::copy()

Return Type

Description

n/a

This method returns no value


Table 10. Exceptions thrown by TuxedoAdapter::copy()

err

desc

TUXEDO-ADAPTER-COPY-ERROR

objects of this class may not be copied


1.1.4. TuxedoAdapter::call()

Synopsis

Invokes a Tuxedo service, waits for the reply and converts it into returned data structure. See tpcall() documentation for details.

Usage
TuxedoAdapter:call(service name, data [, flags])

Table 11. Arguments for TuxedoAdapter::call()

Argument

Type

Description

service name

String

As defined in configuration file (TUXCONFIG).

data

NOTHING,String, Binary or Hash

Data serialized into the Tuxedo format and passed to the service. Hash is converted either into FML or FML32, based on the hint in 'flags' or on the settings 'DefaultFmlType' passed into the constructor.

[flags]

Integer or Hash

If the value is Integer then it is equivalent with flags used by the tpcall(). Hash value may contrain following items: bool value 'use_fml32' (whether to process Hash data as FML or FML32), integer value 'flags' (the same as for tpcall()) and string value 'DefaultReturnedDataType' (allowed values 'CARRAY', 'STRING', 'FML' or 'FML32') giving a hint of output data type. If the TuxedoAdapter constructor did not specified 'DefaultFlagsForCall' settings then the 'flags' needs to be present (either as the Integer or part of the Hash).


Table 12. Return Values for TuxedoAdapter::call()

Return Type

Description

String, Binary or Hash

Received reply converted into a Qore datatype. FML and FML32 are encoded into the Hash.


Table 13. Exceptions thrown by TuxedoAdapter::call()

err

desc

TUXEDO-ADAPTER-CALL

Invalid parameter.

TUXEDO-ERROR

A Tuxedo call failed. Hash parameter has a member 'error' with Tuxedo error code.


1.1.5. TuxedoAdapter::asyncCall()

Synopsis

Invokes a Tuxedo service asynchronously, without waiting for the reply. See tpacall() documentation for details. To retrieve the reply use TuxedoAdapter::waitForAsyncReply() or cancel the pending reply with TuxedoAdapter::cancelAsyncCall(). The same service may be called either synchronously with TuxedoAdapter::call() or asynchronously.

Usage
TuxedoAdapter:asyncCall(service name, data [, flags])

Table 14. Arguments for TuxedoAdapter::asyncCall()

Argument

Type

Description

service name

String

As defined in configuration file (TUXCONFIG).

data

NOTHING, String, Binary or Hash

Data serialized into the Tuxedo format and passed to the service. Hash is converted either into FML or FML32, based on the hint in 'flags' or on the settings 'DefaultFmlType' passed into the constructor.

[flags]

Integer or Hash

If the value is Integer then it is equivalent with flags used by the tpacall(). Hash value may contrain following items: bool value 'use_fml32' (whether to process Hash data as FML or FML32), integer value 'flags' (the same as for tpacall()) and If the TuxedoAdapter constructor did not specified 'DefaultFlagsForAsyncCall' settings then the 'flags' needs to be present (either as the Integer or part of the Hash).


Table 15. Return Values for TuxedoAdapter::asyncCall()

Return Type

Description

Integer

Handle used to later retrieve the pending reply with TuxedoAdapter::waitForAsyncReply(). To cancel the call TuxedoAdapter::cancelAsyncCall(). All pending asynchronous calls are automatically cancelled when the TuxedoAdapter instance is destroyed.


Table 16. Exceptions thrown by TuxedoAdapter::asyncCall()

err

desc

TUXEDO-ADAPTER-ASYNC-CALL

Invalid parameter.

TUXEDO-ERROR

A Tuxedo call failed. Hash exception parameter has member 'error' with Tuxedo error code.


1.1.6. TuxedoAdapter::waitForAsyncReply()

Synopsis

Waits for reply started by TuxedoAdapter::asyncCall() and not cancelled by TuxedoAdapter::cancelAsyncCall(). See tpgetrply() documentation for details.

Table 17. Arguments for TuxedoAdapter::waitForAsyncReply()

Argument

Type

Description

handle

Integer

The value returned by TuxedoAdapter::asyncCall() and not yet cancelled or used in another waitForAsyncReply().

[flags]

Integer or Hash

Integer with values as described in tpacall() documentation. The Hash may contain: string value 'DefaultReturnedDataType' (valid values are 'CARRAY', 'STRING', 'FML', 'FML32') which provides hint about output data type (Tuxedo may ignore this hint) and integer 'flags' (the same as for tpgetrply()). If the TuxedoAdapter constructor did not specified 'DefaultFlagsForwaitForAsyncReply' settings then the 'flags' needs to be present (either as the integer or part of the hash).


Table 18. Return Values for TuxedoAdapter::waitForAsyncReply()

Return Type

Description

String, Binary or Hash

Received reply converted into a Qore type.


Table 19. Exceptions thrown by TuxedoAdapter::waitForAsyncReply()

err

desc

TUXEDO-ADAPTER-WAIT-FOR-ASYNC-REPLY

Missing or invalid parameter.

TUXEDO-ERROR

A Tuxedo call failed. Hash exception parameter has member 'error' with Tuxedo error code.


1.1.7. TuxedoAdapter::cancelAsyncCall()

Synopsis

Cancels asynchronous call to a Tuxedo service started by the TuxedoAdapter::asyncCall() See tpcancel() documentation for details. When TuxedoAdapter object is destroyed all pending asynchronous calls are cancelled automatically.

Usage
TuxedoAdapter::cancelAsyncCall(handle)

Table 20. Arguments for TuxedoAdapter::cancelAsyncCall()

Argument

Type

Description

handle

Integer

The value returned by TuxedoAdapter::asyncCall(), neither cancelled nor used by a TuxedoAdapter::waitForAsyncReply().


Table 21. Return Values for TuxedoAdapter::cancelAsyncCall()

Return Type

Description

n/a

This method does not return any value.


Table 22. Exceptions thrown by TuxedoAdapter::cancelAsyncCall()

err

desc

TUXEDO-ADAPTER-CANCEL-ASYNC-CALL

Missing or invalid parameter.

TUXEDO-ERROR

A Tuxedo call failed. Hash exception parameter has member 'error' with Tuxedo error code.


1.1.8. TuxedoAdapter::enqueue()

Synopsis

Puts data into a Tuxedo queue. For details see tpenqueue() documentation.

Usage
TuxedoAdapter::enqueue(queue space, queue name, data [, flags])

Table 23. Arguments for TuxedoAdapter::enqueue()

Argument

Type

Description

queue space

String

Queue identifier #1.

queue name

String

Queue identifier #2.

data

NOTHING, String, Binary or Hash

Data serialized into the Tuxedo format and put to the queue. Hash is converted either into FML or FML32, based on the hint in 'flags' or on the settings 'DefaultFmlType' passed into the constructor.

[flags]

Integer or Hash

Integer with values as described in tpenqueue() documentation. The Hash may contain: bool value 'use_fml32' (hint whether Hash data are converted into FML or FML32), integer value 'flags' (the same as for tpenqueue()), integer queue control parameters 'queue_control_flags, 'queue_control_deq_time', 'queue_control_priority', 'queue_control_exp_time', 'queue_control_delivery_qos', queue_control_reply_qos', 'queue_control_urcode' and binary queue parameters queue_control_msgid', 'queue_control_corrid'. See tpenqueue() documentation for details on queue control parameters. If the TuxedoAdapter constructor did not specified 'DefaultFlagsForEnqueue' settings then the 'flags' needs to be present (either as the integer or part of the hash).


Table 24. Return Values for TuxedoAdapter::enqueue()

Return Type

Description

Hash

Result of the operation is returned: binary value 'queue_control_msgid' contains generated ID for the data put into the queue, integer value 'queue_control_diagnostic' contains diagnostic of the tpenqueue() call. See tpenqueue() documentation for details.


Table 25. Exceptions thrown by TuxedoAdapter::enqueue()

err

desc

TUXEDO-ADAPTER-ENQUEUE

Missing or invalid parameter.

TUXEDO-ERROR

A Tuxedo call failed. Hash exception parameter has member 'error' with Tuxedo error code.


1.1.9. TuxedoAdapter::dequeue()

Synopsis

Retrieves data from a Tuxedo queue. For details see tpdequeue() documentation.

Usage
TuxedoAdapter::dequeue(queue space, queue name, [, flags])

Table 26. Arguments for TuxedoAdapter::dequeue()

Argument

Type

Description

queue space

String

Queue identifier #1.

queue name

String

Queue identifier #2.

[flags]

Integer or Hash

Integer with values as described in tpdequeue() documentation. The Hash may contain: integer value 'flags' (the same as for tpdequeue()), integer queue control parameter 'queue_control_flags' and binary queue control parameters 'queue_control_msgid' and 'queue_control_corrid'. If the TuxedoAdapter constructor did not specified 'DefaultFlagsForDequeue' settings then the 'flags' needs to be present (either as the integer or part of the hash).


Table 27. Return Values for TuxedoAdapter::dequeue()

Return Type

Description

Hash

Result of the call: data fetched from the queue (the value named 'data') and integer queue control parameters 'queue_control_flags' and 'queue_control_priority'. See tpdequeue() documentation for details.


Table 28. Exceptions thrown by TuxedoAdapter::dequeue()

err

desc

TUXEDO-ADAPTER-DEQUEUE

Missing or invalid parameter.

TUXEDO-ERROR

A Tuxedo call failed. Hash exception parameter has member 'error' with Tuxedo error code.


1.1.10. TuxedoAdapter::joinConversation()

Synopsis

Connects a Tuxedo service in conversational mode, if provided a data is sent. See tpconnect() documentation for details.

Usage
TuxedoAdapter::joinConversation(service name, data [, flags])

Table 29. Arguments for TuxedoAdapter::joinConversation()

Argument

Type

Description

service name

String

As defined in configuration file (TUXCONFIG).

data

NOTHING,String, Binary or Hash

Data serialized into the Tuxedo format and passed to the service. Hash is converted either into FML or FML32, based on the hint in 'flags' or on the settings 'DefaultFmlType' passed into the constructor.

[flags]

Integer or Hash

If the value is Integer then it is equivalent with flags used by the tpconnect(). Hash value may contrain following items: bool value 'use_fml32' (whether to process Hash data as FML or FML32) and integer value 'flags' (the same as for tpconnect()). If the TuxedoAdapter constructor did not specified 'DefaultFlagsForJoinConversation' settings then the 'flags' needs to be present (either as the Integer or part of the Hash).


Table 30. Return Values for TuxedoAdapter::call()

Return Type

Description

Integer

Descriptor of the established conversation. The descriptor is used by TuxedoAdapter::sendConversationData(), TuxedoAdapter::receiveConversationData() and TuxedoAdapter::breakConversation(). When the TuxedoAdapter instance gets destroyed all remaining opened conversations are broken automatically.


Table 31. Exceptions thrown by TuxedoAdapter::joinConversation()

err

desc

TUXEDO-ADAPTER-JOIN-CONVERSATION

Invalid parameter.

TUXEDO-ERROR

A Tuxedo call failed. Hash parameter has a member 'error' with Tuxedo error code.


1.1.11. TuxedoAdapter::breakConversation()

Synopsis

Forcibly breaks an established conversational mode. See tpdiscon() documentation for details. This is NOT the recomended way to close such a connection.

Usage
TuxedoAdapter::breakConversation(service descriptor)

Table 32. Arguments for TuxedoAdapter::joinConversation()

Argument

Type

Description

conversation descriptor

Integer

A valid conversation descriptor returned by TuxedoAdapter::joinConversation().


Table 33. Return Values for TuxedoAdapter::breakConversation()

Return Type

Description

n/a

This method doesn't return any value.


Table 34. Exceptions thrown by TuxedoAdapter::joinConversation()

err

desc

TUXEDO-ADAPTER-BREAK-CONVERSATION

Invalid parameter.

TUXEDO-ERROR

A Tuxedo call failed. Hash parameter has a member 'error' with Tuxedo error code.


1.1.12. TuxedoAdapter::sendConversationData()

Synopsis

Sends data in conversational mode. See tpsend() documentation for details.

Usage
TuxedoAdapter:sendConversationData(conversation descriptor, data [, flags])

Table 35. Arguments for TuxedoAdapter::sendConversationData()

Argument

Type

Description

conversation descriptor

Integer

A valid descriptor returned by TuxedoAdapter::joinConversation().

data

NOTHING,String, Binary or Hash

Data serialized into the Tuxedo format and passed to the service. Hash is converted either into FML or FML32, based on the hint in 'flags' or on the settings 'DefaultFmlType' passed into the constructor.

[flags]

Integer or Hash

If the value is Integer then it is equivalent with flags used by the tpsend(). Hash value may contrain following items: bool value 'use_fml32' (whether to process Hash data as FML or FML32) and integer value 'flags' (the same as for tpsend()). If the TuxedoAdapter constructor did not specified 'DefaultFlagsForSendConversationData' settings then the 'flags' needs to be present (either as the Integer or part of the Hash).


Table 36. Return Values for TuxedoAdapter::sendConversationData()

Return Type

Description

Integer

Event, indicating state of the conversation. See tpsend() documentation for allowed values and their interpretation.


Table 37. Exceptions thrown by TuxedoAdapter::sendConversationData()

err

desc

TUXEDO-ADAPTER-SEND-CONVERSATION-DATA

Invalid parameter.

TUXEDO-ERROR

A Tuxedo call failed. Hash parameter has a member 'error' with Tuxedo error code.


1.1.13. TuxedoAdapter::receiveConversationData()

Synopsis

Receive data in conversational mode. See tprecv() documentation for details.

Usage
TuxedoAdapter:receiveConversationData(conversation descriptor [, flags])

Table 38. Arguments for TuxedoAdapter::receiveConversationData()

Argument

Type

Description

conversation descriptor

Integer

A valid descriptor returned by TuxedoAdapter::joinConversation().

[flags]

Integer or Hash

If the value is Integer then it is equivalent with flags used by the tprecv(). Hash value may contrain following items: integer value 'flags' (the same as for tprecv()) and string value 'DefaultReturnedDataType' (allowed values 'CARRAY', 'STRING', 'FML' or 'FML32') giving a hint of output data type. If the TuxedoAdapter constructor did not specified 'DefaultFlagsForReceiveConversationData' settings then the 'flags' needs to be present (either as the Integer or part of the Hash).


Table 39. Return Values for TuxedoAdapter::receiveConversationData()

Return Type

Description

Hash

The retrned Hash contains item 'data' with received reply converted into a Qore datatype (FML and FML32 are encoded into a Hash) and item 'event' indicating state of the conversation. See tprecv() documentation for details about the events.


Table 40. Exceptions thrown by TuxedoAdapter::receiveConversationData()

err

desc

TUXEDO-ADAPTER-RECEIVE-CONVERSATION-DATA

Invalid parameter.

TUXEDO-ERROR

A Tuxedo call failed. Hash parameter has a member 'error' with Tuxedo error code.


1.1.14. TuxedoAdapter::openResourceManager()

Synopsis

Wrapper for Tuxedo call tpopen(). Use TuxedoAdapter::closeResourceManager() to close the manager.

Usage
TuxedoAdapter::openResourceManager()

Table 41. Arguments for TuxedoAdapter::openResourceManager()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 42. Return Values for TuxedoAdapter::openResourceManager()

Return Type

Description

n/a

This method returns no value


Table 43. Exceptions thrown by TuxedoAdapter::openResourceManager()

err

desc

TUXEDO-ERROR

A Tuxedo call failed. Hash parameter has a member 'error' with Tuxedo error code.


1.1.15. TuxedoAdapter::openResourceManager()

Synopsis

Wrapper for Tuxedo call tpclose(). The manager is opened by calling TuxedoAdapter::openResourceManager().

Usage
TuxedoAdapter::closeResourceManager()

Table 44. Arguments for TuxedoAdapter::closeResourceManager()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 45. Return Values for TuxedoAdapter::closeResourceManager()

Return Type

Description

n/a

This method returns no value


Table 46. Exceptions thrown by TuxedoAdapter::closeResourceManager()

err

desc

TUXEDO-ERROR

A Tuxedo call failed. Hash parameter has a member 'error' with Tuxedo error code.


1.1.16. TuxedoAdapter::openTxResourceManager()

Synopsis

Wrapper for Tuxedo call tx_open(). Use TuxedoAdapter::closeTxResourceManager() to close the manager.

Usage
TuxedoAdapter::openTxResourceManager()

Table 47. Arguments for TuxedoAdapter::openTxResourceManager()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 48. Return Values for TuxedoAdapter::openTxResourceManager()

Return Type

Description

n/a

This method returns no value


Table 49. Exceptions thrown by TuxedoAdapter::openTxResourceManager()

err

desc

TUXEDO-ERROR

A Tuxedo call failed. Hash parameter has a member 'error' with Tuxedo error code.


1.1.17. TuxedoAdapter::closeTxResourceManager()

Synopsis

Wrapper for Tuxedo call tx_close(). Use TuxedoAdapter::openTxResourceManager() to open the manager.

Usage
TuxedoAdapter::closeTxResourceManager()

Table 50. Arguments for TuxedoAdapter::closeTxResourceManager()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 51. Return Values for TuxedoAdapter::closeTxResourceManager()

Return Type

Description

n/a

This method returns no value


Table 52. Exceptions thrown by TuxedoAdapter::closeTxResourceManager()

err

desc

TUXEDO-ERROR

A Tuxedo call failed. Hash parameter has a member 'error' with Tuxedo error code.


1.1.18. TuxedoAdapter::beginTransaction()

Synopsis

Wrapper for Tuxedo call tpbegin().

Usage
TuxedoAdapter::beginTransaction([timeout sec])

Table 53. Arguments for TuxedoAdapter::beginTransaction()

Argument

Type

Description

[timeout sec]

Integer or Date/Time

Timeout in seconds. Default is zero which means no timeout (waiting forever).


Table 54. Return Values for TuxedoAdapter::beginTransaction()

Return Type

Description

n/a

This method returns no value


Table 55. Exceptions thrown by TuxedoAdapter::beginTransaction()

err

desc

TUXEDO-ERROR

A Tuxedo call failed. Hash parameter has a member 'error' with Tuxedo error code.


1.1.19. TuxedoAdapter::commitTransaction()

Synopsis

Wrapper for Tuxedo call tpcommit().

Usage
TuxedoAdapter::commitTransaction()

Table 56. Arguments for TuxedoAdapter::commitTransaction()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 57. Return Values for TuxedoAdapter::commitTransaction()

Return Type

Description

n/a

This method returns no value


Table 58. Exceptions thrown by TuxedoAdapter::commitTransaction()

err

desc

TUXEDO-ERROR

A Tuxedo call failed. Hash parameter has a member 'error' with Tuxedo error code.


1.1.20. TuxedoAdapter::abortTransaction()

Synopsis

Wrapper for Tuxedo call tpabort().

Usage
TuxedoAdapter::abortTransaction()

Table 59. Arguments for TuxedoAdapter::abortTransaction()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 60. Return Values for TuxedoAdapter::abortTransaction()

Return Type

Description

n/a

This method returns no value


Table 61. Exceptions thrown by TuxedoAdapter::abortTransaction()

err

desc

TUXEDO-ERROR

A Tuxedo call failed. Hash parameter has a member 'error' with Tuxedo error code.


1.1.21. TuxedoAdapter::isTransactionRunning()

Synopsis

Wrapper for Tuxedo call tpgetlev().

Usage
TuxedoAdapter::beginTransactionRunning()

Table 62. Arguments for TuxedoAdapter::isTransactionRunning()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 63. Return Values for TuxedoAdapter::beginTransaction()

Return Type

Description

Boolean

True if a Tuxedo transaction is currently running.


Table 64. Exceptions thrown by TuxedoAdapter::isTransactionRunning()

err

desc

TUXEDO-ERROR

A Tuxedo call failed. Hash parameter has a member 'error' with Tuxedo error code.


1.1.22. TuxedoAdapter::suspendTransaction()

Synopsis

Wrapper for Tuxedo call tpsuspend(). Use TuxedoAdapter::resumeTransaction() to resume it.

Usage
TuxedoAdapter::suspendTransaction()

Table 65. Arguments for TuxedoAdapter::suspendTransaction()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 66. Return Values for TuxedoAdapter::suspendTransaction()

Return Type

Description

Integer

Transaction ID to be passed into TuxedoAdapter::resumeTransaction().


Table 67. Exceptions thrown by TuxedoAdapter::suspendTransaction()

err

desc

TUXEDO-ERROR

A Tuxedo call failed. Hash parameter has a member 'error' with Tuxedo error code.


1.1.23. TuxedoAdapter::resumeTransaction()

Synopsis

Wrapper for Tuxedo call tpresume(). The transaction needs to be suspended prior by calling TuxedoAdapter::suspendTransaction().

Usage
TuxedoAdapter::resumeTransaction(transaction ID)

Table 68. Arguments for TuxedoAdapter::resumeTransaction()

Argument

Type

Description

Transaction ID

Integer

The ID returned by the TuxedoAdapter::suspendTransaction().


Table 69. Exceptions thrown by TuxedoAdapter::resumeTransaction()

err

desc

TUXEDO-ERROR

A Tuxedo call failed. Hash parameter has a member 'error' with Tuxedo error code.


1.1.24. TuxedoAdapter::finishCommitAfterDataLogged()

Synopsis

Wrapper for Tuxedo call tpscmt(TP_CMT_LOGGED). To switch to an alternative mechanism use TuxedoAdapter::finishCommitAfterTwoPhaseCompletes().

Usage
TuxedoAdapter::finishCommitAfterDataLogged()

Table 70. Arguments for TuxedoAdapter::finishCommitAfterDataLogged()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 71. Return Values for TuxedoAdapter::finishCommitAfterDataLogged()

Return Type

Description

n/a

This method returns no value


Table 72. Exceptions thrown by TuxedoAdapter::finishCommitAfterDataLogged()

err

desc

TUXEDO-ERROR

A Tuxedo call failed. Hash parameter has a member 'error' with Tuxedo error code.


1.1.25. TuxedoAdapter::finishCommitAfterTwoPhaseCompletes()

Synopsis

Wrapper for Tuxedo call tpscmt(TP_CMT_COMPLETE). To switch to an alternative mechanism use TuxedoAdapter::finishCommitAfterDataLogged().

Usage
TuxedoAdapter::finishCommitAfterTwoPhaseCompletes()

Table 73. Arguments for TuxedoAdapter::finishCommitAfterTwoPhaseCompletes()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 74. Return Values for TuxedoAdapter::finishCommitAfterTwoPhaseCompletes()

Return Type

Description

n/a

This method returns no value


Table 75. Exceptions thrown by TuxedoAdapter::finishCommitAfterTwoPhaseCompletes()

err

desc

TUXEDO-ERROR

A Tuxedo call failed. Hash parameter has a member 'error' with Tuxedo error code.


1.1.26. TuxedoAdapter::beginTxTransaction()

Synopsis

Wrapper for Tuxedo call tx_begin().

Usage
TuxedoAdapter::beginTxTransaction()

Table 76. Arguments for TuxedoAdapter::beginTxTransaction()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 77. Return Values for TuxedoAdapter::beginTxTransaction()

Return Type

Description

n/a

This method returns no value


Table 78. Exceptions thrown by TuxedoAdapter::beginTxTransaction()

err

desc

TUXEDO-ERROR

A Tuxedo call failed. Hash parameter has a member 'error' with Tuxedo error code.


1.1.27. TuxedoAdapter::commitTxTransaction()

Synopsis

Wrapper for Tuxedo call tx_commit().

Usage
TuxedoAdapter::commitTxTransaction()

Table 79. Arguments for TuxedoAdapter::commitTxTransaction()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 80. Return Values for TuxedoAdapter::commitTxTransaction()

Return Type

Description

n/a

This method returns no value


Table 81. Exceptions thrown by TuxedoAdapter::commitTxTransaction()

err

desc

TUXEDO-ERROR

A Tuxedo call failed. Hash parameter has a member 'error' with Tuxedo error code.


1.1.28. TuxedoAdapter::abortTxTransaction()

Synopsis

Wrapper for Tuxedo call tx_abort().

Usage
TuxedoAdapter::abortTxTransaction()

Table 82. Arguments for TuxedoAdapter::abortTxTransaction()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 83. Return Values for TuxedoAdapter::abortTxTransaction()

Return Type

Description

n/a

This method returns no value


Table 84. Exceptions thrown by TuxedoAdapter::abortTxTransaction()

err

desc

TUXEDO-ERROR

A Tuxedo call failed. Hash parameter has a member 'error' with Tuxedo error code.


1.1.29. TuxedoAdapter::finishTxCommitAfterDataLogged()

Synopsis

Wrapper for Tuxedo call tx_set_commit_return(TX_COMMIT_DECISION_LOGGED). To switch to an alternative mechanism use TuxedoAdapter::finishTxCommitAfterTwoPhaseCompletes().

Usage
TuxedoAdapter::finishTxCommitAfterDataLogged()

Table 85. Arguments for TuxedoAdapter::finishTxCommitAfterDataLogged()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 86. Return Values for TuxedoAdapter::finishTxCommitAfterDataLogged()

Return Type

Description

n/a

This method returns no value


Table 87. Exceptions thrown by TuxedoAdapter::finishTxCommitAfterDataLogged()

err

desc

TUXEDO-ERROR

A Tuxedo call failed. Hash parameter has a member 'error' with Tuxedo error code.


1.1.30. TuxedoAdapter::finishTxCommitAfterTwoPhaseCompletes()

Synopsis

Wrapper for Tuxedo call tx_set_commit_return(TX_COMMIT_COMPLETED). To switch to an alternative mechanism use TuxedoAdapter::finishTxCommitAfterDataLogged().

Usage
TuxedoAdapter::finishTxCommitAfterTwoPhaseCompletes()

Table 88. Arguments for TuxedoAdapter::finishTxCommitAfterTwoPhaseCompletes()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 89. Return Values for TuxedoAdapter::finishTxCommitAfterTwoPhaseCompletes()

Return Type

Description

n/a

This method returns no value


Table 90. Exceptions thrown by TuxedoAdapter::finishTxCommitAfterTwoPhaseCompletes()

err

desc

TUXEDO-ERROR

A Tuxedo call failed. Hash parameter has a member 'error' with Tuxedo error code.


1.1.31. TuxedoAdapter::setChainedTransactions()

Synopsis

Wrapper for Tuxedo call tx_set_transaction_control(TX_CHAINED). Use TuxedoAdapter::setUnchainedTxTransactions() to switch to an alternative mechanism.

Usage
TuxedoAdapter::setChainedTxTransactions()

Table 91. Arguments for TuxedoAdapter::setChainedTxTransactions()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 92. Return Values for TuxedoAdapter::setChainedTxTransactions()

Return Type

Description

n/a

This method returns no value.


Table 93. Exceptions thrown by TuxedoAdapter::setChainedTxTransactions()

err

desc

TUXEDO-ERROR

A Tuxedo call failed. Hash parameter has a member 'error' with Tuxedo error code.


1.1.32. TuxedoAdapter::setUnchainedTransactions()

Synopsis

Wrapper for Tuxedo call tx_set_transaction_control(TX_UNCHAINED). Use TuxedoAdapter::setChainedTxTransactions() to switch to an alternative mechanism.

Usage
TuxedoAdapter::setChainedTxTransactions()

Table 94. Arguments for TuxedoAdapter::setUnchainedTxTransactions()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 95. Return Values for TuxedoAdapter::setUnchainedTxTransactions()

Return Type

Description

n/a

This method returns no value.


Table 96. Exceptions thrown by TuxedoAdapter::setUnchainedTxTransactions()

err

desc

TUXEDO-ERROR

A Tuxedo call failed. Hash parameter has a member 'error' with Tuxedo error code.


1.1.33. TuxedoAdapter::setTxTransactionTimeout()

Synopsis

Wrapper for Tuxedo call tx_set_transaction_timeout().

Usage
TuxedoAdapter::setTxTransactionTimeout(timeout sec)

Table 97. Arguments for TuxedoAdapter::setTxTransactionTimeout()

Argument

Type

Description

timeout

Integer or Date/Time

Timeout in seconds.


Table 98. Return Values for TuxedoAdapter:::setTxTransactionTimeout()

Return Type

Description

n/a

This method returns no value.


Table 99. Exceptions thrown by TuxedoAdapter::setTxTransactionTimeout()

err

desc

TUXEDO-ERROR

A Tuxedo call failed. Hash parameter has a member 'error' with Tuxedo error code.


1.1.34. TuxedoAdapter::setStringEncoding()

Synopsis

Sets the string encoding for the object; any strings deserialized with this object will be tagged with this character encoding.

Usage
TuxedoAdapter::setStringEncoding(encoding)

Table 100. Arguments for TuxedoAdapter::setStringEncoding()

Argument

Type

Description

encoding

String

The string encoding to use for this object.


Table 101. Return Values for TuxedoAdapter::setStringEncoding()

Return Type

Description

n/a

This method returns no value


Table 102. Exceptions thrown by TuxedoAdapter::setStringEncoding()

err

desc

TUXEDO-ADAPTER-SET-STRING-ENCODING

Invalid parameter.


1.1.35. TuxedoAdapter::error2string()

Synopsis

Converts a Tuxedo error code (usually retrieved from 'error' item in exception Hash parameter) into human readable form.

Usage
TuxedoAdapter::error2string(error code)

Table 103. Arguments for TuxedoAdapter::setStringEncoding()

Argument

Type

Description

error code

Integer

Tuxedo error code.


Table 104. Return Values for TuxedoAdapter::error2string()

Return Type

Description

String

Human readable description of the error code.


1.1.36. TuxedoAdapter::writeToLog()

Synopsis

Writes given string into Tuxedo log. The function is a wrapper for Tuxedo call userlog().

Usage
TuxedoAdapter::writeToLog(logged string)

Table 105. Arguments for TuxedoAdapter::writeToLog()

Argument

Type

Description

logged string

String

Text to be written into Tuxedo log.


1.1.37. TuxedoAdapter::lastErrorDetails()

Synopsis

Converst a Tuxedo error code (usually retrieved from 'error' item in exception Hash parameter) into human readable form. The function is a wrapper for Tuxedo call tperrordetail().

Usage
TuxedoAdapter::lastErrorDetails()

Table 106. Arguments for TuxedoAdapter::lastErrorDetails()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 107. Return Values for TuxedoAdapter::lastErrorDetails()

Return Type

Description

Integer

Additional info about the last error generated by Tuxedo. See tperrordetail() documentation for more information.


1.1.38. TuxedoAdapter::getPriority()

Synopsis

Wrapper for Tuxedo call tpgprio().

Usage
TuxedoAdapter::getPriority()

Table 108. Arguments for TuxedoAdapter::getPriority()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 109. Return Values for TuxedoAdapter::getPriority()

Return Type

Description

Integer

Current Tuxedo priority.


Table 110. Exceptions thrown by TuxedoAdapter::getPriority()

err

desc

TUXEDO-ERROR

A Tuxedo call failed. Hash parameter has a member 'error' with Tuxedo error code.


1.1.39. TuxedoAdapter::setPriority()

Synopsis

Wrapper for Tuxedo call tpsprio().

Usage
TuxedoAdapter::setPriority(new priority)

Table 111. Arguments for TuxedoAdapter::setPriority()

Argument

Type

Description

new priority

Integer

New Tuxedo priority (1..100).


Table 112. Return Values for TuxedoAdapter::setPriority()

Return Type

Description

n/a

This method returns no value


Table 113. Exceptions thrown by TuxedoAdapter::setTxTransactionTimeout()

err

desc

TUXEDO-ADAPTER-SET-PRIORITY

Invalid parameter.

TUXEDO-ERROR

A Tuxedo call failed. Hash parameter has a member 'error' with Tuxedo error code.


1.1.40. TuxedoAdapter::postEvent()

Synopsis

Posts a Tuxedo event. See tppost() documentation for details.

Usage
TuxedoAdapter:postEvent(event name, data [, flags])

Table 114. Arguments for TuxedoAdapter::postEvent()

Argument

Type

Description

event name

String

Event name, up to 31 characters.

data

NOTHING,String, Binary or Hash

Data serialized into the Tuxedo format and passed to the service. Hash is converted either into FML or FML32, based on the hint in 'flags' or on the settings 'DefaultFmlType' passed into the constructor.

[flags]

Integer or Hash

If the value is Integer then it is equivalent with flags used by the tppost(). Hash value may contrain following items: bool value 'use_fml32' (whether to process Hash data as FML or FML32) and integer value 'flags' (the same as for tppost()). If the TuxedoAdapter constructor did not specified 'DefaultFlagsForPostEvent' settings then the 'flags' needs to be present (either as the Integer or part of the Hash).


Table 115. Return Values for TuxedoAdapter::postEvent()

Return Type

Description

n/a

This method does not return any value.


Table 116. Exceptions thrown by TuxedoAdapter::cancelAsyncCall()

err

desc

TUXEDO-ADAPTER-CANCEL-POST-EVENT

Missing or invalid parameter.

TUXEDO-ERROR

A Tuxedo call failed. Hash exception parameter has member 'error' with Tuxedo error code.