|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Converts a tm structure to a calendar time
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Routine for retrieving service and parameter information from a Tuxedo repository file.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Routine for setting when tpcommit() should return
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Sets commit_return characteristic
|
|
|
Sets transaction_control characteristic
|
|
|
Sets transaction_timeout characteristic
|
|
|
|
|
|
|
|
|
|
|
Note:
|
In various parts of the Oracle Tuxedo documentation we refer to threads. When this term is used in a discussion of multithreaded applications, it is self-explanatory. In some instances, however, the term is used in a discussion of a topic that is relevant for both single-threaded and multithreaded applications. In such cases, readers who are running single-threaded applications may assume that the term thread refers to an entire process.
|
In the conversational model, for messages being exchanged using tpsend() and
tprecv(), a sequence number is added to the message header and messages are received in the order in which they are sent. If a server or client gets a message out of order, the conversation is stopped, any transaction in progress is rolled back, and message
1572 in
LIBTUX, “
Bad Conversational Sequence Number,” is logged.
In the Oracle Tuxedo ATMI system, a transaction is used to define a single logical unit of work that either wholly succeeds or has no effect whatsoever. A transaction allows work performed in many processes, possibly at different sites, to be treated as an atomic unit of work. The initiator of a transaction normally uses
tpbegin() and either
tpcommit() or
tpabort() to delineate the operations within a transaction.
A service routine joining a transaction that was started by another process is called a participant. A transaction can have several participants. A service can be invoked to do work on the same transaction more than once. Only the initiator of a transaction (that is, a process calling either
tpbegin() or
tpresume()) can call
tpcommit() or
tpabort(). Participants influence the outcome of a transaction by using
tpreturn() or
tpforward(). These two calls signify the end of a service routine and indicate that the routine has finished its part of the transaction.
The TX Interface has two calls for opening and closing resource managers in a portable manner, tx_open() and
tx_close(), respectively. Transactions are started with
tx_begin() and completed with either
tx_commit() or
tx_rollback().
tx_info() is used to retrieve transaction information, and there are three calls to set options for transactions:
tx_set_commit_return(),
tx_set_transaction_control(), and
tx_set_transaction_timeout(). The TX Interface has no equivalents to ATMI’s
tpsuspend() and
tpresume().
Since tx_close() cannot be called when the caller is in transaction mode, a caller executing in chained mode must switch to unchained mode and complete the current transaction before calling
tx_close().
The tpstrerror() function is provided to produce a message on the standard error output. It takes one argument, an integer (found in
tperrno) and returns a pointer to the text of an error message in
LIBTUX_CAT. The pointer can be used as an argument to
userlog().
tperrordetail() can be used as the first step of a three step procedure to get additional detail about an error in the most recent Oracle Tuxedo ATMI system call on the current thread.
tperrordetail() returns an integer which is then used as an argument to
tpstrerrordetail() to retrieve a pointer to a string that contains the error message. The pointer can then be used as an argument to
userlog or to
fprintf().
The error codes that can be produced by an ATMI function are described on each ATMI reference page. The F_error() and
F_error32() functions are provided to produce a message on the standard error output for FML errors. They take one parameter, a string; print the argument string appended with a colon and a blank; and then print an error message followed by a newline character. The error message displayed is the one defined for the error number currently in
Ferror() or
Ferror32(), which is set when errors occur.
Fstrerror(), and its counterpart,
Fstrerror32(), can be used to retrieve the text of an FML error message from a message catalog; it returns a pointer that can be used as an argument to
userlog.
The first kind of timeout is specified when a transaction is started with tpbegin(). (See
tpbegin(3c) for details.) The second kind of timeout can occur when using the Oracle Tuxedo ATMI system communication routines defined in
tpcall(3c). Callers of these routines typically block when awaiting a reply that has yet to arrive, although they can also block trying to send data (for example, if request queues are full). The maximum amount of time a caller remains blocked is determined by an Oracle Tuxedo ATMI system configuration file parameter. (See the
BLOCKTIME parameter in
UBBCONFIG(5) for details.)
The tmtype_sw_t structure provides the description required when adding new buffer types to
tm_typesw(), the buffer type switch for a process. The switch elements are defined in
typesw(5). The function names used in this entry are templates for the actual function names defined by the Oracle Tuxedo ATMI system or by applications in which custom buffer types are created. These function names can be mapped easily to switch elements: to create a template name simply add the prefix
_tm to the element name of a function pointer. For example, the template name for the element
initbuf is
_tminitbuf.
The type element must be non-NULL and at most 8 characters in length. If this element is not unique in the switch, then
subtype() must be non-NULL.
The subtype() element can be NULL, a string of at most 16 characters, or * (the wildcard character). The combination of
type() and
subtype() must uniquely identify an element in the switch.
The dfltsize() element is used when allocating or reallocating a buffer. The semantics of
tpalloc() and
tprealloc() are such that the larger of the following two values is used to create or reallocate a buffer: the value of
dfltsize() or the value of the
size parameter for the
tpalloc() and
tprealloc() functions. For some types of structures, such as a fixed-sized C structure, the buffer size should equal the size of the structure. If
dfltsize() is set to this value, then the caller may not need to specify the buffer’s length to routines in which a buffer is passed.
dfltsize() can be 0 or less. However, if
tpalloc() or
tprealloc() is called and the
size parameter for the function being called is also less than or equal to 0, then the routine will fail. We recommend setting
dfltsize() to a value greater than 0.
|
•
|
CARRAY—a character array, possibly containing NULL characters, which is neither encoded nor decoded during transmission
|
|
•
|
STRING—a NULL-terminated character array
|
|
•
|
FML—fielded buffers ( FML or FML32)
|
|
•
|
XML—XML document or datagram buffer
|
|
•
|
VIEW—simple C structures ( VIEW or VIEW32); all views are handled by the same set of routines. The name of a particular view is its subtype name.
|
Two of these buffer types have synonyms: X_OCTET is a synonym for
CARRAY, and both
X_C_TYPE and
X_COMMON are synonyms for
VIEW.
X_C_TYPE supports all the same elements as
VIEW, whereas
X_COMMON supports only longs, shorts, and characters.
X_COMMON should be used when both C and COBOL programs are communicating.
An application wishing to supply its own buffer type can do so by adding an instance to the tm_typesw() array. Whenever adding or deleting a buffer type, be careful to leave a NULL entry at the end of the array. Note that a buffer type with a NULL name is not permitted. An application client or server is linked with the new buffer type switch by explicitly specifying the name of the source or object file on the
buildserver() or
buildclient() command line using the
-f option.
In single-context mode, if tpinit() is called more than once (that is, if it is called after the client has already joined the application), no action is taken and success is returned.
In multicontext mode, each call to tpinit() creates a new application association. The application can obtain a handle representing this application association by calling
tpgetctxt(). Any thread in the same process can call
tpsetctxt() to set that thread’s context.
Once an application has chosen single-context mode, all calls to tpinit() must specify single-context mode until all application associations are terminated. Similarly, once an application has chosen multicontext mode, all calls to
tpinit() must specify multicontext mode until all application associations are terminated.
Table 2 shows the transitions that may occur, within a client process, among the following states: the uninitialized state, the initialized in single-context mode state, and the initialized in multicontext mode state.
|
Note:
|
When tpterm() is called by a thread running in the multicontext state ( TPMULTICONTEXTS), the calling thread is placed in the NULL context state ( TPNULLCONTEXT). All other threads associated with the terminated context are switched to the invalid context state ( TPINVALIDCONTEXT).
|
Table 3 lists all possible context state changes produced by calling
tpinit(),
tpsetctxt(), and
tpterm(). These states are thread-specific; different threads can be in different states when they are part of a multicontexted application. By contrast, each context state listed in the preceding table (
“Per-Process Context Modes”) applies to an entire process.
/*
* The following definitions must be included in atmi.h
*/
/* Flags to service routines */
#define TPNOBLOCK 0x00000001 /* non-blocking send/rcv */
#define TPSIGRSTRT 0x00000002 /* restart rcv on interrupt */
#define TPNOREPLY 0x00000004 /* no reply expected */
#define TPNOTRAN 0x00000008 /* not sent in transaction mode */
#define TPTRAN 0x00000010 /* sent in transaction mode */
#define TPNOTIME 0x00000020 /* no timeout */
#define TPABSOLUTE 0x00000040 /* absolute value on tmsetprio */
#define TPGETANY 0x00000080 /* get any valid reply */
#define TPNOCHANGE 0x00000100 /* force incoming buffer to match */
#define RESERVED_BIT1 0x00000200 /* reserved for future use */
#define TPCONV 0x00000400 /* conversational service */
#define TPSENDONLY 0x00000800 /* send-only mode */
#define TPRECVONLY 0x00001000 /* recv-only mode */
#define TPACK 0x00002000 /* */
/* Flags to tpreturn - also defined in xa.h */
#define TPFAIL 0x20000000 /* service FAILURE for tpreturn */
#define TPEXIT 0x08000000 /* service FAILURE with server exit */
#define TPSUCCESS 0x04000000 /* service SUCCESS for tpreturn */
/* Flags to tpscmt - Valid TP_COMMIT_CONTROL
* characteristic values
*/
#define TP_CMT_LOGGED 0x01 /* return after commit
* decision is logged */
#define TP_CMT_COMPLETE 0x02 /* return after commit has
* completed */
/* client identifier structure */
struct clientid_t {
long clientdata[4]; /* reserved for internal use */
}
typedef struct clientid_t CLIENTID;
/* context identifier structure */
typedef long TPCONTEXT_T;
/* interface to service routines */
struct tpsvcinfo {
name[128];
long flags; /* describes service attributes */
char *data; /* pointer to data */
long len; /* request data length */
int cd; /* connection descriptor
* if (flags TPCONV) true */
long appkey; /* application authentication client
* key */
CLIENTID cltid; /* client identifier for originating
* client */
};
typedef struct tpsvcinfo TPSVCINFO;
/* tpinit(3c) interface structure */
#define MAXTIDENT 30
struct tpinfo_t {
char usrname[MAXTIDENT+2]; /* client user name */
char cltname[MAXTIDENT+2]; /* app client name */
char passwd[MAXTIDENT+2]; /* application password */
long flags; /* initialization flags */
long datalen; /* length of app specific data */
long data; /* placeholder for app data */
};
typedef struct tpinfo_t TPINIT;
/* The transactionID structure passed to tpsuspend(3c) and tpresume(3c) */
struct tp_tranid_t {
long info[6]; /* Internally defined */
};
typedef struct tp_tranid_t TPTRANID;
/* Flags for TPINIT */
#define TPU_MASK 0x00000007 /* unsolicited notification
* mask */
#define TPU_SIG 0x00000001 /* signal based
* notification */
#define TPU_DIP 0x00000002 /* dip-in based
* notification */
#define TPU_IGN 0x00000004 /* ignore unsolicited
* messages */
#define TPU_THREAD 0x00000040 /* THREAD notification */
#define TPSA_FASTPATH 0x00000008 /* System access ==
* fastpath */
#define TPSA_PROTECTED 0x00000010 /* System access ==
* protected */
#define TPMULTICONTEXTS 0x00000020 /* multiple context associa-
* tions per process */
/* /Q tpqctl_t data structure */
#define TMQNAMELEN 127
#define TMMSGIDLEN 32
#define TMCORRIDLEN 32
struct tpqctl_t { /* control parameters to queue primitives */
long flags; /* indicates which values are set */
long deq_time; /* absolute/relative time for dequeuing */
long priority; /* enqueue priority */
long diagnostic; /* indicates reason for failure */
char msgid[TMMSGIDLEN]; /* ID of message before which to queue */
char corrid[TMCORRIDLEN]; /* correlation ID used to identify message */
char replyqueue[TMQNAMELEN+1]; /* queue name for reply message */
char failurequeue[TMQNAMELEN+1]; /* queue name for failure message */
CLIENTID cltid; /* client identifier for */
/* originating client */
long urcode; /* application user-return code */
long appkey; /* application authentication client key */
long delivery_qos; /* delivery quality of service */
long reply_qos; /* reply message quality of service */
long exp_time /* expiration time */
};
typedef struct tpqctl_t TPQCTL;
/* /Q structure elements that are valid - set in flags */
#ifndef TPNOFLAGS
#define TPNOFLAGS 0x00000 /* no flags set -- no get */
#endif
#define TPQCORRID 0x00001 /* set/get correlation ID */
#define TPQFAILUREQ 0x00002 /* set/get failure queue */
#define TPQBEFOREMSGID 0x00004 /* enqueue before message ID */
#define TPQGETBYMSGIDOLD 0x00008 /* deprecated */
#define TPQMSGID 0x00010 /* get msgid of enq/deq message */
#define TPQPRIORITY 0x00020 /* set/get message priority */
#define TPQTOP 0x00040 /* enqueue at queue top */
#define TPQWAIT 0x00080 /* wait for dequeuing */
#define TPQREPLYQ 0x00100 /* set/get reply queue */
#define TPQTIME_ABS 0x00200 /* set absolute time */
#define TPQTIME_REL 0x00400 /* set relative time */
#define TPQGETBYCORRIDOLD 0x00800 /* deprecated */
#define TPQPEEK 0x01000 /* non-destructive dequeue */
#define TPQDELIVERYQOS 0x02000 /* delivery quality of service */
#define TPQREPLYQOS 0x04000 /* reply msg quality of service*/
#define TPQEXPTIME_ABS 0x08000 /* absolute expiration time */
#define TPQEXPTIME_REL 0x10000 /* relative expiration time */
#define TPQEXPTIME_NONE 0x20000 /* never expire */
#define TPQGETBYMSGID 0x40008 /* dequeue by msgid */
#define TPQGETBYCORRID 0x80800 /* dequeue by corrid */
/* Valid flags for the quality of service fields in the TPQCTL structure */
#define TPQQOSDEFAULTPERSIST 0x00001 /* queue's default persistence */
/* policy */
#define TPQQOSPERSISTENT 0x00002 /* disk message */
#define TPQQOSNONPERSISTENT 0x00004 /* memory message */
/* error return codes */
extern int tperrno;
extern long tpurcode;
/* tperrno values - error codes */
* The reference pages explain the context in which the following
* error codes can return.
*/
#define TPMINVAL 0 /* minimum error message */
#define TPEABORT 1
#define TPEBADDESC 2
#define TPEBLOCK 3
#define TPEINVAL 4
#define TPELIMIT 5
#define TPENOENT 6
#define TPEOS 7
#define TPEPERM 8
#define TPEPROTO 9
#define TPESVCERR 10
#define TPESVCFAIL 11
#define TPESYSTEM 12
#define TPETIME 13
#define TPETRAN 14
#define TPGOTSIG 15
#define TPERMERR 16
#define TPEITYPE 17
#define TPEOTYPE 18
#define TPERELEASE 19
#define TPEHAZARD 20
#define TPEHEURISTIC 21
#define TPEEVENT 22
#define TPEMATCH 23
#define TPEDIAGNOSTIC 24
#define TPEMIB 25
#define TPMAXVAL 26 /* maximum error message */
/* conversations - events */
#define TPEV_DISCONIMM 0x0001
#define TPEV_SVCERR 0x0002
#define TPEV_SVCFAIL 0x0004
#define TPEV_SVCSUCC 0x0008
#define TPEV_SENDONLY 0x0020
/* /Q diagnostic codes */
#define QMEINVAL -1
#define QMEBADRMID -2
#define QMENOTOPEN -3
#define QMETRAN -4
#define QMEBADMSGID -5
#define QMESYSTEM -6
#define QMEOS -7
#define QMEABORTED -8
#define QMENOTA QMEABORTED
#define QMEPROTO -9
#define QMEBADQUEUE -10
#define QMENOMSG -11
#define QMEINUSE -12
#define QMENOSPACE -13
#define QMERELEASE -14
#define QMEINVHANDLE -15
#define QMESHARE -16
/* EventBroker Messages */
#define TPEVSERVICE 0x00000001
#define TPEVQUEUE 0x00000002
#define TPEVTRAN 0x00000004
#define TPEVPERSIST 0x00000008
/* Subscription Control Structure */
struct tpevctl_t {
long flags;
char name1[XATMI_SERVICE_NAME_LENGTH];
char name2[XATMI_SERVICE_NAME_LENGTH];
TPQCTL qctl;
};
typedef struct tpevctl_t TPEVCTL;
Table 4 indicates which functions may be called by request/response servers, conversational servers, and clients. Note that
tpsvrinit(),
tpsvrdone(),
tpsvrthrinit(), and
tpsvrthrdone() are not included in this table because they are not called by applications (that is, they are application-supplied functions that are invoked by the Oracle Tuxedo ATMI system).
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Y (in application-
created threads)
|
Y (in application-
created threads)
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
A server is placed in the initialized state by the Oracle Tuxedo ATMI system’s main() before its
tpsvrinit() function is invoked, and it is placed in the uninitialized state by the Oracle Tuxedo ATMI system’s
main() after its
tpsvrdone() function has returned. Note that in all of the state tables shown below, an error return from a function causes the thread to remain in the same state, unless otherwise noted.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
tpsetctxt (set to a non-NULL context)
|
|
|
tpsetctxt
(with the TPNULLCONTEXT context set)
|
|
|
|
|
|
|
|
|
|
|
tpterm (in a different thread of this context)
|
|
|
|
|
|
|
|
|
|
|
Table 6 indicates the state of a client or server with respect to whether or not a resource manager associated with the process has been initialized.
Table 7 indicates the state of a process with respect to whether or not the process is associated with a transaction. For servers, transitions to states T
1and T
2 assume a precondition of state R
1 (for example,
tpopen() has been called with no subsequent call to
tpclose() or
tpterm()).
Table 8 indicates the state of a single request descriptor returned by
tpacall().
|
Note:
|
a This state change occurs only if the descriptor is not associated with the caller’s transaction.
|
b This state change occurs only if the descriptor is associated with the caller’s transaction.
c If the descriptor is associated with the caller’s transaction, then
tpsuspend() returns a protocol error.
Table 9 indicates the state of a connection descriptor returned by
tpconnect() or provided by a service invocation in the
TPSVCINFO structure. For primitives that do not take a connection descriptor, the state changes apply to all connection descriptors, unless otherwise noted.
|
•
|
C1— tpconnect() descriptor send-only
|
|
•
|
C2— tpconnect() descriptor receive-only
|
|
•
|
C3— TPSVCINFO descriptor send-only
|
|
•
|
C4— TPSVCINFO descriptor receive-only
|
|
Note:
|
a If process is in transaction mode and TPNOTRAN is not specified, the connection is in transaction mode.
|
b If the
TPTRAN flag is set, the connection is in transaction mode.
c If the connection is not in transaction mode, no state change.
d If the connection is in transaction mode, then
tpsuspend() returns a protocol error.
|
•
|
S0: No RMs have been opened or initialized. An application association cannot start a global transaction until it has successfully called tx_open.
|
|
•
|
S1: An application association has opened its RM but is not in a transaction. Its transaction_control characteristic is TX_UNCHAINED.
|
|
•
|
S2: An application association has opened its RM but is not in a transaction. Its transaction_control characteristic is TX_CHAINED.
|
|
•
|
S3: An application association has opened its RM and is in a transaction. Its transaction_control characteristic is TX_UNCHAINED.
|
|
•
|
S4: An application association has opened its RM and is in a transaction. Its transaction_control characteristic is TX_CHAINED.
|
|
•
|
TX_SET1 denotes any of the following: TX_OK, TX_ROLLBACK, TX_MIXED, TX_HAZARD, or TX_COMMITTED. TX_ROLLBACK is not returned by tx_rollback() and TX_COMMITTED is not returned by tx_commit().
|
|
•
|
TX_SET2 denotes any of the following: TX_NO_BEGIN, TX_ROLLBACK_NO_BEGIN, TX_MIXED_NO_BEGIN, TX_HAZARD_NO_BEGIN, or TX_COMMITTED_NO_BEGIN. TX_ROLLBACK_NO_BEGIN is not returned by tx_rollback() and TX_COMMITTED_NO_BEGIN is not returned by tx_commit().
|
|
•
|
If TX_FAIL is returned on any call, the application process is in an undefined state with respect to the above table.
|
|
•
|
When tx_info() returns either TX_ROLLBACK_ONLY or TX_TIMEOUT_ROLLBACK_ONLY in the transaction state information, the transaction is marked rollback-only and will be rolled back whether the application program calls tx_commit() or tx_rollback().
|
buffer(3c),
tpadvertise(3c),
tpalloc(3c),
tpbegin(3c),
tpcall(3c),
tpconnect(3c),
tpgetctxt(3c),
tpinit(3c),
tpopen(3c),
tpservice(3c),
tpsetctxt(3c),
tuxtypes(5),
typesw(5)
AEMsetblockinghook() is an “ATMI Extension for Mac” that allows a Mac task to install a new function which the ATMI networking software uses to implement blocking ATMI calls. It takes a pointer to the procedure instance address of the blocking function to be installed.
AEMsetblockinghook() returns a pointer to the procedure-instance of the previously installed blocking function. The application or library that calls the
AEMsetblockinghook() function should save this return value so that it can be restored if necessary. (If “nesting” is not important, the application may simply discard the value returned by
AEMsetblockinghook() and eventually use
AEMsetblockinghook(NULL) to restore the default mechanism.)
AEMsetblockinghook() returns NULL on error and sets
tperrno to indicate the error condition.
Under failure, AEMsetblockinghook() sets
tperrno to the following value:
AEOaddtypesw()—Installs or replaces a user-defined buffer type at execution time.
AEOaddtypesw() is an “ATMI Extension for OS/2” that allows an OS/2 client to install a new, or replace an existing, user-defined buffer type at execution time. The argument to this function is a pointer to a
TMTYPESW structure that contains the information for the buffer type to be installed.
If the type() and the
subtype() match an existing buffer type already installed, then all the information is replaced with the new buffer type. If the information does not match the
type() and the
subtype() fields, then the new buffer type is added to the existing types registered with the Oracle Tuxedo ATMI system. For new buffer types, make sure that the
WSH and other Oracle Tuxedo ATMI system processes involved in the call processing have been built with the new buffer type.
Upon success, AEOaddtypesw() returns the number of user buffer types in the system Upon failure,
AEOaddtypesw() returns -1 and sets
tperrno to indicate the error condition.
Upon failure, AEOaddtypesw() sets
tperrno to one of the following values:
#include <os2.h>
#include <atmi.h>
#include <tmtypes.h>
int FAR PASCAL Nfinit(char FAR *, long);
int (FAR PASCAL * lpFinit)(char FAR *, long);
int FAR PASCAL Nfreinit(char FAR *, long);
int (FAR PASCAL * lpFreinit)(char FAR *, long);
int FAR PASCAL Nfuninit(char FAR *, long);
int (FAR PASCAL * lpFuninit)(char FAR *, long);
TMTYPESW newtype =
{
“MYFML”, ““, 1024, NULL, NULL,
NULL, _fpresend, _fpostsend, _fpostrecv, _fencdec,
_froute
};
newtype.initbuf = Nfinit;
newtype.reinitbuf = Nfreinit;
newtype.uninitbuf = Nfuninit;
if(AEOaddtypesw(newtype) == -1) {
userlog(“AEOaddtypesw failed %s”, tpstrerror(tperrno));
}
int
FAR PASCAL
Nfinit(char FAR *ptr, long len)
{
......
return(1);
}
int
FAR PASCAL
Nfreinit(char FAR *ptr, long len)
{
......
return(1);
}
int
FAR PASCAL
Nfuninit(char FAR *ptr, long mdlen)
{
......
return(1);
}
AEPisblocked() is an “ATMI Extension for OS/2 Presentation Manager” that allows a OS/2 PM task to determine if it is executing while waiting for a previous blocking call to complete.
AEWsetunsol()—Posts a Windows message for Oracle Tuxedo ATMI unsolicited event.
AEWsetunsol() controls which window to notify,
hWnd, and which Windows message type to post,
wMsg. When an Oracle Tuxedo ATMI unsolicited message arrives, a Windows message is posted.
lParam() is set to the Oracle Tuxedo ATMI system buffer pointer, or zero if none. If
lParam() is non-zero, the application must call
tpfree() to release the buffer.
If wMsg is zero, any future unsolicited messages will be logged and ignored.
Upon failure, AEWsetunsol() returns -1 and sets
tperrno to indicate the error condition.
Upon failure, AEWsetunsol() sets
tperrno to one of the following values:
AEWsetunsol() posting of Windows messages may not be activated simultaneously with a
tpsetunsol() callback routine. The most recent
tpsetunsol() or
AEWsetunsol() request controls how unsolicited messages will be handled.
buffer()—Semantics of elements in
tmtype_sw_t.
int /* Initialize a new data buffer */
_tminitbuf(char *ptr, long len)
int /* Reinitialize a reallocated data buffer */
_tmreinitbuf(char *ptr, long len)
int /* Uninitialize a data buffer to be freed */
_tmuninitbuf(char *ptr, long len)
long /* Process buffer before sending */
_tmpresend(char *ptr, long dlen, long mdlen)
void /* Process buffer after sending */
_tmpostsend(char *ptr, long dlen, long mdlen)
long /* Process buffer after receiving */
_tmpostrecv(char *ptr, long dlen, long mdlen)
long /* Encode/decode a buffer to/from a transmission format */
_tmencdec(int op, char *encobj, long elen, char *obj, long olen)
int /* Determine server group for routing based on data */
_tmroute(char *routing_name, char *service, char *data, long \ len, char *group)
int /* Evaluate boolean expression on buffer’s data */
_tmfilter(char *ptr, long dlen, char *expr, long exprlen)
int /* Extract buffer’s data based on format string */
_tmformat(char *ptr, long dlen, char *fmt, char *result, long \ maxresult)
long /* Process buffer before sending, possibly generating copy */
_tmpresend2(char *iptr, long ilen, long mdlen, char *optr, long olen, long *flags )
long /* Multibyte code-set encoding conversion */
_tmconvmb(char *ibufp, long ilen, char *enc_name, char *obufp, long olen, long
*flags)
This page describes the semantics of the elements and routines defined in the tmtype_sw_t structure. These descriptions are necessary for adding new buffer types to a process buffer type switch,
tm_typesw. The switch elements are defined in
typesw(5). The function names used in this entry are templates for the actual function names defined by the Oracle Tuxedo ATMI system as well as by applications adding their own buffer types. The names map to the switch elements very simply: the template names are made by taking each function pointer’s element name and prepending
_tm (for example, the element
initbuf has the function name
_tminitbuf()).
The element type must be non-NULL and up to 8 characters in length. The element
subtype can be NULL, a string of up to 16 characters, or the wildcard character, “*”. If
type is not unique in the switch, then
subtype must be used; the combination of
type and
subtype must uniquely identify an element in the switch.
dfltsize() is used when allocating or reallocating a buffer. The larger of
dfltsize() and the routines’
size parameter is used to create or reallocate a buffer. For some types of structures, like a fixed sized C structure, the buffer size should equal the size of the structure. If
dfltsize() is set to this value, then the caller may not need to specify the buffer’s length to routines in which a buffer is passed.
dfltsize() can be 0 or less; however, if
tpalloc() or
tprealloc() is called and its
size parameter is also less than or equal to 0, then the routine will fail. It is not recommended to set
dfltsize() to a value less than 0.
_tminitbuf() is called from within
tpalloc() after a buffer has been allocated. It is passed a pointer to the new buffer,
ptr, along with its size so that the buffer can be initialized appropriately.
len is the larger of the length passed into
tpalloc() and the default specified in
dfltsize() in that type’s switch entry. Note that
ptr will never be NULL due to the semantics of
tpalloc() and
tprealloc(). Upon successful return,
ptr is returned to the caller of
tpalloc().
Upon success, _tminitbuf() returns 1. If the function fails, it returns -1 causing
tpalloc() to also return failure setting
tperrno to
TPESYSTEM.
_tmreinitbuf() behaves the same as
_tminitbuf() except it is used to reinitialize a reallocated buffer. It is called from within
tprealloc() after the buffer has been reallocated.
Upon success, _tmreinitbuf() returns 1. If the function fails, it returns -1 causing
tprealloc() to also return failure setting
tperrno to
TPESYSTEM.
_tmuninitbuf() is called by
tpfree() before the data buffer is freed.
_tmuninitbuf() is passed a pointer to the application portion of a data buffer, along with its size, and can be used to clean up any structures or state information associated with that buffer.
ptr will never be NULL due to
tpfree()’s semantics. Note that
_tmuninitbuf() should not free the buffer itself. The
tpfree() function is called automatically for any
FLD_PTR fields in the data buffer.
Upon success, _tmuninitbuf() returns 1. If the function fails, it returns -1 causing
tpfree() to print a log message.
_tmpresend() is called before a buffer is sent in
tpcall(),
tpacall(),
tpconnect(),
tpsend(),
tpbroadcast(),
tpnotify(),
tpreturn(), or
tpforward(). It is also called after
_tmroute() but before
_tmencdec(). If
ptr() is non-NULL, preprocessing is performed on a buffer before it is sent.
_tmpresend()’s first argument,
ptr, is the application data buffer passed into the send call. Its second argument,
dlen, is the data’s length as passed into the send call. Its third argument,
mdlen, is the actual size of the buffer in which the data resides.
If _tmpresend2() is not NULL,
_tmpresend() is not called and
_tmpresend2() is called in its place.
Upon success, _tmpresend() returns the amount of data to be sent. If the function fails, it returns -1 causing
_tmpresend()’s caller to also return failure setting
tperrno to
TPESYSTEM.
_tmpostsend() is called after a buffer is sent in
tpcall(),
tpbroadcast(), tpnotify(), tpacall(), tpconnect(), or
tpsend(). This routine allows any post-processing to be performed on a buffer after it is sent and before the function returns. Because the buffer passed into the send call should not be different upon return,
_tmpostsend() is called to repair a buffer changed by
_tmpresend(). This function’s first argument,
ptr, points to the data sent as a result of
_tmpresend(). The data’s length, as returned from
_tmpresend(), is passed in as this function’s second argument,
dlen. The third argument,
mdlen, is the actual size of the buffer in which the data resides. This routine is called only when
ptr is non-NULL.
_tmpostrecv() is called after a buffer is received, and possibly decoded, in
tpgetrply(), tpcall(), tprecv(), or in the Oracle Tuxedo ATMI system’s server abstraction, and before it is returned to the application. If
ptr is non-NULL,
_tmpostrecv() allows post-processing to be performed on a buffer after it is received and before it is given to the application. Its first argument,
ptr, points to the data portion of the buffer received. Its second argument,
dlen, specifies the data’s size coming in to
_tmpostrecv(). The third argument,
mdlen, specifies the actual size of the buffer in which the data resides.
If _tmpostrecv() changes the data length in post-processing, it must return the data’s new length. The length returned is passed up to the application in a manner dependent on the call used (for example,
tpcall() sets the data length in one of its arguments for the caller to check upon return).
On success, _tmpostrecv() returns the size of the data the application should be made aware of when the buffer is passed up from the corresponding receive call. If the function fails, it returns -1 causing
_tmpostrecv()’s caller to return failure, setting
tperrno to
TPESYSTEM.
_tmencdec() is used to encode/decode a buffer sent/received over a network to/from a machine having different data representations. The Oracle Tuxedo ATMI system recommends the use of XDR; however, any encoding/decoding scheme can be used that obeys the semantics of this routine.
This function is called by tpcall(),
tpacall(),
tpbroadcast(),
tpnotify(),
tpconnect(),
tpsend(),
tpreturn(), or
tpforward() to encode the caller’s buffer only when it is being sent to an “unlike” machine. In these calls,
_tmencdec() is called after both
_tmroute() and
_tmpresend(), respectively. Recall from the description of
_tmpresend() that the buffer passed into
_tmencdec() contains no pointers to data that is not contiguous to the buffer.
On the receiving end, tprecv(),
tpgetrply(), the receive half of
tpcall() and the server abstraction all call
_tmencdec() to decode a buffer after they have received it from an “unlike” machine but before calling
_tmpostrecv().
_tmencdec()’s first argument,
op, specifies whether the function is encoding or decoding data.
op can be one of
TMENCODE or
TMDECODE.
When op is
TMENCODE,
encobj points to a buffer allocated by the Oracle Tuxedo ATMI system where the encoded version of the data will be copied. The unencoded data resides in
obj. That is, when
op is
TMENCODE,
_tmencdec() transforms
obj to its encoded format and places the result in
encobj. The size of the buffer pointed to by
encobj is specified by
elen and is at least four times the size of the buffer pointed to by
obj whose length is
olen.
olen is the length returned by
_tmpresend. _tmencdec() returns the size of the encoded data in
encobj (that is, the amount of data to actually send).
_tmencdec() should not free either of the buffers passed into the function.
When op is
TMDECODE,
encobj points to a buffer allocated by the Oracle Tuxedo ATMI system where the encoded version of the data resides as read off a communication endpoint. The length of the buffer is
elen.
obj points to a buffer that is at least the same size as the buffer pointed to by
encobj into which the decoded data is copied. The length of
obj is
olen. As
obj is the buffer ultimately returned to the application, this buffer may be grown by the Oracle Tuxedo ATMI system before calling
_tmencdec() to ensure that it is large enough to hold the decoded data.
_tmencdec() returns the size of the decoded data in
obj. After
_tmencdec() returns,
_tmpostrecv() is called with
obj passed as its first argument,
_tmencdec()’s return value as its second, and
olen as its third.
_tmencdec() should not free either of the buffers passed into the function.
_tmencdec() is called only when non-NULL data needs to be encoded or decoded.
On success, _tmencdec() returns a non-negative length as described above. If the function fails, it returns -1 causing
_tmencdec()’s caller to return failure, setting
tperrno to
TPESYSTEM.
routing_name is the logical name of the routing criteria (as specified in the
UBBCONFIG file) and is associated with every service that needs data dependent routing.
service is the name of the service for which the request is being made. The parameter
data points to the data that is being transmitted in the request and
len is its length. Unlike the other routines described in these pages,
_tmroute() is called even when
ptr is NULL. The
group parameter is used to return the name of the group to which the request should be routed. This group name must match one of the group names listed in the
UBBCONFIG file (and one that is active at the time the group is chosen). If the request can go to any available server providing the specified service,
group should be set to the NULL string and the function should return 1.
Upon success, _tmroute() returns 1. If the function fails, it returns -1 causing
_tmroute()’s caller to also return failure; as a result,
tperrno is set to
TPESYSTEM. If
_tmroute() fails because a requested server or service is not available,
tperrno is set to
TPENOENT.
If group is set to the name of an invalid server group, the function calling
_tmroute() will return an error and set
tperrno to
TPESYSTEM.
_tmfilter() is called by the EventBroker server to analyze the contents of a buffer posted by
tppost(). An expression provided by the subscriber (
tpsubscribe()) is evaluated with respect to the buffer’s contents. If the expression is true,
_tmfilter() returns 1 and the EventBroker performs the subscription’s notification action. Otherwise, if
_tmfilter() returns 0, the EventBroker does not consider this posting a “match” for the subscription.
If exprlen is -1,
expr is interpreted as a NULL-terminated character string. Otherwise
expr is interpreted as
exprlen bytes of binary data. An
exprlen of 0 indicates no expression.
_tmformat() is called by the EventBroker server to convert a buffer’s data into a printable string, based on a format specification named
fmt. The EventBroker converts posted buffers to strings as input for
userlog or
system notification actions.
On success, _tmformat() returns a non-negative integer. 1 means success, 2 means the output string is truncated. If the function fails, it returns -1 and stores an empty string in
result.
_tmpresend2() is called before a buffer is sent in
tpcall(),
tpacall(),
tpconnect(),
tpsend(),
tpbroadcast(),
tpnotify(),
tpreturn(), and
tpforward(). It is also called after
_tmroute() but before
_tmencdec(). If
iptr is not NULL, preprocessing is performed on a buffer before the buffer is sent.
The first argument to _tmpresend2(),
iptr, is the application data buffer passed into the send call. The second argument,
ilen, is the length of the data as passed into the send call. The third argument,
mdlen, is the actual size of the buffer in which the data resides.
Unlike _tmpresend(),
_tmpresend2() receives a pointer,
optr, which is used to pass a pointer to a buffer into which the data in
iptr can be placed, after any required processing is done. Use this pointer if you want to use a new buffer for the data modified by
_tmpresend2() instead of modifying the input buffer. The fifth argument,
olen, is the size of the
optr buffer. The sixth argument,
flags, tells
_tmpresend2() whether the buffer being processed is the parent buffer (the one being sent). The
flags argument is returned by
_tmpresend2() to indicate the results of processing.
The size of the optr buffer may not be large enough for successful postprocessing. If more space is required,
_tmpresend2() returns the negative absolute value of the desired buffer size. All
olen bytes of the
optr buffer are preserved. The calling routine then resizes the buffer and calls
_tmpresend2() a second time.
_tmpresend2() was successful: the processed data is in the buffer referenced by
iptr, and the return value contains the length of the data to be sent.
_tmpresend2() was successful: the processed data is in the buffer referenced by
optr, and the return value contains the length of the data to be sent.
If TMUSEOPTR is returned, the processing done after messages are transmitted is different from the processing done by
_tmpresend(): the
iptr buffer remains unchanged and
_tmpostsend() is not called. If
TMUSEIPTR is returned,
_tmpostsend() is called, as it is called for
_tmpresend(). It is the responsibility of the caller to allocate and to free or cache the
optr buffer.
The _tmpresend2() function ensures that when a function returns, the data in the buffer to be sent can be sent without further processing. Because
_tmencdec() is called only if the buffer is being sent to a dissimilar machine,
_tmpresend2() ensures, upon return, that all data is stored contiguously in the buffer to be sent.
Upon success, _tmpresend2() returns the amount of data to be sent or, if a larger buffer is needed, the negative absolute value of the desired buffer size. If the function fails, it returns -1, causing the caller of
_tmpresend2() to also return failure, setting
tperrno to
TPESYSTEM.
_tmconvmb() is called after
tmpostrecv() to convert multibyte data from a source encoding to a target encoding. The first argument to
_tmconvmb(),
ibufp, is a pointer to a stream of bytes—the multibyte data—to be converted. The second argument,
ilen, is the number of bytes in
ibufp. The third argument,
enc_name, is one of the encoding names used in the processing. For an MBSTRING buffer, the third argument is the target encoding name; for an FML32 buffer, the third argument is the source encoding name.
_tmconvmb() receives a pointer,
obufp, which is used to pass a pointer to a buffer into which the data in
ibufp can be placed, after any required code-set encoding conversion is done. Use this pointer if you want to use a new buffer for the data converted by
_tmconvmb() instead of modifying the input pointer. The fifth argument,
olen, is the size of the
obufp buffer. The
flags argument is returned by
_tmconvmb() to indicate the results of processing.
The size of the obufp buffer may not be large enough for successful post processing. If more space is required,
_tmconvmb() returns the negative absolute value of the desired buffer size. All
ilen bytes of the
ibufp buffer are preserved. The calling routine then resizes the buffer and calls
_tmconvmb() a second time.
_tmconvmb() was successful: the processed data is in the buffer referenced by
ibufp, and the return value contains the length of the converted data to be passed to the service.
_tmconvmb() was successful: the processed data is in the buffer referenced by
obufp, and the return value contains the length of the data to be converted. It is the responsibility of the caller to allocate and to free or cache the
obufp buffer.
Upon success, _tmconvmb() returns the amount of data buffer that had code-set encoding conversion or, if a larger buffer is needed, the negative absolute value of the desired buffer size. If the function fails, it returns -1, causing the caller of
_tmconvmb() to also return failure, setting
tperrno to
TPESYSTEM.
tpacall(3c),
tpalloc(3c),
tpcall(3c),
tpconnect(3c),
tpdiscon(3c),
tpfree(3c),
tpgetrply(3c),
tpgprio(3c),
tprealloc(3c),
tprecv(3c),
tpsend(3c),
tpsprio(3c),
tptypes(3c),
tuxtypes(5)
catgets() attempts to read message
msg_num, in set
set_num, from the message catalogue identified by
catd.
catd is a catalogue descriptor returned from an earlier call to
catopen().
s points to a default message string which will be returned by
catgets() if the identified message catalogue is not currently available.
If the identified message is retrieved successfully, catgets() returns a pointer to an internal buffer area containing the NULL terminated message string. If the call is unsuccessful because the message catalogue identified by
catd is not currently available, a pointer to
s is returned.
catopen(),
catclose()—Opens/closes a message catalogue.
catopen() opens a message catalogue and returns a catalogue descriptor.
name specifies the name of the message catalogue to be opened. If
name contains a “
/” then
name specifies a pathname for the message catalogue. Otherwise, the environment variable
NLSPATH is used. If
NLSPATH does not exist in the environment, or if a message catalogue cannot be opened in any of the paths specified by
NLSPATH, then the default path is used (see
nl_types(5)).
The NLSPATH variable provides both the location of message catalogues, in the form of a search path, and the naming conventions associated with message catalogue files. For example:
The metacharacter % introduces a substitution field, where
%L substitutes the current setting of the
LANG environment variable (see following section), and
%N substitutes the value of the
name parameter passed to
catopen(). Thus, in the above example,
catopen() will search in
/nlslib/$LANG/name.cat, then in
/nlslib/
name/
$LANG, for the required message catalogue.
NLSPATH will normally be set up on a system wide basis (for example, in
/etc/profile) and thus makes the location and naming conventions associated with message catalogues transparent to both programs and users.
The LANG environment variable provides the ability to specify the user’s requirements for native languages, local customs and character set, as an ASCII string in the form
LANG=language[_territory[.codeset]]
If the LANG variable is not set then the value of
LC_MESSAGES as returned by
setlocale(3c) is used. If this is
NULL then the default path as defined in
nl_types(5) is used.
oflag() is reserved for future use and should be set to 0. The results of setting this field to any other value are undefined.
catclose() closes the message catalogue identified by
catd.
If successful, catopen() returns a message catalogue descriptor for use on subsequent calls to
catgets() and
catclose(). Otherwise
catopen() returns
(nl_catd) -1.
catclose() returns 0 if successful, otherwise -1.
decimal()—Decimal conversion and arithmetic routines.
It should never be necessary for programmers to directly access the dec_t structure, but it is presented here nevertheless to give an understanding of the underlying data structure. If large amounts of decimal data need to be stored, the
stdecimal() and
lddecimal() functions may be used to obtain a more compact format.
dectoasc(),
dectoint(),
dectolong(),
dectodbl(), and
dectoflt() allow the conversion of decimals to other data types.
deccvasc(),
deccvint(),
deccvlong(),
deccvdbl(), and
deccvflt() allow the conversion of other data types to the decimal data type.
deccmp() is the function which compares two decimals. It returns -1 if the first decimal is less than the second, 0 if the two decimals are equal, and 1 if the first decimal is greater than the second. A negative value other than -1 is returned if either of the arguments is invalid.
decadd(),
decsub(),
decmul(), and
decdiv() perform arithmetic operations on decimal numbers.
getURLEntityCacheDir() - Specifies a Xerces class method for getting the absolute path to the location where the DTD, schema and Entity files are cached.
getURLEntityCacheDir() is a method that is called to find out the location where the DTD, schema and Entity files are cached. It returns the absolute path to the cached file location. This method is exclusively used in conjunction with the following two Xerces objects:
GetURLEntityCaching() - Specifies a Xerces class method for getting the caching mechanism for DTD, schema and Entity files.
GetURLEntityCaching() is a method that is called to find out if caching of the DTD, schema and Entity files are turned on or off. It returns
true if caching is turned on and
false if caching is turned off. This method is exclusively used in conjunction with the following two Xerces objects:
gp_mktime()—Converts a
tm structure to a calendar time.
gp_mktime() converts the time represented by the
tm structure pointed to by
timeptr into a calendar time (the number of seconds since 00:00:00 Universal Coordinated Time—UTC, January 1, 1970).
The tm structure has the following format:
In addition to computing the calendar time, gp_mktime() normalizes the supplied
tm structure. The original values of the
tm_wday and
tm_yday components of the structure are ignored, and the original values of the other components are not restricted to the ranges indicated in the definition of the structure. On successful completion, the values of the
tm_wday and
tm_yday components are set appropriately, and the other components are set to represent the specified calendar time, but with their values forced to be within the appropriate ranges. The final value of
tm_mday is not set until
tm_mon and
tm_year are determined.
If tm_isdst is positive, the original values are assumed to be in the alternate time zone. If it turns out that the alternate time zone is not valid for the computed calendar time, then the components are adjusted to the main time zone. Likewise, if
tm_isdst is zero, the original values are assumed to be in the main time zone and are converted to the alternate time zone if the main time zone is not valid. If
tm_isdst is negative, the correct time zone is determined and the components are not adjusted.
gp_mktime() returns the specified calendar time. If the calendar time cannot be represented, the function returns the value (
time_t)-1.
tm_year of the tm structure must be for year 1970 or later. Calendar times before 00:00:00 UTC, January 1, 1970 or after 03:14:07 UTC, January 19, 2038 cannot be represented.
In the latter case, the TZ environment variable must be set. Note that in many installations,
TZ is set to the correct value by default when the user logs on. The default value for
TZ is
GMT0. The format for
TZ is the following:
Three or more bytes that designate the standard time zone (std) and daylight savings time time zone (
dst). Only
std is required. If
dst is missing, then daylight savings time does not apply in this locale. Uppercase and lowercase letters are allowed. Any characters except a leading colon (:), digits, a comma (,), a minus (-) or a plus (+) are allowed.
Indicates the value one must add to the local time to arrive at Coordinated Universal Time. The offset has the following form:
hh[:
mm[:
ss]]. The minutes (
mm) and seconds (
ss) are optional. The hour (
hh) is required and may be a single digit. The
offset following
std is required. If no
offset follows
dst, daylight savings time is assumed to be one hour ahead of standard time. One or more digits may be used; the value is always interpreted as a decimal number. The hour must be between 0 and 24, and the minutes (and seconds) if present, between 0 and 59. Out of range values may cause unpredictable behavior. If preceded by a “-”, the time zone is east of the Prime Meridian; otherwise it is west (which may be indicated by an optional preceding “+” sign).
The Julian day n (1
n 365). Leap days are not counted. That is, in all years, February 28 is day 59 and March 1 is day 60. It is impossible to refer to the occasional February 29.
Day d (0
d 6) of week
n of month
m in the year (1
n 5, 1
m 12), where week 5 means “the last
d-day in month
m,” which may occur in either the fourth or the fifth week). Week 1 is the first week in which day
d occurs. Day 0 (zero) is Sunday.
The time has the same format as
offset except that no leading sign (“-” or “+”) is allowed. The default, if
time is not specified, is 02:00:00.
ctime(3c),
getenv(3c),
timezone(4) in a UNIX system reference manual
nl_langinfo() returns a pointer to a NULL-terminated string containing information relevant to a particular language or cultural area defined in the programs locale. The manifest constant names and values of
item are defined by
langinfo.h.
returns a pointer to the string “Dim” if the identified language is French and a French locale is correctly installed; or “
Sun” if the identified language is English.
If setlocale() has not been called successfully, or if
langinf0() data for a supported language is either not available or
item is not defined therein, then
nl_langinfo() returns a pointer to the corresponding string in the C locale. In all locales,
nl_langinfo() returns a pointer to an empty string if
item contains an invalid setting.
Applications call rpc_sm_allocat3() to allocate memory within the RPC stub memory management scheme. The input parameter, size, specifies in bytes, the size of memory to be allocated. Before a call to this routine, the stub memory management environment must have been established. For service code that is called from the server stub, the stub itself normally establishes the necessary environment. When
rpc_sm_allocate() is used by code that is not called from the stub, the application must establish the required memory management environment by calling
rpc_sm_enable_allocate().
rpc_ss_allocate() is the exception-returning version of this function and has no status output parameter. No exceptions are raised.
The rpc_sm_client_free() routine releases memory allocated and returned from a client stub. The input parameter,
node_to_free, specifies a pointer to memory returned from a client stub. Note that in the ISO standard C environments,
idl_void_p_t is defined as void * and in other environments is defined as char *.
rpc_ss_client_free() is the exception-returning version of this function and has no status output parameter. No exceptions are raised.
rpc_sm_disable_allocate(),
rpc_ss_disable_allocate()—Releases resources and allocated memory within the stub memory management scheme.
The rpc_sm_disable_allocate() routine releases all resources acquired by a call to
rpc_sm_enable_allocate(), and any memory allocated by calls to
rpc_sm_allocate() after the call to
rpc_sm_enable_allocate() was made.
The rpc_sm_enable_allocate() and
rpc_sm_disable_allocate() routines must be used in matching pairs. Calling this routine without a previous matching call to
rpc_sm_enable_allocate() results in unpredictable behavior.
rpc_ss_disable_allocate() is the exception-returning version of this function and has no status output parameter. No exceptions are raised.
Applications can call rpc_sm_enable_allocate() to establish a stub memory management environment in cases where one is not established by the stub itself. A stub memory management environment must be established before any calls are made to
rpc_sm_allocate(). For service code called from the server stub, the stub memory management environment is normally established by the stub itself. Code that is called from other contexts needs to call
rpc_sm_enable_allocate() before calling
rpc_sm_allocate() (for example, if the service code is called directly instead of from the stub).
rpc_ss_enable_allocate() is the exception-returning version of this function and has no status output parameter. The following exceptions are raised by this routine:
Applications call rpc_sm_free() to release memory allocated by
rpc_sm_allocate(). The input parameter, node_to_free, specifies a pointer to memory allocated by
rpc_sm_allocate(). Note that in ISO standard C environments,
idl_void_p_t is defined as void * and in other environments is defined as char *.
Unpredictable behavior results if rpc_ss_free() is called with a pointer to memory not allocated by
rpc_sm_allocate() or memory allocated by
rpc_sm_allocate(), but not the first address of such an allocation.
The rpc_sm_set_client_alloc_free() routine overrides the default routines that the client stub uses to manage memory. The input parameters,
p_allocate and
p_free specify memory allocator and free routines. The default memory management routines are ISO C
malloc() and
free() except when the remote call occurs within server code in which case the memory management routines must be
rpc_ss_allocate() and
rpc_ss_free().
rpc_ss_set_client_alloc_free is the exception-returning version of this function and has no status output parameter. The following exceptions are raised by this routine:
rpc_sm_swap_client_alloc_free(),
rpc_ss_swap_client_alloc_free()—Exchanges current memory allocation and freeing mechanism used by client stubs with one supplied by client.
The rpc_sm_swap_client_alloc_free() routine exchanges the current allocate and free mechanisms used by the client stubs for routines supplied by the caller. The input parameters,
p_allocate and
p_free, specify new memory allocation and free routines. The output parameters,
p_p_old_allocate and
p_p_old_free return the memory allocation and free routines in use before the call to this routine.
rpc_ss_swap_client_alloc_free is the exception-returning version of this function and has no status output parameter. The following exceptions are raised by this routine:
setlocale() selects the appropriate piece of the program’s locale as specified by the
category and
locale arguments. The
category argument may have the following values:
These names are defined in the locale.h header file. For the Oracle Tuxedo ATMI system compatibility functions,
setlocale() allows only a single
locale for all categories. Setting any category is treated the same as
LC_ALL, which names the program’s entire locale.
A value of "" for locale specifies that the locale should be taken from an environment variable. The environment variable
LANG is checked for a locale.
If a pointer to a string is given for locale,
setlocale() attempts to set the locale for all the categories to
locale. The
locale must be a simple locale, consisting of a single locale. If
setlocale() fails to set the locale for any category, a NULL pointer is returned and the program’s locale for all categories is not changed. Otherwise, locale is returned.
A NULL pointer for locale causes
setlocale() to return the current locale associated with the
category. The program’s locale is not changed.
$TUXDIR/locale/C/LANGINFO - time and money database for the C locale
$TUXDIR/locale/locale/* - locale specific information for each
locale $TUXDIR/locale/C/*_CAT - text messages for the C locale
ctime(3c),
ctype(3c),
getdate(3c),
localeconv(3c),
strftime(3c),
strtod(3c),
printf(3S),
environ(5) in a UNIX system reference manual
setURLEntityCacheDir() - Specifies a Xerces class method for setting the directory where the DTD, schema and Entity files are to be cached.
setURLEntityCacheDir() is method called when caching is turned on and you want the DTD, schema and Entity files to be cached to a specific directory.
cachedir specifies the absolute path to the location of the files.
setURLEntityCaching() - Specifies a Xerces class method for setting or unsetting DTD, schema or Entity file caching for the XML parser.
setURLEntityCaching()is a method that caches the DTD, schema and Entity files by default. It allows you to turn caching of the files on or off.
UseCache is set to
false if caching is to be turned off and set to
true if caching is to be turned on. This method is exclusively used in conjunction with the following two Xerces objects:
strerror maps the error number in
errnum to an error message string, and returns a pointer to that string.
strerror uses the same set of error messages as
perror. The returned string should not be overwritten.
perror(3) in a UNIX system reference manual
strftime() places characters into the array pointed to by
s as controlled by the string pointed to by
format. The
format string consists of zero or more directives and ordinary characters. All ordinary characters (including the terminating NULL character) are copied unchanged into the array. For
strftime(), no more than
maxsize characters are placed into the array.
If format is (char *)0, then the locale’s default format is used. The default format is the same as
"%c".
The difference between %U and
%W lies in which day is counted as the first of the week. Week number 01 is the first week in January starting with a Sunday for
%U or a Monday for
%W. Week number 00 contains those days before the first Sunday or Monday in January for
%U and
%W, respectively.
By default, the output of strftime(), appears in U.S. English. The user can request that the output of
strftime() be in a specific language by setting the
locale for
category LC_TIME in
setlocale().
The example illustrates the use of strftime(). It shows what the string in
str would look like if the structure pointed to by
tmptr contains the values corresponding to Thursday, August 28, 1986 at 12:44:36 in New Jersey.
$TUXDIR/locale/locale/LANGINFO—file containing compiled locale-specific date and time information
tpabort()—Routine for aborting current transaction.
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.
Upon failure, tpabort() returns -1 and sets
tperrno to indicate the error condition.
Upon failure, tpabort() sets
tperrno to one of the following values:
flags is not equal to 0. The caller’s transaction is not affected.
tpabort() was called improperly (for example, by a participant).
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().
tpacall()—Routine for sending a service request.
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
tpspri(). 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 subtype of
data must match one of the types and subtypes recognized by
svc. Note that for each request sent while in transaction mode, a corresponding reply must ultimately be received.
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.
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.
Upon failure, tpacall() returns a value of -1 and sets
tperrno to indicate the error condition.
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.)
Cannot send to svc because it does not exist or is a conversational service.
svc belongs to a server that does not support transactions and
TPNOTRAN was not set.
tpadmcall() is used to retrieve and update attributes of an unbooted application. It may also be used in an active application to perform direct retrievals of a limited set of attributes without requiring communication to an external process. This function provides sufficient capability such that complete system configuration and administration can take place through system provided interface routines.
inbuf is a pointer to an FML32 buffer previously allocated with
tpalloc() that contains the desired administrative operation and its parameters.
outbuf is the address of a pointer to the FML32 buffer that should contain the results.
outbuf must point to an FML32 buffer originally allocated by
tpalloc(). If the same buffer is to be used for both sending and receiving,
outbuf should be set to the address of
inbuf.
Currently, tpadmcall()’s last argument,
flags, is reserved for future use and must be set to 0.
MIB(5) should be consulted for generic information on construction of administrative requests.
TM_MIB(5) and
APPQ_MIB(5) should be consulted for information on the classes that are accessible through
tpadmcall().
Use of the TA_OCCURS attribute on
GET requests is not supported when using
tpadmcall().
GETNEXT requests are not supported when using
tpadmcall().
Upon failure, tpadmcall() sets
tperrno to one of the following values:
|
Note:
|
Except for TPEINVAL, the caller’s output buffer, outbuf, will be modified to include TA_ERROR, TA_STATUS, and possibly TA_BADFLD attributes to further qualify the error condition. See MIB(5), TM_MIB(5), and APPQ_MIB(5) for an explanation of possible error codes returned in this fashion.
|
tpadmcall() was called with the
TUXCONFIG environment variable pointing to a different release version configuration file.
${TUXDIR}/lib/libtmib.a,
${TUXDIR}/lib/libqm.a,
${TUXDIR}/lib/libtmib.so.<rel>,
${TUXDIR}/lib/libqm.so.<rel>,
${TUXDIR}/lib/libtmib.lib,
${TUXDIR}/lib/libqm.lib
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.
tpadvertise() advertises
svcname for the server (or the set of servers sharing the caller’s MSSQ set).
svcname should be 127 characters or less, but cannot be NULL or the NULL string (“”). (See *SERVICES section of
UBBCONFIG(5).)
func is the address of an Oracle Tuxedo ATMI 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 (see
servopts(5)) can be up to 128 characters long. Names longer than 127 characters are accepted and truncated to 127 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).
Upon failure, tpadvertise() returns -1 and sets
tperrno to indicate the error condition.
Upon failure, tpadvertise() sets
tperrno to one of the following values:
svcname is NULL or the NULL string (“”),or begins with a “.” or
func is NULL.
svcname cannot be advertised because of space limitations. (See
MAXSERVICES in the
RESOURCES section of
UBBCONFIG(5).)
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).
tpadvertise() was called in an improper context (for example, by a client).
tpalloc()—Routine for allocating typed buffers.
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.
Because some buffer types require initialization before they can be used, tpalloc() initializes a buffer (in an Oracle Tuxedo ATMI 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.
Upon failure, tpalloc() sets
tperrno to one of the following values:
No entry in tmtype_sw matches
type and, if non-NULL,
subtype.
tpappthrinit() - Routine for creating and initializing a new Tuxedo context in an application-created server thread
tpappthrinit() creates a new Tuxedo context in an application-created server thread. The context created by
tpappthrinit() connects to the domain that the application server is in. It also sets the context of current application thread to the newly created context.
After tpappthrinit() successfully returns, the application-created server thread can initiate service requests and define transactions.
After tpappthrinit() successfully returns, the application-created server thread can get the current context by calling
tpgetctxt() and pass it as a
tpsetctxt() parameter called by another application-created server thread to associate itself to the context.
The tpappthrinit() argument,
tpthrinfo, is a pointer to a
TPINIT buffer type and a NULL subtype.
TPINIT is a buffer type is defined in the
atmi.h header file. The buffer must be allocated via
tpalloc() prior to calling
tpappthrinit(). It should be released using
tpfree() after calling
tpappthrinit().
Please refer to the tpinit() routine for description of
TPINIT structure. The
tpthrinfo members
usrname,
data, and
datalen are used to pass authentication information to
tpappthrinit(). When
SECURITY is set to
USER_AUTH or above, the
TPINIT buffer passed to
tpappthrinit() is passed to the authentication service configured for the application. Whether or not a particular field in the
TPINIT buffer is used by the authentication services depends on the implementation. At security levels
NONE and
APP_PW, the
tpthrinfo members
cltname,
grpname, and
passwd are currently not used and must be set to 0-length strings. The
TPINIT member
flags is also not used by
tpappthrinit().
tpappthrinit() can only be called in an application created server-thread. The server must be built using the buildserver
-t option.
Upon failure, tpappthrinit() sets
tperrno to one of the following values:
tpappthrinit() has been called improperly. For example: it is called in client program, or service routine, or the server is not built with the
buildserver -t option.
tpappthrterm() - Routine for terminating Tuxedo context created by
tpappthrinit() in an application-created server thread.
tpappthrterm() removes the current Tuxedo context, and sets the context of a current application-created server thread to
TPNULLCONTEXT. If the application thread is in transaction mode, then the transaction is rolled back. When
tpappthrterm() returns successfully, the caller can no longer perform most Tuxedo ATMI operations. Any outstanding conversations are immediately disconnected.
tpappthrterm() can only be used to terminated a context which is created by
tpappthrinit(), and it can only be invoked in an application-created server thread, the server must be built using the
buildserver -t option .
|
Notes:
|
tpappthrterm() is not allowed in service routine, or in application-created server thread which is currently associated with a server-dispatched context.
|
Upon failure, tpappthrterm() returns
-1 and sets
tperrno to indicate the error condition.
Upon failure, tpappthrterm() sets
tperrno to one of the following values:
tpappthrterm() has been called improperly. For example, it is called in client program, or service routine, or it is called in an application-created server thread which is currently associated with a server-dispatched context.
tpatz() checks whether users are allowed to access specified resources. This function can only be called in server side and can be called with multiple threads. This API forwards requests to authorization service for authorization.
tpatz() can work with servers (such as
XAUTHSVR or
EAUTHSVT) to complete authorization.
restype is the resource type defined by users or Tuxedo system.
resname is a string pointer indicating the resource name.
action is resources operation.
flag is reserved.
tpbegin()—Routine for beginning a transaction.
tpbegin()’s first argument,
timeout, 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 by the system).
Currently, tpbegin()’s second argument,
flags, is reserved for future use and must be set to 0.
Upon failure, tpbegin() returns -1 and sets
tperrno to indicate the error condition.
Upon failure, tpbegin() sets
tperrno to one of the following values:
tpbegin() was called in an improper context (for example, the caller is already in transaction mode).
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(). See
buildserver() for details on linking resource managers that meet the XA interface into a server such that operations performed by that resource manager are part of an Oracle Tuxedo ATMI system transaction.
tpbroadcast() allows a client or server to send unsolicited messages to registered clients within the system. The target client set consists of those clients matching identifiers passed to
tpbroadcast(). Wildcards can be used in specifying identifiers.
lmid,
usrname, and
cltname are logical identifiers used to select the target client set. A NULL value for any argument constitutes a wildcard for that argument. A wildcard argument matches all client identifiers for that field. A 0-length string for any argument matches only 0-length client identifiers. Each identifier must meet the size restrictions defined for the system to be considered valid, that is, each identifier must be between 0 and
MAXTIDENT characters in length.
The data portion of the request is pointed to by data, a buffer previously allocated by
tpalloc().
len specifies how much of
data to send. Note that if
data points to a buffer type that does not require a length to be specified (for example, an
FML fielded buffer), then
len is ignored (and may be 0). Also,
data may be NULL, in which case
len is ignored. The buffer passes through the typed buffer switch routines just as any other outgoing or incoming message would; for example, encode/decode are performed automatically.
Upon failure, tpbroadcast() returns -1 and sets
tperrno to indicate the error condition.
Upon failure, tpbroadcast()sends no broadcast messages to application clients and sets
tperrno to one of the following values:
The interfaces described in tpnotify(3c) are supported on native site UNIX-based processors. In addition, the routines
tpbroadcast() and
tpchkunsol() as well as the function
tpsetunsol() are supported on UNIX and MS-DOS workstation processors.
tpcall()—Routine for sending service request and awaiting its reply.
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
tpspri(). 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 subtype of
idata must match one of the types and subtypes 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. As of release 6.4, the default allocation for buffers is 1024 bytes. Also, historical information is maintained on recently used buffers, allowing a buffer of optimal size to be reused as a return buffer.
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.
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.
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().
Upon failure, tpcall() returns -1 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(3c) reference page for more information.
Upon failure, tpcall() sets
tperrno to one of the following values. (Unless otherwise noted, failure does not affect the caller’s transaction, if one exists.)
Cannot send to svc because it does not exist, or it is a conversational service, or the name provided begins with a dot (.).
Either the type and subtype of the reply are not known to the caller; or, TPNOCHANGE was set in
flags and the type and subtype of *
odata do not match the type and subtype 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.
svc belongs to a server that does not support transactions and
TPNOTRAN was not set.
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 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.
A service routine encountered an error either in tpreturn(3c) or
tpforward(3c) (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 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(3c),
tpalloc(3c),
tperrordetail(3c),
tpforward(3c),
tpfree(3c),
tpgprio(3c),
tprealloc(3c),
tpreturn(3c),
tpsprio(3c),
tpstrerrordetail(3c),
tptypes(3c)
tpcancel()—Routine for canceling a call descriptor for outstanding reply.
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.
Upon failure, tpcancel() returns -1 and sets
tperrno to indicate the error condition.
Upon failure, tpcancel() sets
tperrno to one of the following values:
cd is an invalid descriptor.
cd() is associated with the caller’s transaction.
cd remains valid and the caller’s current transaction is not affected.
tpchkauth()—Routine for checking if authentication required to join an application.
tpchkauth() checks if authentication is required by the application configuration. This is typically used by application clients prior to calling
tpinit() to determine if a password should be obtained from the user.
Upon success, tpchkauth() returns one of the following non-negative values:
Upon failure, tpchkauth() returns -1 and sets
tperrno to indicate the error condition.
Upon failure, tpchkauth() sets
tperrno to one of the following values:
tpchkauth() is available only on sites running release 4.2 or later.
tpchkunsol() is used by a client to trigger checking for unsolicited messages. Calls to this routine in a client using signal-based notification do nothing and return immediately. This call has no arguments. Calls to this routine can result in calls to an application-defined unsolicited message handling routine by the Oracle Tuxedo ATMI system libraries.
Upon successful completion, tpchkunsol() returns the number of unsolicited messages dispatched; otherwise it returns -1 and sets
tperrno to indicate the error condition.
Upon failure, tpchkunsol() sets
tperrno to one of the following values:
tpchkunsol() was called in an improper context (for example, from within a server).
The interfaces described in tpnotify(3c) are supported on native site UNIX-based processors. In addition, the routines
tpbroadcast() and
tpchkunsol() as well as the function
tpsetunsol() are supported on UNIX and MS-DOS workstation processors.
tpclose()—Routine for closing a resource manager.
tpclose() tears down the association between the caller and the resource manager to which it is linked. Since resource managers differ in their
close semantics, the specific information needed to close a particular resource manager is placed in a configuration file.
Upon failure, tpclose() returns -1 and sets
tperrno to indicate the error condition.
Upon failure, tpclose() fails and sets
tperrno to one of the following values:
tpclose() was called in an improper context (for example, while the caller is in transaction mode).
tpcommit()—Routine for committing current transaction.
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 (see
tpscmt(3c)),
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).
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.
tpcommit() must be called after all connections associated with the caller’s transaction are closed (otherwise
TPEABORT is returned, the transaction is aborted and these connections are disconnected in a disorderly fashion with a
TPEV_DISCONIMM event). Connections opened before
tpbegin() or with the
TPNOTRAN flag (that is, connections not in transaction mode) are not affected by calls to
tpcommit() or
tpabort().
Currently, tpcommit()’s sole argument,
flags, is reserved for future use and must be set to 0.
Upon failure, tpcommit() returns -1 and sets
tperrno to indicate the error condition.
Upon failure, tpcommit() sets
tperrno to one of the following values:
flags is not equal to 0. The caller’s transaction is not affected.
tpcommit() was called in an improper context (for example, by a participant).
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(). See
buildserver(1) for details on linking resource managers that meet the XA interface into a server such that operations performed by that resource manager are part of an Oracle Tuxedo ATMI system transaction.
tpconnect()—Routine for establishing a conversational service connection.
tpconnect() allows a program to set up a half-duplex connection to a conversational service,
svc. The name must be one of the conversational service names posted by a conversational server.
As part of setting up a connection, the caller can pass application-defined data to the listening program. If the caller chooses to pass data, then data must point to a buffer previously allocated by
tpalloc().
len specifies how much of the buffer to send. 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). Also,
data can be NULL in which case
len is ignored (no application data is passed to the conversational service). The type and subtype of
data must match one of the types and subtypes recognized by
svc.
data and
len are passed to the conversational service via the
TPSVCINFO structure with which the service is invoked; the service does not have to call
tprecv() to get the data.
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.
Upon successful completion, tpconnect() returns a descriptor that is used to refer to the connection in subsequent calls. Otherwise it returns -1 and sets
tperrno to indicate the error condition.
Upon failure, tpconnect() sets
tperrno to one of the following values. (Unless otherwise noted, failure does not affect the caller’s transaction, if one exists.)
Invalid arguments were given (for example, svc is NULL,
data is non-NULL and does not point to a buffer allocated by
tpalloc(),
TPSENDONLY or
TPRECVONLY was not specified in
flags, or
flags are otherwise invalid).
If a transaction timeout has occurred, then, with one exception, any attempts to start new conversations, 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).
svc belongs to a program that does not support transactions and
TPNOTRAN was not set.
tpconvert()—Converts structures to/from string representations.
tpconvert() converts the string representation of interface structures (
strrep) to or from the binary representation (
binrep).
Note that unequal string versions of TPTRANID and
XID values may be considered
equal by the system when accessing
TM_MIB(5) classes that allow these values as key fields (for example,
T_TRANSACTION or
T_ULOG). Therefore, string values for these data types should not be fabricated or manipulated by application programs.
TM_MIB(5) guarantees that only objects matching the global transaction identified by the string are returned when one of these values is used as a key field.
Upon failure, tpconvert() returns -1 and sets
tperrno to indicate the error condition.
tpconvmb()—Converts encoding of characters in an input buffer to a named target encoding.
The bufp argument is a valid pointer to an MBSTRING typed buffer message. This pointer will be reallocated internally if the size of the buffer is insufficient to handle the output data of the converted buffer.
The len argument, on input, contains the number of bytes that need to be converted. Upon successful completion of conversion it will contain the number of bytes used in bufp.
The target_encoding argument is the target codeset encoding name used to convert the typed buffer provided in the bufp message.
The flags argument is not used by the Tuxedo conversion code. It will be passed along to the buffer type switch function for user defined conversion functions.
target_encoding,
len, or
bufp arguments are NULL.
len or
target_encoding is invalid.
bufp translates to a Tuxedo buffer that does not have a buffer typeswitch conversion function
tpcryptpw()—Encrypts the application password in an administrative request.
tpcryptpw() is used to encrypt the application password stored in an administrative request buffer prior to sending the request for servicing. Application passwords are stored as string values using the FML32 field identifier
TA_PASSWORD. This encryption is necessary to insure that clear text passwords are not compromised and that appropriate propagation of the update can take place to all active application sites. Additional system fields may be added to the callers buffer and existing fields may be modified to satisfy the request.
Upon failure, tpcryptpw() returns -1 and sets
tperrno to indicate the error condition.
Upon failure, tpcryptpw() sets
tperrno to one of the following values:
tpdequeue() takes a message for processing from the queue named by
qname in the
qspace queue space.
data is the address of a pointer to the buffer into which a message is read, and
len points to the length of that message. *
data must point to a buffer originally allocated by
tpalloc(). If a message is larger than the buffer passed to
tpdequeue, the buffer is increased in size to accommodate the message. To determine whether a message buffer changed in size, compare its (total) size before
tpdequeue() was issued with *
len. If *
len is larger, then the buffer has grown; otherwise, the buffer has not changed size. Note that *
data may change for reasons other than the buffer’s size increased. If *
len is 0 upon return, then the message dequeued 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.
The message is dequeued in transaction mode if the caller is in transaction mode and the TPNOTRAN flag is not set. This has the effect that if
tpdequeue() returns successfully and the caller’s transaction is committed successfully, then the message is removed from the queue. If the caller’s transaction is rolled back either explicitly or as the result of a transaction timeout or some communication error, then the message will be left on the queue (that is, the removal of the message from the queue is also rolled back). It is not possible to enqueue and dequeue the same message within the same transaction.
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 structure) is specified.
When this flag is set, the type of the buffer pointed to by *data is not allowed to change. 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. That is, the type and subtype of the dequeued message must match the type and subtype of the buffer pointed to by *
data.
If tpdequeue() returns successfully, the application can retrieve additional information about the message using the
ctl data structure. The information may include the message identifier for the dequeued message; a correlation identifier that should accompany any reply or failure message so that the originator can correlate the message with the original request; the quality of service the message was delivered with, the quality of service any replies to the message should be delivered with; the name of a reply queue if a reply is desired; and the name of the failure queue on which the application can queue information regarding failure to dequeue the message. These are described below.
The TPQCTL structure is used by the application program to pass and retrieve parameters associated with dequeuing the message. The
flags element of
TPQCTL is used to indicate what other elements in the structure are valid.
On input to tpdequeue(), the following elements may be set in the
TPQCTL structure:
Note that each tpdequeue() request specifying the
TPQWAIT control parameter requires that a queue manager (
TMQUEUE) action object be available if a message satisfying the condition is not immediately available. If an action object is not available, the
tpdequeue() request fails. The number of available queue manager actions are specified when a queue space is created or modified. When a waiting dequeue request completes, the associated action object associated is made available for another request.
When a thread is non-destructively dequeuing a message using TPQPEEK, the message may not be seen by other non-blocking dequeuers for the brief time the system is processing the non-destructive dequeue request. This includes dequeuers using specific selection criteria (such as message identifier and correlation identifier) that are looking for the message currently being non-destructively dequeued.
On output from tpdequeue(), the following elements may be set in the
TPQCTL structure:
The following is a list of valid bits for the flags parameter controlling output information from
tpdequeue(). For any of these bits, if the flag bit is turned on when
tpdequeue() is called, the associated element in the structure is populated with the value provided when the message was queued, and the bit remains set. If a value is not available or the bit is not set when
tpdequeue() is called,
tpdequeue() completes with the flag turned off.
If this flag is set, the call to tpdequeue() is successful, and the message was queued with an explicit priority, then the priority is stored in
ctl−>priority. The priority is in the range 1 to 100, inclusive, and the higher the number, the higher the priority (that is, a message with a higher number is dequeued before a message with a lower number). For queues not ordered by priority, the value is informational.
If this flag is set and the call to tpdequeue() is successful, the message identifier is stored in
ctl−>msgid. The entire 32 bytes of the message identifier value are significant.
If this flag is set, the call to tpdequeue() is successful, and the message was queued with a correlation identifier, then the correlation identifier is stored in
ctl−>corrid. The entire 32 bytes of the correlation identifier value are significant. Any Oracle Tuxedo ATMI /Q provided reply to a message has the correlation identifier of the original request message.
If this flag is set, the call to tpdequeue() is successful, and the message was queued with a delivery quality of service, then the flag—
TPQQOSDEFAULTPERSIST,
TPQQOSPERSISTENT, or
TPQQOSNONPERSISTENT—is stored in
ctl‑>delivery_qos. If no delivery quality of service was explicitly specified when the message was queued, the default delivery policy of the target queue dictates the delivery quality of service for the message.
If this flag is set, the call to tpdequeue() is successful, and the message was queued with a reply quality of service, then the flag—
TPQQOSDEFAULTPERSIST,
TPQQOSPERSISTENT, or
TPQQOSNONPERSISTENT—is stored in
ctl‑>reply_qos. If no reply quality of service was explicitly specified when the message was queued, the default delivery policy of the
ctl‑>replyqueue queue dictates the delivery quality of service for any reply.
If this flag is set, the call to tpdequeue() is successful, and the message was queued with a reply queue, then the name of the reply queue is stored in
ctl−>replyqueue. Any reply to the message should go to the named reply queue within the same queue space as the request message.
If this flag is set, the call to tpdequeue() is successful, and the message was queued with a failure queue, then the name of the failure queue is stored in
ctl−>failurequeue. Any failure message should go to the named failure queue within the same queue space as the request message.
The following remaining bits for the flags parameter are cleared (set to zero) when
tpdequeue() is called:
TPQTOP,
TPQBEFOREMSGID,
TPQTIME_ABS,
TPQTIME_REL,
TPQEXPTIME_ABS,
TPQEXPTIME_REL, and
TPQEXPTIME_NONE. These bits are valid bits for the
flags parameter controlling input information for
tpenqueue().
If the call to tpdequeue() failed and
tperrno is set to
TPEDIAGNOSTIC, a value indicating the reason for failure is returned in
ctl−>diagnostic. The possible values are defined below in the Diagnostics section.
Additionally on output, if the call to tpdequeue() is successful,
ctl−>appkey is set to the application authentication key,
ctl−>cltid is set to the identifier for the client originating the request, and
ctl−>urcode is set to the user-return code value that was set when the message was enqueued.
If the ctl parameter is NULL, the input flags are considered to be
TPNOFLAGS, and no output information is made available to the application program.
Upon failure, tpdequeue() returns -1 and sets
tperrno to indicate the error condition.
Upon failure, tpdequeue() sets
tperrno to one of the following values. (Unless otherwise noted, failure does not affect the caller’s transaction, if one exists.)
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).
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).
tpdequeue() was called improperly. There is no effect on the queue or the transaction.
tpdiscon()—Routine for taking down a conversational service connection.
tpdiscon() immediately tears down the connection specified by
cd and generates a
TPEV_DISCONIMM event on the other end of the connection.
tpdiscon() can be called only by the initiator of the conversation.
tpdiscon() cannot be called within a conversational service on the descriptor with which it was invoked. Rather, a conversational service must use
tpreturn() to signify that it has completed its part of the conversation. Similarly, even though a program communicating with a conversational service can issue
tpdiscon(), the preferred way is to let the service tear down the connection in
tpreturn(); doing so ensures correct results.
tpdiscon() causes the connection to be torn down immediately (that is, abortive rather than orderly). Any data that has not yet reached its destination may be lost.
tpdiscon() can be issued even when the program on the other end of the connection is participating in the caller’s transaction. In this case, the transaction must be aborted. Also, the caller does not need to have control of the connection when
tpdiscon() is called.
Upon failure, tpdiscon() returns -1 and sets
tperrno to indicate the error condition.
Upon failure, tpdiscon() sets
tperrno to one of the following values:
cd is invalid or is the descriptor with which a conversational service was invoked.
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).
tpenqueue() stores a message on the queue named by
qname in the
qspace queue space. A queue space is a collection of queues, one of which must be
qname.
When the message is intended for an Oracle Tuxedo ATMI system server, the qname matches the name of a service provided by the server. The system provided server,
TMQFORWARD(5), provides a default mechanism for dequeuing messages from the queue and forwarding them to servers that provide a service matching the queue name. If the originator expects a reply, then the reply to the forwarded service request is stored on the originator’s queue, unless otherwise specified. The originator will dequeue the reply message at a subsequent time. Queues can also be used for a reliable message transfer mechanism between any pair of Oracle Tuxedo ATMI system processes (clients and/or servers). In this case, the queue name does not match a service name but some agreed upon name for transferring the message.
If data is non-NULL, it must point to a buffer previously allocated by
tpalloc() and
len should specify the amount of data in the buffer that should be queued. 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. If
data is NULL,
len is ignored and a message is queued with no data portion.
If the caller is within a transaction and the TPNOTRAN flag is not set, the message is queued in transaction mode. This has the effect that if
tpenqueue() returns successfully and the caller’s transaction is committed successfully, then the message is guaranteed to be available subsequent to the transaction completing. If the caller’s transaction is rolled back either explicitly or as the result of a transaction timeout or some communication error, then the message will be removed from the queue (that is, the placing of the message on the queue is also rolled back). It is not possible to enqueue then dequeue the same message within the same transaction.
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.
Additional information about queuing the message can be specified via ctl data structure. This information includes values to override the default queue ordering placing the message at the top of the queue or before an enqueued message; an absolute or relative time after which a queued message is made available; an absolute or relative time when a message expires and is removed from the queue; the quality of service for delivering the message; the quality of service that any replies to the message should use; a correlation identifier that aids in correlating a reply or failure message with the queued message; the name of a queue to which a reply should be enqueued; and the name of a queue to which any failure message should be enqueued.
The TPQCTL structure is used by the application program to pass and retrieve parameters associated with enqueuing the message. The
flags element of
TPQCTL is used to indicate what other elements in the structure are valid.
On input to tpenqueue(), the following elements may be set in the
TPQCTL structure:
If this flag is set, the correlation identifier value specified in ctl−>corrid is available when a message is dequeued with
tpdequeue(). This identifier accompanies any reply or failure message that is queued so that an application can correlate a reply with a particular request. Note that the entire 32 bytes of the correlation identifier value are significant, so the value specified in
ctl−>corrid must be completely initialized (for example, padded with NULL characters).
If this flag is set, a reply queue named in ctl−>replyqueue is associated with the queued message. Any reply to the message will be queued to the named queue within the same queue space as the request message. This string must be NULL terminated (maximum 127 characters in length).
If this flag is set, a failure queue named in the ctl−>failurequeue is associated with the queued message. If (1) the enqueued message is processed by
TMQFORWARD(), (2)
TMQFORWARD was started with the
-d option, and (3) the service fails and returns a non-NULL reply, a failure message consisting of the reply and its associated
tpurcode is enqueued to the named queue within the same queue space as the original request message. This string must be NULL-terminated (maximum 127 characters in length).
If the TPQDELIVERYQOS flag is set, the flags specified by
ctl‑>delivery_qos control the quality of service for delivery of the message. In this case, one of three mutually exclusive flags—
TPQQOSDEFAULTPERSIST,
TPQQOSPERSISTENT, or
TPQQOSNONPERSISTENT—must be set in
ctl‑>delivery_qos. If
TPQDELIVERYQOS is not set, the default delivery policy of the target queue dictates the delivery quality of service for the message.
If the TPQREPLYQOS flag is set, the flags specified by
ctl‑>reply_qos control the quality of service for any reply to the message. In this case, one of three mutually exclusive flags—
TPQQOSDEFAULTPERSIST,
TPQQOSPERSISTENT, or
TPQQOSNONPERSISTENT—must be set in
ctl‑>reply_qos. The
TPQREPLYQOS flag is used when a reply is returned from messages processed by
TMQFORWARD. Applications not using
TMQFORWARD to invoke services may use the
TPQREPLYQOS flag as a hint for their own reply mechanism.
If TPQREPLYQOS is not set, the default delivery policy of the
ctl‑>replyqueue queue dictates the delivery quality of service for any reply. Note that the default delivery policy is determined when the reply to a message is enqueued. That is, if the default delivery policy of the reply queue is modified between the time that the original message is enqueued and the reply to the message is enqueued, the policy used is the one in effect when the reply is finally enqueued.
TPQEXPTIME_ABS,
TPQEXPTIME_REL, and
TPQEXPTIME_NONE are mutually exclusive flags. If none of these flags is set, the default expiration time associated with the target queue is applied to the message.
TPQEXPTIME_ABS,
TPQEXPTIME_REL, and
TPQEXPTIME_NONE are mutually exclusive flags. If none of these flags is set, the default expiration time associated with the target queue is applied to the message.
TPQEXPTIME_ABS,
TPQEXPTIME_REL, and
TPQEXPTIME_NONE are mutually exclusive flags. If none of these flags is set, the default expiration time associated with the target queue is applied to the message.
Setting this flag indicates that you need tpenque() function to return queue space usage when
tpenque() succeeds;
tpenque() will then return the queue space usage percentage in
ctl->auxiliary[AUXIDX_QSPACEUSAGE] when succeeding. For example, if
ctl->auxiliary[AUXIDX_QSPACEUSAGE] is
50, the current queue space usage percentage is 50%.
Additionally, the urcode element of
TPQCTL can be set with a user-return code. This value will be returned to the application that dequeues the message.
On output from tpenqueue(), the following elements may be set in the
TPQCTL structure:
The following is a valid bit for the flags parameter controlling output information from
tpenqueue(). If this flag is turned on when
tpenqueue() is called, the /Q server
TMQUEUE(5) populates the associated element in the structure with a message identifier. If this flag is turned off when
tpenqueue() is called,
TMQUEUE() does
not populate the associated element in the structure with a message identifier.
If this flag is set and the call to tpenqueue() is successful, the message identifier is stored in
ctl−>msgid. The entire 32 bytes of the message identifier value are significant, so the value stored in
ctl−>msgid is completely initialized (for example, padded with NULL characters). The actual padding character used for initialization varies between releases of the Oracle Tuxedo ATMI /Q component.
If the call to tpenqueue() failed and
tperrno is set to
TPEDIAGNOSTIC, a value indicating the reason for failure is returned in
ctl−>diagnostic. The possible values are defined below in the Diagnostics section.
Upon failure, tpenqueue() returns -1 and sets
tperrno to indicate the error condition. Otherwise, the message has been successfully queued when
tpenqueue() returns.
Upon failure, tpenqueue() sets
tperrno to one of the following values. (Unless otherwise noted, failure does not affect the caller’s transaction, if one exists.)
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).
tpenvelope()—Accesses the digital signature and encryption information associated with a typed message buffer.
#include <atmi.h>
int tpenvelope(char *data, long
len, int
occurrence, TPKEY *
outputkey, long *
status, char *
timestamp, long
flags)
tpenvelope() provides access to the following types of digital signature and encryption information associated with a typed message buffer:
A sending process explicitly registers a digital signature request for a message buffer by calling
tpsign(), or
implicitly registers a digital signature request for a message buffer by calling
tpkey_open() with the
TPKEY_AUTOSIGN flag specified.
A sending process explicitly registers an encryption (seal) request for a message buffer by calling
tpseal(), or
implicitly registers an encryption (seal) request for a message buffer by calling
tpkey_open() with the
TPKEY_AUTOENCRYPT flag specified.
data must point to a valid typed message buffer either (1) previously allocated by a process calling
tpalloc() or (2) delivered by the system to a receiving process. If the message buffer is self-describing,
len is ignored (and may be 0). Otherwise,
len must contain the length of data in
data.
|
Note:
|
If outputkey is NULL, no key handle is returned.
|
The status output parameter reports the state of the digital-signature registration request, digital signature, encryption registration request, or encryption envelope. If the value of the status is not NULL, it is set to one of the following states:
The timestamp output parameter contains the digital signature’s timestamp according to the local clock on the machine where the digital signature was generated. The integrity of this value is protected by the associated digital signature. The memory location indicated by
timestamp is set to the NULL-terminated signature time in format
YYYYMMDDHHMMSS, where
YYYY=year,
MM=month,
DD=day,
HH=hour,
MM=minute, and
SS=second.
timestamp may be NULL, in which case no value is returned. Encryption seals do not contain timestamps, and the memory location indicated by
timestamp is unchanged.
The flags parameter may be set to one of the following values:
|
•
|
TPKEY_REMOVE–The item at position occurrence is removed (that is, it is no longer associated with the buffer). Output parameters outputkey, status, and timestamp related to the item are captured before the item is removed. Items at subsequent positions are shifted down by one, so there are never any gaps in the numbering of occurrence.
|
|
•
|
TPKEY_REMOVEALL–All items associated with the message buffer are removed. The output parameters outputkey, status, and timestamp are not returned.
|
|
•
|
TPKEY_VERIFY–All digital signatures associated with the message buffer are reverified. The status of a signature may change after reverification. For example, if a message buffer has been modified by a receiving process, the status of the originator’s signature changes from TPSIGN_OK to TPSIGN_TAMPERED_MESSAGE.
|
This occurrence does not exist.
tperrordetail()—Gets additional detail about an error generated from the last Oracle Tuxedo ATMI system call.
tperrordetail() returns additional detail related to an error produced by the last Oracle Tuxedo ATMI system routine called in the current thread.
tperrordetail() returns a numeric value that is also represented by a symbolic name. If the last Oracle Tuxedo ATMI system routine called in the current thread did not produce an error, then
tperrordetail() will return zero. Therefore,
tperrordetail() should be called after an error has been indicated; that is, when
tperrno has been set.
Currently flags is reserved for future use and must be set to 0.
Upon failure, tperrordetail() returns a
-1 and sets
tperrno to indicate the error condition.
A Jolt client is disconnected currently. The TPACK flag is used in a
tpnotify() call and the target of
tpnotify() is a currently disconnected Jolt client. When
tpnotify() fails, a subsequent call to
tperrordetail() with no intermediate ATMI calls will return
TPED_CLIENTDISCONNECTED.
Note that the TPED_DOMAINUNREACHABLE feature applies to Oracle Tuxedo Domains only. It does not apply to other domains products such as Connect OSI TP Domains and Connect SNA Domains.
No client exists. The TPACK flag is used in a
tpnotify() call but there is no target for
tpnotify(). When
tpnotify() fails,
tperrno is set to
TPENOENT. A subsequent call to
tperrordetail() with no intermediate ATMI calls will return
TPED_NOCLIENT.
A client does not have an unsolicited handler set. The TPACK flag is used in a
tpnotify() call and the target of the
tpnotify() is in an Oracle Tuxedo ATMI session, but it has not set an unsolicited notification handler. When
tpnotify() fails,
tperrno is set to
TPENOENT. A subsequent call to
tperrordetail() with no intermediate ATMI calls will return
TPED_NOUNSOLHANDLER.
RDMA Msgq_daemon failure. When RDMA is enabled, requests sent through RDMA fails when the RDMA daemon process (
Msgq_daemon), encounters a serious problem.
tperrno then returns
TPEOS/TPETIME, and a subsequent call to t
perrordetail() with no intermediate ATMI calls returns
TPED_RDMA_MSGQDAEMON.
Invalid RDMA queue. When RDMA is enabled, Msgq_daemon shared memory may cause an internal error. After the request failure,
tperrno returns
TPEOS, and a subsequent call to t
perrordetail() with no intermediate ATMI calls return
TPED_RDMA_INVALIDQUEUE. Refer to
TPED_RDMA_MSGQDAEMON for the calls that could encounter this failure.
Not enough shared memory to handle RDMA request. When RDMA is enabled and Msgq_daemon starts without enough shared memory, an internal error may develop;
tperrno then returns
TPEOS. A subsequent call to
tperrordetail() with no intermediate ATMI calls will return
TPED_RDMA_NOMEMORY. Refer to
TPED_RDMA_MSGQDAEMON for the calls that may possibly encounter this failure.
Upon failure, tperrordetail() sets
tperrno to one of the following values:
tpexport()—Converts a typed message buffer into an exportable, machine-independent string representation, that includes digital signatures and encryption envelopes.
#include <atmi.h>
int tpexport(char *ibuf, long
ilen, char *
ostr, long *
olen,
long
flags)
tpexport() converts a typed message buffer into an externalized representation. An externalized representation is a message buffer that does
not include any Oracle Tuxedo ATMI header information that is normally added to a message buffer just before the buffer is transmitted.
|
•
|
Any encryption envelopes associated with ibuf. The buffer content remains protected by encryption. Only specified recipients with access to a valid private key for decryption may later import the buffer.
|
ibuf must point to a valid typed message buffer either (1) previously allocated by a process calling
tpalloc() or (2) delivered by the system to a receiving process.
ilen specifies how much of
ibuf to export. Note that if
ibuf points to a buffer type for which a length need not be specified (for example, an
FML fielded buffer), then
ilen is ignored (and may be 0).
ostr is a pointer to the output area that will hold an externalized representation of the buffer’s content and associated properties. If
TPEX_STRING is set in
flags, then the externalized format will be a string type. Otherwise, the output length is determined by *
olen and may contain embedded NULL bytes.
On input, *olen specifies the maximum storage size available at
ostr. On output *
olen is set to the actual number of bytes written to
ostr (including a terminating NULL character if
TPEX_STRING is set in
flags).
The flags argument may be set to
TPEX_STRING if string format (base 64 encoded) is desired for the output buffer. Otherwise, the output will be binary.
Upon success, tpfml32toxml() returns
0. This function returns
-1 on error and sets
tperrno to indicate the error condition.
Upon failure, tpfml32toxml() sets
tperrno to one of the following values:
Either fml32bufp or
xmlbufp is not a valid typed buffer.
Upon success, tpfmltoxml() returns
0. This function returns
-1 on error and sets
tperrno to indicate the error condition.
Upon failure, tpfmltoxml() sets
tperrno to one of the following values:
Either fml32bufp or
xmlbufp is not a valid typed buffer.
tpforward()—Routine for forwarding a service request to another service routine.
tpforward() allows a service routine to forward a client’s request to another service routine for further processing.
tpforward() acts like
tpreturn() in that it is the last call made in a service routine. Like
tpreturn(),
tpforward() should be called from within the service routine dispatched to ensure correct return of control to the Oracle Tuxedo ATMI system dispatcher.
tpforward() cannot be called from within a conversational service.
This function forwards a request to the service named by svc using data pointed to by
data. The service name must not begin with a dot. A service routine forwarding a request receives no reply. After the request is forwarded, the service routine returns to the communication manager dispatcher and the server is free to do other work. Note that because no reply is expected from a forwarded request, the request may be forwarded without error to any service routine in the same executable as the service that forwarded the request.
If the service routine is in transaction mode, tpforward() puts the caller portion of the transaction in a state where it may be completed when the originator of the transaction issues either
tpcommit() or
tpabort(). If a transaction was explicitly started with
tpbegin() while in a service routine, the transaction must be ended with either
tpcommit() or
tpabort() before calling
tpforward(). Thus, all services in a “forward chain” are either all started in transaction mode or none are.
tpforward() should be called after receiving all replies expected from service requests initiated by the service routine. Any outstanding replies which are not received will automatically be dropped by the communication manager dispatcher upon receipt. In addition, the descriptors for those replies become invalid and the request is not forwarded to
svc.
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 Oracle Tuxedo ATMI 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. Also any attempt to reallocate this buffer in another thread is prohibited. However, if the buffer passed to
tpforward() is not the same one with which the service is invoked, then
tpforward() 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 and a request with zero length data is sent.
The flags argument is reserved for future use and should be set to 0 (zero).
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.
If a service routine returns without using either tpreturn() or
tpforward() (that is, if it uses the C language
return statement or simply “falls out of the function”) or if
tpforward() is called from a conversational server, the server will print a warning message in a log file and return a service error to the original requester. All open connections to subordinates will be disconnected immediately, and any outstanding asynchronous replies will be marked stale. If the server was in transaction mode at the time of failure, the transaction is marked abort-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.
|
|
|
|
|
|
LIBTUX_CAT:6835: ERROR' is printed in ULOG. The session will not initiate.
|
|
|
|
LIBTUX_CAT:6836: ERROR' is printed in ULOG. The session will not terminate between affinity client and server.
|
|
|
|
|
|
tpfree()—Routine for freeing a typed buffer.
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.
Once tpfree() returns,
ptr should not be passed as an argument to any Oracle Tuxedo ATMI system routine or used in any other manner.
When freeing an FML32 buffer using
tpfree(), the routine recursively frees all embedded buffers to prevent memory leaks. In order to preserve the embedded buffers, you should assign the associated pointer to NULL before issuing the
tpfree() command. As stated above, if
ptr is NULL, no action occurs.
tpfree() does not return any value to its caller. Thus, it is declared as a void.
tpgblktime()—Retrieves a previously set, per second or millisecond, blocktime value
#include <atmi.h>
int tpgblktime(long flags
)
tpgblktime() retrieves a previously set blocktime value, per second or millisecond according to flag
TPBLK_MILLISECOND. If
tpgblktime() specifies a blocktime flag value, and no such
flag value has been set, the return value is 0. A blocktime flag value less than 0 produces an error.
Upon success, tpgblktime() returns a positive integer indicating the blocking time value currently in effect for the corresponding flag value. A 0 return value indicates that no such blocking time override is currently in effect.
Upon failure, tpgblktime() sets
tperrno to one of the following values:
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.
tpgetadmkey() is available for application use by an application specific authentication server. It returns an application security key suitable for assignment to the indicated user for the purpose of administrative authentication. This routine must be called with a client name (that is,
tpinfo−>cltname) of either
tpsysadm() or
tpsysop(); otherwise, a valid administrative key will not be returned.
Upon success, tpgetadmkey() returns a non-0 value with the high-order bit (0x80000000) set; otherwise it returns 0. Zero may be returned if
tpinfo is NULL,
tpinfo−>cltname is not
tpsysadm() or
tpsysop(), or lastly if the effective user ID is not the configured application administrator for this site.
tpgetcallinfo()— Routine for retrieving call path message monitoring attributes.
tpgetcallinfo() is used for call path monitoring only. It supports the following parameters:
tpgetcallinfo()retrieves the message monitoring attributes when call path monitoring is enabled.
tpgetcallinfo() can be used in different scenarios to accomplish different functions. Typical usage is as follows:
Application server calls tpgetcallinfo() to check the requested message monitoring attributes. It can provide the following information:
|
Note:
|
tpgetcallinfo() can be called at any time for a reply buffer after a reply is received. This is especially useful with tpacall/ tpgetrply.
|
Table 13 lists the FML monitor metrics field names.
Table 14 lists the FML custom HTTP header names.
Upon failure, tpgetcallinfo() returns -1 and sets
tperrno to indicate the error condition.
Upon failure, tpgetcallinfo() sets
tperrno to one of the following values,
tpgetctxt()—Retrieves a context identifier for the current application association.
tpgetctxt() retrieves an identifier that represents the current application context and places that identifier in
context. This function operates on a per-thread basis in a multithreaded environment, and on a per-process basis in a non-threaded environment.
tpgetctxt() may be called in single-context applications as well as in multicontext applications.
Upon successful completion, tpgetctxt() returns a non-negative value. Context is set to the current context ID, which may be represented by any of the following:
|
•
|
TPSINGLECONTEXT, indicating that the current thread has successfully executed tpinit() without the TPMULTICONTEXTS flag, or that the current thread was just created in a process that has successfully executed tpinit() without the TPMULTICONTEXTS flag. The value of TPSINGLECONTEXT is 0.
|
|
•
|
TPNULLCONTEXT, indicating that the current thread is not associated with a context.
|
|
•
|
TPINVALIDCONTEXT, indicating that the current thread is in the invalid context state. If a thread in a multicontexted client issues a call to tpterm() while other threads in the same context are still working, the working threads are placed in the TPINVALIDCONTEXT context. The value of TPINVALIDCONTEXT is -1.
|
Upon failure, tpgetctxt() returns a value of -1 and sets
tperrno to indicate the error condition.
Upon failure, tpgetctxt() sets
tperrno to one of the following values:
tpgetlev()—Routine for checking if a transaction is in progress.
tpgetlev() returns to the caller the current transaction level. Currently, the only levels defined are 0 and 1.
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 and sets
tperrno to indicate the error condition.
Upon failure, tpgetlev() sets
tperrno to one of the following values:
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(). See
buildserver(1) for details on linking resource managers that meet the XA interface into a server such that operations performed by that resource manager are part of an Oracle Tuxedo ATMI system transaction.
tpgetmbenc()—Gets the code-set encoding name from a typed buffer.
The bufp argument is a valid pointer to a typed buffer message.
The enc_name argument will be set to the encoding name, found in
bufp, upon successful execution of this function. The returned string will be NULL terminated. The user must take care to allocate a buffer large enough to hold the encoding name plus the NULL terminator (see
NL_LANGMAX in
<limits.h>). An MBSTRING typed buffer without the encoding name set is invalid.
The flags argument is not currently used and should be set to zero.
Upon success, tpgetmbenc() returns a value of 0. This function returns -1 on error and sets tperrno as described below for each function. The function may fail for the following reasons.
tpgetrepos() - retrieves service parameter information from a Tuxedo service metadata repository file.
tpgetrepos() provides an alternative repository access interface to the
.TMMETAREPOS service provided by
TMMETADATA(5). It retrieves service parameters from a Tuxedo service metadata repository file. To use
tpgetrepos(), the metadata repository file must reside on the native client or server that initiates the request. This allows for repository information access even when
TMMETADATA(5)has not been booted.
|
Note:
|
tpgetrepos() can also be used to view Jolt repository files. It cannot modify an existing Jolt repository file or create a new one.
|
METAREPOS(5)describes the FML32 buffer format
tpgetrepos()uses. It is similar to the format used by the Tuxedo MIB.
tpgetrepos() returns 0 on success. On failure, it sets
tperrno and returns -1. On most failure conditions, the
TA_ERROR field in *odata is populated with information about the specific error, as is done by the Tuxedo MIB.
Upon failure, tpgetrepos() sets
tperrno to one of the following values:
|
Note:
|
Except for TPEINVAL, odata is modified to include TA_ERROR, TA_STATUS for each service entry to further qualify the error condition.
|
The MIB-like request failed. odata is updated and returned to the caller with
FML32 fields indicating the cause of the error as discussed in
MIB(5).
tpgetrepos() was improperly called. The reposfile file argument given is not a valid repository file.
tpgetrply()—Routine for getting a reply from a previous request.
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. As of release 6.4, the default allocation for buffers is 1024 bytes. Also, historical information is maintained on recently used buffers, allowing a buffer of optimal size to be reused as a return buffer.
If *len is 0, then the reply has no data portion and neither *
data nor the buffer it points to were modified.
|
•
|
Calls to tpgetrply(TPGETANY) and tpgetrply() for a specific handle cannot be issued concurrently.
|
Any tpgetrply() call that would, if issued, cause a violation of either of these restrictions, returns -1 and sets
tperrno to
TPEPROTO.
|
•
|
A call to tpgetrply( TPGETANY) in a single context concurrently with a call to tpgetrply(), with or without TPGETANY, in a different context.
|
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.
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).
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().
Upon failure, tpgetrply() returns -1 and sets
tperrno to indicate the error condition.
Upon failure, tpgetrply() 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(3c) reference page for more information.
Either the type and subtype of the reply are not known to the caller; or, TPNOCHANGE was set in
flags and the type and subtype of *
data do not match the type and subtype 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.
cd points to an invalid descriptor.
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 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.
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 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.
tpgprio()—Routine for getting a service request priority.
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.
Upon failure, tpgprio() returns -1 and sets
tperrno to indicate the error condition.
Upon failure, tpgprio() sets
tperrno to one of the following values:
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.
tpimport()—Converts an externalized representation of a message buffer into a typed message buffer.
#include <atmi.h>
int tpimport(char *istr, long
ilen, char **
obuf, long *
olen,
long
flags)
tpimport() converts an externalized representation of a message buffer into a typed message buffer. An externalized representation is a message buffer that does
not include any Oracle Tuxedo ATMI header information that is normally added to a message buffer just before the buffer is transmitted. A process converts a typed message buffer into an externalized representation by calling the
tpexport() function.
If the istr buffer representation is encrypted, the importing process must have access to a valid private key for decryption. Decryption is performed automatically during the importing process.
If TPEX_STRING is
not set in
flags, then
ilen contains the length of the binary data contained in
istr. If
ilen is 0,
istr is assumed to point to a NULL-terminated string, and the
TPEX_STRING flag is inferred.
*obuf must point to a valid typed message buffer either (1) previously allocated by a process calling
tpalloc() or (2) delivered by the system to a receiving process. The buffer will be reallocated as necessary to accommodate the result, and its buffer type or subtype may change.
*olen is set to the amount of valid data contained in the output buffer. If
olen is NULL on input, it is ignored.
The flags argument should be set to
TPEX_STRING if the input externalized representation is in string format (base 64 encoded). Otherwise, the input is in binary format of length
ilen.
tpinit() allows a client to join an Oracle Tuxedo ATMI system application. Before a client can use any of the Oracle Tuxedo ATMI system communication or transaction routines, it must first join an Oracle Tuxedo ATMI system application.
tpinit() has two modes of operation: single-context mode and multicontext mode, which will be discussed in detail below. Because calling
tpinit() is optional when in single-context mode, a single-context client may also join an application by calling many ATMI routines (for example,
tpcall()), which 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 multicontext mode is required, when application authentication is required (see the description of the
SECURITY keyword in
UBBCONFIG(5)), or when the application wishes to supply its own buffer type switch (see
typesw(5)). After
tpinit() successfully returns, the client can initiate service requests and define transactions.
In single-context mode, if tpinit() is called more than once (that is, if it is called after the client has already joined the application), no action is taken and success is returned.
In a multithreaded client, a thread in the TPINVALIDCONTEXT state is not allowed to issue a call to
tpinit(). To join an Oracle Tuxedo ATMI application, a multithreaded Workstation client must always call
tpinit() with the
TPMULTICONTEXTS flag set, even if the client is running in single-context mode.
|
Note:
|
The TPMULTICONTEXTS mode of tpinit will continue to work properly when the TMNOTHREADS environment variable is set to yes. Setting this environment variable to yes turns off multithreaded processing for applications that do not use threads.
|
tpinit()’s argument,
tpinfo, is a pointer to a typed buffer of type
TPINIT and a NULL subtype.
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() after calling
tpinit(). The
TPINIT typed buffer structure includes the following members:
The values of 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 Workstation clients. Note that
grpname is not related to ACL GROUPS.
tpinit() has two modes of operation: single-context mode and multicontext mode. In single-context mode, a process may join at most one application at any one time. Multiple application threads may access this application. Single-context mode is specified by calling
tpinit() with a NULL parameter or by calling it without specifying the
TPMULTICONTEXTS flag in the
flags field of the
TPINIT structure. Single-context mode is also specified when
tpinit() is called implicitly by another ATMI function. The context state for a process operating in single-context mode is
TPSINGLECONTEXT.
|
Note:
|
The TPMULTICONTEXTS mode of tpinit will continue to work properly when the TMNOTHREADS environment variable is set to “yes”.
|
In single-context mode, if tpinit() is called more than once (that is, if it is called after the client has already joined the application), no action is taken and success is returned.
Multicontext mode is entered by calling tpinit() with the
TPMULTICONTEXTS flag set in the
flags field of the
TPINIT structure. In multicontext mode, each call to
tpinit() results in the creation of a separate application association.
For native clients, the value of the TUXCONFIG environment variable is used to identify the application to which the new association will be made. For Workstation clients, the value of the
WSNADDR or
WSENVFILE environment variable is used to identify the application to which the new association will be made. The context for the current thread is set to the new association.
In addition to controlling multicontext and single-context modes, the setting of flags is used to indicate both the client-specific notification mechanism and the mode of system access. These two settings may override the application default. If these settings cannot override the application default,
tpinit() prints a warning in a log file, ignores the setting, and restores the application default setting in the
flags field upon return from
tpinit(). For client notification, the possible values for
flags are as follows:
Select THREAD notification in a separate thread managed by the Oracle Tuxedo ATMI system. This flag is allowed only on platforms that support multithreading. If
TPU_THREAD is specified on a platform that does not support multithreading, it is considered an invalid argument and will result in an error return with
tperrno set to
TPEINVAL.
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(8) 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 Oracle Tuxedo ATMI 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.
Upon failure, tpinit() leaves the calling process in its original context, returns
-1, and sets
tperrno to indicate the error condition. Also,
tpurcode() is set to the value returned by the
AUTHSVR(5) server.
Upon failure, tpinit() sets
tperrno to one of the following values:
tpinit() has been called improperly. For example: (a) the caller is a server; (b) the
TPMULTICONTEXTS flag has been specified in single-context mode; or (c) the
TPMULTICONTEXTS flag has not been specified in multicontext mode.
tpchkauth() and a non-NULL value for the
TPINIT typed buffer argument of
tpinit() are available only on sites running release 4.2 or later.
The interfaces described in tpinit(3c) are supported on UNIX system, Windows, and MS-DOS operating systems. However, signal-based notification is not supported on 16-bit Windows or MS-DOS platforms. If it is selected at
tpinit() time, then a
userlog() message is generated and the method is automatically set to dip-in.
Used within tpinit() when invoked by a native client. It indicates the application to which the client should connect. Note that this environment variable is referenced only when
tpinit() is called. Subsequent calls make use of the application context.
Used within tpinit() when invoked by a Workstation client. It indicates a file containing environment variable settings that should be set in the caller’s environment. See
compilation(5) for details on environment variable settings necessary for Workstation clients. Note that this file is processed only when
tpinit() is called and not before.
Used within tpinit() when invoked by a Workstation client. It indicates the network addresses of the workstation listener that is to be contacted for access to the application. This variable is required for Workstation clients and is ignored for native clients.
In the first format, the domain finds an address for hostname using the local name resolution facilities (usually DNS).
hostname must be the local machine, and the local name resolution facilities must unambiguously resolve
hostname to the address of the local machine.
In the second format, the string #.#.#.# is in dotted-decimal format. In dotted-decimal format, each # should be a number from 0 to 255. This dotted-decimal number represents the IP address of the local machine.
In both of the above formats, port_number is the TCP port number at which the domain process will listen for incoming requests.
port_number can either be a number between 0 and 65535 or a name. If
port_number is a name, then it must be found in the network services database on your local machine.
Because the pipe symbol (|) is considered a special character in Windows, it must be preceded by a carat ( ^ )—an escape character in the Windows environment—when it is specified on the command line. However, if
WSNADDR is defined in an envfile, the Oracle Tuxedo ATMI system gets the values defined by
WSNADDR through the
tuxgetenv(3c) function. In this context, the pipe symbol (
|) is not considered a special character, so you do not need to escape it with a carat (
^).
Used within tpinit() when invoked by a Workstation client. It specifies the network address used by the Workstation client when connecting to the workstation listener or workstation handler. This variable, along with the
WSFRANGE variable, determines the range of TCP/IP ports to which a Workstation client will attempt to bind before making an outbound connection. This address must be a TCP/IP address. The port portion of the TCP/IP address represents the base address from which a range of TCP/IP ports can be bound by the Workstation client. The
WSFRANGE variable specifies the size of the range. For example, if this address is
//mymachine.oracle.com:30000 and
WSFRANGE is 200, then all native processes attempting to make outbound connections from this
LMID will bind a port on
mymachine.oracle.com between 30000 and 30200. If not set, this variable defaults to the empty string, which implies the operating system chooses a local port randomly.
Used within tpinit() when invoked by a Workstation client. It specifies the range of TCP/IP ports to which a Workstation client process will attempt to bind before making an outbound connection. The
WSFADDR parameter specifies the base address of the range. For example, if the
WSFADDR parameter is set to
//mymachine.oracle.com:30000 and
WSFRANGE is set to 200, then all native processes attempting to make outbound connections from this
LMID will bind a port on
mymachine.oracle.com between 30000 and 30200. The valid range is 1-65535. The default is 1.
Used within tpinit() when invoked by a Workstation client. It indicates the device name to be used to access the network. This variable is used by Workstation clients and ignored for native clients. Note that certain supported transport level network interfaces do not require a device name; for example, sockets and NetBIOS. Workstation clients supported by such interfaces need not specify
WSDEVICE.
Used within tpinit() when invoked by a Workstation client to negotiate encode/decode responsibilities with the native site. This variable is optional for Workstation clients and ignored for native clients.
Used by tpinit() to set the maximum amount of core memory that should be used for buffering application replies before they are dumped to file. The default for this parameter 256,000 bytes. For more information, see the programming documentation for your instantiation.
tpkey_close() releases a previously opened key handle and all resources associated with it. Any sensitive information, such as the principal’s private key, is erased from memory.
It is the application’s responsibility to release key resources by calling tpkey_close(). Once a process closes a key, the process can no longer use the key handle to register a message buffer for digital signature or encryption. If the process opened the key using
tpkey_open() with the
TPKEY_AUTOSIGN or
TPKEY_AUTOENCRYPT flag specified, the key handle no longer applies to future communication operations after the key is closed.
The flags argument is reserved for future use and must be set to 0.
#include <atmi.h>
int tpkey_getinfo(TPKEY hKey, char *
attribute_name, void *
value, long *
value_len, long
flags)
tpkey_getinfo() reports information about a key handle. A key handle represents a specific principal’s key and the information associated with it.
The key under examination is identified by the hKey input parameter. The attribute for which information is desired is identified by the
attribute_name input parameter. Some attributes are specific to a cryptographic service provider, but the following core set of attributes should be supported by all providers.
|
|
|
|
|
|
|
|
An ASN.1 Distinguished Encoding Rules (DER) object identifier of the public key algorithm used by the key for public key encryption.
|
|
|
|
|
|
An ASN.1 DER object identifier of the digital signature algorithm used by the key for digital signature.
|
|
|
|
|
|
An ASN.1 DER object identifier of the symmetric key algorithm used by the key for bulk data encryption.
|
|
|
When an algorithm with a fixed key length is set in ENCRYPT_ALG, the ENCRYPT_BITS value is automatically set to the fixed key length. For example, if ENCRYPT_ALG is set to DES, the ENCRYPT_BITS value is automatically set to 56.
|
|
|
An ASN.1 DER object identifier of the message digest algorithm used by the key for digital signature.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
{ 0x06, 0x09, 0x2a, 0x86, 0x48, 0x86, 0xf7, 0x0d, 0x01, 0x01, 0x01 }
|
|
|
|
|
{ 0x06, 0x09, 0x60, 0x86, 0x48, 0x01, 0x65, 0x03, 0x04, 0x01, 0x02 }
|
|
{ 0x06, 0x09, 0x60, 0x86, 0x48, 0x01, 0x65, 0x03, 0x04, 0x01, 0x2a }
|
|
|
|
|
|
|
|
|
|
|
The information associated with the specified attribute_name parameter will be stored in the memory location indicated by
value. The maximum amount of data that can be stored at this location is specified by the caller in
value_len.
After tpkey_getinfo() completes,
value_len is set to the size of the data actually returned (including a terminating NULL value for string values). If the number of bytes that need to be returned exceeds
value_len,
tpkey_getinfo() fails (with the
TPELIMIT error code) and sets
value_len to the required amount of space.
The flags argument is reserved for future use and must be set to 0.
tpkey_open()—Opens a key handle for digital signature generation, message encryption, or message decryption.
#include <atmi.h>
int tpkey_open(TPKEY *hKey, char *
principal_name, char *
location, char *
identity_proof, long
proof_len, long
flags)
tpkey_open() makes a key handle available to the calling process. A key handle represents a specific principal’s key and the information associated with it.
Calling tpkey_open() with the principal’s name and either the
TPKEY_SIGNATURE or
TPKEY_AUTOSIGN flag returns a handle to the principal’s private key and digital certificate.
Calling tpkey_open() with the principal’s name and either the
TPKEY_ENCRYPT or
TPKEY_AUTOENCRYPT flag returns a handle to the principal’s public key via the principal’s digital certificate.
Calling tpkey_open() with the principal’s name and the
TPKEY_DECRYPT flag returns a handle to the principal’s private key and digital certificate.
The principal_name input parameter specifies the key owner’s identity. If the value of
principal_name is a NULL pointer or an empty string, a default identity is assumed. The default identity may be based on the current login session, the current operating system account, or another attribute such as a local hardware device.
To authenticate the identity of principal_name, proof material such as a password or pass phrase may be required. If required, the proof material should be referenced by
identity_proof. Otherwise, the value of this parameter may be NULL.
tpkey_setinfo()—Sets optional attribute parameters associated with a key handle.
#include <atmi.h>
int tpkey_setinfo(TPKEY hKey, char *
attribute_name, void *
value, long
value_len, long
flags)
tpkey_setinfo() sets an optional attribute parameter for a key handle. A key handle represents a specific principal’s key and the information associated with it.
The information to be associated with the attribute_name parameter is stored in the memory location indicated by
value. If the data content of
value is self-describing,
value_len is ignored (and may be 0). Otherwise,
value_len must contain the length of data in
value.
The flags argument is reserved for future use and must be set to 0.
The value provided is too large.
tpnotify()—Routine for sending notification by client identifier.
tpnotify() allows a client or server to send an unsolicited message to an individual client.
clientid is a pointer to a client identifier saved from the
TPSVCINFO structure of a previous or current service invocation, or passed to a client via some other communications mechanism (for example, retrieved via the administration interface).
The data portion of the request is pointed to by data, a buffer previously allocated by
tpalloc().
len specifies how much of
data to send. Note that if
data points to a buffer type that does not require a length to be specified, (for example, an
FML fielded buffer) then
len is ignored (and may be 0). Also,
data may be NULL in which case
len is ignored.
Upon successful return from tpnotify(), the message has been delivered to the system for forwarding to the identified client. If the
TPACK flag was set, a successful return means the message has been received by the client. Furthermore, if the client has registered an unsolicited message handler, the handler will have been called.
Unless the TPACK flag is set,
tpnotify() does not wait for the message to be delivered to the client.
Upon failure, tpnotify() returns -1 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(3c) reference page for more information.
Upon failure, tpnotify() sets
tperrno to one of the following values:
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.)
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.
tpopen()—Routine for opening a resource manager.
tpopen() opens the resource manager to which the caller is linked. At most one resource manager can be linked to the caller. This function is used in place of resource manager-specific
open() calls and allows a service routine to be free of calls that may hinder portability. Since resource managers differ in their initialization semantics, the specific information needed to open a particular resource manager is placed in a configuration file.
If the current server is built with the -M option, tpopen will open all of RMs in UBBCONFIG (5) *RMS section configured as
AUTO=Y related with current server group and set correspond context fields.
Upon failure, tpopen() returns -1 and sets
tperrno to indicate the error condition.
Upon failure, tpopen() sets
tperrno to one of the following values:
tpopen() was called in an improper context (for example, by a client that has not joined an Oracle Tuxedo system server group).
tpclose(3c),, tprmopen(3c), tprmclose(3c), tprmstart(3c), tprmend(3c)
The caller uses tppost() to post an event and any accompanying data. The event is named by
eventname and
data, if not NULL, points to the data. The posted event and its data are dispatched by the Oracle Tuxedo ATMI EventBroker to all subscribers whose subscriptions successfully evaluate against
eventname and whose optional filter rules successfully evaluate against
data.
eventname is a NULL-terminated string 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.
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 posted with the event. 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. If
data is NULL,
len is ignored and the event is posted with no data.
When tppost() is used within a transaction, the transaction boundary can be extended to include those servers and/or stable-storage message queues notified by the EventBroker. When a transactional posting is made, some of the recipients of the event posting are notified on behalf of the poster’s transaction (for example, servers and queues), while some are not (for example, clients).
If the poster is within a transaction and the TPNOTRAN flag is not set, the posted event goes to the EventBroker in transaction mode such that it dispatches the event as part of the poster’s transaction. The broker dispatches transactional event notifications only to those service routine and stable-storage queue subscriptions that used the
TPEVTRAN bit setting in the
ctl−>flags parameter passed to
tpsubscribe(). Client notifications, and those service routine and stable-storage queue subscriptions that did not use the
TPEVTRAN bit setting in the
ctl−>flags parameter passed to
tpsubscribe(), are also dispatched by the EventBroker but not as part of the posting process’s transaction.
If the poster is outside a transaction, tppost() is a one-way post with no acknowledgement when the service associated with the event fails. This occurs even when
TPEVTRAN is set for that event (using the
ctl−>flags parameter passed to
tpsubscribe()). If the poster is in a transaction, then
tppost() returns
TPESVCFAIL when the associated service fails in the event.
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.
Upon successful return from tppost(),
tpurcode() contains the number of event notifications dispatched by the EventBroker on behalf of
eventname (that is, postings for those subscriptions whose event expression evaluated successfully against
eventname and whose filter rule evaluated successfully against
data). Upon return where
tperrno is set to
TPESVCFAIL,
tpurcode() contains the number of non-transactional event notifications dispatched by the EventBroker on behalf of
eventname.
Upon failure, tppost() returns -1 sets
tperrno to indicate 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.)
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).
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.
tprealloc()—Routine to change the size of a typed buffer.
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 reallocated. 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.
Upon failure, tprealloc() returns NULL and sets
tperrno to indicate the error condition.
If the reinitialization function fails, tprealloc() fails, returning NULL and the contents of the buffer pointed to by
ptr may not be valid. Upon failure,
tprealloc() sets
tperrno to one of the following values:
If buffer reinitialization 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()).
tprecv()—Routine for receiving a message in a conversational connection.
tprecv() is used to receive data sent across an open connection from another program.
tprecv()’s first argument,
cd, specifies on which open connection to receive data.
cd is a descriptor returned from either
tpconnect() or the
TPSVCINFO parameter to the service. The second argument,
data, is the address of a pointer to a buffer previously allocated by
tpalloc().
data must be the address of a pointer to a buffer previously allocated by
tpalloc() and
len should point to a long that
tprecv() 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 buffer.
FML and
FML32 buffers often assume a minimum size of 4096 bytes; if the reply is larger than 4096 bytes, the size of the buffer is increased to a size large enough to accommodate the data being returned.
If *len is 0, then no data was received and neither
*data nor the buffer it points to were modified. It is an error for
data,
*data or
len to be NULL.
tprecv() can be issued only by the program that does not have control of the connection.
tprecv() does not wait for data to arrive. If data is already available to receive, then
tprecv() gets the data and returns. When this flag is not specified and no data is available to receive, the caller blocks until data arrives.
If an event exists for the descriptor, cd, then
tprecv() will return setting
tperrno to
TPEEVENT. The event type is returned in
revent. Data can be received along with the
TPEV_SVCSUCC,
TPEV_SVCFAIL, and
TPEV_SENDONLY events. Valid events for
tprecv() are as follows:
Received by the originator of a conversation, this event indicates that the subordinate of the conversation has issued tpreturn().
tpreturn() encountered an error that precluded the service from returning successfully. For example, bad arguments may have been passed to
tpreturn() or
tpreturn() may have been called while the service had open connections to other subordinates. Due to the nature of this event, any application defined data or return code are not available. The connection has been torn down and is no longer a valid descriptor. If this event occurred as part of the
cd recipient’s transaction, then the transaction is marked abort-only.
Upon return from tprecv() where
revent is set to either
TPEV_SVCSUCC or
TPEV_SVCFAIL, the
tpurcode global contains an application defined value that was sent as part of
tpreturn().
Upon failure, tprecv() returns -1 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(3c) reference page for more information.
Upon failure, tprecv() sets
tperrno to one of the following values:
Either the type and subtype of the incoming buffer are not known to the caller, or TPNOCHANGE was set in
flags and the type and subtype of
*data do not match the type and subtype of the incoming buffer. Regardless, neither
*data, its contents nor
*len are changed. If the conversation is part of the caller’s current transaction, then the transaction is marked abort-only because the incoming buffer is discarded.
An event occurred and its type is available in revent. There is a relationship between the [TPETIME] and the [
TPEEVENT] return codes. While in transaction mode, if the receiving side of a conversation is blocked on
tprecv and the sending side calls
tpabort(), then the receiving side gets a return code of [
TPEVENT] with an event of
TPEV_DISCONIMM. If, however, the sending side calls
tpabort() before the receiving side calls
tprecv(), then the transaction may have already been removed from the GTT, which causes
tprecv() to fail with the [
TPETIME] code.
tprecv() was called in an improper context (for example, the connection was established such that the calling program can only send data).
tpresume() is used to resume work on behalf of a previously suspended transaction. Once the caller resumes work on a transaction, it must either suspend it with
tpsuspend(), or complete it with one of
tpcommit() or
tpabort() at a later time.
tpresume() places the caller in transaction mode on behalf of the global transaction identifier pointed to by
tranid. It is an error for
tranid to be NULL.
Currently, flags are reserved for future use and must be set to 0.
tpresume()can take effect in all participated resource managers including those in a multiple resource mangers server group in a global transaction.
tpresume() returns -1 on error and sets
tperrno to indicate the error condition.
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.
tranid points to a transaction identifier that another process has already resumed. The caller’s state with respect to the transaction is not changed.
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.
tpreturn()—Returns from an Oracle Tuxedo ATMI system service routine.
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 Oracle Tuxedo ATMI system dispatcher). It is recommended that
tpreturn() be called from within the service routine dispatched to ensure correct return of control to the Oracle Tuxedo ATMI 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 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.
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.
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.
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.
If rval is not set to one of these three values, then it defaults to
TPFAIL.
An application 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 Oracle Tuxedo ATMI 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. Also any attempt to reallocate this buffer in another thread is prohibited. However, if the buffer passed to
tpreturn() is not the same one with which the service is invoked, then
tpreturn() frees that buffer. Although the main buffer is freed, any buffers referenced by embedded fields within that buffer are not freed.
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 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 Oracle Tuxedo ATMI 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.
tperrordetail() and
tpstrerrordetail() can be used to get additional information about an error produced by the last Oracle Tuxedo ATMI 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.
tpalloc(3c),
tpcall(3c),
tpconnect(3c),
tpforward(3c),
tprecv(3c),
tpsend(3c),
tpservice(3c), tprmopen(3c), tprmclose(3c), tprmstart(3c), tprmend(3c)
tprmclose() - Routine that closes a specified RM configured in a multiple RMs server group.
tprmclose() closes a specified resource manager by the argument rmname. If current context is in a transaction context, this routine does nothing and returns error to caller. If current RM is still not opened or already closed (that is,
tprmclose() is called more than once), no action is taken and success is returned.
tprmclose() can only close those resource manager opened via
tprmopen() routine.
The first parameter rmname currently must be a value which is configured in the
*RMS section of UBBCONFIG. The flags must be 0.
Upon failure, tprmclose() returns -1 and sets the tperrno to indicate the error condition.
Upon failure, tprmclose() sets
tperrno to one of the following values:
tprmclose() was called in a improper context. For example, it was invoked by a server which is not built specified using the
-M option when executing buildserver, it was executed in an ongoing transaction context.
tprmend() - Routine for ending current work performed on behalf of a transaction branch in a specified RM.
tprmend() ends current work performed on behalf of a transaction branch in a specified RM. This routine informs the resource manager to disassociate with the transaction branch. If current RM is still not opened or current context is not in a transaction state,
tprmend() does nothing and return success to caller.
The first parameter rmid currently must be a value which is configured in UBBCONFIG of this multiple resource manager group. The flags must be 0.
Upon failure, tprmend() returns -1 and sets the tperrno to indicate the error condition.
Upon failure, tprmend() sets tperrno to one of the following values:
tprmend() was called in a improper context (for example, it war invoked in a server which was not specified with
-M option when executing buildserver).
tprmend() was called in a non-transaction context.
tprmopen() - Routines for open a specified RM configured in the UBBCONFIG
*RMS section which is associated with a multiple RMs server group.
tprmopen() opens a specific resource manager by name configured in the UBBCONFIG
*RMS section and associated with a multiple resource managers server group. If the resource manager specified by
rmname is already open (that is,
tprmopen() is called more than once with this r
mname, or the
rmname has been opened by
tpopen()), no action is taken and success is returned.
The first parameter rmname currently must be a value which is configured in UBBCONFIG of this multiple resource manager group. The flags must be 0.
Upon failure, tprmopen() returns
-1 and sets the tperrno to indicate the error condition.
Upon failure, tprmopen() sets tperrno to one of the following values:
tprmopen() was called in a improper context(for example, it was invoked by a server which is not built with
-M option by buildserver, it was invoked by a client process).
tprmstart() - Routine that starts work on behalf of a transaction branch of a specified RM in a MRM server.
tprmstart() informs the opened RM to join this transaction work unit on behalf of a transaction branch. If current RM is already in started state, then this routine skips the operation. If current RM is still not opened,
tprmstart() does nothing and return error to caller.
The first parameter rmname currently must be a value which is configured in UBBCONFIG of this multiple resource manager group. The flags must be 0.
tprmstart() does not support old preliminary specification type of RM.
Upon failure, tprmstart() returns
-1 and sets the tperrno to indicate the error condition.
Upon failure, tprmopen() sets tperrno to one of the following values:
tprmstart() was called in a improper context (for example, it was invoked by a server which is not in a Multiple RMs server group or current process was not built with
-M option in buildserver, the current RM is still not open).
tpsblktime() —
Routine for setting blocktime in seconds or milliseconds for the next service call or for all service calls
#include <atmi.h>
int tpsblktime(int blktime,long flags
)
tpsblktime() is used to set the blocktime value, in seconds or milliseconds, of a potential blocking
API. A
potential blocking API is defined as: any system API that can use the flag
TBNOBLOCK as a value. It does not have any effect on transaction timeout values.
The blktime range is 0 to 32767. If the flag
TPBLK_MILLISECOND is set, the scope is from 0 to 32767 milliseconds; if the flag
TPBLK_SECOND is set, the scope is from 0 to 32767 seconds. Effective blocktime values are rounded up to the nearest multiple of the
SCANUNIT value as depicted in the following example:
A 0 value indicates that any previously set blocking time flag value is cancelled, and the blocking time set with a different blocktime flag value prevails. If
tpsblktime() is not called, the
BLOCKTIME value in the
*SERVICES section or the default
*RESOURCES section of the
UBBCONFIG file is used.
|
Note:
|
Blocking timeouts set with tpsblktime() take precedence over the BLOCKTIME parameter set in the SERVICES and RESOURCES section of the UBBCONFIG file. The precedence for blocktime checking is as follows: tpsblktime(TPBLK_NEXT), tpsblktime(TPBLK_ALL), *SERVICES, *RESOURCES
|
A TPBLK_NEXT flag value overrides a
TPBLK_ALL flag value for those API calls that immediately follow it. For example:
tpcall(two) will have a 30 millisecond blocking timeout based on
tpsblktime (
30,TPBLK_NEXT|TPBLK_MILLISECOND).
tpcall(one) and
tpcall(three) will have a 50 second blocking timeout based on tpsblktime (
50,TPBLK_ALL).
tpsblktime(TPBLK_NEXT) operates on a per-thread basis. Therefore, it is not necessary for applications to use any mutex around the
tpsblktime(TPBLK_NEXT) call and the subsequent API call which it affects.
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.
When tpsblktime(TPBLK_ALL) is called in a service on a multi-threaded server, it will affect the
currently executed thread only. To set the blocktime for all services, it is best to use
tpsblktime(TPBLK_ALL) with
tpsvrinit(3c) or
tpsvrthrinit(3c).
tpsblktime()returns -1 on error and sets
tperrno to indicate the error condition.
Upon failure, tpsblktime() sets
tperrno to one of the following values:
tpsblktime() was called in a client attached to a workstation handler running an earlier Tuxedo release.
tpscmt()—Routine for setting when
tpcommit() should return.
tpscmt() sets the
TP_COMMIT_CONTROL characteristic to the value specified in
flags. The
TP_COMMIT_CONTROL characteristic affects the way
tpcommit() behaves with respect to returning control to its caller. A program can call
tpscmt() regardless of whether it is in transaction mode or not. Note that if the caller is participating in a transaction that another program must commit, then its call to
tpscmt() does not affect that transaction. Rather, it affects subsequent transactions that the caller will commit.
In most cases, a transaction is committed only when an Oracle Tuxedo ATMI system thread of control calls tpcommit(). There is one exception: when a service is dispatched in transaction mode because the
AUTOTRAN variable in the
*SERVICES section of the
UBBCONFIG file is enabled, then the transaction completes upon calling
tpreturn(). If
tpforward() is called, then the transaction will be completed by the server ultimately calling
tpreturn(). Thus, the setting of the
TP_COMMIT_CONTROL characteristic in the service that calls
tpreturn() determines when
tpcommit() returns control within a server. If
tpcommit() returns a heuristic error code, the server will write a message to a log file.
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.
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.
Upon success, tpscmt() returns the previous value of the
TP_COMMIT_CONTROL characteristic.
Upon failure, tpscmt() returns -1 and sets
tperrno to indicate the error condition.
Upon failure, tpscmt() sets
tperrno to one of the following values:
flags is not one of
TP_CMT_LOGGED or
TP_CMT_COMPLETE.
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(). See
buildserver(1) for details on linking resource managers that meet the XA interface into a server such that operations performed by that resource manager are part of an Oracle Tuxedo ATMI system transaction.
tpseal()—Marks a typed message buffer for encryption.
tpseal() marks, or registers, a message buffer for encryption. The principal who owns
hKey can decrypt this buffer and access its content. A buffer may be sealed for more than one recipient principal by making several calls to
tpseal().
data must point to a valid typed message buffer either (1) previously allocated by a process calling
tpalloc() or (2) delivered by the system to a receiving process. The content of the buffer may be modified after
tpseal() is invoked.
When the message buffer pointed to by data is transmitted from a process, the public key software encrypts the message content and attaches an encryption envelope to the message buffer for each encryption registration request. An encryption envelope enables a receiving process to decrypt the message.
The flags argument is reserved for future use and must be set to 0.
tpsend()—Routine for sending a message in a conversational connection.
#include <atmi.h>
int tpsend(int cd, char *data, long len, long flags, long *revent)
tpsend() is used to send data across an open connection to another program. The caller must have control of the connection.
tpsend()’s first argument,
cd, specifies the open connection over which data is sent.
cd is a descriptor returned from either
tpconnect() or the
TPSVCINFO parameter passed to a conversational service.
The second argument, data, must point to a buffer previously allocated by
tpalloc().
len specifies how much of the buffer to send. 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). Also,
data can be NULL in which case
len is ignored (no application data is sent—this might be done, for instance, to grant control of the connection without transmitting any data). The type and subtype of
data must match one of the types and subtypes recognized by the other end of the connection.
Received by the originator of a conversation, this event indicates that the subordinate of the conversation has issued tpreturn() without having control of the conversation. In addition,
tpreturn() has been issued in a manner different from that described for
TPEV_SVCFAIL below. This event can be caused by an ACL permissions violation; that is, the originator does not have permission to connect to the receiving process. This event is not returned at the time the
tpconnect() is issued, but is returned with the first
tpsend() (following a
tpconnect() with flag
TPSENDONLY) or
tprecv() (following a
tpconnect() with flag
TPRECVONLY). A system event and a log message are also generated.
If the value of either SVCTIMEOUT in the
UBBCONFIG file or
TA_SVCTIMEOUT in the
TM_MIB is non-zero,
TPESVCERR is returned when a service timeout occurs.
Upon return from tpsend() where
revent is set to either
TPEV_SVCSUCC or
TPEV_SVCFAIL, the
tpurcode() global contains an application-defined value that was sent as part of
tpreturn(). The function
tpsend() returns -1 on error and sets
tperrno to indicate the error condition. Also, if an event exists and no errors were encountered,
tpsend() returns -1 and
tperrno is set to
[TPEEVENT].
Upon failure, tpsend() sets
tperrno to one of the following values:
An event occurred. data is not sent when this error occurs. The event type is returned in
revent.
tpsend() was called in an improper context (for example, the connection was established such that the calling program can only receive data).
tpservice() is the template for writing service routines. This template is used for services that receive requests via
tpcall(),
tpacall() or
tpforward() routines as well as by services that communicate via
tpconnect(),
tpsend() and
tprecv() routines.
name is populated with the service name that the requester used to invoke the service.
The setting of flags upon entrance to a service routine indicates attributes which the service routine may want to note. The following are the possible values for
flags:
data points to the data portion of a request message and
len is the length of the data. The buffer pointed to by
data was allocated by
tpalloc() in the communication manager. This buffer may be grown by the user with
tprealloc(); however, it cannot be freed by the user. It is recommended that this buffer be the one passed to either
tpreturn() or
tpforward() when the service ends. If a different buffer is passed to those routines, then that buffer is freed by them. Note that the buffer pointed to by
data will be overwritten by the next service request even if this buffer is not passed to
tpreturn() or
tpforward().
data may be NULL if no data accompanied the request. In this case,
len will be 0.
When TPCONV is set in
flags,
cd is the connection descriptor that can be used with
tpsend() and
tprecv() to communicate with the program that initiated the conversation.
appkey is set to the application key assigned to the requesting client by the application defined authentication service. This key value is passed along with any and all service requests made while within this invocation of the service routine.
appkey will have a value of -1 for originating clients that do not pass through the application authentication service.
cltid is the unique client identifier for the originating client associated with this service request. The definition of this structure is made available to the application in
atmi.h solely so that client identifiers may be passed between application servers if necessary. Therefore, the semantics of the fields defined below are not documented and applications should not manipulate the contents of
CLIENTID structures. Doing so will invalidate the structures. The
CLIENTID structure includes the following member:
A service routine does not return any value to its caller, the communication manager 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 a log file and return a service error to the originator or requester. All open connections to subordinates will be disconnected immediately, and any outstanding asynchronous replies will be marked stale. If the server was in transaction mode at the time of failure, the transaction is marked abort-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().
tpsetcallinfo()- Routine for adding out-of-band information to a Tuxedo request.
tpsetcallinfo() is used for adding out-of-band data to an existing Tuxedo typed message. It supports the following parameters:
Upon failure, tpsetcallinfo() returns
-1 and sets
tperrno to indicate the error condition.
Upon failure, tpsetcallinfo() sets tperrno to one of the following values:
tpsetctxt()—Sets a context identifier for the current application association.
tpsetctxt() defines the context in which the current thread operates. This function operates on a per-thread basis in a multithreaded environment, and on a per-process basis in a non-threaded environment.
A thread in the TPINVALIDCONTEXT state is prohibited from issuing calls to most ATMI functions. (For a complete list of the functions that may and may not be called, see
“Introduction to the C Language Application-to-Transaction Monitor Interface.”.) Therefore, you may sometimes need to move a thread out of the
TPINVALIDCONTEXT state. To do so, call
tpsetctxt() with context set to
TPNULLCONTEXT or another valid context. (It is also allowable to call the
tpterm() function to exit from the
TPINVALIDCONTEXT state.)
Upon failure, tpsetctxt() sets
tperrno to one of the following values:
tpsetctxt() has been called in an improper context. For example: (a) it has been called in a server-dispatched thread; (b) it has been called in a process that has not called
tpinit(); (c) it has been called in a process that has called
tpinit() without specifying the
TPMULTICONTEXTS flag; or (d) it has been called from more than one thread in a process where the
TMNOTHREADS environment variable has been turned on.
tpsetmbenc()—Sets the code-set encoding name for a typed buffer.
tpsetmbenc() sets the codeset encoding name to be included with a Tuxedo system request. Once this function sets a non-NULL encoding name in the caller's buffer, all requests sent (via
tpcall(),
tpsend()) include this string until reset or unset. An initial codeset encoding name is applied to a MBSTRING buffer, during
tpalloc(), using the TPMBENC environment variable. An MBSTRING buffer without an encoding name defined is invalid.
The bufp argument is a valid pointer to a typed buffer with an encoding name.
The enc_name argument is the encoding name to use to identify the codeset encoding.
The flags argument is 0 or RM_ENC. For RM_ENC the encoding name will be removed from the MBSTRING buffer and the
enc_name argument will be ignored. Note that an MBSTRING buffer without an encoding name will fail the _tmconvmb() conversion.
Upon success, tpsetmbenc() returns a 0 value otherwise it returns a non-zero on error and sets
tperrno to indicate the error condition. This function may fail for the following reasons.
buf,
enc_name argument is NULL or
enc_name is not a valid name to use.
tpsetrepos() - adds, edits, or deletes service parameter information from a Tuxedo Service Metadata repository file
tpsetrepos() provides an alternative repository access interface to the
.TMMETAREPOS service provided by
TMMETADATA(5). It adds, edits, or deletes parameter information from a Tuxedo Service Metadata repository file. To use
tpsetrepos(), the metadata repository file must reside on the native client or server that initiates the request. This allows for repository information access even when
TMMETADATA(5)has not been booted.
tpsetrepos() is available in processes linked with the Oracle Tuxedo native libraries, but is not available in processes linked with the Oracle Tuxedo workstation libraries.
|
Note:
|
tpsetrepos() cannot be used to add, edit, or delete service parameter information in a JOLT Repository file.
|
METAREPOS(5)describes the FML32 buffer format
tpsetrepos()uses. It is similar to the format used by
MIB(5).
tpsetrepos() returns 0 on success. On failure, it sets tperrno and returns -1. On most failure conditions, the
TA_ERROR field in
*odata is populated with information about the specific error, as is done by the Tuxedo MIB.
Upon failure, tpsetrepos() sets
tperrno to one of the following values:
|
Note:
|
Except for TPEINVAL, odata is modified to include TA_ERROR, TA_STATUS for each service entry to further qualify the error condition.
|
The MIB-like request failed. odata is updated and returned to the caller with
FML32 fields indicating the cause of the error as discussed in
MIB(5).
tpsetrepos() was improperly called. The reposfile file argument given is not a valid repository file.
tpsetunsol()—Sets the method for handling unsolicited messages.
tpsetunsol() allows a client to identify the routine that should be invoked when an unsolicited message is received by the Oracle Tuxedo ATMI system libraries. Before the first call to
tpsetunsol(), any unsolicited messages received by the Oracle Tuxedo ATMI system libraries on behalf of the client are logged and ignored. A call to
tpsetunsol() with a NULL function pointer has the same effect. The method used by the system for notification and detection is determined by the application default, which can be overridden on a per-client basis (see
tpinit(3c)).
data points to the typed buffer received and
len is the length of the data.
flags are currently unused.
data can be NULL if no data accompanied the notification.
data may be of a buffer type/subtype that is not known by the client, in which case the message data is unintelligible.
data cannot be freed by application code. However, the system frees it and invalidates the data area following return.
If tpsetunsol() is called from a thread that is not currently associated with a context, this establishes a per-process default unsolicited message handler for all new
tpinit() contexts created. It has no effect on contexts already associated with the system. A specific context may change this default unsolicited message handler by calling
tpsetunsol() again when the context is active. The per-process default unsolicited message handler may be changed by again calling
tpsetunsol() in a thread not currently associated with a context.
Upon success, tpsetunsol() returns the previous setting for the unsolicited message handling routine. (NULL is a successful return indicating that no message handling function had been set previously.)
Upon failure, tpsetunsol() sets
tperrno to one of the following values:
tpsetunsol() has been called in an improper context. For example, it has been called from within a server.
The interfaces described in tpnotify(3c) are supported on native site UNIX-based and Windows processors. In addition, the routines
tpbroadcast() and
tpchkunsol(), as well as the function
tpsetunsol(), are supported on UNIX and MS-DOS workstation processors.
tpsign()—Marks a typed message buffer for digital signature.
tpsign() marks, or registers, a message buffer for digital signature on behalf of the principal associated with
hKey.
data must point to a valid typed message buffer either (1) previously allocated by a process calling
tpalloc() or (2) delivered by the system to a receiving process. The content of the buffer may be modified after
tpsign() is invoked.
When the buffer pointed to by data is transmitted from a process, the public key software generates and attaches a digital signature to the message buffer for each digital-signature registration request. A digital signature enables a receiving process to verify the signer (originator) of the message.
The flags argument is reserved for future use and must be set to 0.
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.
tpsprio() has no effect on messages sent via
tpconnect() or
tpsend().
Upon failure, tpsprio() returns -1 and sets
tperrno to indicate the error condition.
Upon failure, tpsprio() sets
tperrno to one of the following values:
tpstrerror()—Gets error message string for an Oracle Tuxedo ATMI system error.
tpstrerror() is used to retrieve the text of an error message from
LIBTUX_CAT.
err is the error code set in
tperrno when an Oracle Tuxedo ATMI system function call returns a -1 or other failure value.
Upon success, tpstrerror() returns a pointer to a string that contains the error message text.
If err is an invalid error code,
tpstrerror() returns a NULL.
Upon failure, tpstrerror() returns a NULL but does not set
tperrno.
tpstrerrordetail()—Gets error detail message string for an Oracle Tuxedo ATMI system error.
tpstrerrordetail() is used to retrieve the text of an error detail of an Oracle Tuxedo ATMI system error.
err is the value returned by
tperrordetail().
Currently flags is reserved for future use and must be set to 0.
Upon failure, tpstrerrordetail() returns a NULL but does not set
tperrno.
The caller uses tpsubscribe() to subscribe to an event or set of events named by
eventexpr. Subscriptions are maintained by the Oracle Tuxedo ATMI EventBroker,
TMUSREVT(5), and are used to notify subscribers when events are posted via
tppost(). Each subscription specifies a notification method which can take one of three forms: client notification, service calls, or message enqueuing to stable-storage queues. Notification methods are determined by the subscriber’s process type and the arguments passed to
tpsubscribe().
The event or set of events being subscribed to is named by eventexpr, a NULL-terminated string of at most 255 characters containing a regular expression. For example, if
eventexpr is “
\e\e..*”, the caller is subscribing to all system-generated events; if
eventexpr is “
\e\e.SysServer.*”, the caller is subscribing to all system-generated events related to servers. If
eventexpr is “
[A-Z].*”, the caller is subscribing to all user events starting with A-Z; if
eventexpr is “
.*(ERR|err).*”, the caller is subscribing to all user events containing either the substring
ERR or the substring
err in the event name. Events called
account_error and
ERROR_STATE, for example, would both qualify. For more information on regular expressions, see
“Regular Expressions” on page 260.
If present, filter is a string containing a Boolean filter rule that must be evaluated successfully before the EventBroker posts the event. Upon receiving an event to be posted, the EventBroker applies the filter rule, if one exists, to the posted event’s data. If the data passes the filter rule, the EventBroker invokes the notification method; otherwise, the broker does not invoke the associated notification method. The caller can subscribe to the same event multiple times with different filter rules.
If the subscriber is an Oracle Tuxedo ATMI system client process and ctl is NULL, then the EventBroker sends an unsolicited message to the subscriber when the event to which it subscribed is posted. That is, when an event name is posted that evaluates successfully against
eventexpr, the EventBroker tests the posted data against the filter rule associated with
eventexpr. If the data passes the filter rule or if there is no filter rule for the event, then the subscriber receives an unsolicited notification along with any data posted with the event. In order to receive unsolicited notifications, the client must register (via
tpsetunsol()) an unsolicited message handling routine. If an Oracle Tuxedo ATMI system server process calls
tpsubscribe() with a NULL
ctl parameter, then
tpsubscribe() fails setting
tperrno to
TPEPROTO.
Setting this flag indicates that the subscriber wants event notifications to be sent to the Oracle Tuxedo ATMI system service routine named in ctl−>name1. That is, when an event name is posted that evaluates successfully against
eventexpr, the EventBroker tests the posted data against the filter rule associated with
eventexpr. If the data passes the filter rule or if there is no filter rule for the event, then a service request is sent to
ctl−>name1 along with any data posted with the event. The service name in
ctl−>name1 can be any valid Oracle Tuxedo ATMI system service name and it may or may not be active at the time the subscription is made. Service routines invoked by the EventBroker should return with no reply data. That is, they should call
tpreturn() with a NULL data argument. Any data passed to
tpreturn() will be dropped.
TPEVSERVICE and
TPEVQUEUE are mutually exclusive flags.
If TPEVTRAN is also set in
ctl−>flags, then if the process calling
tppost() is in transaction mode, the EventBroker calls the subscribed service routine such that it will be part of the poster’s transaction. Both the EventBroker,
TMUSREVT(5), and the subscribed service routine must belong to server groups that support transactions (see
UBBCONFIG(5) for details). If
TPEVTRAN is not set in
ctl−>flags, then the EventBroker calls the subscribed service routine such that it will not be part of the poster’s transaction.
Setting this flag indicates that the subscriber wants event notifications to be enqueued to the queue space named in ctl−>name1 and the queue named in
ctl−>name2. That is, when an event name is posted that evaluates successfully against
eventexpr, the EventBroker tests the posted data against the filter rule associated with
eventexpr. If the data passes the filter rule or if there is no filter rule for the event, then the EventBroker enqueues a message to the queue space named in
ctl−>name1 and the queue named in
ctl−>name2 along with any data posted with the event. The queue space and queue name can be any valid Oracle Tuxedo ATMI system queue space and queue name, either of which may or may not exist at the time the subscription is made.
ctl−>qctl can contain options further directing the EventBroker’s enqueuing of the posted event. If no options are specified, then
ctl−>qctl.flags should be set to
TPNOFLAGS. Otherwise, options can be set as described in the “Control Parameter” subsection of
tpenqueue(3c) (specifically, see the section describing the valid list of flags controlling input information for
tpenqueue(3c)).
TPEVSERVICE and
TPEVQUEUE are mutually exclusive flags.
If TPEVTRAN is also set in
ctl−>flags, then if the process calling
tppost() is in transaction mode, the EventBroker enqueues the posted event and its data such that it will be part of the poster’s transaction. The EventBroker,
TMUSREVT(5), must belong to a server group that supports transactions (see
UBBCONFIG(5) for details). If
TPEVTRAN is not set in
ctl−>flags, then the EventBroker enqueues the posted event and its data such that it will not be part of the poster’s transaction.
If this flag is used with TPEVTRAN and the resource is not available at the time of event notification, then the EventBroker will return to the poster such that its transaction must be aborted. That is, even though the subscription remains intact, the resource’s unavailability will cause the poster’s transaction to fail.
If the subscriber is an Oracle Tuxedo ATMI system client process and ctl is NULL (such that the caller receives unsolicited notifications when events are posted), then its system-defined client identifier (known as a
CLIENTID) is also used to detect matches. That is,
tpsubscribe() fails if
eventexpr,
filter, and the caller’s
CLIENTID match those of a subscription already known to the EventBroker.
If the caller has set ctl−>flags to
TPEVSERVICE, then
tpsubscribe() fails if
eventexpr,
filter, and the service name set in
ctl−>name1 match those of a subscription already known to the EventBroker.
For subscriptions to stable-storage queues, the queue space, queue name, and correlation identifier are used, in addition to eventexpr and
filter, when determining matches. The correlation identifier can be used to differentiate among several subscriptions for the same event expression and filter rule, destined for the same queue. Thus, if the caller has set
ctl−>flags to
TPEVQUEUE, and
TPQCOORID is not set in
ctl−>qctl.flags, then
tpsubscribe() fails if
eventexpr,
filter, the queue space name set in
ctl−>name1, and the queue name set in
ctl−>name2 match those of a subscription (which also does not have a correlation identifier specified) already known to the EventBroker. Further, if
TPQCOORID is set in
ctl−>qctl.flags, then
tpsubscribe() fails if
eventexpr,
filter,
ctl−>name1,
ctl−>name2, and
ctl−>qctl.corrid match those of a subscription (which has the same correlation identifier specified) already known to the EventBroker.
The regular expressions described in Table 17 are much like those used in the UNIX system editor,
ed(1). The alternation operator, (
|), has been added along with some other practical things. In general, however, there should be few surprises.
|
|
|
|
|
Itself (character is any ASCII character except the special ones mentioned below).
|
|
|
|
|
|
Its unspecial self. The special characters are . * + ? | ( ) [ { and \\.
|
|
|
any character in the class denoted by a sequence of characters and/or ranges. A range is given by the construct character- character. For example, the character class, [a-zA-Z0-9_], will match any alphameric character or “_”. To be included in the class, a hyphen, “-”, must be escaped (preceded by a “\\”) or appear first or last in the class. A literal “]” must be escaped or appear first in the class. A literal “^” must be escaped if it appears first in the class.
|
|
|
|
|
|
|
|
|
Either the left RE or the right RE. (left to right alternation)
|
|
|
|
|
|
|
|
|
|
|
|
n occurrences of RE. n must be between 0 and 255, inclusive.
|
|
|
m through n occurrences of RE, inclusive. A missing m is taken to be zero. A missing n denotes m or more occurrences of RE.
|
|
|
|
|
|
The text matching RE is copied into the nth user buffer. n may be 0 through 9. User buffers are cleared before matching begins and loaded only if the entire pattern is matched.
|
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.
Upon failure, tpsubscribe() returns -1 and sets
tperrno to indicate 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.)
buffer(3c),
tpenqueue(3c),
tppost(3c),
tpsetunsol(3c),
tpunsubscribe(3c),
Fboolco, Fboolco32, Fvboolco, Fvboolco32(3fml),
Fboolev, Fboolev32, Fvboolev, Fvboolev32(3fml),
EVENTS(5),
EVENT_MIB(5),
TMSYSEVT(5),
TMUSREVT(5),
tuxtypes(5),
typesw(5),
UBBCONFIG(5)
tpsuspend() is used to suspend the transaction active in the caller’s process. A transaction begun with
tpbegin() may be suspended with
tpsuspend(). Either the suspending process or another process may use
tpresume() to resume work on a suspended transaction. When
tpsuspend() returns, the caller is no longer in transaction mode. However, while a transaction is suspended, all resources associated with that transaction (such as database locks) remain active. Like an active transaction, a suspended transaction is susceptible to the transaction timeout value that was assigned when the transaction first began.
For the transaction to be resumed in another process, the caller of tpsuspend() must have been the initiator of the transaction by explicitly calling
tpbegin().
tpsuspend() may also be called by a process other than the originator of the transaction (for example, a server that receives a request in transaction mode). In the latter case, only the caller of
tpsuspend() may call
tpresume() to resume that transaction. This case is allowed so that a process can temporarily suspend a transaction to begin and do some work in another transaction before completing the original transaction (for example, to run a transaction to log a failure before rolling back the original transaction).
tpsuspend() returns in the space pointed to by
tranid the transaction identifier being suspended. The caller is responsible for allocating the space to which
tranid points. It is an error for
tranid to be NULL.
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().
Currently, flags are reserved for future use and must be set to 0.
tpsuspend()can take effect in all participated resource managers including those in a multiple resource mangers server group in a global transaction.
tpsuspend() returns -1 on error and sets
tperrno to indicate the error condition.
tranid is a NULL pointer or
flags is not 0. The caller’s state with respect to the transaction is not changed.
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.
tpsvrdone()—Terminates an Oracle Tuxedo ATMI system server.
The Oracle Tuxedo ATMI 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, Oracle Tuxedo ATMI 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 Oracle Tuxedo ATMI system will close its connections, ignore any pending replies, and abort the transaction before the server exits.
When called in tpsvrdone(), the
tpreturn() and
tpforward() functions simply return with no effect.
tpsvrinit()—Initializes an Oracle Tuxedo system server.
The Oracle Tuxedo ATMI 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, Oracle Tuxedo ATMI system communication may be performed and transactions may be defined in this routine. However, if
tpsvrinit() returns with either open connections or asynchronous replies pending, or while still in transaction mode, the Oracle Tuxedo ATMI system closes the connections, ignores any pending replies, and aborts the transaction before the server exits.
If a server has been defined as a single-threaded server, the default tpsvrinit() calls
tpsvrthrinit(), and the default version of
tpsvrthrinit() calls
tx_open(). If a server has been defined as a multithreaded server,
tpsvrthrinit() is called in each server dispatch thread, but is not called from
tpsvrinit(). Regardless of whether the server is single-threaded or multithreaded, the default version of
tpsvrinit() calls
userlog() to indicate that the server started successfully.
|
Note:
|
When invoking tpsvrinit() in your code, avoid long blocking actions. Otherwise, when one remote server in an MP configuration has trouble with tpsvrinit() processing, then tmboot fails to boot the other servers on that node.
|
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 itself should not call
exit().
When tpsvrinit() returns -1, the system does not restart the server. Instead, the administrator must run
tmboot to restart the server.
The Oracle Tuxedo ATMI server abstraction calls tpsvrthrdone() during the termination of each thread that has been started to handle dispatched service requests. In other words, even if a thread is terminated before it has handled a request, the
tpsvrdone() function is called. When this routine is called, the thread of control is still part of the Oracle Tuxedo ATMI server, but the thread has finished processing all service requests. Thus, Oracle Tuxedo ATMI communication may be performed and transactions may be defined in this routine. However, if
tpsvrthrdone() returns with either open connections or asynchronous replies pending, or while still in transaction mode, the Oracle Tuxedo ATMI system closes the connections, ignores any pending replies, and aborts the transaction before the server dispatch thread exits.
tpsvrthrdone() is called even in single-threaded servers. In a single-threaded server,
tpsvrthrdone() is called from the default version of
tpsvrdone(). In a server with the potential for multiple dispatch threads,
tpsvrdone() does not call
tpsvrthrdone().
When called from tpsvrthrdone(), the
tpreturn() and
tpforward() functions simply return with no effect.
The Oracle Tuxedo ATMI server abstraction calls tpsvrthrinit() during the initialization of each thread that handles dispatched service requests. This routine is called after the thread of control has become part of the Oracle Tuxedo ATMI server but before the thread handles any service requests. Thus, Oracle Tuxedo ATMI communication may be performed and transactions may be defined in this routine. However, if
tpsvrthrinit() returns with either open connections or asynchronous replies pending, or while still in transaction mode, the Oracle Tuxedo ATMI system closes the connections, ignores any pending replies, and aborts the transaction before the server dispatch thread exits.
tpsvrthrinit() is called even in single-threaded servers. In a single-threaded server,
tpsvrthrinit() is called from the default version of
tpsvrinit(). In a server with the potential for multiple dispatch threads,
tpsvrinit() does not call
tpsvrthrinit().
If an error occurs in tpsvrthrinit(), the application can cause the server dispatch thread to exit gracefully (and not take any service requests) by returning -1. The application should not call
exit() or any operating system thread exit function.
getopt(3) in a C language reference manual
tpterm() removes a client from an Oracle Tuxedo ATMI system application. If the client is in transaction mode, then the transaction is rolled back. When
tpterm() returns successfully, the caller can no longer perform Oracle Tuxedo ATMI client operations. Any outstanding conversations are immediately disconnected.
If tpterm() is called more than once (that is, if it is called after the caller has already left the application), no action is taken and success is returned.
|
•
|
tpsetctxt() with the TPNULLCONTEXT context or another valid context
|
It is forbidden to call tpsetctxt() with a context of
TPINVALIDCONTEXT; doing so results in failure with
tperrno set to
TPEPROTO. When a thread invokes ATMI functions other than
tpsetunsol()that do not require the caller to be associated with an application, these functions behave as if they were invoked in the NULL context. Client applications using unsolicited thread notification should explicitly call
tpterm() to terminate the unsolicited notification thread.
After invoking tpterm(), a thread is placed in the
TPNULLCONTEXT context. Most ATMI functions invoked by a thread in the
TPNULLCONTEXT context perform an implicit
tpinit(). Whether or not the call to
tpinit() succeeds depends on the usual determining factors, unrelated to context-specific or thread-specific issues.
Upon failure, tpterm() leaves the calling process in its original context state, returns -1, and sets
tperrno to indicate the error condition.
Upon failure, tpterm() sets
tperrno to one of the following values:
tpterm() was called in an improper context (for example, the caller is a server).
tptypes()—Routine to determine information about a typed buffer.
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.
Upon success, tptypes() returns the size of the allocated buffer. Note that this value is the allocated buffer, which is used to save the return data, rather than the length of the return data.
Upon failure, tptypes() sets tperrno to one of the following values:
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 shut down.
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 127 characters or less. (See the *SERVICES section of
UBBCONFIG(5)). Longer names will be accepted and truncated to 127 characters. Care should be taken such that truncated names do not match other service names.
Upon failure, tpunadvertise() returns -1 and sets
tperrno to indicate the error condition.
Upon failure, tpunadvertise() sets
tperrno to one of the following values:
svcname is NULL or the NULL string (“”).
svcname is not currently advertised by the server.
tpunadvertise() was called in an improper context (for example, by a client).
The caller uses tpunsubscribe() to remove an event subscription or a set of event subscriptions from the Oracle Tuxedo EventBroker’s list of active subscriptions.
subscription is an event subscription handle returned by
tpsubscribe(). Setting
subscription to the wildcard value, -1, directs
tpunsubscribe() to unsubscribe to all non-persistent subscriptions previously made by the calling process. Non-persistent subscriptions are those made without the
TPEVPERSIST bit setting in the
ctl−>flags parameter of
tpsubscribe(). Persistent subscriptions can be deleted only by using the handle returned by
tpsubscribe().
Upon completion of tpunsubscribe(),
tpurcode() contains the number of subscriptions deleted (zero or greater) from the EventBroker’s list of active subscriptions.
tpurcode() may contain a number greater than 1 only when the wildcard handle, -1, is used. Also,
tpurcode() may contain a number greater than 0 even when
tpunsubscribe() completes unsuccessfully (that is, when the wildcard handle is used, the EventBroker may have successfully removed some subscriptions before it encountered an error deleting others).
Upon failure, tpunsubscribe() returns -1 and sets
tperrno to indicate 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.)
tputrace()—User-defined trace information application.
tputrace(3c)is a
user-defined API the allows flexibility in monitoring and obtaining detailed trace output information (such as full user data content that is passed to or returned from ATMI functions) and defines how and where this information is output. By default,
tputrace() outputs trace record information to
userlog(3c) if the user does not update or modify otherwise.
tputrace(3c) is called exclusively by specifying the
utrace receiver with
TMTRACE. For example:
TMTRACE=atmi:utrace. Specifying the
utrace receiver automatically invokes
tputrace(3c)and applies it only to atmi trace category records for output. For more
TMTRACE and
utrace receiver information, see
tmtrace(5) in the
File Formats, Data Descriptions, MIBs, and System Processes Reference.
Valid tputrace(3c) arguments are:
Indicates whether tputrace(3c) is called when entering or leaving an ATMI function. Set values as follows:
0 = entering,
1 = leaving.
Define arguments passed to the tputrace(3c) output function. This includes user data or flags passed to ATMI functions. The list of the arguments for each ATMI functions are defined in the
tputrace() example implementation in the
Example(s) section. The argument list is also available from
tmtrace(5) trace information output.
A separate Tuxedo library, libutrace, is used in conjunction with
tputrace(). The default
libutrace is installed in the Tuxedo system shared library directory (
$TUXDIR/lib in UNIX and
%TUXDIR%\bin in Windows).
If the custom libutrace library is installed in the system directory, it replaces the default
libutrace and is used by all Tuxedo clients and servers on the machine. If the custom
libutrace library is installed in the application directory, it is used only by the clients and the servers in the application.
Whenever tputrace() is modified, the
libutrace library
must be recompiled and linked to Tuxedo 9.0 or later. A sample
tputrace() source file is located in the
$TUXDIR/samples/atmi/libutrace directory.
The Example(s) section further illustrates how to customize
tputrace().
|
WARNING:
|
The default or custom libutrace library is loaded into every Tuxedo application process, including system servers such as BBL or WSL. This being the case, all Tuxedo system servers consume some amount of memory for loading libutrace. The default libutrace library is very small so memory consumption is negligible. But a custom libutrace can consume a larger amount of memory depending on how much functionality the user adds.
|
For this example, when TMTRACE=atmi:utrace is specified it writes the contents of the user data and flags passed to the ATMI functions to the Tuxedo userlog.
tmutrace(3c) returns
0 when run successfully, and return
-1 when a failure occurs.
Failure depends on the tputrace() user-level implementation/customization. The default
tputrace() implementation included in Tuxedo 9.0 or later does not cause failure.
Sets setValidationScheme to Val_Never. The parser will not report Schema validation errors.
Sets setValidationScheme to Val_Always. The parser will always report Schema validation errors.
|
Note:
|
TPXPARSNEVER takes precedent over TPXPARSALWAYS if both arguments are used at the same time.
|
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.
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.
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.
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.
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.
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.
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.
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.
Resets resetCachedGrammarPool. Resets the documents vector pool and release all the associated memory back to the system.
Upon success, tpxmltofml32 () returns
0. This function returns
-1 on error and sets
tperrno to indicate the error condition.
Either fml32bufp or
xmlbufp is not a valid typed buffer, or parser has problems understanding the input.
Sets setValidationScheme to Val_Never. The parser will not report Schema validation errors.
Sets setValidationScheme to Val_Always. The parser will always report Schema validation errors.
|
Note:
|
TPXPARSNEVER takes precedent over TPXPARSALWAYS if both arguments are used at the same time.
|
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.
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.
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.
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.
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.
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.
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.
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.
Resets resetCachedGrammarPool. Resets the documents vector pool and release all the associated memory back to the system.
Upon success, tpxmltofml () returns a 0. This function returns -1 on error and sets
tperrno to indicate the error condition.
Either fml32bufp or
xmlbufp is not a valid typed buffer, or parser has problems understanding the input.
TRY()—Exception-returning interface.
#include <texc.h>
TRY
try_block
[ CATCH(exception_name) handler_block] ...
[CATCH_ALL handler_block]
ENDTRY
TRY
try_block
FINALLY
finally_block
ENDTRY
RAISE(exception_name)
RERAISE
/* declare exception */
EXCEPTION exception_name;
/* initialize address (application) exception */
EXCEPTION_INIT(EXCEPTION exception_name)
/* intialize status exception (map status to exception */
exc_set_status(EXCEPTION *exception_name, long status)
/* map status exception to status */
exc_get_status(EXCEPTION *exception_name, long *status)
/* compare exceptions */
exc_matches(EXCEPTION *e1, EXCEPTION *e2)
/* print error to stderr */
void exc_report(EXCEPTION *exception)
The TRY/
CATCH interface provides a mechanism to handle exceptions without the use of status variables (for example,
errno or status variables passed back from an RPC operation). These macros are defined in
texc.h.
The TRY try_block is a block of C or C++ declarations and statements in which an exception may be raised (code that is not associated with raising an exception should be placed before or after the
try_block). Each
TRY/
ENDTRY pair constitutes a “scope,” with respect to exceptions (not unlike C scoping), or a region of code over which exceptions are caught. These scopes can be properly nested. When an exception is raised, an error is reported to the application by searching the active scopes for actions written to handle (“absorb”) an exception (
CATCH or
CATCH_ALL clauses) or complete the scopes (
FINALLY clauses). If a scope does not handle an exception, the scope is torn down with the exception raised at the next higher level (unwinding the stack of exception scopes). Execution resumes at the point after which the exception is handled; there is no provision for resuming execution at the point of error. If the exception is not handled by any scope, the program is terminated (a message is written to the log via
userlog(3c) and
abort(3) is called).
Zero or more occurrences of CATCH (
exception_name)
handler_block may be provided. Each
handler_block is a block of C or C++ declarations and statements in which the associated exception (
exception_name) is processed (normally, actions are specified for recovery from the failure). If an exception is raised by a statement in
try_block, then the first
CATCH clause that matches the exception is executed.
Within a CATCH or
CATCH_ALL handler_block, the current exception can be referenced by the
EXCEPTION pointer
THIS_CATCH (for example, for logic based on or printing the exception value).
If the exception is not handled by one of the CATCH clauses, then the
CATCH_ALL clause is executed. By default, no further action is taken for an exception that is handled by a
CATCH or
CATCH_ALL clause. If no
CATCH_ALL clause exists, then the exception is raised at the
try_block at the next higher level, assuming that the
try_block is nested within another
try_block. If an ANSI C compiler is used, register and automatic variables that are used in the handler blocks should be declared with the
volatile attribute (as is true of any blocks that use
setjmp/longjmp). Also note that output parameters and return values from the functions that can generate an exception are indeterminate.
Within a CATCH or
CATCH_ALL handler_block, the current exception can be propagated to the next higher level (the exception is “reraised”) using the
RERAISE statement. The
RERAISE statement must appear lexically within the scope of a
handler_block (that is, not within a function called by the
handler_block). Any exception that is caught but not fully handled should be reraised. In many cases, a
CATCH_ALL handler should reraise the exception because the handler is not written to handle every exception. The application should also be written such that an exception is raised to the proper scope such that the handler blocks take the appropriate actions and modify the appropriate state (for example, if an exception occurs while opening a file, the handler function for that level should not try to close the unopened file).
The FINALLY clause can be used to specify an epilogue block of code that is executed after the
try_block, whether or not an exception is raised. If an exception is raised in the
try_block, it is reraised after the
finally_block is executed. This clause can be used to avoid replicating epilogue code twice, once in a
CATCH_ALL clause, and again after the
ENDTRY. It is normally used to execute cleanup activities, restoring invariants (for example, shared data, locks) as the scopes are unwound, whether or not exceptions are raised (that is, on both normal and abnormal exits from the block). Note (in the “Synopsis” section) that a
FINALLY clause cannot be used with a
CATCH or
CATCH_ALL clause for the same
try_block; use nested
try_blocks.
The ENDTRY statement must be used to complete the
TRY block, since it contains code that must be executed to make sure that exceptions are handled and the context is cleaned up. A
try_block,
handler_block, or
finally_block must not contain a
return, non-local jump, or any other means of leaving the block such that the
ENDTRY is not reached (for example,
goto(),
break(),
continue(),
longjmp()).
One type of exception is used to define application exceptions. It is initialized by calling the EXCEPTION_INIT() macro. The address of the exception is stored as the value within the
address exception. Note that this value is valid only within a single address space and will change if the exception is an automatic variable. For this reason, an
address exception should be declared as a static or external variable, not an automatic or register variable. The
exc_get_status() macro will evaluate to -1 for an
address exception. Using the
exc_set_status() macro on this exception will make it a
status exception.
The exc_matches macro can be used to compare two exceptions. To compare equal, the exceptions must both be the same type and have the same value (for example, the same status value for
status exceptions, or the same addresses for
address exceptions). This comparison is used for the
CATCH clause, described above.
The status of RPC operations can be determined portably by defining status variables for each operation ([comm_status] and [
fault_status] parameters are defined via the Attribute Configuration File). The status-returning interface is the only interface provided in the X/OPEN RPC specification. The
fault_status attribute indicates that errors occurring on the server due to incorrectly specified parameter values, resource constraints, or coding errors be reported by an additional status argument or return value. Similarly, the
comm_status attribute indicates that RPC communications failures be reported by an additional status argument or return value. Using status values works well for fine-grained error handling (on a per-call basis) with recovery specified for each possible error on each call, and where it is necessary to retry from the point of failure. The disadvantage is that it is not transparent whether or not the call is local or remote. The remote call has additional status parameters, or a status return value instead of being a void return. Thus, the application must have procedure declarations adjusted between local and distributed code.
For application portability from an OSF/DCE environment, the TRY/
CATCH exception-returning interface is also provided. This interface may not be provided in all environments. However, it has the advantage that procedure declarations need not be adjusted between local and distributed code, maintaining existing interfaces. The checking for errors can be simplified such that each procedure call does not have specific failure checking or recovery code. If an error is not handled at some level, then the program exits with a system error message such that the error is detected and can be corrected (omissions become more obvious). Exceptions work better for coarse-grained exception handling.
The exceptions shown in Table 18 are “built-in” to the use of this exception interface. The first
TRY clause sets up a signal handler to catch the signals list below if they are not currently ignored or caught; the other exceptions are defined only for DCE program portability.
These same exception codes are also defined with the “_e” at the end of the name (for example,
exc_e_SIGBUS is also defined as
exc_SIGBUS_e). Equivalent status codes are defined with similar names but the “
_e_” is changed to “
_s_” (for example,
exc_e_SIGBUS is equivalent to the
exc_s_SIGBUS status code).
In OSF/DCE, the header file is named exc_handling.h; the Oracle Tuxedo ATMI system header file is
texc.h. It is not possible for the same source file to use both DCE and Oracle Tuxedo ATMI system exception handling. Further, within a program, the handling of signal exceptions can only be done by either DCE or the Oracle Tuxedo ATMI system, not both.
abort(2) in a UNIX system reference manual
tuxgetenv() searches the environment list for a string of the form
name=value and, if the string is present, returns a pointer to the
value in the current environment. Otherwise, it returns a NULL pointer.
tuxgetmbaconv()—Gets the value for environment variable
TPMBACONV in the process environment.
The flags argument is not currently used and should be set to 0.
tuxgetnombaconv() returns MBAUTOCONVERSION_ON if the TPMBACONV is set and MBAUTOCONVERSION_OFF if TPMBACONV is not set.
tuxgetmbenc()—Gets the code-set encoding name for environment variable
TPMBENC in the process environment.
The enc_name argument will contain the value of the TPMBENC environment variable upon successful execution of this function. This pointer should be large enough for the encoding name to be copied into.
The flags argument is not currently used and should be set to 0.
tuxputenv()—Changes or adds a value to the environment.
string points to a string of the form “name=value.”
tuxputenv() makes the value of the environment variable name equal to value by altering an existing variable or creating a new one. In either case, the string pointed to by
string becomes part of the environment.
If tuxputenv() cannot obtain enough space, via
malloc(), for an expanded environment, it returns a non-zero integer. Otherwise, it returns zero.
tuxreadenv() reads a file containing environment variables and adds them to the environment, independent of platform. These variables are available using
tuxgetenv() and can be reset using
tuxputenv().
where variable must begin with an alphabetic or underscore character and contain only alphanumeric or underscore characters, and
value may contain any character except newline.
|
•
|
Within the value, strings of the form ${ env} are expanded using variables already in the environment (forward referencing is not supported and if a value is not set, the variable is replaced with the empty string). Backslash (\) may be used to escape the dollar sign and itself. All other shell quoting and escape mechanisms are ignored and the expanded value is placed into the environment.
|
where label follows the same rules for
variable above (lines with invalid
label values are ignored).
If file is NULL, then a default filename is used. The fixed filenames are as follows:
If label is NULL, then only variables in the global section are put into the environment. For other values of
label, the global section variables plus any variables in a section matching the
label are put into the environment.
If tuxreadenv()cannot obtain enough space, via
malloc(), for an expanded environment, or if it cannot open and read a file with a non-NULL name, it returns a non-zero integer. Otherwise,
tuxreadenv() returns zero.
tuxsetmbaconv()—Sets the value for environment variable
TPMBACONV in the process environment.
The onoff argument is equal to
MBAUTOCONVERSION_OFF to unset
TPMBACONV and turn off auto-conversions. It is equal to
MBAUTOCONVERSION_ON to set
TPMBACONV and turn on the typed switch buffers auto-conversion of codeset multi-byte data.
The flags argument is not currently used and should be set to 0.
Upon success, tuxsetnombaconv() returns 0; otherwise, it returns a non-zero value on error. (for example, it returns -1 if the
onoff arg is not one of the defined values).
tuxsetmbenc()—Sets the code-set encoding name for environment variable
TPMBENC in the process environment.
The enc_name argument is the encoding name to use to identify the codeset.
The flags argument is not currently used and should be set to 0.
Upon success, tuxsetmbenc() returns 0; otherwise, it returns a non-zero value on error.
tuxthrputenv()—Changes or adds an environment variable for the current thread.
string points to a string of the form “
name=value.”
tuxthrputenv() makes the value of the environment variable name equal to value by altering an existing variable or creating a new one. In either case, the string pointed to by string becomes part of the environment.
tuxthrputenv works only when it is read by
tuxgetenv(). If
getenv is used,
tuxthrputenv fails.
|
Note:
|
tuxthrputenv() is case-sensitive, it overrides the tuxputenv set value.
|
If tuxthrputenv() cannot obtain enough space via
malloc()for an expanded environment, it returns a non-zero integer. Otherwise, it returns zero.
On MS Windows, tuxthrputenv() overcomes the inability to share environment variables between an application and a Dynamic Link Library. The Oracle Tuxedo ATMI system Workstation DLL maintains an environment copy for each application that is attached to it. This associated environment and context information is destroyed when
tpterm() is called from a Windows application. The value of an environment variable could be changed after the application program calls
tpterm().
tx_begin() is used to place the calling thread of control in transaction mode. The calling thread must first ensure that its linked resource managers have been opened (via
tx_open()) before it can start transactions.
tx_begin() fails (returning [
TX_PROTOCOL_ERROR]) if the caller is already in transaction mode or
tx_open() has not been called.
Once in transaction mode, the calling thread must call tx_commit() or
tx_rollback() to complete its current transaction. There are certain cases related to transaction chaining where
tx_begin() does not need to be called explicitly to start a transaction. See
tx_commit() and
tx_rollback() for details.
tx_close() closes a set of resource managers in a portable manner. It invokes a transaction manager to read resource-manager-specific information in a transaction-manager-specific manner and pass this information to the resource managers linked to the caller.
tx_close() closes all resource managers to which the caller is linked. This function is used in place of resource-manager-specific “close” calls and allows an application program to be free of calls which may hinder portability. Since resource managers differ in their termination semantics, the specific information needed to “close” a particular resource manager must be published by each resource manager.
tx_close() should be called when an application thread of control no longer wishes to participate in global transactions.
tx_close() fails (returning [
TX_PROTOCOL_ERROR]) if the caller is in transaction mode. That is, no resource managers are closed even though some may not be participating in the current transaction.
When tx_close() returns success (
TX_OK), all resource managers linked to the calling thread are closed.
tx_commit() is used to commit the work of the transaction active in the caller’s thread of control.
If the transaction_control characteristic (see
tx_set_transaction_control(3c)) is
TX_UNCHAINED, then when
tx_commit() returns, the caller is no longer in transaction mode. However, if the
transaction_control characteristic is
TX_CHAINED, then when
tx_commit() returns, the caller remains in transaction mode on behalf of a new transaction (see the Return Value and Errors sections below).
tx_info()—Returns global transaction information.
tx_info() returns global transaction information in the structure pointed to by
info. In addition, this function returns a value indicating whether the caller is currently in transaction mode or not. If
info is non-NULL, then
tx_info() populates a
TXINFO structure pointed to by
info with global transaction information. The
TXINFO structure contains the following elements:
If tx_info() is called in transaction mode, then
xid will be populated with a current transaction branch identifier and
transaction_state will contain the state of the current transaction. If the caller is not in transaction mode,
xid will be populated with the NULL XID (see the
tx.h file for details). In addition, regardless of whether the caller is in transaction mode,
when_return,
transaction_control, and
transaction_timeout contain the current settings of the
commit_return and
transaction_control characteristics, and the transaction timeout value in seconds.
If info is NULL, no
TXINFO structure is returned.
Within the same global transaction, subsequent calls to tx_info() are guaranteed to provide an XID with the same
gtrid component, but not necessarily the same
bqual component. Both the X/Open TX interface and the X-Windows system define the type XID. It is not possible to use both X-Windows calls and TX calls in the same file.
tx_open() opens a set of resource managers in a portable manner. It invokes a transaction manager to read resource-manager-specific information in a transaction-manager-specific manner and pass this information to the resource managers linked to the caller.
tx_open() attempts to open all resource managers that have been linked with the application. This function is used in place of resource-manager-specific “open” calls and allows an application program to be free of calls which may hinder portability. Since resource managers differ in their initialization semantics, the specific information needed to “open” a particular resource manager must be published by each resource manager.
If tx_open() returns
TX_ERROR, then no resource managers are open. If
tx_open() returns
TX_OK, some or all of the resource managers have been opened. Resource managers that are not open will return resource-manager-specific errors when accessed by the application.
tx_open() must successfully return before a thread of control participates in global transactions.
Once tx_open() returns success, subsequent calls to
tx_open() (before an intervening call to
tx_close()) are allowed. However, such subsequent calls will return success, and the TM will not attempt to reopen any RMs.
tx_rollback() is used to roll back the work of the transaction active in the caller’s thread of control.
If the transaction_control characteristic (see
tx_set_transaction_control(3c)) is
TX_UNCHAINED, then when
tx_rollback() returns, the caller is no longer in transaction mode. However, if the
transaction_control characteristic is
TX_CHAINED, then when
tx_rollback() returns, the caller remains in transaction mode on behalf of a new transaction (see the Return Value and Errors sections below).
tx_set_commit_return() sets the
commit_return characteristic to the value specified in
when_return. This characteristic affects the way
tx_commit() behaves with respect to returning control to its caller.
tx_set_commit_return() may be called regardless of whether its caller is in transaction mode. This setting remains in effect until changed by a subsequent call to
tx_set_commit_return().
This flag indicates that tx_commit() 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
tx_commit(). However, there is a risk that a transaction will have a heuristic outcome, in which case the caller will not find out about this situation via return codes from
tx_commit(). Under normal conditions, participants that promise to commit during the first phase will do so during the second phase. In certain unusual circumstances however (for example, long-lasting network or node failures), phase 2 completion may not be possible and heuristic results may occur.
This flag indicates that tx_commit() should return after the two-phase commit protocol has finished completely. This setting allows the caller of
tx_commit() to see return codes that indicate that a transaction had or may have had heuristic results.
Under the following conditions, tx_set_commit_return() does not change the setting of the
commit_return characteristic and returns one of these negative values:
when_return is not one of
TX_COMMIT_DECISION_LOGGED or
TX_COMMIT_COMPLETED.
tx_set_transaction_control() sets the
transaction_control characteristic to the value specified in
control. This characteristic determines whether
tx_commit() and
tx_rollback() start a new transaction before returning to their caller.
tx_set_transaction_control() may be called regardless of whether the application program is in transaction mode. This setting remains in effect until changed by a subsequent call to
tx_set_transaction_control().
This flag indicates that tx_commit() and
tx_rollback() should not start a new transaction before returning to their caller. The caller must issue
tx_begin() to start a new transaction.
Under the following conditions, tx_set_transaction_control() does not change the setting of the
transaction_control characteristic and returns one of these negative values:
control is not one of
TX_UNCHAINED or
TX_CHAINED.
tx_set_transaction_timeout() sets the
transaction_timeout characteristic to the value specified in
timeout. This value specifies the time period in which the transaction must complete before becoming susceptible to transaction timeout; that is, the interval between the AP calling
tx_begin() and
tx_commit() or
tx_rollback().
tx_set_transaction_timeout() may be called regardless of whether its caller is in transaction mode or not. If
tx_set_transaction_timeout() is called in transaction mode, the new
timeout value does not take effect until the next transaction.
The initial transaction_timeout value is 0 (no timeout).
timeout specifies the number of seconds allowed before the transaction becomes susceptible to transaction timeout. It may be set to any value up to the maximum value for a
long as defined by the system. A
timeout value of zero disables the timeout feature.
Under the following conditions, tx_set_transaction_timeout() does not change the setting of the
transaction_timeout characteristic and returns one of these negative values:
userlog()—Writes a message to the Oracle Tuxedo ATMI system central event log.
userlog() accepts a
printf(3S) style format specification, with a fixed output file—the Oracle Tuxedo ATMI system central event log.
The central event log is an ordinary UNIX file whose pathname is composed as follows. When attached to a native Tuxedo application, the value of the TUXCONFIG parameter
ULOGPFX is used as the prefix for the filename. If
ULOGPFX is not set in
TUXCONFIG,
$APPDIR/ULOG is used. The prefix is determined at
tpinit() time or at server boot time. When not attached to a native Tuxedo application, the value of the environment variable
ULOGPFX is used as the prefix for the filename. If
ULOGPFX is not set,
ULOG is used. The prefix is determined the first time
userlog() is called. Each time
userlog() is called the date is determined, and the month, day, and year are concatenated to the prefix as
mmddyy to set the name for the file. The first time a process writes to the user log, it first writes an additional message indicating the associated Oracle Tuxedo ATMI system version.
Messages are appended to the log file with a tag made up of the time (hhmmss), system name, process name, and process ID, thread ID, and context ID of the calling process. The tag is terminated with a colon (
:). The name of the process is taken from the pathname of the external variable
proc_name. If
proc_name has value NULL, the printed name is set to
?proc.
userlog() is used by the Oracle Tuxedo ATMI system to record a variety of events.
The userlog mechanism is entirely independent of any database transaction logging mechanism.
|
Note:
|
If ULOGRTNSIZE is not specified, file rotation does not take place.
|
A valid value is of the form TUX_SIGNAL_ULOGPATTERN=<var>signal_number</var>:<var>regular_expression</var> where
<var>signal_number</var> is a positive integer and the
<var>regular_expression</var> format is as described on the
<code>tpsub scribe(3c)</code> manual page.
If the variable ULOGPFX is set to
/application/logs/log and if the first call to
userlog() occurred on 9/7/90, the log file created is named
/application/logs/log.090790. If the call:
If the shell variable ULOGDEBUG has a value of
y, the log message is also written to the standard error of the program named
security.
userlog() hangs if the message sent to it is larger than
BUFSIZ as defined in
stdio.h
userlog() returns the number of characters output, or a negative value if an output error was encountered. Output errors include the inability to open, or write to the current log file. Inability to write to the standard error, when
ULOGDEBUG is set, is not considered an error.
It is recommended that applications’ use of userlog() messages be limited to messages that can be used to help debug application errors; flooding the log with incidental information can make it hard to spot actual errors.
|
•
|
printf(3S) in a UNIX system reference manual
|
Usignal()—Signal handling in an Oracle Tuxedo ATMI system environment.
User code that uses calls rmopen() or
tpinit() should catch signals through the use of the
Usignal() function.
Usignal() behaves like the UNIX
signal() system call, except that
Usignal() first arranges for the signal to be caught by an internal routine before dispatching the user routine.
The UDEFERSIGS() macro should be used when entering a section of critical code. After
UDEFERSIGS() is called, signals are held in a pending state. The
URESUMESIGS() macro should be invoked when the critical section is exited. Note that signal deferrals stack. The stack is implemented via a counter which is initially set to zero. When signals are deferred by a call to
UDEFERSIGS(), the counter is incremented. When signals are resumed, by a call to
URESUMESIGS(), the counter is decremented. If a signal arrives while the counter is non-zero, the processing of the signal is deferred. If the counter is zero when the signal arrives, the signal is processed immediately. If signal resumption causes the counter to be become zero (that is, prior to the resumption it had value 1), any signals that arrived during the deferral period are processed. In general, each call to
UDEFERSIGS() should have a counterpart call to
URESUMESIGS().
UDEFERSIGS increments the deferral counter, but returns the value of the counter prior to its incrementation. The macro
UENSURESIGS() may be used to explicitly set the deferral counter to zero (and thus force the processing of deferred signals), in case the user wishes to protect against unmatching
UDEFERSIGS() and
URESUMESIGS().
The function UGDEFERLEVEL() returns the current setting of the deferral counter. The macro
USDEFERLEVEL(level) allows the setting of a specific deferral level.
UGDEFERLEVEL() and
USDEFERLEVEL() are useful to set the counter appropriately in
setjmp/longjmp situations where a set of deferrals/resumes are bypassed. The idea is to save the value of the counter when
setjmp() is called, via a call to
UGDEFERLEVEl(), and to restore it via a call to
USDEFERLEVel() when the
longjmp() is performed.
Usignal provides signal deferral for the following signals:
SIGHUP,
SIGINT,
SIGQUIT,
SIGALRM,
SIGTERM,
SIGUSR1, and
SIGUSR2. Handling requests for all other signal numbers are passed directly to
signaL() by
Usignal(). Signals may be deferred for a considerable time. For this reason, during signal deferral, individual signal arrivals are counted. When it is safe to process a signal that may have arrived many times, the signal’s processing routine is iteratively called to process each arrival of the signal. Before each call the default action for the signal is instantiated. The idea is to handle the deferred occurrences of the signal as if they happened in quick succession in safe code.
In general, users should not mix calls to signaL() and
UsignaL() for the same signal. The recommended procedure is to go through
Usignal(), so that it is always aware of the state of the signal. Sometimes it may be necessary, such as when an application wants to use alarms within Oracle Tuxedo ATMI system services. To do this,
UsiginiT() should be called to initialize the signal deferring mechanism. Then
signaL() can be called to override the mechanism for the desired signal. To restore the deferring mechanism for the signal, it is necessary to call
UsignaL() for the signal with
SIG_IGN, and then again with the desired signal-handling function.
The shell variable UIMMEDSIGS can be used to override the deferral of signals. If the value of this variable begins with the letter
y as in:
Usignal is not available under DOS operating systems.
signal(2) in a UNIX system reference manual
The Uunix_err() function is provided to produce a message on the standard error output, describing the last system call error encountered during a call to an Oracle Tuxedo ATMI system function. It takes one argument, a string. The function prints the argument string, then a colon and a blank, followed by the name of the system call that failed, the reason for failure, and a newline. To be of most use, the argument string should include the name of the program that incurred the error. The system call error number is taken from the external variable
Uunixerr(), the reason is taken from
errno(). Both variables are set when errors occur. They are not cleared when non-erroneous calls are made.
is provided; Uunixerr() can be used as an index into this table to get the name of the system call that failed (without the newline).
