com.oracle.tuxedo.tjatmi

Interface TuxApplicationToMonitorInterface

All Known Implementing Classes:

TuxAppContext

public interface TuxApplicationToMonitorInterface

This interface represents the Java Application-to-Transaction Monitor Interface.

Method Summary

Methods

Modifier and Type	Method and Description
int	tpabort(long flags) tpabort() signifies the abnormal end of a transaction.
int	tpacall(java.lang.String svc, weblogic.wtc.jatmi.TypedBuffer idata, long flags) Sends a request message to the service named by svc.
int	tpadvertise(java.lang.String svcname, java.lang.String clsname, java.lang.String methodnm, long flags) tpadvertise() allows a application to advertise the services that it offers.
int	tpbegin(long trntime, long flags) tpbegin() signifies the beginning of a transaction.
int	tpbroadcast(java.lang.String lmid, java.lang.String usrname, java.lang.String cltname, weblogic.wtc.jatmi.TypedBuffer data, long flags) tpbroadcast is used by a client or server to send an unsolicited message to registered clients within the system.
TuxATMIReply	tpcall(java.lang.String svc, weblogic.wtc.jatmi.TypedBuffer idata, long flags) Sends a request and synchronously awaits the reply.
int	tpcancel(int cd) Cancels a call descriptor returned, cd, returned by tpacall.
int	tpcommit(long flags) tpcommit() signifies the end of a transaction, using a two-phase commit protocol to coordinate participants.
TuxATMIReply	tpdequeue(java.lang.String qspace, java.lang.String qname, TPQCTL ctl, long flags) tpdequeue method can be used to take a message for processing from the queue tpdequeue method can be used to take a message for processing from the queue named by qname in the qspace queue space.
int	tpenqueue(java.lang.String qspace, java.lang.String qname, TPQCTL ctl, weblogic.wtc.jatmi.TypedBuffer data, long flags) tpenqueue method can be used to store a message on the queue tpenqueue method can be used to store a message on the queue named by qname in qspace queue space.
weblogic.wtc.jatmi.TypedXML	tpfml32toxml(weblogic.wtc.jatmi.TypedFML32 fmldata, java.lang.String xfile, java.lang.String rtag, long flags) tpfml32toxml is used to convert a TypedFML32 object to a TypedXML object.
weblogic.wtc.jatmi.TypedXML	tpfmltoxml(weblogic.wtc.jatmi.TypedFML fmldata, java.lang.String xfile, java.lang.String rtag, long flags) tpfmltoxml is used to convert a TypedFML object to a TypedXML object.
void	tpforward(java.lang.String svcname, weblogic.wtc.jatmi.TypedBuffer data, long flags) tpforward method allows a service routine to forward a client's request to another service routine for further processing.
int	tpgblktime(long flags) tpgblktime retrieves a previously set blocktime value.
int	tpgetlev() tpgetlev() returns the current transaction level to the caller.
TuxATMIReply	tpgetrply(int cd, long flags) Returns a reply from a previously sent request.
int	tpgprio() tpgprio() returns the priority for the last request sent or received by the current thread in its current context.
int	tpnotify(CLIENTID cltid, weblogic.wtc.jatmi.TypedBuffer data, long flags) tpnotify() method can be used by a client or server to send an unsolicited message to an individual client.
int	tppost(java.lang.String eventname, weblogic.wtc.jatmi.TypedBuffer data, long flags) tppost method can be used to post an event and any accompanying data.
int	tpresume(TPTRANID trnId, long flags) tpresume is used to resume work on behalf of a previously suspended transaction.
void	tpreturn(int rval, long rcode, weblogic.wtc.jatmi.TypedBuffer rdata, long flags) Indicates that a service routine has completed.
int	tpsblktime(int blktime, long flags) tpsblktime method can be used to set the blocktime value.
int	tpscmt(long flags) tpscmt method sets the TP_COMMIT_CONTROL characteristic to the value specified in flags.
int	tpsprio(int prio, long flags) tpsprio sets the priority for the next request sent or forwarded by the current thread.
long	tpsubscribe(java.lang.String eventexpr, java.lang.String filter, TPEVCTL ctl, long flags) Subscribes an event or set of events named by eventexpr.
TPTRANID	tpsuspend(long flags) tpsuspend() is used to suspend the transaction active in the caller's process.
int	tpunadvertise(java.lang.String svcname, long flags) tpunadvertise() allows a application to unadvertise the services that it offers.
int	tpunsubscribe(long subscription, long flags) tpunsubscribe can be used to remove an event subscription or a set of event subscriptions from the Oracle Tuxedo EventBroker's list of active subscriptions.
weblogic.wtc.jatmi.TypedFML	tpxmltofml(weblogic.wtc.jatmi.TypedXML xmldata, java.lang.String xfile, java.lang.String rtag, long flags) tpxmltofml method can be used to convert a TypedXML object to TypedFML object.
weblogic.wtc.jatmi.TypedFML32	tpxmltofml32(weblogic.wtc.jatmi.TypedXML xmldata, java.lang.String xfile, java.lang.String rtag, long flags) tpxmltofml method can be used to convert a TypedXML object to TypedFML32 object.

Method Detail

tpcall

TuxATMIReply tpcall(java.lang.String svc,
                  weblogic.wtc.jatmi.TypedBuffer idata,
                  long flags)
                    throws TuxATMITPException,
                           TuxATMITPReplyException

Sends a request and synchronously awaits the reply. tpcall sends a request to the service named by svc. 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

idata - 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.
• TPSIGRSTRT:If a signal interrupts any underlying system calls, then the interrupted system call is reissued.

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:

TuxATMITPException - Upon failure tpcall sets tperrno in TuxATMITPException 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 idata 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.
• TPGOTSIG: A signal was received and TPSIGRSTRT was not specified.
• TPEPROTO: tpcall was called improperly.
• TPESYSTEM: A Oracle 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.

TuxATMITPReplyException - If there was a service failure (TPESVCFAIL or TPSVCERROR), the exception will also have the reply data from the service. tperrno in TuxATMITPReplyException is set to one of the following values.

• TPESVCFAIL: The service routine sending the caller's reply called tpreturn() with TPFAIL. This is an application-level failure. The contents of the service's reply, if one was sent, is available in TuxATMITPReplyException. If the service request was made on behalf of the caller's current transaction, then the transaction is marked abort-only. Note that regardless of whether the transaction has timed out, the only valid communications before the transaction is aborted are calls to tpacall() with TPNOREPLY, TPNOTRAN, and TPNOBLOCK set.
• TPESVCERR: A service routine encountered an error either intpreturn or tpforward (for example, bad arguments were passed). No reply data is returned when this error occurs. If the service request was made on behalf of the caller's transaction (that is, TPNOTRAN was not set), then the transaction is marked abort-only. Note that regardless of whether the transaction has timed out, the only valid communications before the transaction is aborted are calls to tpacall() with TPNOREPLY, TPNOTRAN, and TPNOBLOCK set. If either SVCTIMEOUT in the UBBCONFIG file or TA_SVCTIMEOUT in the TM_MIB is non-zero, TPESVCERR is returned when a service timeout occurs.

tpacall

int tpacall(java.lang.String svc,
          weblogic.wtc.jatmi.TypedBuffer idata,
          long flags)
            throws TuxATMITPException

Sends a request message to the service named by svc. The request is sent out at the priority defined by svc unless overridden by a previous call to tpsprio().

Parameters:

svc - The name of the Tuxedo service.

idata - A valid TypedBuffer object.

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. If svc belongs to a server that does not support transactions, then 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 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.
• TPNOREPLY: Informs tpacall() that a reply is not expected. When TPNOREPLY is set, the function returns 0 on success, where 0 is an invalid descriptor. When the caller is in transaction mode, this setting cannot be used unless TPNOTRAN is also set.
• TPNOBLOCK: The request is not sent if a blocking condition exists (for example, the internal buffers into which the message is transferred are full). 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: This flag signifies that the caller is willing to block indefinitely and wants to be immune to blocking timeouts. Transaction timeouts may still occur.
• TPSIGRSTRT: If a signal interrupts any underlying system calls, then the interrupted system call is reissued.

Returns:

Upon successfully completion, tpacall returns a description that can be used to receive the reply of the request sent.

Throws:

TuxATMITPException - Upon failure, tpacall() sets tperrno 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, data does not point to space allocated with tpalloc(), or flags are invalid).
• [TPENOENT]: Cannot send to svc because it does not exist or is a conversational service.
• [TPEITYPE]: The type and subtype of data is not one of the allowed types and subtypes that svc accepts.
• [TPELIMIT]: The caller's request was not sent because the maximum number of outstanding asynchronous requests has been reached.
• [TPETRAN]: svc belongs to a server that does not support transactions and TPNOTRAN was not set.
• [TPETIME]: This error code indicates that either a timeout has occurred or tpacall() has been attempted, in spite of the fact that the current transaction is already marked rollback only. If the caller is in transaction mode, then either the transaction is already rollback only or a transaction timeout has occurred. The transaction is marked abort-only. If the caller is not in transaction mode, a blocking timeout has occurred. (A blocking timeout cannot occur if TPNOBLOCK and/or TPNOTIME is specified.) If a transaction timeout has 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 (that is, tpacall() with TPNOTRAN, TPNOBLOCK, and TPNOREPLYset). When a service fails inside a transaction, the transaction is put into the TX_ROLLBACK_ONLY state. This state is treated, for most purposes, as though it were equivalent to a timeout. All further ATMI calls for this transaction (with the exception of those issued in the circumstances described in the previous paragraph) will fail with TPETIME.
• [TPEBLOCK]: A blocking condition exists and TPNOBLOCK was specified.
• [TPGOTSIG]: A signal was received and TPSIGRSTRT was not specified.
• [TPEPROTO]: tpacall() was called improperly.
• [TPESYSTEM]: An Oracle 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 tpacall() returned successfully.

tpgetrply

TuxATMIReply tpgetrply(int cd,
                     long flags)
                       throws TuxATMITPException

Returns a reply from a previously sent request. This first argument, cd, points to a call descriptor returned by tpacall. By default, the function waits until the reply matching *cd arrives or a timeout occurs.

Parameters:

cd - It points a call descriptor returned by tpacall.

flags - The following is a list of valid flags:

• TPGETANY: This flag signifies that tpgetrply() should ignore the descriptor pointed to by cd, return any reply available and set cd to point to the call descriptor for the reply returned. If no replies exist, tpgetrply() by default will wait for one to arrive.
• TPNOBLOCK: tpgetrply() does not wait for the reply to arrive. If the reply is available, then tpgetrply() 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 transaction or blocking timeout).
• TPNOTIME: This flag signifies that the caller is willing to block indefinitely for its reply and wants to be immune to blocking timeouts. Transaction timeouts may still occur.
• TPSIGRSTRT: If a signal interrupts any underlying system calls, then the interrupted system call is reissued.

Returns:

Upon successful return from tpgetrply or upon return where tperrno is set to TPESVCFAIL, tpurcode contains an application defined value that was sent as part of tpreturn

Throws:

TuxATMITPException - Upon failure, tpgetrply() throws TuxATMITPException, and TuxATMITPException.gettperrno() can be used to get the error condition. When TuxATMIConstants.TPGETANY bit value is specified, the real call descriptor associated with the reply message can be got by invoking TuxATMIReply.getCd(). Upon failure, tpgetrply sets tperrno as indicated below.

• [TPEINVAL]: Invalid arguments were given (for example, cd, flags are invalid).
• [TPEBADDESC]: cd points to an invalid descriptor.
• [TPETIME]: This error code indicates that either a timeout has occurred or tpgetrply() has been attempted, in spite of the fact that the current transaction is already marked rollback only. If the caller is in transaction mode, then either the transaction is already rollback only or a transaction timeout has occurred. The transaction is marked abort-only. If the caller is not in transaction mode, a blocking timeout has occurred. (A blocking timeout cannot occur if TPNOBLOCK and/or TPNOTIME is specified.)
• [TPESVCFAIL]: The service routine sending the caller's reply called tpreturn with TPFAIL. This is an application-level failure.
• [TPESVCERR]: A service routine encountered an error either in tpreturn or tpforward (for example, bad arguments were passed).
• [TPEBLOCK]: A blocking condition exists and TPNOBLOCK was specified.
• [TPGOTSIG]: A signal was received and TPSIGRSTRT was not specified.
• [TPEPROTO]: tpgetrply() was called improperly.
• [TPESYSTEM]: An Oracle 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 possibly be returned.

tpcancel

int tpcancel(int cd)
             throws TuxATMITPException

Cancels a call descriptor returned, cd, returned by tpacall.

Parameters:

cd - It is a call descriptor returned by tpacall

Returns:

Upon success, the call descriptor is not longer valid and any reply received on behalf of cd will be silently discarded.

Throws:

TuxATMITPException - Upon failure, tpcancel() throws TuxATMITPException, and TuxATMITPException.gettperrno() can be used to got the error condition. Upon failure, tpcancel() sets tperrno to one of the following values:

• [TPEBADDESC]: cd is an invalid descriptor.
• [TPETRAN]: cd() is associated with the caller's transaction. cd remains valid and the caller's current transaction is not affected.
• [TPEPROTO]: tpcancel() was called improperly.
• [TPESYSTEM]: An Oracle Tuxedo system error has occurred. The exact nature of the error is written to a log file.
• [TPEOS]: An operating system error has occurred.

tpreturn

void tpreturn(int rval,
            long rcode,
            weblogic.wtc.jatmi.TypedBuffer rdata,
            long flags)
              throws TuxATMITPException

Indicates that a service routine has completed. tpreturn does not acts like a return statement in the C language. (that is, when tpreturn() is called, the service routine remains in Java service. User must make sure the tpreturn() is the last execution statement in Java service)

tpreturn is used to send a service's reply message. If the program receiving the reply is waiting in either tpcall(), tpgetrply(), then after a successful call to tpreturn(), the reply is available in the receiver's buffer.

If the service routine was in transaction mode,tpreturn() places the service's portion of the transaction in a state from which it may be either committed or rolled back when the transaction is completed. A service may be invoked multiple times as part of the same transaction so it is not necessarily fully committed or rolled back until either tpcommit() or tpabort() is called by the originator of the transaction.

tpreturn() should be called after receiving all replies expected from service requests initiated by the service routine. Otherwise, depending on the nature of the service, either a TPESVCERR status or a TPEV_SVCERR event will be returned to the program that initiated communication with the service routine. Any outstanding replies that are not received will automatically be dropped by the communication manager. In addition, the descriptors for those replies become invalid.

Parameters:

rval - rval can be set to one of the following:

• TPSUCCESS: The service has terminated successfully. If data is present, then it will be sent (barring any failures processing the return). If the caller is in transaction mode, then tpreturn() places the caller's portion of the transaction in a state such that it can be committed when the transaction ultimately commits. Note that a call to tpreturn() does not necessarily finalize an entire transaction. Also, even though the caller indicates success, if there are any outstanding replies or open connections, if any work done within the service caused its transaction to be marked rollback-only, then a failed message is sent (that is, the recipient of the reply receives a TPESVCERR indication or a TPEV_SVCERR event). Note that if a transaction becomes rollback-only while in the service routine for any reason, then rval should be set to TPFAIL. If TPSUCCESS is specified for a conversational service, a TPEV_SVCSUCC event is generated.
• TPFAIL: The service has terminated unsuccessfully from an application standpoint. An error will be reported to the program receiving the reply. That is, the call to get the reply will fail and the recipient receives a TPSVCFAIL indication or a TPEV_SVCFAIL event. If the caller is in transaction mode, then tpreturn() marks the transaction as rollback-only (note that the transaction may already be marked rollback-only). Barring any failures in processing the return, the caller's data is sent, if present. One reason for not sending the caller's data is that a transaction timeout has occurred. In this case, the program waiting for the reply will receive an error of TPETIME. If TPFAIL is specified for a conversational service, a TPEV_SVCFAIL event is generated.
• TPEXIT: This value behaves the same as TPFAIL with respect to completing the service, but when TPEXIT is returned, the server exits after the transaction is rolled back and the reply is sent back to the requester. When specified for a multithreaded process, TPEXIT indicates that an entire process (not only a single thread within that process) will be killed. If the server is restartable, then the server is restarted automatically.

If rval is not set to one of these three values, then it defaults to TPFAIL.

rcode - An application defined return code. It may be sent to the program receiving the service reply. This code is sent regardless of the setting of rval as long as a reply can be successfully sent (that is, as long as the receiving call returns success or TPESVCFAIL). The value of rcode is available in the receiver in the variable, tpurcode.

rdata - points to the data object of a reply to be sent. If data is non-NULL, it must point to a valid Typed buffer object.

It rdata is null, when a reply is expected by the program that invoked the service, then a reply is sent with no data. If no reply is expected, then tpreturn() returns sending no reply.

flags - Currently, flags is reserved for future use and must be set to 0 (if set to a non-zero value, the recipient of the reply receives a TPESVCERR indication or a TPEV_SVCERR event).

Throws:

TuxATMITPException - If the a jvm-options is specified by -Dtuxedo.tjatmi.strictlyCheck=yes or -Dtuxedo.tjatmi.strictlyCheck=true, tpreturn may throw a TuxATMITPException when active outstanding replies are still existing. The error code is set to TPERTNOUTRPLY. When the exception with this error code is caught, the normal action is call tpcancel() to cancel existing outstanding replies. Java service routines, are expected to terminate using either tpreturn or tpforward. If a service routine returns without using either tpreturn (that is, it uses the Java language return statement or just simply "falls out of the function") , the server will return a service error to the service requester. Any outstanding asynchronous replies will be dropped. If the server was in transaction mode at the time of failure, the transaction is marked rollback-only.

Since tpreturn is the latst excecution statement in the service routine, any errors encountered either in handling arguments or in processing cannot be indicated to the function's caller. Such errors cause tperrno to be set to TPESVCERR for a program receiving the service's outcome via either tpcallor tpgetrply.

tpforward

void tpforward(java.lang.String svcname,
             weblogic.wtc.jatmi.TypedBuffer data,
             long flags)
               throws TuxATMITPException

tpforward method allows a service routine to forward a client's request to another service routine for further processing.

Parameters:

svcname - This method forwards a request to the service named by svcname.

data - points to the data object of a reply to be sent. If data is not null, it must point to a Typed buffer.

flags - Currently, flags is reserved for future use and must be set to 0.

Throws:

TuxATMITPException - Upon failure, tpforward() throws TuxATMITPException. TuxATMITPException.gettperrno() can be used to retreive real error condition as one of the following values:

• [TPEINVAL]: Invalid arguments were given. For example the svcname is null, or its length is greate than the allowable maximum service name limitation.
• [TPEFWDOUTRPLY]: Still existing outstanding replies when performs tpforward. When this error is encountered, usually, it needs to call tpcancel to cancel current active outstanding replies. Default, tpforward doesn't throw TuxATMITPException with this error code, it can be enabled by specifying the jvm-options with -Dtuxedo.tjatmi.strictlyCheck=yes or -Dtuxedo.tjatmi.strictlyCheck=true in configuration block.
• [TPEFWDNOENT]: The specific forwarding service is not advertised. Default, tpforward doesn't throw TuxATMITPException with this error code, it can be enabled by specifying the jvm-options with -Dtuxedo.tjatmi.strictlyCheck=yes or -Dtuxedo.tjatmi.strictlyCheck=true in configuration block.

tpadvertise

int tpadvertise(java.lang.String svcname,
              java.lang.String clsname,
              java.lang.String methodnm,
              long flags)
                throws TuxATMITPException

tpadvertise() allows a application to advertise the services that it offers.

Parameters:

svcname - The name of the Tuxedo service. It should be 127 characters or less.

clsname - The server class name implementing the service method specified with parameter methodnm. The class should be in the class path accessible to or associated with current server module.

methodnm - The method should be declared as public. The method has only one TPSVCINFO type of parameter and a void type of return value.

flags - It is currently reserved and must set to 0.

Throws:

TuxATMITPException - Upon successfully completion, tpadvertise() returns 0. Upon failure, tpadvertise() throws a TuxATMITPException. TuxATMITPException.gettperrno() can be used to get the error number. And TuxATMITPException.tpstrerror() can be used to get the error description. The possible error values are as following:

• TPEINVAL: Invalid argument parameter is passed. For example: The svcname is null or the length of svcname exceeds 127. The svcname is started with dot (.). The clsname is null or the methodnm is null. Cannot find the specific service method from the server class. A service method must be declared "void public tuxedoSvcMethod(TPSVCINFO rqst)" mode. It can be static and also can throw exceptions.
• TPELIMIT: No free space is available to register this command. (See MAXSERVICES in the RESOURCE section of UBBCONFIG(5)).
• TPESYSTEM: An Oracle Tuxedo system error has occurred. The exact nature of error is written to a log file.
• TPEOS: An operating system error has occurred.

tpunadvertise

int tpunadvertise(java.lang.String svcname,
                long flags)
                  throws TuxATMITPException

tpunadvertise() allows a application to unadvertise the services that it offers. svcname should be 127 characters or less.

Parameters:

svcname - The name of the Tuxedo service. It should be 127 characters or less.

flags - It is currently reserved and must set to 0.

Throws:

TuxATMITPException - Upon failure, tpunadvertise() throws a TuxATMITPException. TuxATMITPException.gettperrno() can be used to get the error number. And TuxATMITPException.tpstrerror() can be used to get the error description. The possible error values are as following:

• TPEINVAL: Invalid argument parameter is passed. For example: The svcname is null or the length of svcname exceeds 127.
• TPENOENT: svcname is not currently advertised by the application.
• TPEPROTO: tpadvertise() was called in a improper context. (for example, (1). try to unadvertise a service not associated to current server module, (2). try to unadvertised a service that is not a Java service, or (3). this service is not advertised by the Java server itself).
• TPESYSTEM: An Oracle Tuxedo system error has occurred. The exact nature of error is written to a log file.
• TPEOS: An operating system error has occurred.

tpsubscribe

long tpsubscribe(java.lang.String eventexpr,
               java.lang.String filter,
               TPEVCTL ctl,
               long flags)
                 throws TuxATMITPException

Subscribes an event or set of events named by eventexpr. The caller uses tpsubscribe to subscribe to an event or set of events named by eventexpr. Each subscription specifies a notification method which can take one of three forms: client notification, service calls, or message enqueuing to stable-storage message. Notification methods are determined by the subscriber's process type and the arguments passed to tpsubscribe.

Parameters:

eventexpr - The event or set of events being subscribed to is named by eventexpr. It is a string of at most 255 characters containing a regular expression.

filter - If present, filter is a string containing a Boolean filter rule that must be evaluated successfully before the EventBroker posts the event.

ctl - An event control object. (See TPQCTL).

flags - The following is a list of valid flags:

• TPNOBLOCK: The subscription is not made if a blocking condition exists. If such a condition occurs, the call fails and tperrno is set to TPEBLOCK. 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: This flag signifies that the caller is willing to block indefinitely and wants to be immune to blocking timeouts. Transaction timeouts may still occur.
• TPSIGRSTRT: If a signal interrupts any underlying system calls, then the interrupted system call is reissued. When TPSIGRSTRT is not specified and a signal interrupts a system call, then tpsubscribe() fails and tperrno is set to TPGOTSIG.

Returns:

Upon successful completion, tpsubscribe returns a handle that can be used to remove this subscription from the EventBroker's list of active subscriptions. The subscriber or any other process is allowed to use the returned handle to delete this subscription.

Throws:

TuxATMITPException - Upon failure, tpsubscribe() throws TuxATMITPException, and TuxATMITPException.gettperrno() can be used to get the error condition. Upon failure, tpsubscribe sets tperrno 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, eventexpr is NULL).
• [TPENOENT]: Cannot access the Oracle Tuxedo EventBroker.
• [TPELIMIT]: The subscription failed because the EventBroker's maximum number of subscriptions has been reached.
• [TPEMATCH]: The subscription failed because it matched one already listed with the EventBroker.
• [TPEPERM]: The client is not attached as tpsysadm and the subscription action is either a service call or the enqueuing of a message.
• [TPETIME]: This error code indicates that either a timeout has occurred or tpsubscribe has been attempted, in spite of the fact that the current transaction is already marked rollback only. If the caller is in transaction mode, then either the transaction is already rollback only or a transaction timeout has occurred. The transaction is marked abort-only. If the caller is not in transaction mode, a blocking timeout has occurred. (A blocking timeout cannot occur if TPNOBLOCK and/or TPNOTIME is specified.) If a transaction timeout has 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 (that is, tpacall() with TPNOTRAN, TPNOBLOCK, and TPNOREPLY set). When a transactional ATMI call fails inside a transaction, the transaction is put into the TX_ROLLBACK_ONLY state. This state is treated, for most purposes, as though it were equivalent to a timeout. All further ATMI calls for this transaction (with the exception of those issued in the circumstances described in the previous paragraph) will fail with TPETIME.
• [TPEBLOCK]: A blocking condition exists and TPNOBLOCK was specified.
• [TPGOTSIG]: A signal was received and TPSIGRSTRT was not specified.
• [TPEPROTO]: tpsubscribe() was called improperly.
• [TPESYSTEM]: An Oracle Tuxedo system error has occurred. The exact nature of the error is written to a log file.
• [TPEOS]: An operating system error has occurred.

tpunsubscribe

int tpunsubscribe(long subscription,
                long flags)
                  throws TuxATMITPException

tpunsubscribe can be used to remove an event subscription or a set of event subscriptions from the Oracle Tuxedo EventBroker's list of active subscriptions.

Parameters:

subscription - It is an event subscription handle returned by tpsubscribe().

flags - The following is a list of valid flags:

• TPNOBLOCK: The subscription is not removed if a blocking condition exists. If such a condition occurs, the call fails and tperrno is set to TPEBLOCK. 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: This flag signifies that the caller is willing to block indefinitely and wants to be immune to blocking timeouts. Transaction timeouts may still occur.
• TPSIGRSTRT: If a signal interrupts any underlying system calls, then the interrupted system call is reissued. When TPSIGRSTRT is not specified and a signal interrupts a system call, then tpunsubscribe() fails and tperrno is set to TPGOTSIG.

Returns:

Upon successful completion, the tpurcode, can be used to get the number of subscriptions deleted from the EventBroker's list of active subscriptions.

Throws:

TuxATMITPException - Upon failure, tpunsubscribe throws TuxATMITPException, and TuxATMITPException.gettperrno() can be used to get the error condition. Upon failure, tpunsubscribe sets tperrno 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, subscription is an invalid subscription handle).
• [TPENOENT]: Cannot access the Oracle Tuxedo EventBroker.
• [TPETIME]: This error code indicates that either a timeout has occurred or tpunsubscribe has been attempted, in spite of the fact that the current transaction is already marked rollback only. If the caller is in transaction mode, then either the transaction is already rollback only or a transaction timeout has occurred. The transaction is marked abort-only. If the caller is not in transaction mode, a blocking timeout has occurred. (A blocking timeout cannot occur if TPNOBLOCK and/or TPNOTIME is specified.) If a transaction timeout has 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 (that is, tpacall() with TPNOTRAN, TPNOBLOCK, and TPNOREPLY set). When a transactional ATMI call fails inside a transaction, the transaction is put into the TX_ROLLBACK_ONLY state. This state is treated, for most purposes, as though it were equivalent to a timeout. All further ATMI calls for this transaction (with the exception of those issued in the circumstances described in the previous paragraph) will fail with TPETIME.
• [TPEBLOCK]: A blocking condition exists and TPNOBLOCK was specified.
• [TPGOTSIG]: A signal was received and TPSIGRSTRT was not specified.
• [TPEPROTO]: tpunsubscribe() was called improperly.
• [TPESYSTEM]: An Oracle Tuxedo system error has occurred. The exact nature of the error is written to a log file.
• [TPEOS]: An operating system error has occurred.

tppost

int tppost(java.lang.String eventname,
         weblogic.wtc.jatmi.TypedBuffer data,
         long flags)
           throws TuxATMITPException

tppost method can be used to post an event and any accompanying data. The event is named by eventname and data, if not null, it is a typed buffer object. tppost can be invoked in a transaction context or outside of a transaction.

Parameters:

eventname - Eventname is a string composed of at most 31 characters. Eventname's first character cannot be a dot (".") as this character is reserved as the starting character for all events defined by the Oracle Tuxedo ATMI system itself.

data - Point a valid typed buffer object.

flags - The following is a list of valid flags:

• TPNOTRAN: If the caller is in transaction mode and this flag is set, then the event posting is not made on behalf of the caller's transaction. A caller in transaction mode that sets this flag is still subject to the transaction timeout (and no other) when posting events. If the event posting fails, the caller's transaction is not affected.
• TPNOREPLY: Informs tppost() not to wait for the EventBroker to process all subscriptions for eventname before returning. When TPNOREPLY is set, tpurcode() is set to zero regardless of whether tppost() returns successfully or not. When the caller is in transaction mode, this setting cannot be used unless TPNOTRAN is also set.
• TPNOBLOCK: The event is not posted if a blocking condition exists. If such a condition occurs, the call fails and tperrno is set to TPEBLOCK. 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: This flag signifies that the caller is willing to block indefinitely and wants to be immune to blocking timeouts. Transaction timeouts may still occur.
• TPSIGRSTRT: If a signal interrupts any underlying system calls, then the interrupted system call is reissued. When TPSIGRSTRT is not specified and a signal interrupts a system call, then tppost() fails and tperrno is set to TPGOTSIG.

Returns:

Upon successful completion, the tpurcode can be used to get the number of event notifications dispatched by the EventBroker on behalf of eventname.

Throws:

TuxATMITPException - Upon failure, tppost throws a TuxATMITPException, and TuxATMITPException.gettperrno() can be used to get the error condition. Upon failure, tppost sets tperrno 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, eventname is NULL).
• [TPENOENT]: Cannot access the Oracle Tuxedo User EventBroker.
• [TPETRAN]: The caller is in transaction mode, TPNOTRAN was not set and tppost contacted an EventBroker that does not support transaction propagation (that is, TMUSREVT(5) is not running in an Oracle Tuxedo ATMI system group that supports transactions).
• [TPETIME]: This error code indicates that either a timeout has occurred or tppost has been attempted, in spite of the fact that the current transaction is already marked rollback only. If the caller is in transaction mode, then either the transaction is already rollback only or a transaction timeout has occurred. The transaction is marked abort-only. If the caller is not in transaction mode, a blocking timeout has occurred. (A blocking timeout cannot occur if TPNOBLOCK and/or TPNOTIME is specified.) If a transaction timeout has 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 (that is, tpacall() with TPNOTRAN, TPNOBLOCK, and TPNOREPLY set). When tppost() fails inside a transaction, the transaction is put into the TX_ROLLBACK_ONLY state. This state is treated, for most purposes, as though it were equivalent to a timeout. All further ATMI calls for this transaction (with the exception of those issued in the circumstances described in the previous paragraph) will fail with TPETIME.
• [TPESVCFAIL]: The EventBroker encountered an error posting a transactional event to either a service routine or to a stable storage queue on behalf of the caller's transaction. The caller's current transaction is marked abort-only. When this error is returned, tpurcode() contains the number of non-transactional event notifications dispatched by the EventBroker on behalf of eventname; transactional postings are not counted since their effects will be aborted upon completion of the transaction. Note that so long as the transaction has not timed out, further communication may be performed before aborting the transaction and that any work performed on behalf of the caller's transaction will be aborted upon transaction completion (that is, for subsequent communication to have any lasting effect, it should be done with TPNOTRAN set).
• [TPEBLOCK]: A blocking condition exists and TPNOBLOCK was specified.
• [TPGOTSIG]: A signal was received and TPSIGRSTRT was not specified.
• [TPEPROTO]: tppost() was called improperly.
• [TPESYSTEM]: An Oracle Tuxedo system error has occurred. The exact nature of the error is written to a log file.
• [TPEOS]: An operating system error has occurred.

tpnotify

int tpnotify(CLIENTID cltid,
           weblogic.wtc.jatmi.TypedBuffer data,
           long flags)
             throws TuxATMITPException

tpnotify() method can be used by a client or server to send an unsolicited message to an individual client.

Parameters:

cltid - It is a CLIETNID object got from the TPSVCINFO request object of a previous or current service invocation.

data - A valid typed buffer object.

flags - The following is a list of valid flags:

• TPACK: The request is sent and the caller blocks until an acknowledgement message is received from the target client.
• TPNOBLOCK: The request is not sent if a blocking condition exists in sending the notification (for example, the internal buffers into which the message is transferred are full).
• TPNOTIME: This flag signifies that the caller is willing to block indefinitely and wants to be immune to blocking timeouts. Transaction timeouts may still occur.
• TPSIGRSTRT: If a signal interrupts any underlying system calls, then the interrupted system call is reissued. Unless the TPACK flag is set, tpnotify() does not wait for the message to be delivered to the client.

Returns:

Upon failure, tpnotify throws a TuxATMITPException.

Throws:

TuxATMITPException - Upon failure, tpnotify() throws TuxATMITPException, and TuxATMITPException.gettperrno() can be used to get the error condition; TuxATMITPException.gettperrordetail() can be used to get the detail error description.

• [TPEINVAL]: Invalid arguments were given (for example, invalid flags).
• [TPENOENT]: The target client does not exist or does not have an unsolicited handler set and the TPACK flag is set.
• [TPETIME]: A blocking timeout occurred and neither TPNOBLOCK nor TPNOTIME were specified, or TPACK was set but no acknowledgment was received and TPNOTIME was not specified. (A blocking timeout cannot occur if TPNOBLOCK and/or TPNOTIME is specified.)
• [TPEBLOCK]: A blocking condition was found on the call and TPNOBLOCK was specified.
• [TPGOTSIG]: A signal was received and TPSIGRSTRT was not specified.
• [TPEPROTO]: tpnotify() was called improperly.
• [TPESYSTEM]: An Oracle Tuxedo system error has occurred. The exact nature of the error is written to a log file.
• [TPEOS]: An operating system error has occurred.
• [TPERELEASE]: When the TPACK is set and the target is a client from a prior release of Oracle Tuxedo that does not support the acknowledgment protocol.

tpbroadcast

int tpbroadcast(java.lang.String lmid,
              java.lang.String usrname,
              java.lang.String cltname,
              weblogic.wtc.jatmi.TypedBuffer data,
              long flags)
                throws TuxATMITPException

tpbroadcast is used by a client or server to send an unsolicited message to registered clients within the system. tpbroadcast is used by a client or server to send an unsolicited message to registered clients within the system. The target client set consists of those clients matching identifiers passed to tpbroadcast().

Parameters:

lmid - logic identifier used to select the target logic machine.

usrname - logic identifier used to select the target user by name.

cltname - logic identifier used to select the target client by name.

data - It is a valid typed buffer object.

flags - The following is a list of valid flags:

• TPNOBLOCK: The request is not sent if a blocking condition exists (for example, the internal buffers into which the message is transferred are full).
• TPNOTIME: This flag signifies that the caller is willing to block indefinitely and wants to be immune to blocking timeouts. Transaction timeouts may still occur.
• TPSIGRSTRT: If a signal interrupts any underlying system calls, then the interrupted system call is reissued. Upon successful return from tpbroadcast(), the message has been delivered to the system for forwarding to the selected clients. tpbroadcast() does not wait for the message to be delivered to each selected client.

Returns:

Upon failure, tpbroadcast throws TuxATMITPException.

Throws:

TuxATMITPException - Upon failure, tpbroadcast throws TuxATMITPException, and TuxATMITPException.gettperrno() can be used to get the error condition.

• [TPEINVAL]: Invalid arguments were given (for example, identifiers too long or invalid flags). Note that use of an illegal LMID will cause tpbroadcast() to fail and return TPEINVAL. However, non-existent user or client names will simply successfully broadcast to no one.
• [TPETIME]: A blocking timeout occurred. (A blocking timeout cannot occur if TPNOBLOCK and/or TPNOTIME is specified.)
• [TPEBLOCK]: A blocking condition was found on the call and TPNOBLOCK was specified.
• [TPGOTSIG]: A signal was received and TPSIGRSTRT was not specified.
• [TPEPROTO]: tpbroadcast() was called improperly.
• [TPESYSTEM]: An Oracle Tuxedo system error has occurred. The exact nature of the error is written to a log file.
• [TPEOS]: An operating system error has occurred.

tpenqueue

int tpenqueue(java.lang.String qspace,
            java.lang.String qname,
            TPQCTL ctl,
            weblogic.wtc.jatmi.TypedBuffer data,
            long flags)
              throws TuxATMITPException

tpenqueue method can be used to store a message on the queue tpenqueue method can be used to store a message on the queue named by qname in qspace queue space.

Parameters:

qspace - and qname A queue space is a collection of queues, one of which must be qname.

ctl - It is a TPQCTL control object that is used by the application programs to pass and retrieve parameters associated with enqueuing the message.

data - It is a typed buffer object; if it is null, no data part is enqueued into the queue.

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 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 fails, tperrno is set to TPEDIAGNOSTIC, and the diagnostic field of the TPQCTL structure is set to QMESHARE. In the latter case, the other application, which is based on an Oracle product other than the Oracle Tuxedo ATMI 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 is set to TPETIME.
• TPSIGRSTRT: If this flag is set and a signal interrupts any underlying system calls, the interrupted system call is reissued. If TPSIGRSTRT is not set and a signal interrupts a system call, tpenqueue() fails and tperrno is set to TPGOTSIG.

Returns:

Upon failure, tpenqueue throws TuxATMITPException.

Throws:

TuxATMITPException - Upon failure, tpenqueue() throws TuxATMITPException exception, and TuxATMITPException.gettperrno() method can be used to get the error condition.

• [TPEINVAL]: Invalid arguments were given (for example flags is 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]: This error code indicates that either a timeout has occurred or tpenqueue has been attempted, in spite of the fact that the current transaction is already marked rollback only. If the caller is in transaction mode, then either the transaction is already rollback only or a transaction timeout has occurred. The transaction is marked abort-only. If the caller is not in transaction mode, a blocking timeout has occurred. (A blocking timeout cannot occur if TPNOBLOCK and/or TPNOTIME is specified.) If a transaction timeout has 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 (that is, tpacall() with TPNOTRAN, TPNOBLOCK, and TPNOREPLY set). When a service fails inside a transaction, the transaction is put into the TX_ROLLBACK_ONLY state. This state is treated, for most purposes, as though it were equivalent to a timeout. All further ATMI calls for this transaction (with the exception of those issued in the circumstances described in the previous paragraph) will fail with TPETIME.
• [TPEBLOCK]: A blocking condition exists and TPNOBLOCK was specified.
• [TPGOTSIG]: A signal was received and TPSIGRSTRT was not specified.
• [TPEPROTO]: tpenqueue() was called improperly.
• [TPESYSTEM]: An Oracle 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]: Enqueuing a message on the specified queue failed. The reason for failure can be determined by the diagnostic returned via ctl.

tpdequeue

TuxATMIReply tpdequeue(java.lang.String qspace,
                     java.lang.String qname,
                     TPQCTL ctl,
                     long flags)
                       throws TuxATMITPException

tpdequeue method can be used to take a message for processing from the queue tpdequeue method can be used to take a message for processing from the queue named by qname in the qspace queue space.

Parameters:

qspace - and A queue space is a collection of queues, one of which qname must be qname.

ctl - It is a TPQCTL control object.

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 tperrno 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 fails, tperrno is set to TPEDIAGNOSTIC, and the diagnostic field of the TPQCTL structure is set to QMESHARE. In the latter case, the other application, which is based on a Oracle product other than the Oracle Tuxedo ATMI 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 the TPQWAIT option in flags (of the TPQCTL control object) is specified.
• 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.
• TPSIGRSTRT: Setting this flag indicates that any underlying system calls that are interrupted by a signal should be reissued. When this flag is not set and a signal interrupts a system call, the call fails and sets tperrno to TPGOTSIG.

Returns:

Upon failure, tpdequeue throws TuxATMITPException.

Throws:

TuxATMITPException - Upon failure, tpdequeue() throws TuxATMITPException, and TuxATMITPException.gettperrno() can be used to get the error condition.

• [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).
• [TPETIME]: This error code indicates that either a timeout has occurred or tpdequeue has been attempted, in spite of the fact that the current transaction is already marked rollback only. If the caller is in transaction mode, then either the transaction is already rollback only or a transaction timeout has occurred. The transaction is marked abort-only. If the caller is not in transaction mode, a blocking timeout has occurred. (A blocking timeout cannot occur if TPNOBLOCK and/or TPNOTIME is specified.). If a transaction timeout has occurred, then, with one exception, any attempts to perform further conversational work, 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 (that is, tpacall with TPNOTRAN,TPNOBLOCK, and TPNOREPLY set). When a service fails inside a transaction, the transaction is put into the TX_ROLLBACK_ONLY state. This state is treated, for most purposes, as though it were equivalent to a timeout. All further ATMI calls for this transaction (with the exception of those issued in the circumstances described in the previous paragraph) will fail with TPETIME.
• [TPEBLOCK]: A blocking condition exists and TPNOBLOCK was specified.
• [TPGOTSIG]: A signal was received and TPSIGRSTRT was not specified.
• [TPEPROTO]: tpdequeue() was called improperly. There is no effect on the queue or the transaction.
• [TPESYSTEM]: An Oracle 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]: Dequeuing a message from the specified queue failed. The reason for failure can be determined by the diagnostic value returned via ctl structure. Diagnostic The following diagnostic values are returned during the dequeuing of a message:
• [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.
• [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.
• [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 an Oracle product other than the Oracle Tuxedo system that opened the queue for exclusive read and/or write using the Queuing Services API (QSAPI).

tpsblktime

int tpsblktime(int blktime,
             long flags)
               throws TuxATMITPException

tpsblktime method can be used to set the blocktime value. tpsblktime method can be used to set the blocktime value, in seconds or milliseconds, of a potential blocking application API method.

Parameters:

blktime -

flags - The following is a list of valid flags:

• TPBLK_MILLISECOND: This flag sets the blocktime value, in milliseconds. To set millisecond blocktime, second argument flags must contain TPBLK_MILLISECOND. Without that, the unit of the first argument is second. If the unit of SCANUNIT is second in TUXCONFIG, invoking tpsblktime with flag TPBLK_MILLISECOND will return an errorTPEINVAL.
• TPBLK_SECOND: This flag sets the blocktime value, in seconds. This is default behavior.
• TPBLK_NEXT: This flag sets the blocktime value for the next potential blocking API. Any API that is called containing the TPNOBLOCK flag is not effected by tpsblktime (TPBLK_NEXT) and continues to be non-blocking. A TPBLK_NEXT flag value overrides a TPBLK_ALL flag value for those API calls that immediately follow it.
• TPBLK_ALL: This flag sets the blocktime value for the all subsequent potential blocking APIs until the next tpsblktime() is called within that context. Any API that is called containing the TPNOBLOCK flag is not effected by tpsblktime(TPBLK_ALL) and continues to be non-blocking. tpsblktime(TPBLK_ALL) operates on a per-context basis. Therefore, it is necessary to call tpsblktime(TPBLK_ALL) in only one thread of context that is used in multiple threads.

Returns:

tpsblktime throws TuxATMITPException.

Throws:

TuxATMITPException - Upon failure, tpsblktime() throws TuxATMITPException, and TuxATMITPException.gettperrno() can be used to get real error condition. Upon failure, tpsblktime() sets tperrno to one of the following values:

• [TPEINVAL]: Invalid arguments were given.
• [TPERELEASE]: tpsblktime() was called in a client attached to a workstation handler running an earlier Tuxedo release.
• [TPESYSTEM]: An Oracle Tuxedo system error has occurred. The exact nature of the error is written to a log file.

tpgblktime

int tpgblktime(long flags)
               throws TuxATMITPException

tpgblktime retrieves a previously set blocktime value. tpgblktime tpgblktime retrieves a previously set blocktime value, per second or millisecond according to flag TPBLK_MILLISECOND.

Parameters:

flags - The following is a list of valid flags:

• TPBLK_MILLISECOND: This flag sets the return blocktime value in milliseconds. If the unit of SCANUNIT is millisecond in TUXCONFIG, invoking tpgblktime without flag TPBLK_MILLISECOND will return an error TPEINVAL.
• TPBLK_SECOND: This flag sets the return blocktime value in seconds. This is default behavior.
• TPBLK_NEXT: This flag returns blocktime value for the previously set tpsblktime(TPBLK_NEXT) call.
• TPBLK_ALL: This flag returns blocktime value for the previously set tpsblktime(TPBLK_ALL) call.

Returns:

Upon success, tpgblktime() returns a positive integer value indicating the blocking time value currently in effect for the corresponding flag value.

Throws:

TuxATMITPException - - Upon failure, tpgblktime() throws a TuxATMITPException exception, and TuxATMITPException.gettperrno() can be used to get real error condition.

• [TPEINVAL]: Invalid arguments were given. For example, the flags value is negative or more than one blocktime flag value (TPBLK_NEXT, TPBLK_ALL, TPBLK_NEXT | TPBLK_MILLISECOND, TPBLK_NEXT | TPBLK_SECOND, TPBLK_ALL | TPBLK_MILLISECOND, TPBLK_ALL | TPBLK_SECOND, or 0) was specified.
• [TPESYSTEM]: An Oracle Tuxedo system error has occurred. The exact nature of the error is written to a log file.

tpsprio

int tpsprio(int prio,
          long flags)
            throws TuxATMITPException

tpsprio sets the priority for the next request sent or forwarded by the current thread. tpsprio tpsprio 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(), if the queued message facility is installed. 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.

Parameters:

prio - The priority value.

flags - The following is a list of valid flags:

• TPABSOLUTE: 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.

Returns:

Upon failure, tpsprio throws TuxATMITPException.

Throws:

TuxATMITPException - Upon failure, and TuxATMITPException.gettperrno() can be used to get real error condition

• [TPEINVAL]: flags are invalid.
• [TPEPROTO]: tpsprio() was called improperly.
• [TPESYSTEM] An Oracle Tuxedo system error has occurred. The exact nature of the error is written to a log file.
• [TPEOS]: An operating system error has occurred.

tpgprio

int tpgprio()
            throws TuxATMITPException

tpgprio() returns the priority for the last request sent or received by the current thread in its current context. tpgprio tpgprio() returns the priority for the last request sent or received by the current thread in its current context. Priorities can range from 1 to 100, inclusive, with 100 being the highest priority. tpgprio may be called after tpcall or tpacall, (also tpenqueue(), or tpdequeue(), assuming the queued management facility is installed), and the priority returned is for the request sent. Also, tpgprio() may be called within a service routine to find out at what priority the invoked service was sent. tpgprio() may be called any number of times and will return the same value until the next request is sent.

Returns:

Upon success, tpgprio() returns a request's priority; Upon failure, tpgprio() throws TuxTATMITPException and sets tperrno to indicate the error condition.

Throws:

TuxATMITPException - Upon failure, and TuxATMITPException.gettperrno() can be used to get real error condition

• [TPENOENT]: tpgprio() was called and no requests (via tpcall() or tpacall()) have been sent, or it is called within a conversational service for which no requests have been sent.
• [TPEPROTO]: tpgprio() was called improperly.
• [TPESYSTEM]: An Oracle Tuxedo system error has occurred. The exact nature of the error is written to a log file.
• [TPEOS]: An operating system error has occurred.

tpxmltofml

weblogic.wtc.jatmi.TypedFML tpxmltofml(weblogic.wtc.jatmi.TypedXML xmldata,
                                     java.lang.String xfile,
                                     java.lang.String rtag,
                                     long flags)
                                       throws TuxATMITPException

tpxmltofml method can be used to convert a TypedXML object to TypedFML object. tpxmltofml tpxmltofml method can be used to convert a TypedXML object to TypedFML object.

Parameters:

xmldata - It is a TypedXML object.

xfile - It is the fully qualified path name of an XML schema file used to validate XML input.

rtag - It is current unused.

flags - They are bit values used in the method to map to the XML parser classes. The following is a list of valid XML parser flags:

• TPXPARSNEVER: Sets setValidationScheme to Val_Never. The parser will not report Schema validation errors.
• TPXPARSALWAYS: Sets setValidationScheme to Val_Always. The parser will always report Schema validation errors. Note that TPXPARSNEVER takes precedent over TPXPARSALWAYS if both arguments are used at the same time.
• TPXPARSSCHFULL: Sets setValidationSchemaFullChecking to true. This flag allows the user to turn full Schema constraint checking on/off. Only takes effect if Schema validation is enabled. If turned off, partial constraint checking is done. Full schema constraint checking includes those checking that may be time-consuming or memory intensive. Currently, particle unique attribution constraint checking and particle derivation restriction checking are controlled by this option.
• TPXPARSCONFATAL: Sets setValidationConstraintFatal to true. This flag allows users to set the parser's behavior when it encounters a validation constraint error. If set to true, and the parser will treat validation error as fatal and will exit depends on the state of getExitOnFirstFatalError. If false, then it will report the error and continue processing.
• TPXPARSNSPACE: Sets setDoNamespaces to true. This flag allows users to enable or disable the parser's namespace processing. When set to true, parser starts enforcing all the constraints and rules specified by the NameSpace specification.
• TPXPARSDOSCH: Sets setDoSchema to true. This flag allows users to enable or disable the parser's schema processing. When set to false, parser will not process any schema found. Note that, if set to true, namespace processing must also be turned on.
• TPXPARSEREFN: Sets setCreateEntityReferencNodes to false. This flag allows the user to specify whether the parser should create entity reference nodes in the DOM tree being produced. When the create flag is true, the parser will create EntityReference nodes in the DOM tree. The EntityReference nodes and their child nodes will be read-only. When the create flag is false, no EntityReference nodes will be created. The replacement text of the entity is included in either case, either as a child of the Entity Reference node or in place at the location of the reference.
• TPXPARSNOEXIT: Sets setExitOnFirstFatalError to false. This flag allows users to set the parser's behavior when it encounters the first fatal error. If set to true, the parser will exit at the first fatal error. If false, then it will report the error and continue processing.
• TPXPARSNOINCWS: Sets setIncludeIgnorableWhitespace to false. This flag allows the user to specify whether a validating parser should include ignorable whitespaces as text nodes. It has no effect on non-validating parsers which always include non-markup text. When set to false, all ignorable whitespace will be discarded and no text node is added to the DOM tree.
• TPXPARSCACHESET: Sets setcacheGrammarFromParse to true. This flag allows users to enable or disable caching of grammar when parsing XML documents. When set to true, the parser will cache the resulting grammar for use in subsequent parses. If the flag is set to true, the Use cached grammar flag will also be set to true.
• TPXPARSCACHERESET: Resets resetCachedGrammarPool. Resets the documents vector pool and release all the associated memory back to the system. When parsing a document using a DOM parser, all memory allocated for a DOM tree is associated to the DOM document. If you do multiple parse using the same DOM parser instance, then multiple DOM documents will be generated and saved in a vector pool. All these documents (and thus all the allocated memory) won't be deleted until the parser instance is destroyed. If you do not need these DOM documents anymore and do not want to destroy the DOM parser instance at this moment, then you can call this method to reset the document vector pool and release all the allocated memory back to the system. It is an error to call this method if you are in the middle of a parse (for example, a mid progressive parse).

Returns:

Upon successful completion, tpxmltofml() returns TypedFML object converted from inputted TypedXML object.

Throws:

TuxATMITPException - Upon failure, tpxmltofml() throws a TuxATMITPException exception, and TuxATMITPException.gettperrno() can be used to get the real error condition. The function may fail for the following reasons.

• [TPEINVAL]: Either xmldata is not a valid typed buffer, or parser has problems understanding the input.
• [TPESYSTEM]: A Tuxedo system error has occurred. The exact nature of the error is written to userlog. This will also indicate when a conversion to FML was unable to be done. In that instance error detail info will be added to the userlog.
• [TPEOS]: An operating system error has occurred. A numeric value representing the system call that failed is available in Uunixerr.

tpxmltofml32

weblogic.wtc.jatmi.TypedFML32 tpxmltofml32(weblogic.wtc.jatmi.TypedXML xmldata,
                                         java.lang.String xfile,
                                         java.lang.String rtag,
                                         long flags)
                                           throws TuxATMITPException

tpxmltofml method can be used to convert a TypedXML object to TypedFML32 object. tpxmltofml32 tpxmltofml32 method can be used to convert a TypedXML object to TypedFML32 object.

Parameters:

xmldata - It is a TypedXML object.

xfile - It is the fully qualified path name of an XML schema file used to validate XML input.

rtag - It is current unused.

flags - They are bit values used in the method to map to the XML parser classes. The following is a list of valid XML parser flags:

• TPXPARSNEVER: Sets setValidationScheme to Val_Never. The parser will not report Schema validation errors.
• TPXPARSALWAYS: Sets setValidationScheme to Val_Always. The parser will always report Schema validation errors. Note that TPXPARSNEVER takes precedent over TPXPARSALWAYS if both arguments are used at the same time.
• TPXPARSSCHFULL: Sets setValidationSchemaFullChecking to true. This flag allows the user to turn full Schema constraint checking on/off. Only takes effect if Schema validation is enabled. If turned off, partial constraint checking is done. Full schema constraint checking includes those checking that may be time-consuming or memory intensive. Currently, particle unique attribution constraint checking and particle derivation restriction checking are controlled by this option.
• TPXPARSCONFATAL: Sets setValidationConstraintFatal to true. This flag allows users to set the parser's behavior when it encounters a validation constraint error. If set to true, and the parser will treat validation error as fatal and will exit depends on the state of getExitOnFirstFatalError. If false, then it will report the error and continue processing.
• TPXPARSNSPACE: Sets setDoNamespaces to true. This flag allows users to enable or disable the parser's namespace processing. When set to true, parser starts enforcing all the constraints and rules specified by the NameSpace specification.
• TPXPARSDOSCH: Sets setDoSchema to true. This flag allows users to enable or disable the parser's schema processing. When set to false, parser will not process any schema found. Note that, if set to true, namespace processing must also be turned on.
• TPXPARSEREFN: Sets setCreateEntityReferencNodes to false. This flag allows the user to specify whether the parser should create entity reference nodes in the DOM tree being produced. When the create flag is true, the parser will create EntityReference nodes in the DOM tree. The EntityReference nodes and their child nodes will be read-only. When the create flag is false, no EntityReference nodes will be created. The replacement text of the entity is included in either case, either as a child of the Entity Reference node or in place at the location of the reference.
• TPXPARSNOEXIT: Sets setExitOnFirstFatalError to false. This flag allows users to set the parser's behavior when it encounters the first fatal error. If set to true, the parser will exit at the first fatal error. If false, then it will report the error and continue processing.
• TPXPARSNOINCWS: Sets setIncludeIgnorableWhitespace to false. This flag allows the user to specify whether a validating parser should include ignorable whitespaces as text nodes. It has no effect on non-validating parsers which always include non-markup text. When set to false, all ignorable whitespace will be discarded and no text node is added to the DOM tree.
• TPXPARSCACHESET: Sets setcacheGrammarFromParse to true. This flag allows users to enable or disable caching of grammar when parsing XML documents. When set to true, the parser will cache the resulting grammar for use in subsequent parses. If the flag is set to true, the Use cached grammar flag will also be set to true.
• TPXPARSCACHERESET: Resets resetCachedGrammarPool. Resets the documents vector pool and release all the associated memory back to the system. When parsing a document using a DOM parser, all memory allocated for a DOM tree is associated to the DOM document. If you do multiple parse using the same DOM parser instance, then multiple DOM documents will be generated and saved in a vector pool. All these documents (and thus all the allocated memory) won't be deleted until the parser instance is destroyed. If you do not need these DOM documents anymore and do not want to destroy the DOM parser instance at this moment, then you can call this method to reset the document vector pool and release all the allocated memory back to the system. It is an error to call this method if you are in the middle of a parse (for example, a mid progressive parse).

Returns:

Upon successful completion, tpxmltofml returns TypedFML32 object converted from inputted TypedXML object.

Throws:

TuxATMITPException - Upon failure, tpxmltofml32 throws a TuxATMITPException exception, and TuxATMITPException.gettperrno() can be used to get the real error condition. The function may fail for the following reasons.

• [TPEINVAL]: Either xmldata is not a valid typed buffer, or parser has problems understanding the input.
• [TPESYSTEM]: A Tuxedo system error has occurred. The exact nature of the error is written to userlog. This will also indicate when a conversion to FML was unable to be done. In that instance error detail info will be added to the userlog.
• [TPEOS]: An operating system error has occurred. A numeric value representing the system call that failed is available in Uunixerr.

tpfml32toxml

weblogic.wtc.jatmi.TypedXML tpfml32toxml(weblogic.wtc.jatmi.TypedFML32 fmldata,
                                       java.lang.String xfile,
                                       java.lang.String rtag,
                                       long flags)
                                         throws TuxATMITPException

tpfml32toxml is used to convert a TypedFML32 object to a TypedXML object. tpfml32toxml tpfml32toxml is used to convert a TypedFML32 object to a TypedXML object.

Parameters:

fmldata - It is a valid TypedFML32 typed buffer object.

xfile - It is currently unused and reserved.

rtag - If present, it is the root element name of converted xml data.

flags - It is currently reserved for future use.

Returns:

Upon successful completion, tpfml32toxml method returns a TypedXML object converted from a TypedFML32 object.

Throws:

TuxATMITPException - Upon failure, tpfml32toxml throws a TuxATMITPException exception, and TuxATMITPException.gettperrno() can be used to get the real error condition.

• [TPEINVAL]: Either fmldata is not a valid typed buffer.
• [TPESYSTEM]: A Tuxedo system error has occurred. The exact nature of the error is written to userlog. This will also indicate when a conversion to XML was unable to be done. In that instance error detail info will be added to the userlog.
• [TPEOS]: An operating system error has occurred. A numeric value representing the system call that failed is available in Uunixerr.

tpfmltoxml

weblogic.wtc.jatmi.TypedXML tpfmltoxml(weblogic.wtc.jatmi.TypedFML fmldata,
                                     java.lang.String xfile,
                                     java.lang.String rtag,
                                     long flags)
                                       throws TuxATMITPException

tpfmltoxml is used to convert a TypedFML object to a TypedXML object. tpfmltoxml tpfmltoxml is used to convert a TypedFML object to a TypedXML object.

Parameters:

fmldata - It is a valid TypedFML typed buffer object.

xfile - It is currently unused and reserved.

rtag - If present, it is the root element name of converted xml data.

flags - It is currently reserved for future use.

Returns:

Upon successful completion, tpfmltoxml method returns a TypedXML object converted from a TypedFML object.

Throws:

TuxATMITPException - Upon failure, tpfmltoxml throws a TuxATMITPException exception, and TuxATMITPException.gettperrno() can be used to get the real error condition.

• [TPEINVAL]: Either fmldata is not a valid typed buffer.
• [TPESYSTEM]: A Tuxedo system error has occurred. The exact nature of the error is written to userlog. This will also indicate when a conversion to XML was unable to be done. In that instance error detail info will be added to the userlog.
• [TPEOS]: An operating system error has occurred. A numeric value representing the system call that failed is available in Uunixerr.

tpbegin

int tpbegin(long trntime,
          long flags)
            throws TuxATMITPException

tpbegin() signifies the beginning of a transaction. A transaction in the Oracle Tuxedo ATMI system is used to define a single logical unit of work that either wholly succeeds or has no effect whatsoever. A transaction allows work being performed in many processes, at possibly different sites, to be treated as an atomic unit of work.The initiator of a transaction uses tpbegin() and either tpcommit() or tpabort() to delineate the operations within a transaction. Once tpbegin() is called, communication with any other program can place the latter (of necessity, a server) in "transaction mode" (that is, the server's work becomes part of the transaction). Programs that join a transaction are called participants. A transaction always has one initiator and can have several participants. Only the initiator of a transaction can call tpcommit() or tpabort(). Participants can influence the outcome of a transaction by the return values (rvals) they use when they call tpreturn(). Once in transaction mode, any service requests made to servers are processed on behalf of the transaction (unless the requester explicitly specifies otherwise).

Parameters:

trntime - Specifies that the transaction should be allowed at least timeout seconds before timing out. Once a transaction times out it must be marked abort-only. If timeout is 0, then the transaction is given the maximum number of seconds allowed by the system before timing out (that is, the timeout value equals the maximum value for an unsigned long as defined

flags - It is reserved for future use and must be set to 0.

Returns:

Upon failure, tpbegin() returns -1.

Throws:

TuxATMITPException - Upon failure tpbegin sets tperrno in TuxATMITPException to one of the following values.

• TPEINVAL: flags is not equal to 0.
• TPETRAN: The caller cannot be placed in transaction mode because an error occurred starting the transaction.
• TPEPROTO: tpbegin() was called in an improper context (for example, the caller is already in transaction mode).
• TPESYSTEM: An Oracle Tuxedo system error has occurred. The exact nature of the error is written to a log file.
• TPEOS: An operating system error has occurred.

Notices

When using tpbegin(), andtpcommit(), and tpabort(), to delineate an Oracle Tuxedo ATMI system transaction, it is important to remember that only the work done by a resource manager that meets the XA interface (and is linked to the caller appropriately) has transactional properties. All other operations performed in a transaction are not affected by either tpcommit() or tpabort().

tpcommit

int tpcommit(long flags)
             throws TuxATMITPException

tpcommit() signifies the end of a transaction, using a two-phase commit protocol to coordinate participants. tpcommit() can be called only by the initiator of a transaction. If any of the participants cannot commit the transaction (for example, they call tpreturn() with TPFAIL), then the entire transaction is aborted and tpcommit() fails. That is, all of the work involved in the transaction is undone. If all participants agree to commit their portion of the transaction, then this decision is logged to stable storage and all participants are asked to commit their work.

Depending on the setting of the TP_COMMIT_CONTROL characteristic, tpcommit() can return successfully either after the commit decision has been logged or after the two-phase commit protocol has completed. If tpcommit() returns after the commit decision has been logged but before the second phase has completed (TP_CMT_LOGGED), then all participants have agreed to commit the work they did on behalf of the transaction and should fulfill their promise to commit the transaction during the second phase. However, because tpcommit() is returning before the second phase has completed, there is a hazard that one or more of the participants can heuristically complete their portion of the transaction (in a manner that is not consistent with the commit decision) even though the function has returned success. If the TP_COMMIT_CONTROL characteristic is set such that tpcommit() returns after the two-phase commit protocol has completed (TP_CMT_COMPLETE), then its return value reflects the exact status of the transaction (that is, whether the transaction heuristically completed or not). Currently TP_COMMIT_CONTROL is set to the default value TP_CMT_LOGGED. So tpcommit() returns after the commit decision has been logged but before the second phase has completed (TP_CMT_LOGGED).

Note that if only a single resource manager is involved in a transaction, then a one-phase commit is performed (that is, the resource manager is not asked whether or not it can commit; it is simply told to commit). In this case, the TP_COMMIT_CONTROL characteristic has no bearing and tpcommit() will return heuristic outcomes if present.

If tpcommit() is called while call descriptors exist for outstanding replies, then upon return from the function, the transaction is aborted and those descriptors associated with the caller's transaction are no longer valid. Call descriptors not associated with the caller's transaction remain valid.

Parameters:

flags - It reserved for future use and must be set to 0.

Returns:

Upon failure, tpcommit() returns -1.

Throws:

TuxATMITPException - Upon failure tpcommit sets tperrno in TuxATMITPException to one of the following values.

• TPEABORT: The transaction could not commit because either the work performed by the initiator or by one or more of its participants could not commit. This error is also returned if tpcommit() is called with outstanding replies or open conversational connections.
• TPEHAZARD: Due to some failure, the work done on behalf of the transaction could have been heuristically completed.
• TPEHEURISTIC: Due to a heuristic decision, the work done on behalf of the transaction was partially committed and partially aborted.
• TPEINVAL: flags is not equal to 0. The caller's transaction is not affected.
• TPEOS: An operating system error has occurred.
• TPEPROTO: tpcommit() was called in an improper context (for example, by a participant).
• TPESYSTEM: An Oracle Tuxedo system error has occurred. The exact nature of the error is written to a log file.
• TPETIME: The transaction has timed out and its status is unknown: it may have been either committed or aborted. If a transaction has timed out and its status is known to be aborted, then TPEABORT is returned.

Notices

When using tpbegin(), tpcommit(), and tpabort(), to delineate an Oracle Tuxedo ATMI system transaction, it is important to remember that only the work done by a resource manager that meets the XA interface (and is linked to the caller appropriately) has transactional properties. All other operations performed in a transaction are not affected by either tpcommit() or tpabort().

tpabort

int tpabort(long flags)
            throws TuxATMITPException

tpabort() signifies the abnormal end of a transaction. When this call returns, all changes made to resources during the transaction are undone. Like tpcommit(), this function can be called only by the initiator of a transaction. Participants (that is, service routines) can express their desire to have a transaction aborted by calling tpreturn() with TPFAIL.

If tpabort() is called while call descriptors exist for outstanding replies, then upon return from the function, the transaction is aborted and those descriptors associated with the caller's transaction are no longer valid. Call descriptors not associated with the caller's transaction remain valid.

Parameters:

flags - It is reserved for future use and should be set to 0.

Returns:

Upon failure, tpabort() returns -1.

Throws:

TuxATMITPException - Upon failure tpabort sets tperrno in TuxATMITPException to one of the following values.

• TPEINVAL: flags is not equal to 0. The caller's transaction is not affected.
• TPEHEURISTIC: Due to a heuristic decision, the work done on behalf of the transaction was partially committed and partially aborted.
• TPEHAZARD: Due to some failure, the work done on behalf of the transaction could have been heuristically completed.
• TPEPROTO: tpabort() was called improperly (for example, by a participant).
• TPESYSTEM: An Oracle Tuxedo system error has occurred. The exact nature of the error is written to a log file.
• TPEOS: An operating system error has occurred.

Notices

When using tpbegin(), tpcommit(), and tpabort(), to delineate an Oracle Tuxedo ATMI system transaction, it is important to remember that only the work done by a resource manager that meets the XA interface (and is linked to the caller appropriately) has transactional properties. All other operations performed in a transaction are not affected by either tpcommit() or tpabort().

tpsuspend

TPTRANID tpsuspend(long flags)
                   throws TuxATMITPException

tpsuspend() is used to suspend the transaction active in the caller's process. tpsuspend tpsuspend() is used to suspend the transaction active in the caller's process. To ensure success, the caller must have completed all outstanding transactional communication with servers before issuing tpsuspend. That is, the caller must have received all replies for requests sent with tpacall that were associated with the caller's transaction. Also, the caller must have closed all connections with conversational services associated with the caller's transaction (that is, tprecv() must have returned the TPEV_SVCSUCC event). If either rule is not followed, then tpsuspend() fails, the caller's current transaction is not suspended and all transactional communication descriptors remain valid. Communication descriptors not associated with the caller's transaction remain valid regardless of the outcome of tpsuspend.

Parameters:

flags - It is reserved for future use and must be set to 0.

Returns:

Upon successful completion, tpsuspend() returns a TPTRANID object.

Throws:

TuxATMITPException - Upon failure, tpsuspend() throws a TuxATMITPException exception.

• [TPEINVAL]: tranid is a NULL pointer or flags is not 0. The caller's state with respect to the transaction is not changed.
• [TPEABORT]: The caller's active transaction has been aborted. All communication descriptors associated with the transaction are no longer valid.
• [TPEPROTO]: tpsuspend() was called in an improper context (for example, the caller is not in transaction mode). The caller's state with respect to the transaction is not changed.
• [TPESYSTEM]: An Oracle Tuxedo system error has occurred. The exact nature of the error is written to a log file.
• [TPEOS]: An operating system error has occurred.

tpresume

int tpresume(TPTRANID trnId,
           long flags)
             throws TuxATMITPException

tpresume is used to resume work on behalf of a previously suspended transaction. tpresume() tpresume is used to resume work on behalf of a previously suspended transaction.

Parameters:

trnId - It is a valid TPTRANID object returned by previously invoking tpsuspend() method.

flags - It is reserved for future use and must be set to 0.

Returns:

tpresume() throws TuxATMITPException.

Throws:

TuxATMITPException - Upon failure, tpresume() throws a TuxATMITPException exception. TuxATMITPException.gettperrno() can be used to get real error condition. Under the following conditions, tpresume() fails and sets tperrno to:

• [TPEINVAL]: Either tranid is a NULL pointer, it points to a non-existent transaction identifier (including previously completed or timed-out transactions), or it points to a transaction identifier that the caller is not allowed to resume. The caller's state with respect to the transaction is not changed.
• [TPEMATCH]: tranid points to a transaction identifier that another process has already resumed. The caller's state with respect to the transaction is not changed.
• [TPETRAN]: The Oracle Tuxedo system is unable to resume the global transaction because the caller is currently participating in work outside any global transaction with one or more resource managers. All such work must be completed before a global transaction can be resumed. The caller's state with respect to the local transaction is unchanged.
• [TPEPROTO]: tpresume() was called in an improper context (for example, the caller is already in transaction mode). The caller's state with respect to the transaction is not changed.
• [TPESYSTEM]: An Oracle Tuxedo system error has occurred. The exact nature of the error is written to a log file.
• [TPEOS]: An operating system error has occurred.

tpgetlev

int tpgetlev()
             throws TuxATMITPException

tpgetlev() returns the current transaction level to the caller. Currently, the only levels defined are 0 and 1.

Returns:

Upon successful completion, tpgetlev() returns either a 0 to indicate that no transaction is in progress, or 1 to indicate that a transaction is in progress; Upon failure, tpgetlev() returns -1

Throws:

TuxATMITPException - Upon failure tpgetlev sets tperrno in TuxATMITPException to one of the following values.

• TPEPROTO: tpgetlev() was called improperly.
• TPESYSTEM: An Oracle Tuxedo system error has occurred. The exact nature of the error is written to a log file.
• TPEOS: An operating system error has occurred.

Notices

When using tpbegin(), tpcommit(), and tpabort(), to delineate an Oracle Tuxedo ATMI system transaction, it is important to remember that only the work done by a resource manager that meets the XA interface (and is linked to the caller appropriately) has transactional properties. All other operations performed in a transaction are not affected by either tpcommit() or tpabort().

tpscmt

int tpscmt(long flags)
           throws TuxATMITPException

tpscmt method sets the TP_COMMIT_CONTROL characteristic to the value specified in flags. tpscmt tpscmt method sets the TP_COMMIT_CONTROL characteristic to the value specified in flags.

Parameters:

flags - The following is a list of valid flags:

• TP_CMT_LOGGED: This flag indicates that tpcommit() should return after the commit decision has been logged by the first phase of the two-phase commit protocol but before the second phase has completed. This setting allows for faster response to the caller of tpcommit() although there is a risk that a transaction participant might decide to heuristically complete (that is, abort) its work due to timing delays waiting for the second phase to complete. If this occurs, there is no way to indicate this situation to the caller since tpcommit() has already returned (although the Oracle Tuxedo ATMI system writes a message to a log file when a resource manager takes a heuristic decision). Under normal conditions, participants that promise to commit during the first phase will do so during the second phase. Typically, problems caused by network or site failures are the sources for heuristic decisions being made during the second phase.
• TP_CMT_COMPLETE: This flag indicates that tpcommit(3c) should return after the two-phase commit protocol has finished completely. This setting allows for tpcommit() to return an indication that a heuristic decision occurred during the second phase of commit.

Returns:

Upon success, tpscmt() returns the previous value of TP_COMMIT_CONTROL characteristic.

Throws:

TuxATMITPException - Upon failure, tpscmt() throws a TuxATMITPException exception. Upon failure, tpscmt() sets tperrno to one of the following values, TuxATMITPException.gettperno() can be used to retrieve the real error condition:

• [TPEINVAL]: flags is not one of TP_CMT_LOGGED or TP_CMT_COMPLETE.
• [TPEPROTO]: tpscmt() was called improperly.
• [TPESYSTEM]: An Oracle Tuxedo system error has occurred. The exact nature of the error is written to a log file.
• [TPEOS]: An operating system error has occurred.