Overview | Package | Class | Use | Tree | Deprecated | Index | Help
|  | BEA Systems, Inc.
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## weblogic.wtc.jatmi
Interface ApplicationToMonitorInterface

All Known Implementing Classes:
  TuxedoConnection

    public interface ApplicationToMonitorInterface

This interface represents the Java Application-to-Transaction Monitor Interface (JATMI) that provides connectivity between WebLogic Server and Tuxedo Services.

Field Summary
`static int` | `TPABSOLUTE` Internal flag
`static int` | `TPACK` Request acknowledgment of tpnotify
`static int` | `TPAPPAUTH` System and application authentication
`static int` | `TPCONV` Internal flag
`static int` | `TPGETANY` Get any reply
`static int` | `TPNOAUTH` Authentication not required
`static int` | `TPNOBLOCK` Do not block
`static int` | `TPNOCHANGE` Do not allow buffer type to change (not used in JATMI)
`static int` | `TPNOREPLY` No reply expected
`static int` | `TPNOTIME` Do not time out this call
`static int` | `TPNOTRAN` Do not execute inside current transaction
`static int` | `TPRECVONLY` Set conversation to read only mode
`static int` | `TPRMICALL` Indicates an outbound RMI/IIOP call
`static int` | `TPSENDONLY` Set conversation to send only mode
`static int` | `TPSIGRSTRT` Restart on signal (not used in JATMI)
`static int` | `TPSYSAUTH` System password authentication required
`static int` | `TPTRAN` Execute in a trasaction
`static int` | `TPUNKAUTH` Unknown authentication level

Method Summary
`CallDescriptor` | `tpacall(String svc, TypedBuffer data, int flags)` Sends a deferred asyncronous request message to a Tuxedo service.
`CallDescriptor` | `tpacall(String svc, TypedBuffer data, int flags, TpacallAsyncReply callBack)` Sends an asyncronous request message to a Tuxedo service.
`Reply` | `tpcall(String svc, TypedBuffer data, int flags)` Sends a request and synchronously awaits for the reply.
`void` | `tpcancel(CallDescriptor cd, int flags)` Cancels a call descriptor for outstanding reply.
`Conversation` | `tpconnect(String svc, TypedBuffer data, int flags)` Establishes a half-duplex connection to a conversational service, `svc`.
`DequeueReply` | `tpdequeue(String qspace, String qname, byte[] msgid, byte[] corrid, boolean doWait, boolean doPeek, int flags)` Removes a message for processing from the queue named by qname in the qspace queue space.
`DequeueReply` | `tpdequeue(String qspace, String qname, int flags)` Removes a message for processing from the queue named by qname in the qspace queue space using the following parameters: `msgid` and `corrid` set to null.
`byte[]` | `tpenqueue(String qspace, String qname, EnqueueRequest ctl, TypedBuffer data, int flags)` Stores a message on the queue named by qname in the qspace queue space.
`Reply` | `tpgetrply(CallDescriptor cd, int flags)` Returns a reply using the call descriptor returned by a deferred `tpacall`.
`void` | `tpsprio(int prio, int flags)` Sets the priority for the next request sent or forwarded by the current thread in the current context.
`void` | `tpterm()` Dissasociates an object from a Tuxedo session.

Field Detail

### TPNOBLOCK

    static final int TPNOBLOCK

  Do not block

  See Also:
    Constant Field Values

### TPSIGRSTRT

    static final int TPSIGRSTRT

  Restart on signal (not used in JATMI)

  See Also:
    Constant Field Values

### TPNOREPLY

    static final int TPNOREPLY

  No reply expected

  See Also:
    Constant Field Values

### TPNOTRAN

    static final int TPNOTRAN

  Do not execute inside current transaction

  See Also:
    Constant Field Values

### TPTRAN

    static final int TPTRAN

  Execute in a trasaction

  See Also:
    Constant Field Values

### TPNOTIME

    static final int TPNOTIME

  Do not time out this call

  See Also:
    Constant Field Values

### TPABSOLUTE

    static final int TPABSOLUTE

  Internal flag

  See Also:
    Constant Field Values

### TPGETANY

    static final int TPGETANY

  Get any reply

  See Also:
    Constant Field Values

### TPNOCHANGE

    static final int TPNOCHANGE

  Do not allow buffer type to change (not used in JATMI)

  See Also:
    Constant Field Values

### TPCONV

    static final int TPCONV

  Internal flag

  See Also:
    Constant Field Values

### TPSENDONLY

    static final int TPSENDONLY

  Set conversation to send only mode

  See Also:
    Constant Field Values

### TPRECVONLY

    static final int TPRECVONLY

  Set conversation to read only mode

  See Also:
    Constant Field Values

### TPACK

    static final int TPACK

  Request acknowledgment of tpnotify

  See Also:
    Constant Field Values

### TPRMICALL

    static final int TPRMICALL

  Indicates an outbound RMI/IIOP call

  See Also:
    Constant Field Values

### TPUNKAUTH

    static final int TPUNKAUTH

  Unknown authentication level

  See Also:
    Constant Field Values

### TPNOAUTH

    static final int TPNOAUTH

  Authentication not required

  See Also:
    Constant Field Values

### TPSYSAUTH

    static final int TPSYSAUTH

  System password authentication required

  See Also:
    Constant Field Values

### TPAPPAUTH

    static final int TPAPPAUTH

  System and application authentication

  See Also:
    Constant Field Values

Method Detail

### tpacall

    CallDescriptor tpacall(String svc,
                           TypedBuffer data,
                           int flags)
                           throws TPException

  Sends a deferred asyncronous request message to a Tuxedo service. A deferred `tpacall` service call sends a request to a Tuxedo service and immediately returns from the call. The service specified (`svc`) must be advertised by your Tuxedo application. Upon successful completion of the call, `tpacall` returns an object that serves as a descriptor. The calling thread is now available to perform other tasks.

  You can use the call descriptor to get the correct reply for the sent request using `tpgetreply` or cancel an outstanding message reply using `tpcancel`.

  A `tpacall` message request is sent with a message priority of 50. The type and sub-type of `data` must match one of the types and sub-types recognized by `svc`. If `data` is non-null, it must point to an object that implements the TypedBuffer interface. If `data` is null, a request is sent with no data portion. If `tpacall` is in a transaction, you must receive the reply using `tpgetreply` before the transaction can commit. You can not use `tpcancel` to cancel a call descriptor associated with a transaction.

  Parameters:
    `svc` - The name of the Tuxedo service
    `data` - Pointer to the data buffer; null specifies no data sent
    `flags` -
    - TPNOTRAN: Specifies if the caller is in transaction mode when `svc` is invoked, the call does not becoome part of the caller's transaction. If `svc` belongs to a server that does not support transactions, this flag must be set when the caller is in transaction mode. Note that `svc` may still be invoked in transaction mode but it will not be the same transaction: a `svc` may have a configuration attribute that it is automatically invoked in transaction mode. A caller in transaction mode that sets this flag is still subject to the transaction timeout (and no other). If a service fails that was invoked with this flag, the caller's transaction is not affected.
    - TPNOREPLY: Specifies a reply is not expected. When set, a call returns 0 on success, where 0 is not a valid descriptor. When the caller is in transaction mode, this setting can only be used if TPNOTRAN is also set.
    - TPNOBLOCK: Specifies this request is not sent if a blocking condition exists. For example, a blocking condition exits if the internal buffers into which this message is transferred is full. If TPNOBLOCK is not specified and a blocking condition exists, the caller blocks until the condition subsides, a transaction timeout occurs, or a blocking timeout occurs.
    - TPNOTIME: Specifies this caller blocks indefinitely and is immune from blocking timeouts but remains subject to transaction timeouts.
  Returns:
    Returns an object that serves as a descriptor. You can use the call descriptor to:
    - Get the correct reply for the sent request using `tpgetreply` or
    - Cancel an outstanding message reply using `tpcancel`.
  Throws:
    `TPException` - Returns a TPException indicating the error condition. `tperrno` is set to one of the following values:
    - TPEINVAL: Invalid arguments given. For example, `svc` is null or flags are invalid.
    - TPENOENT: Indicates `svc` does not exist or is a conversational service.
    - TPEITYPE: Indicates the type and sub-type of `data` does not match the type and sub-type expected by `svc`.
    - TPELIMIT: Indicates the request failed because the maximum number of outstanding asynchronous requests has been reached.
    - TPETRAN: Indicates `svc` belongs to a server that does not support transactions and TPNOTRAN was not set.
    - TPETIME: Indicates a timeout occurred. If the caller is in transaction mode, then a transaction timeout occurred and the transaction is marked abort-only:
      - Any attempt to send new requests or receive outstanding replies will fail with TPETIME until the transaction is aborted.
      - The only exception is a request that does not block, expects no reply, and is not sent on behalf of the caller's transaction - `tpacall` with TPNOTRAN, TPNOBLOCK, and TPNOREPLY set.
      Otherwise, a blocking timeout occurred and neither TPNOBLOCK nor TPNOTIME was specified.
    - TPEBLOCK: Indicates a blocking condition exists and TPNOBLOCK is specified.
    - TPEPROTO: Indicates `tpacall` was called improperly.
    - TPESYSTEM: A BEA Tuxedo system error occurred. The exact nature of the error is written to a log file.
    - TPEOS: An operating system error occurred. If a message queue on a remote location is filled, TPEOS may be returned even if `tpacall` returned successfully.

### tpacall

    CallDescriptor tpacall(String svc,
                           TypedBuffer data,
                           int flags,
                           TpacallAsyncReply callBack)
                           throws TPException

  Sends an asyncronous request message to a Tuxedo service. An asynchronous `tpacall` service call sends a request to a Tuxedo service and releases the thread resource that performed the call to the thread pool. This allows a very large number of outstanding requests to be serviced with a much smaller number of threads. The service specified (`svc`) must be advertised by your Tuxedo application. Upon successful completion of the call, asynchronous `tpacall` returns an object that serves as a descriptor. The calling thread is now available to perform other tasks. You can use the call descriptor to identify the correct message reply from `TpacallAsynchReply` for a sent message request or cancel an outstanding message reply using `tpcancel`. You can not use the call descriptor to invoke tpgetreply().

  Parameters:
    `callBack` - The object to invoke when the service reply is ready. If the original request succeeded, the `TpacallAsynchReply.sucess` method returns the reply from the service. If the original request failed, the `TpacallAsynchReply.failure` method returns a failure code. If null, the request becomes a deferred asyncronous `tpacall`.
    `svc` - The name of the Tuxedo service
    `data` - Pointer to the data buffer; null specifies no data sent
    `flags` -
    - TPNOTRAN: Specifies if the caller is in transaction mode when `svc` is invoked, the call does not becoome part of the caller's transaction. If `svc` belongs to a server that does not support transactions, this flag must be set when the caller is in transaction mode. Note that `svc` may still be invoked in transaction mode but it will not be the same transaction: a `svc` may have a configuration attribute that it is automatically invoked in transaction mode. A caller in transaction mode that sets this flag is still subject to the transaction timeout (and no other). If a service fails that was invoked with this flag, the caller's transaction is not affected.
    - TPNOREPLY: Specifies a reply is not expected. When set, a call returns 0 on success, where 0 is not a valid descriptor. When the caller is in transaction mode, this setting can only be used if TPNOTRAN is also set.
    - TPNOBLOCK: Specifies this request is not sent if a blocking condition exists. For example, a blocking condition exits if the internal buffers into which this message is transferred is full. If TPNOBLOCK is not specified and a blocking condition exists, the caller blocks until the condition subsides, a transaction timeout occurs, or a blocking timeout occurs.
    - TPNOTIME: Specifies this caller blocks indefinitely and is immune from blocking timeouts but remains subject to transaction timeouts.
  Throws:
    `TPException` - Returns a TPException indicating the error condition. If an exception is thrown by this method the callBack will not be invoked. `tperrno` is set to one of the following values:
    - TPEINVAL: Invalid arguments given. For example, `svc` is null or flags are invalid.
    - TPENOENT: Indicates `svc` does not exist or is a conversational service.
    - TPEITYPE: Indicates the type and sub-type of `data` does not match the type and sub-type expected by `svc`.
    - TPELIMIT: Indicates the request failed because the maximum number of outstanding asynchronous requests has been reached.
    - TPETRAN: Indicates `svc` belongs to a server that does not support transactions and TPNOTRAN was not set.
    - TPETIME: Indicates a timeout occurred. If the caller is in transaction mode, then a transaction timeout occurred and the transaction is marked abort-only:
      - Any attempt to send new requests or receive outstanding replies will fail with TPETIME until the transaction is aborted.
      - The only exception is a request that does not block, expects no reply, and is not sent on behalf of the caller's transaction - `tpacall` with TPNOTRAN, TPNOBLOCK, and TPNOREPLY set.
      Otherwise, a blocking timeout occurred and neither TPNOBLOCK nor TPNOTIME was specified.
    - TPEBLOCK: Indicates a blocking condition exists and TPNOBLOCK is specified.
    - TPEPROTO: Indicates `tpacall` was called improperly.
    - TPESYSTEM: A BEA Tuxedo system error occurred. The exact nature of the error is written to a log file.
    - TPEOS: An operating system error occurred. If a message queue on a remote location is filled, TPEOS may be returned even if `tpacall` returned successfully.

### tpcancel

    void tpcancel(CallDescriptor cd,
                  int flags)
                  throws TPException

  Cancels a call descriptor for outstanding reply. `tpcancel` cancels a call descriptor, `cd`, returned by `tpacall`. `cd` is no longer valid and any reply received on behalf of `cd` is silently discarded. It is an error to cancel a call descriptor associated with a transaction.

  Parameters:
    `cd` - Call descriptor returned by a deferred or ansyncronous tpacall.
    `flags` - Must be zero
  Throws:
    `TPExcpetion` - The following return codes may be thrown:
    - TPEINVAL: Invalid arguments given.
    - TPEBADDESC: Invalid call descriptor.
    - TPETRAN: Indicates the call descriptor is associated with the callers transaction. The call descriptor remains valid and the caller's transaction is not affected.
    - TPEPROTO: Indicates `pcancel` was called improperly.
    - TPESYSTEM: A BEA Tuxedo system error occurred. The exact nature of the error is written to a log file.
    - TPEOS: An operating system error occurred.
    `TPException`

### tpgetrply

    Reply tpgetrply(CallDescriptor cd,
                    int flags)
                    throws TPException,
                           TPReplyException

  Returns a reply using the call descriptor returned by a deferred `tpacall`. `tpgetreply` waits until the reply matching the call descriptor, `cd` arrives or a timeout occurs.

  Within any particular context of a multithreaded program:

  - Calls to `tpgetrply(TPGETANY)` and `tpgetrply` for a specific handle cannot be issued concurrently.
  - Multiple calls to `tpgetrply(TPGETANY)` cannot be issued concurrently.
  - Any `tpgetrply` call causes a violation of either of these restrictions throws a TPException with `errno` set to `TPEPROTO`.
  You can issue:
  - Concurrent calls to `tpgetrply` for different handles
  - A call to `tpgetrply(TPGETANY)` in a single context concurrently with a call to `tpgetrply`, with or without `TPGETANY`, in a different context.``

  Parameters:
    `cd` - Call descriptor returned from deferred tpacall or null if `TPGETANY` flag is set
    `flags` - The following is a list of valid flags:
    - TPGETANY: Specifies `tpgetrply` ignores the call descriptor, returns any reply available, and sets `cd` in the `replyrtn` object corresponding to the reply returned. If no reply exists, the default behavior of `tpgetrply` is to wait for a reply to arrive.
    - TPNOBLOCK: Indicates `tpgetrply` does not wait for the reply to arrive. If the reply is available, then gets the reply and returns. When this flag is not specified and a reply is not available, the caller blocks until the reply arrives or a timeout occurs (either a transaction or blocking timeout).
    - TPNOTIME: Indicates the caller is willing to block indefinitely for the reply and is immune to blocking timeouts. Transaction timeouts may still occur.
  Returns:
    Upon success `tpgetrply` returns a reply object that contains the reply data from the service, the service return status, and the call descriptor of the returned data. You should always check the return status of the reply object to determine if the service returned successfully.
  Throws:
    `TPException` - Upon failure `tpgetrply` throws `TPException` to indicate the error condition. tperrno in TPException will be set to one of the following values:
    - TPEINVAL: Invalid arguments were given. For example: `cd` or `flags` are invalid.
    - TPEOTYPE: The type and sub-type of the reply are not known to the caller. If the reply was to be received on behalf of the caller's current transaction, then the transaction is marked abort-only as the reply is discarded.
    - TPEBADDESC: `cd` points to an invalid descriptor.
    - TPETIME: A timeout occurred. If the caller is in transaction mode, then a transaction timeout occurred and the transaction is marked abort-only. Otherwise, a blocking timeout occurred and neither TPNOBLOCK nor TPNOTIME were specified. If a transaction timeout occurred, then with one exception, any attempts to send new requests or receive outstanding replies will fail with TPETIME until the transaction has been aborted. The exception is a request that does not block, expects no reply and is not sent on behalf of the caller's transaction - `tpacall` with TPNOTRAN, TPNOBLOCK and TPNOREPLY set.
    - TPEBLOCK: A blocking condition exists and TPNOBLOCK was specified.
    - TPEPROTO: `tpgetrply` was called improperly.
    - TPESYSTEM: A BEA Tuxedo system error has occurred. The exact nature of the error is written to a log file.
    - TPEOS: An operating system error has occurred. If a message queue on a remote location is filled, TPEOS may be returned.
    `TPReplyException` - If there is a service failure (TPESVCFAIL or TPSVCERROR) in which case the exception will also have reply data from the service. However, unlike the `tpcall` case, this execption may also be thrown in any of the above TPException cases as well, so that specific TPException return codes can be matched with the request object returned from `tpacall`. If TPReplyException is thrown then it is on behalf of an outstanding request and that request is considered to have completed with a failure.

### tpcall

    Reply tpcall(String svc,
                 TypedBuffer data,
                 int flags)
                 throws TPException,
                        TPReplyException

  Sends a request and synchronously awaits for the reply. A call to `tpcall` is the same as a deferred `tpacall` immediately followed by `tpgetrply`. `tpcall` sends a request to the service named by `svc`. The request is sent out at the priority defined for `svc` unless overridden by a previous call to `tpsprio`. The type and sub-type of data must match one of the types and sub-types recognized by `svc`.

  Parameters:
    `svc` - The name of the Tuxedo service
    `data` - Pointer to the data buffer; null specifies no data sent
    `flags` - The following is a list of valid flags:
    - TPNOTRAN: If the caller is in transaction mode and this flag is set, then when svc is invoked, it is not performed on behalf of the caller's transaction. Note that svc may still be invoked in transaction mode but it will not be the same transaction: a svc may have as a configuration attribute that it is automatically invoked in transaction mode. A caller in transaction mode that sets this flag is still subject to the transaction timeout (and no other). If a service fails that was invoked with this flag, the caller's transaction is not affected.
    - TPNOBLOCK: The request is not sent if a blocking condition exists. For example: the internal buffers into which the message is transferred are full. This flag applies only to the send portion of `tpcall` - the function may block when waiting for the reply. When TPNOBLOCK is not specified and a blocking condition exists, the caller blocks until the condition subsides or a timeout occurs (either transaction or blocking timeout).
    - TPNOTIME: Specifies that the caller is willing to block indefinitely and is immune to blocking timeouts. An exception is when the caller is in transaction mode. If the call is in transaction, this flag has no effect and transaction timeouts may occur.
  Returns:
    Upon success `tpcall` returns a reply object that contains the reply data from the service and the service return status. You should always check the return status of the reply object to determine if the service returned successfully.
  Throws:
    `TPException` - Upon failure `tpcall` sets tperrno in TPException to one of the following values. Unless otherwise noted, failure does not affect the caller's transaction, if one exists.
    - TPEINVAL: Invalid arguments were given. For example: `svc` is null or flags are invalid.
    - TPENOENT: Cannot send to `svc` because it does not exist, it is a conversational service, or the name provided begins with "." - a dot.
    - TPEITYPE: The type and sub-type of data is not one of the allowed types and sub-types that `svc` accepts.
    - TPEOTYPE: The type and sub-type of the reply are not known to the caller. If the service request was made on behalf of the caller's current transaction, then the transaction is marked abort-only since the reply is discarded.
    - TPETRAN: `svc` belongs to a server that does not support transactions and TPNOTRAN was not set.
    - TPETIME: A timeout occurred. If the caller is in transaction mode, then a transaction timeout occurred and the transaction is marked abort-only. Otherwise, a blocking timeout occurred and neither TPNOBLOCK nor TPNOTIME was specified. If a transaction timeout occurred, then with one exception, any attempts to send new requests or receive outstanding replies fail with TPETIME until the transaction has been aborted. The exception is a request that does not block, expects no reply, and is not sent on behalf of the caller's transaction - that is, `tpacall` with TPNOTRAN, TPNOBLOCK, and TPNOREPLY set.
    - TPEBLOCK: A blocking condition was found on the send call and TPNOBLOCK was specified.
    - TPEPROTO: `tpcall` was called improperly.
    - TPESYSTEM: A BEA Tuxedo system error has occurred. The exact nature of the error is written to a log file.
    - TPEOS: An operating system error has occurred. If a message queue on a remote location is filled, TPEOS may be returned even if `tpcall` returned successfully.
    `TPReplyException` - If there was a service failure (TPESVCFAIL or TPSVCERROR), the exception will also have the reply data from the service.

### tpenqueue

    byte[] tpenqueue(String qspace,
                     String qname,
                     EnqueueRequest ctl,
                     TypedBuffer data,
                     int flags)
                     throws TPException

  Stores a message on the queue named by qname in the qspace queue space. A queue space is a collection of queues, one of which must be qname.

  When the message is intended for a BEA Tuxedo system server, the qname matches the name of a service provided by the server. The system provided server, TMQFORWARD(5), provides a default mechanism for dequeuing messages from the queue and forwarding them to servers that provide a service matching the queue name. If the originator expects a reply, then the reply to the forwarded service request is stored on the originator's queue, unless otherwise specified. The originator will dequeue the reply message at a subsequent time. Queues can also be used for a reliable message transfer mechanism between any pair of BEA Tuxedo system processes (clients and/or servers). In this case, the queue name does not match a service name but some agreed upon name for transferring the message.

  If data is non-null, it must point to an object that implements the TypedBuffer interface. If data is null a message is queued with no data portion.

  The message is queued at the priority defined for qspace unless overridden by a previous call to tpsprio().

  If the caller is within a transaction and the TPNOTRAN flag is not set, the message is queued in transaction mode. This has the effect that if tpenqueue() returns successfully and the caller's transaction is committed successfully, then the message is guaranteed to be available subsequent to the transaction completing. If the caller's transaction is rolled back either explicitly or as the result of a transaction timeout or some communication error, then the message will be removed from the queue (that is, the placing of the message on the queue is also rolled back). It is not possible to enqueue then dequeue the same message within the same transaction.

  The message is not queued in transaction mode if either the caller is not in transaction mode, or the TPNOTRAN flag is set. Once tpenqueue() returns successfully, the submitted message is guaranteed to be in the queue. When not in transaction mode, if a communication error or a timeout occurs, the application will not know whether or not the message was successfully stored on the queue.

  The order in which messages are placed on the queue is controlled by the application via ctl object as described in the EnqueueRequest manual page; the default queue ordering is set when the queue is created.

  Additional information about queuing the message can be specified via ctl object. This information includes values to override the default queue ordering placing the message at the top of the queue or before an enqueued message; an absolute or relative time after which a queued message is made available; an absolute or relative time when a message expires and is removed from the queue; the quality of service for delivering the message; the quality of service that any replies to the message should use; a correlation identifier that aids in correlating a reply or failure message with the queued message; the name of a queue to which a reply should be enqueued; and the name of a queue to which any failure message should be enqueued. See the EnqueueRequest object for more information.

  Parameters:
    `qspace` - The name of the queue space to enqueue this message on
    `qname` - The name of the queue within qspace to enqueue this message on
    `ctl` - The EnqueueRequest object describing this enqueue operation
    `data` - The data to be enqueued
    `flags` - The following is a list of valid flags:
    - TPNOTRAN If the caller is in transaction mode and this flag is set, the message is not queued within the caller's transaction. A caller in transaction mode that sets this flag is still subject to the transaction timeout (and no other) when queuing the message. If message queuing fails, the caller's transaction is not affected.
    - TPNOBLOCK The message is not enqueued if a blocking condition exists. If this flag is set and a blocking condition exists such as the internal buffers into which the message is transferred are full, the call fails and tperrno in TPException is set to TPEBLOCK. If this flag is set and a blocking condition exists because the target queue is opened exclusively by another application, the call succeeds but the diagnostic field of the Enqueue object is set to QMESHARE. In the latter case, the other application, which is based on a BEA product other than the BEA Tuxedo system, opened the queue for exclusive read and/or write using the Queuing Services API (QSAPI).

      When TPNOBLOCK is not set and a blocking condition exists, the caller blocks until the condition subsides or a timeout occurs (either transaction or blocking timeout). If a timeout occurs, the call fails and tperrno in TPException is set to TPETIME.

    - TPNOTIME Setting this flag signifies that the caller is willing to block indefinitely and wants to be immune to blocking timeouts. Transaction timeouts may still occur.
  Returns:
    The message id of the enqueued message
  Throws:
    `TPException` - Upon failure, tpenqueue() sets tperrno in TPException to one of the following values (unless otherwise noted, failure does not affect the callers transaction, if one exists)
    - TPEINVAL Invalid arguments were given (for example, qspace is null or flags are invalid).
    - TPENOENT Cannot access the qspace because it is not available (that is, the associated TMQUEUE(5) server is not available), or cannot start a global transaction due to the lack of entries in the Global Transaction Table (GTT).
    - TPETIME A timeout occurred. If the caller is in transaction mode, a transaction timeout occurred and the transaction is to be aborted; otherwise, a blocking timeout occurred and neither TPNOBLOCK nor TPNOTIME was specified. If a transaction timeout occurred, any attempts to enqueue new messages will fail with TPETIME until the transaction has been aborted.
    - TPEBLOCK A blocking condition exists and TPNOBLOCK was specified.
    - TPEPROTO tpenqueue() was called improperly.
    - TPESYSTEM A BEA Tuxedo system error has occurred. The exact nature of the error is written to a log file.
    - TPEOS An operating system error has occurred.
    - TPEDIAGNOSTIC One of the following values is available in the diagnostic field of the execption:
      - QMEINVAL An invalid flag value was specified.
      - QMEBADRMID An invalid resource manager identifier was specified.
      - QMENOTOPEN The resource manager is not currently open.
      - QMETRAN The call was not in transaction mode or was made with the TPNOTRAN flag set and an error occurred trying to start a transaction in which to enqueue the message. This diagnostic is not returned by queue managers from BEA Tuxedo Release 7.1 or later.
      - QMEBADMSGID An invalid message identifier was specified.
      - QMESYSTEM A system error occurred. The exact nature of the error is written to a log file.
      - QMEOS An operating system error occurred.
      - QMEABORTED The operation was aborted. When executed within a global transaction, the global transaction has been marked rollback-only. Otherwise, the queue manager aborted the operation.
      - QMEPROTO An enqueue was done when the transaction state was not active.
      - QMEBADQUEUE An invalid or deleted queue name was specified.
      - QMENOSPACE Due to an insufficient resource, such as no space on the queue, the message with its required quality of service (persistent or non-persistent storage) was not enqueued. QMENOSPACE is returned when any of the following configured resources is exceeded: (1) the amount of disk (persistent) space allotted to the queue space, (2) the amount of memory (non-persistent) space allotted to the queue space, (3) the maximum number of simultaneously active transactions allowed for the queue space, (4) the maximum number of messages that the queue space can contain at any one time, (5) the maximum number of concurrent actions that the Queuing Services component can handle, or (6) the maximum number of authenticated users that may concurrently use the Queuing Services component.
      - QMERELEASE An attempt was made to enqueue a message to a queue manager that is from a version of the BEA Tuxedo system that does not support a newer feature.
      - QMESHARE When enqueuing a message from a specified queue, the specified queue is opened exclusively by another application. The other application is one based on a BEA product other than the BEA Tuxedo system that opened the queue for exclusive read and/or write using the Queuing Services API (QSAPI).

### tpdequeue

    DequeueReply tpdequeue(String qspace,
                           String qname,
                           byte[] msgid,
                           byte[] corrid,
                           boolean doWait,
                           boolean doPeek,
                           int flags)
                           throws TPException

  Removes a message for processing from the queue named by qname in the qspace queue space.

  By default, the message at the top of the queue is dequeued. The order of messages on the queue is defined when the queue is created. The application can request a particular message for dequeuing by specifying its message identifier or correlation identifier. There are also parameters used to indicate that the application wants to wait for a message, in the case when a message is not currently available. It is possible to use tpdequeue to look at a message without removing it from the queue or changing its relative position on the queue.

  The message is dequeued in transaction mode if the caller is in transaction mode and the TPNOTRAN flag is not set. This has the effect that if tpdequeue() returns successfully and the caller's transaction is committed successfully, then the message is removed from the queue. If the caller's transaction is rolled back either explicitly or as the result of a transaction timeout or some communication error, then the message will be left on the queue (that is, the removal of the message from the queue is also rolled back). It is not possible to enqueue and dequeue the same message within the same transaction.

  The message is not dequeued in transaction mode if either the caller is not in transaction mode, or the TPNOTRAN flag is set. When not in transaction mode, if a communication error or a timeout occurs, the application will not know whether or not the message was successfully dequeued and the message may be lost.

  Parameters:
    `qspace` - The name of the queue space to enqueue this message on
    `qname` - The name of the queue within qspace to enqueue this message on
    `msgid` - If non-null it requests that the message with this identifier be dequeued. Note that a message identifier changes if the message has moved from one queue to another
    `corrid` - If non-null it requests that the message with this correlation id be dequeued. The correlation identifier is specified by the application when enqueuing the message with tpenqueue
    `doWait` - If true it indicates that an error should not be returned if the queue is empty. Instead the process should wait until a message is available. If doWait is true and msgid or corrid is not null, it indicates that an error should not be returned if no message with the specified message identifier or correlation identifier is present in the queue. Instead, the process should wait until until a message meeting the criteria is available. The process is still subject to the caller's transaction timeout, or, when not in transaction mode, the process is subject to the timeout specified on the TMQUEUE process by the -t option.
    `doPeek` - If this is true, then the specified message is read but not removed from the queue. This flag implies the TPNOTRAN flag has been set for the tpdequeue operation. That is, non-destructive dequeueing is non-transactional. Note that it is not possible to read messages enqueued or dequeued within a transaction before the transaction completes.
    `flags` - The following is a list of valid flags:
    - TPNOTRAN If the caller is in transaction mode and this flag is set, the message is not dequeued within the caller's transaction. A caller in transaction mode that sets this flag is still subject to the transaction timeout (and no other) when dequeuing the message. If message dequeuing fails, the caller's transaction is not affected.
    - TPNOBLOCK The message is not dequeued if a blocking condition exists. If this flag is set and a blocking condition exists such as the internal buffers into which the message is transferred are full, the call fails and TPException() is set to TPEBLOCK. If this flag is set and a blocking condition exists because the target queue is opened exclusively by another application, the call will throw an exception, and the diagnostic value in the TPException object is set to QMESHARE. In the latter case, the other application, which is based on a BEA product other than the BEA Tuxedo system, opened the queue for exclusive read and/or write using the Queuing Services API (QSAPI). When TPNOBLOCK is not set and a blocking condition exists, the caller blocks until the condition subsides or a timeout occurs (either transaction or blocking timeout). This blocking condition does not include blocking on the queue itself if doWait is true.
    - TPNOTIME Setting this flag signifies that the caller is willing to block indefinitely and wants to be immune to blocking timeouts. Transaction timeouts may still occur.
  Returns:
    If tpdequeue() returns successfully, the application can retrieve additional information about the message using the DequeueReply object. The information may include the message identifier for the dequeued message; a correlation identifier that should accompany any reply or failure message so that the originator can correlate the message with the original request; the quality of service the message was delivered with, the quality of service any replies to the message should be delivered with; the name of a reply queue if a reply is desired; and the name of the failure queue on which the application can queue information regarding failure to dequeue the message. These are described in the DequeueReply object manual page.
  Throws:
    `TPException` - tperrno is set to one of the following values. (Unless otherwise noted, failure does not affect the caller's transaction, if one exists.)
    - TPEINVAL Invalid arguments were given (for example, qname is null or flags are invalid).
    - TPENOENT Cannot access the qspace because it is not available (that is, the associated TMQUEUE(5) server is not available), or cannot start a global transaction due to the lack of entries in the Global Transaction Table (GTT).
    - TPEOTYPE The type and sub-type of the dequeued message are not known to the caller. When the call is made in transaction mode and this error occurs, the transaction is marked abort-only, and the message remains on the queue.
    - TPETIME A timeout occurred. If the caller is in transaction mode, a transaction timeout occurred and the transaction is to be aborted; otherwise, a blocking timeout occurred and neither TPNOBLOCK nor TPNOTIME was specified. If a transaction timeout occurred, any attempts to dequeue new messages will fail with TPETIME until the transaction has been aborted.
    - TPEBLOCK A blocking condition exists and TPNOBLOCK was specified.
    - TPEPROTO tpdequeue() was called improperly. There is no effect on the queue or the transaction.
    - TPESYSTEM A BEA Tuxedo system error has occurred. The exact nature of the error is written to a log file. There is no effect on the queue.
    - TPEOS An operating system error has occurred. There is no effect on the queue.
    - TPEDIAGNOSTIC The following diagnostic values may be returned in the exception:
      - QMEINVAL An invalid flag value was specified.
      - QMEBADRMID An invalid resource manager identifier was specified.
      - QMENOTOPEN The resource manager is not currently open.
      - QMETRAN The call was not in transaction mode or was made with the TPNOTRAN flag set and an error occurred trying to start a transaction in which to dequeue the message. This diagnostic is not returned by queue managers from BEA Tuxedo Release 7.1 or later.
      - QMEBADMSGID An invalid message identifier was specified for dequeuing.
      - QMESYSTEM A system error has occurred. The exact nature of the error is written to a log file.
      - QMEOS An operating system error has occurred.
      - QMEABORTED The operation was aborted. When executed within a global transaction, the global transaction has been marked rollback-only. Otherwise, the queue manager aborted the operation.
      - QMEPROTO A dequeue was done when the transaction state was not active.
      - QMEBADQUEUE An invalid or deleted queue name was specified.
      - QMENOMSG No message was available for dequeuing. Note that it is possible that the message exists on the queue and another application process has read the message from the queue. In this case, the message may be put back on the queue if that other process rolls back the transaction.
      - QMEINUSE When dequeuing a message by message identifier or correlation identifier, the specified message is in use by another transaction. Otherwise, all messages currently on the queue are in use by other transactions. This diagnostic is not returned by queue managers from BEA Tuxedo Release 7.1 or later.
      - QMESHARE When dequeuing a message from a specified queue, the specified queue is opened exclusively by another application. The other application is one based on a BEA product other than the BEA Tuxedo system that opened the queue for exclusive read and/or write using the Queuing Services API (QSAPI).
      - QMERELEASE An attempt was made to dequeue a message to a queue manager that is from a version of the BEA Tuxedo system that does not support a newer feature.

### tpdequeue

    DequeueReply tpdequeue(String qspace,
                           String qname,
                           int flags)
                           throws TPException

  Removes a message for processing from the queue named by qname in the qspace queue space using the following parameters:
  - `msgid` and `corrid` set to null.
  - `doWait` and `doPeek` set to false.

  Throws:
    `TPException`

### tpterm

    void tpterm()
                throws TPException

  Dissasociates an object from a Tuxedo session. No further ATMI calls can be made on this object after this `tpterm` has been called.

  Throws:
    `TPException` - if called in the wrong context

### tpconnect

    Conversation tpconnect(String svc,
                           TypedBuffer data,
                           int flags)
                           throws TPException

  Establishes a half-duplex connection to a conversational service, `svc`. The name must be one of the conversational service names posted by a conversational server. As part of setting up the connection, the caller can pass application data to the listening program. If the caller chooses to pass data, then data must be a TypedBuffer. The type and subtype of data must match one of the types and sub-types recognized by `svc`. `data` is passed to the conversational service via the TPServiceInformation structure with which the service is invoked. The service does not have to call `tprecv` to get the data.

  Parameters:
    `svc` - The conversational service to invoke
    `data` - The initial data to send to the service
    `flags` - The following is the list of valid flags
    - TPNOTRAN: If the caller is in transaction mode and this flag is set, then when `svc` is invoked, it is not performed on behalf of the caller's transaction. Note that code>svc may still be invoked in transaction mode but it will not be the same transaction: a code>svc may have as a configuration attribute that it is automatically invoked in transaction mode. A caller in transaction mode that sets this flag is still subject to the transaction timeout and no other time out. If a service fails that was invoked with this flag, the caller's transaction is not affected.
    - TPSENDONLY: The caller wants the connection to be set up initially such that it can only send data and the called service can only receive data. This establishes the caller with initial control of the connection. Either TPSENDONLY or TPRECVONLY must be specified.
    - TPRECVONLY: The caller wants the connection to be set up initially such that it can only receive data and the called service can only send data. This establishes that the service being called initially has control of the connection. Either TPSENDONLY or TPRECVONLY must be specified.
    - TPNOBLOCK: The request is not sent if a blocking condition exists. For example: the internal buffers into which the message is transferred are full. Note that this flag applies only to the send portion of `tpconnect`, the function may block waiting for the reply. When TPNOBLOCK is not specified and a blocking condition exists, the caller blocks until the condition subsides or a timeout occurs (either transaction or blocking timeout).
    - TPNOTIME: Specifies that the caller is willing to block indefinitely and is immune to blocking timeouts. An exception is when the caller is in transaction mode. If the call is in transaction, this flag has no effect and transaction timeouts may occur.
  Returns:
    Upon successful completion, `tpconnect` returns an object that can be used to send and receive data on this conversation.
  Throws:
    `TPException` - Upon failure, t`tpconnect` returns a TPException exception to indicate the error condition. tperrno in TPException will be set to one of the following values:
    - TPEINVAL: Invalid arguments were given. For example, `svc` is null or flags are invalid.
    - TPETIME: A timeout occurred. If the caller is in transaction mode, then a transaction timeout occurred and the transaction is marked abort-only. Otherwise, a blocking timeout occurred and neither TPNOBLOCK nor TPNOTIME was specified. If a transaction timeout occurred, then with one exception, any attempts to send new requests or receive outstanding replies fail with TPETIME until the transaction has been aborted. The exception is a request that does not block, expects no reply, and is not sent on behalf of the caller's transaction - a `tpacall` with TPNOTRAN, TPNOBLOCK, and TPNOREPLY set.
    - TPEPROTO: `tpconnect` was called improperly.
    - TPESYSTEM: A BEA Tuxedo system error has occurred. The exact nature of the error is written to a log file.

### tpsprio

    void tpsprio(int prio,
                 int flags)
                 throws TPException

  Sets the priority for the next request sent or forwarded by the current thread in the current context. The priority set affects only the next request sent. Priority can also be set for messages enqueued or dequeued by `tpenqueue` or `tpdequeue`. By default, the setting of `prio` increments or decrements a service's default priority up to a maximum of 100 or down to a minimum of 1, depending on its sign, where 100 is the highest priority. The default priority for a request is determined by the service to which the request is being sent. This default may be specified administratively (see UBBCONFIG(5)), or take the system default of 50. tpsprio() has no effect on messages sent via `tpconnect`or `tpsend`. A lower priority message does not remain enqueued forever because every tenth message is retrieved on a "first in, first out" (FIFO) basis. Response time should not be a concern of the lower priority interface or service. `flags` may be set to 0 or may be set to TPABSOLUTE. If TPABSOLUTE is set, then the priority of the next request should be sent out at the absolute value of prio. The absolute value of prio must be within the range 1 and 100, inclusive, with 100 being the highest priority. Any value outside of this range causes a default value to be used.

  ``
  Throws:
    `TPException`

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| Documentation is available at http://e-docs.bea.com/wls/docs92 Copyright 2006 BEA Systems Inc.
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD