Corporate Info  |  News  |  Solutions  |  Products  |  Partners  |  Services  |  Events  |  Download  |  How To Buy
	http://www.oracle.com/technology/documentation/index.html   |   Search   |   PDF Files   |   Contact   |   Glossary
eLink Adapter Development Kit Doc Home   |   Previous Topic   |   Next Topic   |   Contents   |

The information included in this section is excerpted from the Tuxedo Online Documentation. These are some of the most commonly used Tuxedo ATMI functions used for adapter development. For additional details and a complete list of Tuxedo functions and commands, see http://edocs.beasys.com/tuxedo/tux65/index.htm.

Following is an alphabetical list of the the functions described in this section.

Refer to
tpacall
tpadvertise
tpalloc
tpcall
tpcancel
tpfree
tpgetrply
tpinit
tprealloc
tpreturn
tpsvrdone
tpsvrinit
tpterm
tptypes
tpunadvertise

Routine for joining an application

#include <atmi.h>
int tpinit(TPINIT *tpinfo) 

tpinit() allows a client to join a BEA Tuxedo system application. Before a client can use any of the BEA Tuxedo system communication or transaction routines, it must first join a BEA Tuxedo system application. Because calling tpinit() is optional, a client may also join an application by calling many ATMI routines (for example, tpcall) that transparently call tpinit() with tpinfo set to NULL. A client may want to call tpinit() directly so that it can set the parameters described below. In addition, tpinit() must be used when application authentication is required (see the description of the SECURITY keyword in ubbconfig), or when the application wishes to supply its own buffer type switch (see typesw). After tpinit() successfully returns, the client can initiate service requests and define transactions. If tpinit() is called more than once (that is, after the client has already joined the application), no action is taken and success is returned.

tpinit()'s argument, tpinfo, is a pointer to a typed buffer of type TPINIT and a NULL sub-type.

TPINIT is a buffer type that is typedefed in the atmi.h header file. The buffer must be allocated via tpalloc() prior to calling tpinit. The buffer should be freed using tpfree(3) after calling tpinit(). The TPINIT typed buffer structure includes the following members:

char      usrname[MAXTIDENT+2]; 
char      cltname[MAXTIDENT+2];
char      passwd[MAXTIDENT+2];
char      grpname[MAXTIDENT+2];
long      flags;
long      datalen;
long      data;

usrname, cltname, grpname and passwd are all NULL-terminated strings. usrname is a name representing the caller. cltname is a client name whose semantics are application defined. The value, sysclient, is reserved by the system for the cltname field. The usrname and cltname fields are associated with the client at tpinit() time and are used for both broadcast notification and administrative statistics retrieval. They should not have more characters than MAXTIDENT, which is defined as 30. passwd is an application password in unencrypted format that is used for validation against the application password. The passwd is limited to 30 characters. grpname is used to associate the client with a resource manager group name. If grpname is set to a 0-length string, then the client is not associated with a resource manager and is in the default client group. The value of grpname must be the null string (0-length string) for /WS clients. Note that grpname is not related to ACL GROUPS. The setting of flags is used to indicate both the client-specific notification mechanism and the mode of system access. These settings may override the application default; however, in the event that they cannot, tpinit() prints a warning in a log file, ignores the setting and returns the application default setting in the flags element upon return from tpinit(). For client notification, the possible values for flags are as follows:

TPU_SIG-Select unsolicited notification by signals.

TPU_DIP-Select unsolicited notification by dip-in.

TPU_IGN-ignore unsolicited notification.

Only one of the above flags can be used at a time. If the client does not select a notification method via the flags field, then the application default method will be set in the flags field upon return from tpinit(). For setting the mode of system access, the possible values for flags are as follows:

TPSA_FASTPATH-Set system access to fastpath.

TPSA_PROTECTED-Set system access to protected.

Only one of the above flags can be used at a time. If the client does not select a notification method or a system access mode via the flags field, then the application default method(s) will be set in the flags field upon return from tpinit(). See ubbconfig for details on both client notification methods and system access modes. datalen is the length of the application specific data that follows. The buffer type switch entry for the TPINIT typed buffer sets this field based on the total size passed in for the typed buffer (the application data size is the total size less the size of the TPINIT structure itself plus the size of the data placeholder as defined in the structure). data is a place holder for variable length data that is forwarded to an application-defined authentication service. It is always the last element of this structure. A macro, TPINITNEED, is available to determine the size TPINIT buffer necessary to accommodate a particular desired application-specific data length. For example, if 8 bytes of application specific data are desired, TPINITNEED will return the required TPINIT buffer size. A NULL value for tpinfo is allowed for applications not making use of the authentication feature of the BEA Tuxedo system. Clients using a NULL argument will get defaults of 0-length strings for usrname, cltname, and passwd, no flags set, and no application data.

tpinit() returns -1 on error and sets tperrno to indicate the error condition.

Under the following conditions, tpinit() fails and sets tperrno to:

[TPEINVAL]

Invalid arguments were specified. tpinfo is non-NULL and does not point to a typed buffer of type TPINIT.

[TPENOENT]

The client cannot join the application because of space limitations.

[TPEPERM]

The client cannot join the application because it does not have permission to do so or because it has not supplied the correct application password. Permission may be denied based on an invalid application password, failure to pass application specific authentication, or use of restricted names.

[TPEPROTO]

tpinit() was called in an improper context (for example, the caller is a server).

[TPESYSTEM]

A BEA Tuxedo system error has occurred. The exact nature of the error is written to a log file.

[TPEOS]

An operating system error has occurred.

Routine for leaving an application

#include <atmi.h> 
int tpterm(void) 

tpterm() removes a client from a BEA Tuxedo system application. If the client is in transaction mode, thenthe transaction is rolled back. When tpterm() returns successfully, the caller can no longer communicate with any other program nor can it participate in any transactions. Any outstanding conversations are immediately disconnected. If tpterm() is called more than once (that is, after the caller has already left the application), no action is taken and success is returned.

tpterm() returns \-1 on error and sets tperrno to indicate the error condition.

Under the following conditions, tpterm() fails and sets tperrno to:

[TPEPROTO]

tpterm() was called in an improper context (for example, the caller is a server).

[TPESYSTEM]

A BEA Tuxedo system error has occurred. The exact nature of the error is written to a log file.

[TPEOS]

An operating system error has occurred.

Routine for allocating typed buffers

#include <atmi.h>
char * tpalloc(char *type, char *subtype, long size)

tpalloc() returns a pointer to a buffer of type type. Depending on the type of buffer, both subtype and size are optional. The BEA Tuxedo system provides a variety of typed buffers, and applications are free to add their own buffer types. Consult tuxtypes for more details. If subtype is non-NULL in tmtype_sw for a particular buffer type, then subtype must be specified when tpalloc() is called. The allocated buffer will be at least as large as the larger of size and dfltsize, where dfltsize is the default buffer size specified in tmtype_sw for the particular buffer type. For buffer type STRING the minimum is 512 bytes; for buffer types FML and VIEW the minimum is 1024 bytes. Note that only the first eight bytes of type and the first 16 bytes of subtype are significant. Because some buffer types require initialization before they can be used, tpalloc() initializes a buffer (in a BEA Tuxedo system-specific manner) after it is allocated and before it is returned. Thus, the buffer returned to the caller is ready for use. Note that unless the initialization routine cleared the buffer, the buffer is not initialized to zeros by tpalloc().

Upon successful completion, tpalloc() returns a pointer to a buffer of the appropriate type aligned on a long word; otherwise, it returns NULL and sets tperrno to indicate the condition.

Under the following conditions, tpalloc() fails and sets tperrno to:

[TPEINVAL]

Invalid arguments were given (for example, type is NULL).

[TPENOENT]

No entry in tmtype_sw matches type and, if non-NULL, subtype.

[TPEPROTO]

tpalloc() was called in an improper context.

[TPESYSTEM]

A BEA Tuxedo system error has occurred. The exact nature of the error is written to a log file.

[TPEOS]

An operating system error has occurred.

If buffer initialization fails, the allocated buffer is freed and tpalloc() fails returning NULL. This function should not be used in concert with malloc, realloc, or free in the C library (for example, a buffer allocated with tpalloc() should not be freed with free()). Two buffer types are supported by any compliant implementation of the BEA Tuxedo system extension.

Routine to change the size of a typed buffer

#include <atmi.h>  
char * tprealloc(char *ptr, long size) 

tprealloc() changes the size of the buffer pointed to by ptr to size bytes and returns a pointer to the new (possibly moved) buffer. Similar to tpalloc, the size of the buffer will be at least as large as the larger of size and dfltsize, where dfltsize is the default buffer size specified in tmtype_sw. If the larger of the two is less than or equal to zero, then the buffer is unchanged and NULL is returned. A buffer's type remains the same after it is re-allocated. After this function returns successfully, the returned pointer should be used to reference the buffer; ptr should no longer be used. The buffer's contents will not change up to the lesser of the new and old sizes. Some buffer types require initialization before they can be used. tprealloc() re-initializes a buffer (in a communication manager-specific manner) after it is re-allocated and before it is returned. Thus, the buffer returned to the caller is ready for use.

Upon successful completion, tprealloc() returns a pointer to a buffer of the appropriate type aligned on a long word; otherwise it returns NULL and sets tperrno to indicate the error condition.

If the re-initialization function fails, tprealloc() fails returning NULL and the contents of the buffer pointed to by ptr may not be valid. Under the following conditions, tprealloc() fails and sets tperrno to:

[TPEINVAL]

Invalid arguments were given (for example, ptr does not point to a buffer originally allocated by tpalloc).

[TPEPROTO]

tprealloc() was called in an improper context.

[TPESYSTEM]

A BEA Tuxedo system error has occurred. The exact nature of the error is written to a log file.

[TPEOS]

An operating system error has occurred.

If buffer re-initialization fails, tprealloc() fails returning NULL and the contents of the buffer pointed to by ptr may not be valid. This function should not be used in concert with malloc, realloc or free in the C library (for example, a buffer allocated with tprealloc() should not be freed with free()).

Routine for freeing a typed buffer

#include <atmi.h> 
void tpfree(char *ptr) 

The argument to tpfree() is a pointer to a buffer previously obtained by either tpalloc or tprealloc. If ptr is NULL, no action occurs. Undefined results will occur if ptr does not point to a typed buffer (or if it points to space previously freed with tpfree()). Inside service routines, tpfree() returns and does not free the buffer if ptr points to the buffer passed into a service routine. Some buffer types require state information or associated data to be removed as part of freeing a buffer. tpfree() removes any of these associations (in a communication manager-specific manner) before a buffer is freed. Once tpfree() returns, ptr should not be passed as an argument to any BEA Tuxedo system routine or used in any other manner.

tpfree() does not return any value to its caller. Thus, it is declared as a void.

This function should not be used in concert with malloc, realloc or free in the C library (for example, a buffer allocated with tpalloc should not be freed with free).

Routine to determine information about a typed buffer

#include <atmi.h> 
long tptypes(char *ptr, char *type, char *subtype) 

tptypes() takes as its first argument a pointer to a data buffer and returns the type and subtype of that buffer in its second and third arguments, respectively. ptr must point to a buffer gotten from tpalloc. If type and subtype are non-NULL, then the function populates the character arrays to which they point with the names of the buffer's type and subtype, respectively. If the names are of their maximum length (8 for type, 16 for subtype), the character array is not null-terminated. If no subtype exists, then the array pointed to by subtype will contain a NULL string. Note that only the first eight bytes of type and the first 16 bytes of subtype are populated.

Upon success, tptypes() returns the size of the buffer; otherwise it returns \-1 upon failure and sets tperrno to indicate the error condition.

Under the following conditions, tptypes() fails and sets tperrno to:

[TPEINVAL]

Invalid arguments were given (for example, ptr does not point to a buffer gotten from \% tpalloc).

[TPEPROTO]

tptypes() was called in an improper context.

[TPESYSTEM]

A BEA Tuxedo system error has occurred. The exact nature of the error is written to a log file.

[TPEOS]

An operating system error has occurred.

Routine for sending service request and awaiting its reply

int tpcall(char *svc, char *idata, long ilen, char **odata, long 
\*olen, long flags

tpcall sends a request and synchronously awaits its reply. A call to this function is the same as calling tpacall immediately followed by tpgetrply. tpcall sends a request to the service named by svc. The request is sent out at the priority defined for svc unless overridden by a previous call to tpsprio. The data portion of a request is pointed to by idata, a buffer previously allocated by tpalloc. ilen specifies how much of idata to send. Note that if idata points to a buffer of a type that does not require a length to be specified, (for example, an FML fielded buffer), then ilen is ignored (and may be 0). Also, idata may be NULL, in which case ilen is ignored. The type and sub-type of idata must match one of the types and sub-types recognized by svc. odata is the address of a pointer to the buffer where a reply is read into, and olen points to the length of that reply. *odata must point to a buffer originally allocated by tpalloc. If the same buffer is to be used for both sending and receiving, odata should be set to the address of idata. FML and FML32 buffers often assume a minimum size of 4096 bytes; if the reply is larger than 4096, the size of the buffer is increased to a size large enough to accommodate the data being returned. Also, if idata and *odata were equal when tpcall was invoked, and *odata is changed, then idata no longer points to a valid address. Using the old address can lead to data corruption or process exceptions. Buffers on the sending side that may be only partially filled (for example, FML or STRING buffers) will have only the amount that is used sent. The system may then enlarge the received data size by some arbitrary amount. This means that the receiver may receive a buffer that is smaller than what was originally allocated by the sender, yet larger than the data that was sent. The receive buffer may grow, or it may shrink, and its address almost invariably changes, as the system swaps buffers around internally. To determine whether (and how much) a reply buffer changed in size, compare its total size before tpgetrply was issued with *len. If *olen is 0 upon return, then the reply has no data portion and neither *odata nor the buffer it points to were modified. It is an error for *odata or olen to be NULL.

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.

TPNOCHANGE

By default, if a buffer is received that differs in type from the buffer pointed to by *odata, then *odata's buffer type changes to the received buffer's type so long as the receiver recognizes the incoming buffer type. When this flag is set, the type of the buffer pointed to by *odata is not allowed to change. That is, the type and sub-type of the received buffer must match the type and sub-type of the buffer pointed to by *odata.

TPNOBLOCK

The request is not sent if a blocking condition exists (for example, the internal buffers into which the message is transferred are full). Note that this flag applies only to the send portion of tpcall: the function may block waiting for the reply. When TPNOBLOCK is not specified and a blocking condition exists, the caller blocks until the condition subsides or a timeout occurs (either transaction or blocking timeout).

TPNOTIME

This flag signifies that the caller is willing to block indefinitely and wants to be immune to blocking timeouts. However, if the caller is in transaction mode, this flag has no effect; it is subject to the transaction timeout limit. Transaction timeouts may still occur.

TPSIGRSTRT

If a signal interrupts any underlying system calls, then the interrupted system call is re-issued.

Upon successful return from tpcall or upon return where tperrno is set to TPESVCFAIL, tpurcode contains an application-defined value that was sent as part of tpreturn. tpcall returns -1 on error and sets tperrno to indicate the error condition. If a call fails with a particular tperrno value, a subsequent call to tperrordetail with no intermediate ATMI calls, may provide more detailed information about the generated error. Refer to the tperrordetail reference page for more information.

Under the following conditions, tpcall fails and 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 or flags are invalid).

[TPENOENT]

Can not send to svc because it does not exist, or 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]

Either the type and sub-type of the reply are not known to the caller; or, TPNOCHANGE was set inflags and the type and sub-type of *odata do not match the type and sub-type of the reply sent by the service. Neither *odata, its contents, nor *olen is changed. 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. In either case, neither *odata, its contents, nor *olen is changed. If a transaction timeout occurred, then with one exception, any attempts to send new requests or receive outstanding replies will fail with TPETIME until the transaction has been aborted. The exception is a request that does not block, expects no reply, and is not sent on behalf of the caller's transaction (that is, tpacall with TPNOTRAN, TPNOBLOCK, and TPNOREPLY set).

[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 the buffer pointed to by *odata. If the service request was made on behalf of the caller's current transaction, then the transaction is marked abort-only. 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).

[TPESVCERR]

A service routine encountered an error either in tpreturn or tpforward (for example, bad arguments were passed). No reply data is returned when this error occurs (that is, neither *odata, its contents, nor *olen is changed). 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 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). 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.

[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 in an improper context.

[TPESYSTEM]

A BEA Tuxedo system error has occurred. The exact nature of the error is written to a log file.

[TPEOS]

An operating system error has occurred. If a message queue on a remote location is filled, TPEOS may be returned even if tpcall returned successfully.

Routine for sending a service request

#include <atmi.h>
int tpacall(char *svc, char *data, long len, long flags) 

tpacall() sends a request message to the service named by svc. The request is sent out at the priority defined for svc unless overridden by a previous call to tpsprio. If data is non-NULL, it must point to a buffer previously allocated by tpalloc and len should specify the amount of data in the buffer that should be sent. Note that if data points to a buffer of a type that does not require a length to be specified, (for example, an FML fielded buffer), then len is ignored (and may be 0). If data is NULL, len is ignored and a request is sent with no data portion. The type and sub-type of data must match one of the types and sub-types recognized by svc. Note that for each request sent while in transaction mode, a corresponding reply must ultimately be received.

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 re-issued.

Upon successful completion, tpacall() returns a descriptor that can be used to receive the reply of the request sent. Otherwise it returns a value of \-1 and sets tperrno to indicate the error condition.

Under the following conditions, tpacall() fails and 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 sub-type of data is not one of the allowed types and sub-types 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]

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

[TPEBLOCK]

A blocking condition exists and TPNOBLOCK was specified.

[TPGOTSIG]

A signal was received and TPSIGRSTRT was not specified.

[TPEPROTO]

tpacall() was called in an improper context.

[TPESYSTEM]

A BEA Tuxedo system error has occurred. The exact nature of the error is written to a log file.

[TPEOS]

An operating system error has occurred. If a message queue on a remote location is filled, TPEOS may be returned even if tpacall returned successfully.

Routine for getting a reply from a previous request

#include <atmi.h> 
int tpgetrply(int *cd, char **data, long *len, long flags) 

tpgetrply returns a reply from a previously sent request. This function's 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. data must be the address of a pointer to a buffer previously allocated by tpalloc and len should point to a long that tpgetrply sets to the amount of data successfully received. Upon successful return, *data points to a buffer containing the reply and *len contains the size of the data. FML and FML32 buffers often assume a minimum size of 4096 bytes; if the reply is larger than 4096, the size of the buffer is increased to a size large enough to accommodate the data being returned. Buffers on the sending side that may be only partially filled (for example, FML or STRING buffers) will have only the amount that is used send. The system may then enlarge the received data size by some arbitrary amount. This means that the receiver may receive a buffer that is smaller than what was originally allocated by the sender, yet larger than the data that was sent. The receive buffer may grow, or it may shrink, and its address almost invariably changes, as the system swaps buffers around internally. To determine whether (and how much) a reply buffer changed in size, compare its total size before tpgetrply was issued with *len. If *len is 0, then the reply has no data portion and neither *data nor the buffer it points to were modified. It is an error for *data or len to be NULL.

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.

TPNOCHANGE

By default, if a buffer is received that differs in type from the buffer pointed to by *data, then *data's buffer type changes to the received buffer's type so long as the receiver recognizes the incoming buffer type. When this flag is set, the type of the buffer pointed to by *data is not allowed to change. That is, the type and sub-type of the received buffer must match the type and sub-type of the buffer pointed to by *data.

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 re-issued. Except as noted below, *cd is no longer valid after its reply is received.

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. tpgetrply returns -1 on error and sets tperrno to indicate the error condition.

Under the following conditions, tpgetrply fails and sets tperrno as indicated below. Note that if TPGETANY is not set, then *cd is invalidated unless otherwise stated. If TPGETANY is set, then cd points to the descriptor for the reply on which the failure occurred; if an error occurred before a reply could be retrieved, then cd points to 0. Also, the failure does not affect the caller's transaction, if one exists, unless otherwise stated. If a call fails with a particular tperrno value, a subsequent call to tperrordetail with no intermediate ATMI calls, may provide more detailed information about the generated error. Refer to the tperrordetail reference page for more information.

[TPEINVAL]

Invalid arguments were given (for example, cd, data, *data or len is NULL or flags are invalid). If cd is non-NULL, then it is still valid after this error and the reply remains outstanding.

[TPEOTYPE]

Either the type and sub-type of the reply are not known to the caller; or, TPNOCHANGE was set in flags and the type and sub-type of *data do not match the type and sub-type of the reply sent by the service. Regardless, neither *data, its contents nor *len are changed. If the reply was to be received on behalf of the caller's current transaction, then the transaction is marked abort-only since the reply is discarded.

[TPEBADDESC]

cd points to an invalid descriptor.

[TPETIME]

A timeout occurred. If the caller is in transaction mode, then a transaction timeout occurred and the transaction is marked abort-only; otherwise, a blocking timeout occurred and neither TPNOBLOCK nor TPNOTIME were specified. In either case, neither *data, its contents nor *len are changed. *cd remains valid unless the caller is in transaction mode (and TPGETANY was not set). If a transaction timeout occurred, then with one exception, any attempts to send new requests or receive outstanding replies will fail with TPETIME until the transaction has been aborted. The exception is a request that does not block, expects no reply and is not sent on behalf of the caller's transaction (that is, tpacall with TPNOTRAN, TPNOBLOCK and TPNOREPLY set).

[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 the buffer pointed to by *data. If the service request was made on behalf of the caller's transaction, then the transaction is marked abort-only. Note that so long as the transaction has not timed out, further communication may be performed before completely 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).

[TPESVCERR]

A service routine encountered an error either in tpreturn or tpforward (for example, bad arguments were passed). No reply data is returned when this error occurs (that is, neither *data, its contents nor *len are changed). If the service request was made on behalf of the caller's transaction, then the transaction is marked abort-only. Note that so long as the transaction has not timed out, further communication may be performed before completely 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). 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.

[TPEBLOCK]

A blocking condition exists and TPNOBLOCK was specified. *cd remains valid.

[TPGOTSIG]

A signal was received and TPSIGRSTRT was not specified.

[TPEPROTO]

tpgetrply was called in an improper context.

[TPESYSTEM]

A BEA Tuxedo system error has occurred. The exact nature of the error is written to a log file.

[TPEOS]

An operating system error has occurred. If a message queue on a remote location is filled, TPEOS may possibly be returned.

Routine for canceling a call descriptor for outstanding reply

#include <atmi.h> 
int tpcancel(int cd)

tpcancel() cancels a call descriptor, cd, returned by tpacall. It is an error to attempt to cancel a call descriptor associated with a transaction. Upon success, cd is no longer valid and any reply received on behalf of cd will be silently discarded.

tpcancel() returns \-1 on error and sets tperrno to indicate the error condition.

Under the following conditions, tpcancel() fails and sets tperrno to:

[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 in an improper context.

[TPESYSTEM]

A BEA Tuxedo system error has occurred. The exact nature of the error is written to a log file.

[TPEOS]

An operating system error has occurred.

The BEA Tuxedo system server initialization routine

#include <atmi.h> 
int tpsvrinit(int argc, char **argv) 

The BEA Tuxedo system server abstraction calls tpsvrinit() during its initialization. This routine is called after the thread of control has become a server but before it handles any service requests; thus, BEA Tuxedo system communication may be performed and transactions may be defined in this routine. However, if tpsvrinit() returns with open connections, asynchronous replies pending or while still in transaction mode, the BEA Tuxedo system will close the connections, ignore replies pending, abort the transaction, and the server will exit gracefully. If an application does not provide this routine in a server, then the default version provided by the BEA Tuxedo system is called instead. The default tpsvrinit() calls tpopen() and userlog() to announce that the server has successfully started. Application-specific options can be passed into a server and processed in tpsvrinit() (see servopts). The options are passed through argc and argv. Since getopt is used in a BEA Tuxedo system server abstraction, optarg, optind and opterr may be used to control option parsing and error detection in tpsvrinit(). If an error occurs in tpsvrinit(), the application can cause the server to exit gracefully (and not take any service requests) by returning -1. The application should not call exit(2) itself.

A negative return value will cause the server to exit gracefully.

If either tpreturn() or tpforward() are used outside of a service routine (e.g., in clients, or in tpsvrinit() or tpsvrdone()), then these routines simply return having no effect.

BEA Tuxedo system server termination routine

#include <atmi.h>
void tpsvrdone(void)

The BEA Tuxedo system server abstraction calls tpsvrdone after it has finished processing service requests but before it exits. When this routine is invoked, the server is still part of the system but its own services have been unadvertised. Thus, BEA Tuxedo system communication can be performed and transactions can be defined in this routine. However, if tpsvrdone returns with open connections, asynchronous replies pending or while still in transaction mode, the BEA Tuxedo system will close its connections, ignore any pending replies and abort the transaction before the server exits. If a server is shut down by the invocation of tmshutdown -y, services are suspended and the ability to perform communication or to begin transactions in tpsvrdone is limited. If an application does not provide this routine in a server, then the default version provided by the BEA Tuxedo system is called instead. The default tpsvrdone calls tpclose and userlog to announce that the server is about to exit.

If either tpreturn or tpforward is called in tpsvrdone, it simply returns having no effect.

Routine for returning from a service routine

void tpreturn(int rval, long rcode, char *data, long len, long      flags) 

tpreturn indicates that a service routine has completed. tpreturn acts like a return statement in the C language (that is, when tpreturn is called, the service routine returns to the BEA Tuxedo system dispatcher). It is recommended that tpreturn be called from within the service routine dispatched to ensure correct return of control to the BEA Tuxedo system dispatcher. tpreturn is used to send a service's reply message. If the program receiving the reply is waiting in either tpcall, tpgetrply, or tprecv, then after a successful call to tpreturn, the reply is available in the receiver's buffer. For conversational services, tpreturn also tears down the connection. That is, the service routine cannot call tpdiscon directly. To ensure correct results, the program that connected to the conversational service should not call tpdiscon; rather, it should wait for notification that the conversational service has completed (that is, it should wait for one of the events, like TPEV_SVCSUCC or TPEV_SVCFAIL, sent by tpreturn). If the service routine was in transaction mode, tpreturn places the service's portion of the transaction in a state where 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 nor 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 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. tpreturn should be called after closing all connections initiated by the service. Otherwise, depending on the nature of the service, either a TPESVCERR or a TPEV_SVCERR event will be returned to the program that initiated communication with the service routine. Also, an immediate disconnect event (that is, TPEV_DISCONIMM) is sent over all open connections to subordinates. Since a conversational service has only one open connection which it did not initiate, the communication manager knows over which descriptor data (and any event) should be sent. For this reason, a descriptor is not passed to tpreturn.

The following is a description of tpreturn 's arguments. 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 is the same as TPFAIL, with respect to completing the service, but the server will exit after the transaction is rolled back and the reply is sent back to the requester. If the server is restartable, then the server will automatically be restarted.

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

An applicatio-defined return code, rcode, 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). In addition, for conversational services, this code can be sent only if the service routine has control of the connection when it issues tpreturn. The value of rcode is available in the receiver in the variable, tpurcode. data points to the data portion of a reply to be sent. If data is non-NULL, it must point to a buffer previously obtained by a call to tpalloc. If this is the same buffer passed to the service routine upon its invocation, then its disposition is up to the BEA Tuxedo system dispatcher; the service routine writer does not have to worry about whether it is freed or not. In fact, any attempt by the user to free this buffer will fail. However, if the buffer passed to tpreturn is not the same one with which the service is invoked, then tpreturn will free that buffer. len specifies the amount of the data buffer to be sent. If data points to a buffer which does not require a length to be specified, (for example, an FML fielded buffer), then len is ignored (and can be 0). If data is NULL, then len is ignored. In this case, if 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 frees data as necessary and returns sending no reply. 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). If the service is conversational, there are two cases where the caller's return code and the data portion are not transmitted: if the connection has already been torn down when the call is made (that is, the caller has received TPEV_DISCONIMM on the connection), then this call simply ends the service routine and rolls back the current transaction, if one exists. If the caller does not have control of the connection, either TPEV_SVCFAIL or TPEV_SVCERR is sent to the originator of the connection as described above. Regardless of which event the originator receives, no data is transmitted; however, if the originator receives the TPEV_SVCFAIL event, the return code is available in the originator's tpurcode variable.

A service routine does not return any value to its caller, the BEA Tuxedo system dispatcher; thus, it is declared as a void. Service routines, however, are expected to terminate using either tpreturn or tpforward. A conversational service routine must use tpreturn, and cannot use tpforward. If a service routine returns without using either tpreturn or tpforward (that is, it uses the C language return statement or just simply "falls out of the function") or tpforward is called from a conversational server, the server will print a warning message in the log and return a service error to the service requester. In addition, all open connections to subordinates will be disconnected immediately, and 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. Note also that if either tpreturn or tpforward are used outside of a service routine (for example, in clients, or in tpsvrinit or tpsvrdone), then these routines simply return having no effect.

Since tpreturn ends 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 tpcall or tpgetrply, and cause the event, TPEV_SVCERR, to be sent over the conversation to a program using tpsend or tprecv. If either SVCTIMEOUT in the ubbconfig file or TA_SVCTIMEOUT in the TM_MIB is non-zero, the event TPEV_SVCERR is returned when a service timeout occurs. tprrordetail and tpstrerrordetail can be used to get additional information about an error produced by the last BEA Tuxedo system routine called in the current thread. If an error occurred, tperrordetail returns a numeric value that can be used as an argument to trstrerrordetail to retrieve the text of the error detail.

Routine for advertising a service name

#include <atmi.h>
int tpadvertise(char *svcname, void (*func)(TPSVCINFO *))

tpadvertise allows a server to advertise the services that it offers. By default, a server's services are advertised when it is booted and unadvertised when it is shutdown. All servers belonging to a multiple server, single queue (MSSQ) set must offer the same set of services. These routines enforce this rule by affecting the advertisements of all servers sharing an MSSQ set. tpadvertise advertises svcname for the server (or the set of servers sharing the caller's MSSQ set). svcname should be 15 characters or less, but cannot be NULL or the NULL string (""). func is the address of a BEA Tuxedo system service function. This function will be invoked whenever a request for svcname is received by the server. func cannot be NULL. Explicitly specified function names can be up to 128 characters long. Names longer than 15 characters are accepted and truncated to 15 characters. Users should make sure that truncated names do not match other service names. If svcname is already advertised for the server and func matches its current function, then tpadvertise returns success (this includes truncated names that match already advertised names). However, if svcname is already advertised for the server but func does not match its current function, then an error is returned (this can happen if truncated names match already advertised names). Service names starting with dot (.) are reserved for administrative services. An error will be returned if an application attempts to advertise one of these services.

tpadvertise returns -1 on error and sets tperrno to indicate the error condition.

Under the following conditions, tpadvertise fails and sets tperrno to:

[TPEINVAL]

svcname is NULL or the NULL string (""),or begins with a "." or func is NULL.

[TPELIMIT]

svcname cannot be advertised because of space limitations.

[TPEMATCH]

svcname is already advertised for the server but with a function other than func. Although the function fails, svcname remains advertised with its current function (that is, func does not replace the current function).

[TPEPROTO]

tpadvertise was called in an improper context (for example, by a client).

[TPESYSTEM]

A BEA Tuxedo system error has occurred. The exact nature of the error is written to a log file.

[TPEOS]

An operating system error has occurred.

Routine for unadvertising a service name

#include <atmi.h> 
int tpunadvertise(char *svcname)

tpunadvertise() allows a server to unadvertise a service that it offers. By default, a server's services are advertised when it is booted and they are unadvertised when it is shutdown. All servers belonging to a multiple server, single queue (MSSQ) set must offer the same set of services. These routines enforce this rule by affecting the advertisements of all servers sharing an MSSQ set. tpunadvertise() removes svcname as an advertised service for the server (or the set of servers sharing the caller's MSSQ set). svcname cannot be NULL or the NULL string (""). Also, svcname should be 15 characters or less. (See *SERVICES section of ubbconfig). Longer names will be accepted and truncated to 15 characters. Care should be taken such that truncated names do not match other service names.

tpunadvertise() returns \-1 on error and sets tperrno to indicate the error condition.

Under the following conditions, tpunadvertise() fails and sets tperrno to:

[TPEINVAL]

svcname is NULL or the NULL string ("").

[TPENOENT]

svcname is not currently advertised by the server.

[TPEPROTO]

tpunadvertise() was called in an improper context (for example, by a client).

[TPESYSTEM]

A BEA Tuxedo system error has occurred. The exact nature of the error is written to a log file.

[TPEOS]

An operating system error has occurred.