|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Sets when TPCOMMIT should return
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Sets commit_return characteristic
|
|
|
Sets transaction_control characteristic
|
|
|
Sets transaction_timeout characteristic
|
|
|
|
In the Oracle Tuxedo 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 program 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 program calling either
TPBEGIN() or
TPRESUME()) can call
TPCOMMIT() or
TPABORT(). Participants influence the outcome of a transaction by using
TPRETURN() or
TPFORWAR(). These two calls signify the end of a service routine and indicate that the routine has finished its part of the transaction.
Since TXCLOSE() 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
TXCLOSE().
The first kind of timeout is specified when a transaction is started with TPBEGIN() (see
TPBEGIN() for details). The second kind of timeout can occur when using the Oracle Tuxedo ATMI communication routines defined in
TPCALL(). 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 configuration file parameter. (See the
BLOCKTIME parameter in
UBBCONFIG(5) for details.)
In order to send data to another application program, the sending application program first places the data in a record. The ATMI interface supports the notion of a
typed record. A typed record is really a pair of COBOL records. The data record is defined in static storage and contains application data to be passed to another application program. An auxiliary type record accompanies the data record and it identifies to the Oracle Tuxedo system the interpretation and translation rules of the data record as it passes across heterogeneous machine boundaries. The auxiliary type record contains the data record’s type, its optional subtype, and its optional length. Some record types require further specification via a subtype (for example, a particular record layout) and those of variable length require a length to be specified.
The CARRAY record type allows an arbitrary number of characters which may contain
LOW-VALUE characters anywhere in the record. When sending data,
LEN must contain the number of bytes to be transferred.
The STRING record type allows an arbitrary number of characters which may not contain
LOW-VALUE characters within the record but may be at the end of the record. When sending data,
LEN must contain the number of bytes to be transferred.
Two of the above record types have synonyms: X_OCTET is a synonym for
CARRAY, and
X_COMMON is a synonym for
VIEW.
X_COMMON supports a subset of the data types supported by
VIEW:
longs (PIC S9(9) COMP-5),
shorts (PIC S9(4) COMP-5), and
characters (PIC X(n)).
X_COMMON should be used when both C and COBOL programs are communicating.
In all three cases, after a successful transfer, LEN contains the number of bytes transferred. When receiving data,
LEN must contain the maximum number of bytes the data area contains. After a successful call,
LEN contains the number of bytes moved into the data area. If the size of the incoming message is larger than the size specified in
LEN, only
LEN amount of data is moved into the data area; the remaining data is discarded.
In single-context mode, if TPINITIALIZE() 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 multi-context mode, each call to TPINITIALIZE() creates a new application association. The program can obtain a handle representing this application association by calling
TPGETCTXT() and it can call
TPSETCTXT() to set its context.
Once an application has chosen single-context mode, all calls to TPINITIALIZE() must specify single-context mode until all application associations are terminated. Similarly, once an application has chosen multi-context mode, all calls to
TPINITIALIZE() must specify multi-context 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 multi-context mode state.
The TPTYPE COBOL structure is used whenever sending or receiving application data.
REC-TYPE indicates the type of data record that is to be sent.
SUB-TYPE indicates the name of the view if a
VIEW REC-TYPE is specified.
LEN indicates the amount of data to send and the amount received.
The TPSVCDEF data structure is used by functions to pass settings to and from the Oracle Tuxedo system:
The TPINFDEF data structure is used by
TPINITIALIZE() to join the application:
The TPCONTEXTDEF data structure is used by
TPGETCTXT() and
TPSETCTXT() to manipulate program contexts:
The TPQUEDEF data structure is used to pass and retrieve information associated with enqueuing the message:
The TPSVCRET data structure is used by
TPRETURN() to indicate the status of the transaction:
The TPTRXDEF data structure is used by
TPBEGIN() to set transaction timeouts, and by
TPSUSPEND() and
TPRESUME() to get and set, respectively, transaction identifiers:
The TPCMTDEF data structure is used by
TPSCMT() to set the commit level characteristics:
The TPAUTDEF data structure is used by
TPCHKAUTH() to check if authentication is required:
The TPPRIDEF data structure is used by
TPSPRIO() and
TPGPRIO() to manipulate message priorities:
The TPTRXLEV data structure is used by
TPGETLEV() to receive transaction level setting:
The TPBCTDEF data structure is used by
TPNOTIFY() and
TPBROADCAST() to send notifications:
The FML-INFO data structure is used by
FINIT(),
FVSTOF(), and
FVFTOS() to deal with FML buffers:
The TPEVTDEF data structure is used by
TPPOST(),
TPSUBSCRIBE(), and
TPUNSUBSCRIBE() to handle event postings and subscriptions:
The TPKEYDEF data structure is used by
TPKEYCLOSE(),
TPKEYGETINFO(),
TPKEYOPEN(), and
TPKEYSETINFO()to manage public-private keys for performing message-based digital signature and encryption operations:
The TXINFDEF record defines a data structure where the result of the
TXINFORM() call will be stored:
Table 3 indicates which functions may be called by request/response servers, conversational servers, and clients. Note that
TPSVRINIT() and
TPSVRDONE() 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 system).
Table 4 indicates whether or not a client program has been initialized and registered with the transaction manager. Note that this table assumes the use of
TPINITIALIZE(), which is optional in single-context mode. That is, a single-context client may implicitly join an application by issuing one of many ATMI functions (for example,
TPACALL() or
TPCALL()). A client must use
TPINITIALIZE() when one of the following is true:
Table 4 shows the initialization states.
Table 5 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 6 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
1 and T
2 assume a precondition of state R
1 (for example,
TPOPEN() has been called with no subsequent call to
TPCLOSE() or
TPTERM()).
Table 7 indicates the state of a single request handle 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 8 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.
C0 - No handle
C
1 - TPCONNECT handle send-only
C
2 - TPCONNECT handle receive-only
C
3 - TPSVCDEF handle send-only
C
4 - TPSVCDEF handle receive-only
|
Note:
|
a If the program 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.
|
•
|
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 is rolled back, regardless of whether the application program calls tx_commit() or tx_rollback().
|
buffer(3c),
TPINITIALIZE(3cbl),
TPADVERTISE(3cbl),
TPBEGIN(3cbl),
TPCALL(3cbl),
TPCONNECT(3cbl),
TPGETCTXT(3cbl),
TPKEYCLOSE(3cbl),
TPKEYGETINFO(3cbl),
TPKEYOPEN(3cbl),
TPKEYSETINFO(3cbl),
TPOPEN(3cbl),
TPSETCTXT(3cbl),
TPSVCSTART(3cbl),
tuxtypes(5),
typesw(5)
FINIT(),
FINIT32() - initialize fielded buffer
01 FML-BUFFER.
05 FML-ALIGN PIC S9(9) USAGE IS COMP.
05 FML-DATA PIC X(applen).
01 FML-REC
COPY FMLINFO.
CALL "FINIT" USING FML-BUFFER FML-REC.
CALL "FINIT32" USING FML-BUFFER FML-REC.
FINIT() can be called to initialize a fielded buffer.
FML-BUFFER is the record to be used for the fielded buffer; it should be aligned on a 4-byte boundary to work with both FML16 and FML32. This can be accomplished by defining two record elements as shown in the synopsis above.
FML-LENGTH IN FML-REC is the length of the record. The internal structure is set up for a fielded buffer with no fields; the application program should not interpret the record, other than to pass it to
FINIT(),
FVFTOS(), or
FVSTOF(), or an ATMI call that takes a typed record (in this case, the type is “FML” and there is no subtype).
On error, FML-STATUS is set to a non-zero value.
Introduction to FML Functions in
Oracle Tuxedo ATMI FML Function Reference
FVFTOS(),
FVFTOS32() - copy from fielded buffer to COBOL structure
The FVFTOS() function transfers data from a fielded buffer to a COBOL record.
FML-BUFFER is a pointer to a fielded buffer initialized with
FINIT().
DATA-REC is a pointer to a C structure.
VIEWNAME IN FML-REC is the name of the view describing the COBOL record.
FVFTOS32() is used for views defined with
view32() typed buffers for larger views with more fields.
On error, FML-STATUS is set to a non-zero value.
FVSTOF() - copy from C structure to fielded buffer
FVSTOF() transfers data from a C structure to a fielded buffer.
FML-BUFFER is a record containing the fielded buffer.
DATA-REC is the COBOL record.
VIEWNAME IN FML-REC is the name of the view describing the COBOL record.
FML-MODE IN FML-REC specifies the manner in which the transfer is made.
FML-MODE has four possible values:
FVSTOF32() is used for views defined with
view32() typed buffers for larger views with more fields.
On error, FML-STATUS is set to a non-zero value.
TPABORT() - abort current Oracle Tuxedo ATMI transaction
01 TPTRXDEF-REC.
COPY TPTRXDEF.
01 TPSTATUS-REC.
COPY TPSTATUS.
CALL "TPABORT" USING TPTRXDEF-REC TPSTATUS-REC.
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 routine 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 communication handles exist for outstanding replies, then upon return from the routine, the transaction is aborted and those communications handles associated with the caller’s transaction are no longer valid. Communications handles not associated with the caller’s transaction remain valid.
The TPABORT() argument,
TPTRXDEF-REC, is reserved for future use.
TPABORT() was called in an improper context (for example, by a participant).
When using TPBEGIN(),
TPCOMMIT() and
TPABORT() to delineate an Oracle Tuxedo ATMI 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 to send a message to a service asynchronously
01 TPSVCDEF-REC.
COPY TPSVCDEF.
01 TPTYPE-REC.
COPY TPTYPE.
01 DATA-REC.
COPY User data.
01 TPSTATUS-REC.
COPY TPSTATUS.
CALL "TPACALL" USING TPSVCDEF-REC TPTYPE-REC DATA-REC TPSTATUS-REC.
TPACALL() sends a request message to the service named by
SERVICE-NAME IN TPSVCDEF-REC. The request is sent out at the priority defined for
SERVICE-NAME unless overridden by a previous call to
TPSPRIO().
DATA-REC is a message to be sent and
LEN IN TPTYPE-REC specifies the amount of data in
DATA-REC that should be sent. Note that if
DATA-REC is a record of a type that does not require a length to be specified, then
LEN is ignored (and may be
0). If
REC-TYPE IN TPTYPE-REC is
SPACES,
DATA-REC and
LEN are ignored and a request is sent with no data portion. If
REC-TYPE is
STRING and
LEN is
0, then the request is sent with no data portion. The
REC-TYPE and
SUB-TYPE of
DATA-REC must match one of the
REC-TYPE and
SUB-TYPEs recognized by
SERVICE-NAME. 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 setting is used, then when SERVICE-NAME is invoked, it is not performed on behalf of the caller’s transaction. If
SERVICE-NAME belongs to a server that does not support transactions, then this setting must be used when the caller is in transaction mode. A caller in transaction mode that uses this setting is still subject to the transaction timeout (and no other). If a service fails that was invoked with this setting, the caller’s transaction is not affected. Either
TPNOTRAN or
TPTRAN must be set.
Informs TPACALL() that a reply is not expected. When
TPNOREPLY is set, the routine returns [
TPOK] on success and sets
COMM-HANDLE IN TPSVCDEF-REC to
0, an invalid communications handle. When the caller is in transaction mode, this setting cannot be used when
TPTRAN is also set. Either
TPNOREPLY or
TPREPLY must be set.
Informs TPACALL() that a reply is expected. When
TPREPLY is set, the routine returns [
TPOK] on success and sets
COMM-HANDLE to a valid communications handle. When the caller is in transaction mode, this setting must be used when
TPTRAN is also set. Either
TPNOREPLY or
TPREPLY must be set.
When TPBLOCK is specified and a blocking condition exists, the caller blocks until the condition subsides or a timeout occurs (either transaction or blocking timeout). Either
TPNOBLOCK or
TPBLOCK must be set.
Upon successful completion, TPACALL() sets
TP-STATUS to [
TPOK]. In addition, if
TPREPLY was set in
TPSVCDEF-REC, then
TPCALL() returns a valid communications handle in
COMM-HANDLE that can be used to receive the reply of the request sent.
Under the following conditions, TPACALL() fails and sets
TP-STATUS to (unless otherwise noted, failure does not affect the caller’s transaction, if one exists):
Cannot send to SERVICE-NAME because it does not exist or is not a request/response service (that is, it is a conversational service).
The pair REC-TYPE and
SUB-TYPE is not one of the allowed types and subtypes that
SERVICE-NAME accepts.
SERVICE-NAME belongs to a server that does not support transactions and
TPTRAN was set.
01 SVC-NAME PIC X(127).
01 PROGRAM-NAME PIC X(32).
01 TPSTATUS-REC.
COPY TPSTATUS.
CALL "TPADVERTISE" USING SVC-NAME PROGRAM-NAME TPSTATUS-REC.
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 shut down.
TPADVERTISE() advertises
SVC-NAME for the server (or the set of servers sharing the caller’s MSSQ set).
SVC-NAME should be 127 characters or less, but cannot be
SPACES. (See
SERVICES section of
UBBCONFIG(5).) Longer names are truncated to 127 characters. Users should make sure that truncated names do not match other service names.
PROGRAM-NAME is the name of an Oracle Tuxedo ATMI service program. This program will be invoked whenever a request for
SVC-NAME is received by the server.
PROGRAM-NAME cannot be
SPACES.
If SVC-NAME is already advertised for the server and
PROGRAM-NAME matches its current program, then
TPADVERTISE() returns success (this includes truncated names that match already advertised names). However, if
SVC-NAME is already advertised for the server but
PROGRAM-NAME does not match its current program, then an error is returned (this can happen if truncated names match already advertised names).
TPADVERTISE() Upon successful completion,
TPADVERTISE() sets
TP-STATUS to [
TPOK].
Either SVC-NAME or
PROGRAM-NAME is
SPACES, or
PROGRAM-NAME is not a name of a valid program.
SVC-NAME cannot be advertised because of space limitations. (See
MAXSERVICES in the
RESOURCES section of
UBBCONFIG(5))
SVC-NAME is already advertised for the server but with a program other than
PROGRAM-NAME. Although
TPADVERTISE() fails,
SVC-NAME remains advertised with its current program (that is,
PROGRAM-NAME does not replace the current program).
TPBEGIN() - routine to begin an Oracle Tuxedo ATMI transaction
01 TPTRXDEF-REC.
COPY TPTRXDEF.
01 TPSTATUS-REC.
COPY TPSTATUS.
CALL "TPBEGIN" USING TPTRXDEF-REC TPSTATUS-REC.
T-OUT specifies that the transaction should be allowed at least
T-OUT seconds before timing out. Once a transaction times out it must be aborted. If
T-OUT 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).
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 transaction, it is important to remember that only the work done by a resource manager that meets the XA0 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 transaction.
01 TPBCTDEF-REC.
COPY TPBCTDEF.
01 TPTYPE-REC.
COPY TPTYPE.
01 DATA-REC.
COPY User data.
01 TPSTATUS-REC.
COPY TPSTATUS.
CALL "TPBROADCAST" USING TPBCTDEF-REC TPTYPE-REC DATA-REC TPSTATUS-REC.
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, all in
TPBCTDEF-REC, are logical identifiers used to select the target client set. A
SPACES value for any logical identifiers constitutes a wildcard for that argument. A wildcard argument matches all client identifiers for that field. Each identifier must meet the size restrictions defined for the system to be considered valid, that is, each identifier must be between 0 and 30 characters in length.
The data portion of the request is identified by DATA-REC and
LEN in
TPTYPE-REC specifies how much of
DATA-REC to send. Note that if
DATA-REC is a record of a type that does not require a length to be specified, then
LEN is ignored (and may be
0). If
REC-TYPE in
TPTYPE-REC is
SPACES, in which case
DATA-REC and
LEN are ignored and a request is sent with no data portion.
The interfaces described in TPNOTIFY() are supported on native site UNIX-based processors. In addition, the routines
TPBROADCAST() and
TPCHKUNSOL() as well as the routine
TPSETUNSOL() are supported on UNIX and MS-DOS workstation processors.
TPCALL() - routine to send a message to a service synchronously
01 TPSVCDEF-REC.
COPY TPSVCDEF.
01 ITPTYPE-REC.
COPY TPTYPE.
01 IDATA-REC.
COPY User data.
01 OTPTYPE-REC.
COPY TPTYPE.
01 ODATA-REC.
COPY User data.
01 TPSTATUS-REC.
COPY TPSTATUS.
CALL "TPCALL" USING TPSVCDEF-REC ITPTYPE-REC IDATA-REC OTPTYPE-REC ODATA-REC TPSTATUS-REC.
TPCALL() sends a request and synchronously awaits its reply. A call to this routine is the same as calling
TPACALL() immediately followed by
TPGETRPLY().
TPCALL() sends a request to the request/response service named by
SERVICE-NAME in
TPSVCDEF-REC. The request is sent out at the priority defined for
SERVICE-NAME unless overridden by a previous call to
TPSPRIO(). The data portion of a request is specified by
IDATA-REC and
LEN in
ITPTYPE-REC specifies how much of
IDATA-REC to send. Note that if
IDATA-REC is a record of a type that does not require a length to be specified, then
LEN in
ITPTYPE-REC is ignored (and may be
0). If
REC-TYPE in
ITPTYPE-REC is
SPACES,
IDATA-REC and
LEN in
ITPTYPE-REC are ignored and a request is sent with no data portion. If
REC-TYPE in
ITPTYPE-REC is
STRING and
LEN in
ITPTYPE-REC is
0, then the request is sent with no data portion. The
REC-TYPE in
ITPTYPE-REC and
SUB-TYPE in
ITPTYPE-REC must match one of the
REC-TYPEs and
SUB-TYPEs recognized by
SERVICE-NAME.
ODATA-REC specifies where a reply is read into, and, on input
LEN in
OTPTYPE-REC indicates the maximum number of bytes that should be moved into
ODATA-REC. If the same record is to be used for both sending and receiving,
ODATA-REC should be
REDEFINED to
IDATA-REC. Upon successful return from
TPCALL(),
LEN in
OTPTYPE-REC contains the actual number of bytes moved into
ODATA-REC.
REC-TYPE and
SUB-TYPE in
OTPTYPE-REC contain the replies type and subtype respectively. If the reply is larger than
ODATA-REC, then
ODATA-REC will contain only as many bytes as will fit in the record. The remainder of the reply is discarded and
TPCALL() sets
TPTRUNCATE().
If LEN in
OTPTYPE-REC is
0 upon successful return, then the reply has no data portion and
ODATA-REC was not modified. It is an error for
LEN in
OTPTYPE-REC to be
0 on input.
If the caller is in transaction mode and this setting is used, then when SERVICE-NAME is invoked, it is not performed on behalf of the caller’s transaction. If the
SERVICE-NAME belongs to a server that does not support transactions then this setting must be used when the caller is in transaction mode. A caller in transaction mode that sets this to
true is still subject to the transaction timeout (and no other). If a service fails that was invoked with this setting, the caller’s transaction is not affected. Either
TPNOTRAN or
TPTRAN must be set.
When this setting is used, the type of ODATA-REC is not allowed to change. That is, the type and subtype of the replied record must match
REC-TYPE IN OTPTYPE-REC and
SUB-TYPE IN OTPTYPE-REC, respectively, so long as the receiver recognizes the incoming record type. Either
TPNOCHANGE or
TPCHANGE must be set.
When TPBLOCK is specified and a blocking condition exists, the caller blocks until the condition subsides or a timeout occurs (either transaction or blocking timeout). Either
TPNOBLOCK or
TPBLOCK must be set.
Upon successful completion, TPCALL() sets
TP-STATUS to [
TPOK]. When
TP-STATUS is set to
TPOK or
TPESVCFAIL,
APPL-RETURN-CODE IN TPSTATUS-REC contains an application-defined value that was sent as part of
TPRETURN().
Under the following conditions, TPCALL() fails and sets
TP-STATUS to (unless otherwise noted, failure does not affect the caller’s transaction, if one exists):
Cannot send to SERVICE-NAME because it does not exist or is not a request/response service (that is, it is a conversational service).
The pair REC-TYPE and
SUB-TYPE is not one of the allowed types and subtypes that
SERVICE-NAME accepts.
Either the type and subtype of the reply are not known to the caller; or, TPNOCHANGE was set and the
REC-TYPE and
SUB-TYPE in
ODATA-REC do not match the type and subtype of the reply sent by the service. Neither
ODATA-REC nor
LEN in
OTPTYPE-REC are 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.
SERVICE-NAME belongs to a server that does not support transactions and
TPTRAN was 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
ODATA-REC. 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.
An error was encountered either in invoking a service routine or during its completion in TPRETURN() (for example, bad arguments were passed). No reply data is returned when this error occurs (that is, neither
ODATA-REC nor
OTPTYPE-REC are 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.
TPCANCEL() - cancel a communication handle for an outstanding reply
01 TPSVCDEF-REC.
COPY TPSVCDEF.
01 TPSTATUS-REC.
COPY TPSTATUS.
CALL "TPCANCEL" USING TPSVCDEF-REC TPSTATUS-REC.
TPCANCEL() cancels a communication handle,
COMM-HANDLE IN TPSVCDEF-REC, returned by
TPACALL(). It is an error to attempt to cancel a communication handle associated with a transaction.
Upon success, COMM-HANDLE is no longer valid and any reply received on behalf of
COMM-HANDLE will be silently discarded.
COMM-HANDLE is associated with the caller’s transaction.
COMM-HANDLE remains valid and the caller’s current transaction is not affected.
TPCHKAUTH()—check if authentication required to join an Oracle Tuxedo ATMI application
01 TPAUTDEF-REC.
COPY TPAUTDEF.
01 TPSTATUS-REC.
COPY TPSTATUS.
CALL "TPCHKAUTH" USING TPAUTDEF-REC TPSTATUS-REC.
TPCHKAUTH() checks if authentication is required by the application configuration. This is typically used by application clients prior to calling
TPINITIALIZE() to determine if a password should be obtained from the user.
01 MSG-NUM PIC S9(9) COMP-5.
01 TPSTATUS-REC.
COPY TPSTATUS.
CALL "TPCHKUNSOL" USING MSG-NUM TPSTATUS-REC.
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. Calls to this routine can result in calls to an application-defined unsolicited message handling routine by the Oracle Tuxedo ATMI libraries.
Upon successful completion, TPCHKUNSOL() sets
TP-STATUS to [
TPOK] and returns the number of unsolicited messages dispatched in
MSG-NUM.
TPCHKUNSOL() was called in an improper context (for example, from within a server).
The interfaces described in TPNOTIFY() are supported on native site UNIX-based processors. In addition, the routines
TPBROADCAST() and
TPCHKUNSOL() as well as the routine
TPSETUNSOL() are supported on UNIX and MS-DOS workstation processors.
TPCLOSE() - close the Oracle Tuxedo ATMI resource manager
01 TPSTATUS-REC.
COPY TPSTATUS.
CALL "TPCLOSE" USING TPSTATUS-REC.
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.
TPCLOSE() was called in an improper context (for example, while the caller is in transaction mode).
TPCOMMIT() - commit current Oracle Tuxedo ATMI transaction
01 TPTRXDEF-REC.
COPY TPTRXDEF.
01 TPSTATUS-REC.
COPY TPSTATUS.
CALL "TPCOMMIT" USING TPTRXDEF-REC TPSTATUS-REC
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()),
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 routine 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 communication handles exist for outstanding replies, then upon return from
TPCOMMIT(), the transaction is aborted and those handles associated with the caller’s transaction are no longer valid. Communication handles 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 setting (that is, connections not in transaction mode) are not affected by calls to
TPCOMMIT() or
TPABORT().
Currently, TPCOMMIT()’s argument,
TPTRXDEF-REC, is reserved for future use.
TPTRXDEF-REC 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 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 transaction.
01 TPSVCDEF-REC.
COPY TPSVCDEF.
01 TPTYPE-REC.
COPY TPTYPE.
01 DATA-REC.
COPY User data.
01 TPSTATUS-REC.
COPY TPSTATUS.
CALL "TPCONNECT" USING TPSVCDEF-REC TPTYPE-REC DATA-REC TPSTATUS-REC.
TPCONNECT() allows a program to set up a half-duplex connection to a conversational service,
SERVICE-NAME in
TPSVCDEF-REC. The name must be one of the conversational service names posted by a conversational server.
If the caller is in transaction mode and this setting is used, then when SERVICE-NAME is invoked, it is not performed on behalf of the caller’s transaction. If
SERVICE-NAME belongs to a server that does not support transactions, then this setting must be used when the caller is in transaction mode. A caller in transaction mode that uses this setting is still subject to the transaction timeout (and no other). If a service fails that was invoked with this setting, the caller’s transaction is not affected. Either
TPNOTRAN or
TPTRAN must be set.
When TPBLOCK is specified and a blocking condition exists, the caller blocks until the condition subsides or a timeout occurs (either transaction or blocking timeout). Either
TPNOBLOCK or
TPBLOCK must be set.
When TPNOSIGRSTRT is specified and a signal interrupts a system call, the call fails and
TP-STATUS is set to
TPGOTSIG(). Either
TPNOSIGRSTRT or
TPSIGRSTRT must be set.
Upon successful completion, TPCONNECT() sets
TP-STATUS to [
TPOK] and returns a communications handle in
COMM-HANDLE in
TPSVCDEF-REC that is used to refer to the connection in subsequent calls.
Under the following conditions, TPCONNECT() fails and sets
TP-STATUS to (unless otherwise noted, failure does not affect the caller’s transaction, if one exists).
The pair REC-TYPE and
SUB-TYPE is not one of the allowed types and subtypes that
SERVICE-NAME accepts.
SERVICE-NAME belongs to a program that does not support transactions and
TPNOTRAN was not set.
TPDEQUEUE() - routine to dequeue a message from a queue
01 TPQUEDEF-REC.
COPY TPQUEDEF.
01 TPTYPE-REC.
COPY TPTYPE.
01 DATA-REC.
COPY User data.
01 TPSTATUS-REC.
COPY STATDEF.
CALL "TPDEQUEUE" USING TPQUEDEF-REC TPTYPE-REC DATA-REC TPSTATUS-REC.
TPDEQUEUE() takes a message for processing from the queue named by
QNAME in the
QSPACE-NAME queue space.
DATA-REC specifies where a dequeued message is to be read into, and, on input
LEN indicates the maximum number of bytes that should be moved into
DATA-REC. Upon successful return,
LEN contains the actual number of bytes moved into
DATA-REC.
REC-TYPE and
SUB-TYPE contain the replies type and subtype respectively. If the reply is larger than
DATA-REC, then
DATA-REC will contain only as many bytes as will fit in the record. The remainder of the reply is discarded and
TPDEQUEUE() fails returning [
TPTRUNCATE].
If LEN is
0 upon successful return, then the reply has no data portion and
DATA-REC was not modified. It is an error for
LEN to be
0 on input.
The message is dequeued in transaction mode if the caller is in transaction mode and TPTRAN is set. This has the effect that if
TPDEQUEUE returns successfully and the caller’s transaction is committed successfully, then the message is removed from the queue. If the caller’s transaction is rolled back either explicitly or as the result of a transaction timeout or some communication error, then the message will be left on the queue (that is, the removal of the message from the queue is also rolled back). It is not possible to enqueue and dequeue the same message within the same transaction.
The message is not dequeued if a blocking condition exists. If TPNOBLOCK is set and a blocking condition exists such as the internal buffers into which the message is transferred are full, the call fails and
TP-STATUS is set to
TPEBLOCK. If
TPNOBLOCK is set and a blocking condition exists because the target queue is opened
exclusively by another application, the call fails,
TP-STATUS is set to
TPEDIAGNOSTIC, and the
DIAGNOSTIC field of the
TPQUEDEF record is set to
QMESHARE. In the latter case, the other application, which is based on an Oracle product other than the Oracle Tuxedo system, opened the queue for exclusive read and/or write using the Queuing Services API (QSAPI). Either
TPNOBLOCK or
TPBLOCK must be set.
When TPBLOCK is 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 setting is specified. Either
TPNOBLOCK or
TPBLOCK must be set.
When this setting is used, the type of DATA-REC is not allowed to change. That is, the type and subtype of the dequeued message must match
REC-TYPE IN TPTYPE-REC and
SUB-TYPE IN TPTYPE-REC, respectively, so long as the receiver recognizes the incoming record type. Either
TPNOCHANGE or
TPCHANGE must be set.
If TPDEQUEUE() returns successfully, the application can retrieve additional information about the message using the
TPQUEDEF-REC 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.
TPQUEDEF-REC is used by the application program to pass and retrieve information associated with dequeuing the message. The settings in
TPQUEDEF-REC are used to indicate what other elements in the structure are valid.
On input to TPDEQUEUE(), the following elements may be set in the
TPQUEDEF-REC:
Setting this value requests that the message identified by MSGID be dequeued. The message identifier may be acquired by a prior call to
TPENQUEUE(). Note that the message identifier changes if the message has moved from one queue to another. Note also that the entire 32 bytes of the message identifier value are significant, so the value identified by
MSGID must be completely initialized (for example, padded with spaces).
Setting this value requests that the message identified by CORRID be dequeued. The correlation identifier is specified by the application when enqueuing the message with
TPENQUEUE(). Note that the entire 32 bytes of the correlation identifier value are significant, so the value identified by
CORRID must be completely initialized (for example, padded with spaces).
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 one 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.
If TPQPEEK is set, the specified message is read but not removed from the queue. The
TPNOTRAN flag must be set. It is not possible to read messages enqueued or dequeued within a transaction before the transaction completes.
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
TPQUEDEF-REC:
The following is a list of valid settings in TPQUEDEF-REC controlling output information from
TPDEQUEUE(). For any of these settings, if the setting is true when
TPDEQUEUE() is called, the associated element in the record is populated with the value provided when the message was queued, and the setting remains true. If the value is not available (that is, no value was provided when the message was queued) or the setting is not
true when
TPDEQUEUE() is called,
TPDEQUEUE() completes with the setting not
true.
If this value is set, the call to TPDEQUEUE() is successful, and the message was queued with an explicit priority, then the priority is stored in
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). If
TPQNOPRIORITY is set, the priority is not available.
If this value is set and the call to TPDEQUEUE() is successful, the message identifier is stored in
MSGID. The entire 32 bytes of the message identifier value are significant. If
TPQNOMSGID is set, the message identifier is not available.
If this value is set, the call to TPDEQUEUE() is successful, and the message was queued with a correlation identifier, then the correlation identifier is stored in
CORRID. The entire 32 bytes of the correlation identifier value are significant. Any Oracle Tuxedo /Q provided reply to a message has the correlation identifier of the original message. If
TPQNOCORRID is set, the correlation identifier is not available.
If this value is set, the call to TPDEQUEUE() is successful, and the message was queued with a delivery quality of service, then the flag—
TPQQOSDELIVERYDEFAULTPERSIST,
TPQQOSDELIVERYPERSISTENT, or
TPQQOSDELIVERYNONPERSISTENT—specified by
TPQUEQOS-DELIVERY-FLAG indicates the delivery quality of service. If
TPQNODELIVERYQOS is set, the delivery quality of service is not available.
If this value is set, the call to TPDEQUEUE() is successful, and the message was queued with a reply quality of service, then the flag—
TPQQOSREPLYDEFAULTPERSIST,
TPQQOSREPLYPERSISTENT, or
TPQQOSREPLYNONPERSISTENT—specified by
TPQUEQOS-REPLY-FLAG indicates the reply quality of service. If
TPQNOREPLYQOS is set, the reply quality of service is not available.
If this value 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
REPLYQUEUE. Any reply to the message should go to the named reply queue within the same queue space as the request message. If
TPQNOREPLYQ is set, the reply queue is not available.
If this value 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
FAILUREQUEUE. Any failure message should go to the named failure queue within the same queue space as the request message. If
TPQNOFAILUREQ is set, the failure queue is not available.
The remaining settings in TPQUEDEF-REC are set to the following values when
TPDEQUEUE() is called:
TPQNOTOP,
TPQNOBEFOREMSGID,
TPQNOTIME_ABS,
TPQNOTIME_REL,
TPQNOEXPTIME_ABS,
TPQNOEXPTIME_REL, and
TPQNOEXPTIME_NONE.
If the call to TPDEQUEUE() fails and
TP-STATUS is set to
TPEDIAGNOSTIC, a value indicating the reason for failure is returned in
DIAGNOSTIC. The possible values are defined below in the
DIAGNOSTICS section.
Additionally on output, if the call to TPDEQUEUE() is successful,
APPKEY is set to the application authentication key,
CLIENTID is set to the identifier for the client originating the request, and
APPL-RETURN-CODE is set to the user-return code value that was set when the message was enqueued.
Under the following conditions, TPDEQUEUE() fails and sets
TP-STATUS to the following values (unless otherwise noted, failure does not affect the caller’s transaction, if one exists):
Cannot access the QSPACE-NAME 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).
Either the REC-TYPE and
SUB-TYPE of the dequeued message are not known to the caller; or,
TPNOCHANGE was set and the
REC-TYPE and
SUB-TYPE do not match the type and subtype of the dequeued message. Neither
DATA-REC nor
TPTYPE-REC are changed. When the call is made in transaction mode and this error occurs, the transaction is marked abort-only, and the message remains on the queue.
TPDEQUEUE() was called improperly. There is no effect on the queue or the transaction.
TPDISCON() - take down a conversational connection
01 TPSVCDEF-REC.
COPY TPSVCDEF.
01 TPSTATUS-REC.
COPY TPSTATUS.
CALL "TPDISCON" USING TPSVCDEF-REC TPSTATUS-REC.
TPDISCON() immediately tears down the connection specified by
COMM-HANDLE in
TPSVCDEF-REC, the communications handle, and generates a
TPEV-DISCONIMM event on the other end of the connection.
TPDISCON() can only be called by the initiator of the conversation.
TPDISCON() can not be called within a conversational service on the communications handle 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. If the initiator of the connection is a server, then
TPRETURN() can also be used to cause an orderly disconnection. If the initiator of the connection is in a transaction, then
TPCOMMIT() or
TPABORT() can be used to cause an orderly disconnection.
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 is aborted. Also, the caller does not need to have control of the connection when
TPDISCON() is called.
COMM-HANDLE is invalid or is the communications handle 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).
01 TPQUEDEF-REC.
COPY TPQUEDEF.
01 TPTYPE-REC.
COPY TPTYPE.
01 DATA-REC.
COPY User data.
01 TPSTATUS-REC.
COPY TPSTATUS.
CALL "TPENQUEUE" USING TPQUEDEF-REC TPTYPE-REC DATA-REC TPSTATUS-REC.
TPENQUEUE() stores a message on the queue named by
QNAME in the
QSPACE-NAME 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 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 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.
The data portion of a message is specified by DATA-REC and
LEN in
TPTYPE-REC specifies how much of
DATA-REC to enqueue. Note that if
DATA-REC is a record of a type that does not require a length to be specified, then
LEN is ignored (and may be
0). If
REC-TYPE in
TPTYPE-REC is
SPACES,
DATA-REC and
LEN are ignored and a message is enqueued with no data portion. The
REC-TYPE and
SUB-TYPE, both in
TPTYPE-REC, must match one of the
REC-TYPEs and
SUB-TYPEs recognized by
QSPACE-NAME.
If the caller is within a transaction and TPTRAN is set, the message is queued in transaction mode. This has the effect that if
TPENQUEUE() returns successfully and the caller’s transaction is committed successfully, then the message is guaranteed to be available subsequent to the transaction completing. If the caller’s transaction is rolled back either explicitly or as the result of a transaction timeout or some communication error, then the message will be removed from the queue (that is, the placing of the message on the queue is also rolled back). It is not possible to enqueue then dequeue the same message within the same transaction.
The message is not enqueued if a blocking condition exists. If TPNOBLOCK is set and a blocking condition exists such as the internal buffers into which the message is transferred are full, the call fails and
TP-STATUS is set to
TPEBLOCK. If
TPNOBLOCK is set and a blocking condition exists because the target queue is opened
exclusively by another application, the call fails,
TP-STATUS is set to
TPEDIAGNOSTIC, and the
DIAGNOSTIC field of the
TPQUEDEF record is set to
QMESHARE. In the latter case, the other application, which is based on an Oracle product other than the Oracle Tuxedo system, opened the queue for exclusive read and/or write using the Queuing Services API (QSAPI). Either
TPNOBLOCK or
TPBLOCK must be set.
When TPBLOCK is set and a blocking condition exists, the caller blocks until the condition subsides or a timeout occurs (either transaction or blocking timeout). Either
TPNOBLOCK or
TPBLOCK must be set.
Additional information about queuing the message can be specified via TPQUEDEF-REC. 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.
TPQUEDEF-REC is used by the application program to pass and retrieve information associated with enqueuing the message. Settings are used to indicate what elements in the record are valid.
On input to TPENQUEUE(), the following elements may be set in
TPQUEDEF-REC:
If this value is set, the message is made available after the time specified by DEQ-TIME.
DEQ-TIME is an absolute time value as generated by
time(2) or
mktime(3C) (the number of seconds since 00:00:00 Universal Coordinated Time—UTC, January 1, 1970). Set
TPQNOTIME if neither an absolute nor relative time value is set.
TPQTIME-ABS,
TPQTIME-REL, or
TPQNOTIME must be set. The absolute time is determined by the clock on the machine where the queue manager process resides.
If this value is set, the correlation identifier value specified in 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. Set
TPQNOCORRID if a correlation identifier is not available.
If this value is set, a reply queue named in REPLYQUEUE is associated with the queued message. Any reply to the message is queued to the named queue within the same queue space as the request message. Set
TPQNOREPLYQ if a reply queue name is not available.
If this value is set, a failure queue named in 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
APPL-RETURN-CODE in the
TPSTATUS record is enqueued to the named queue within the same queue space as the original request message. Set
TPQNOFAILUREQ if a failure queue name is not available.
If TPQDELIVERYQOS is set, the flags specified by
TPQUEQOS-DELIVERY-FLAG control the quality of service for message delivery. One of the following mutually exclusive flags must be set:
TPQQOSDELIVERYDEFAULTPERSIST,
TPQQOSDELIVERYPERSISTENT, or
TPQQOSDELIVERYNONPERSISTENT. If
TPQDELIVERYQOS is not set,
TPQNODELIVERYQOS must be set. When
TPQNODELIVERYQOS is set, the default delivery policy of the target queue dictates the delivery quality of service for the message.
If TPQREPLYQOS is set, the flags specified by
TPQUEQOS-REPLY-FLAG control the quality of service for reply message delivery for any reply. One of the following mutually exclusive flags must be set:
TPQQOSREPLYDEFAULTPERSIST,
TPQQOSREPLYPERSISTENT, or
TPQQOSREPLYNONPERSISTENT. 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,
TPQNOREPLYQOS must be set. When
TPQNOREPLYQOS is set, the default delivery policy of the
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.
The valid TPQUEQOS-DELIVERY-FLAG and
TPQUEQOS-REPLY-FLAG flags are:
Additionally, APPL-RETURN-CODE can be set with a user-return code. This value is returned to the application that dequeues the message.
On output from TPENQUEUE(), the following elements may be set in
TPQUEDEF-REC:
The following is a valid setting in TPQUEDEF-REC controlling output information from
TPENQUEUE(). If this setting is
true when
TPENQUEUE() is called, the /Q server
TMQUEUE(5) populates the associated element in the record with a message identifier. If this setting is not
true when
TPENQUEUE() is called,
TMQUEUE() does
not populate the associated element in the record with a message identifier.
If this value is set and the call to TPENQUEUE() is successful, the message identifier is stored in
MSGID. The entire 32 bytes of the message identifier value are significant, so the value stored in
MSGID is completely initialized (for example, padded with NULL characters). The actual padding character used for initialization varies between releases of the Oracle Tuxedo /Q component. If
TPQNOMSGID is set, the message identifier is not available.
If the call to TPENQUEUE() failed and
TP-STATUS is set to
TPEDIAGNOSTIC, a value indicating the reason for failure is returned in
DIAGNOSTIC. The possible values are defined below in the
DIAGNOSTICS section.
Under the following conditions, TPENQUEUE() fails and sets
TP-STATUS to the following values (unless otherwise noted, failure does not affect the caller’s transaction, if one exists).
Cannot access the QSPACE-NAME 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).
TPENQUEUE() was called improperly. There is no effect on the queue or the transaction.
TPFORWAR() - forward an Oracle Tuxedo ATMI service request to another routine
01 TPSVCDEF-REC.
COPY TPSVCDEF.
01 TPTYPE-REC.
COPY TPTYPE.
01 DATA-REC.
COPY User data.
01 TPSTATUS-REC.
COPY TPSTATUS.
COPY TPFORWAR REPLACING TPSVCDEF-REC BY TPSVCDEF-REC
TPTYPE-REC BY TPTYPE-REC
DATA-REC BY DATA-REC
TPSTATUS-REC BY TPSTAUS-REC
TPFORWAR() allows a service routine to forward a client’s request to another service routine for further processing. Since
TPFORWAR() contains an
EXIT PROGRAM statement, it should be called from within the same routine that was invoked to ensure correct return of control to the Oracle Tuxedo ATMI dispatcher (that is,
TPFORWAR() should not be invoked in a sub-program of the service routine since control would not return to the Oracle Tuxedo ATMI dispatcher).
TPFORWAR() cannot be called from within a conversational service.
This routine forwards a request to the service named by SERVICE-NAME in
TPSVCDEF-REC using data contained in
DATA-REC. A service routine forwarding a request receives no reply. After the request is forwarded, the service routine returns to the Oracle Tuxedo ATMI 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 which forwarded the request.
TPFORWAR() 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 Oracle Tuxedo ATMI dispatcher upon receipt. In addition, the communications handle for those replies become invalid and the request is not forwarded to
SERVICE-NAME.
DATA-REC is the record to be sent and
LEN in
TPTYPE-REC specifies the amount of data in
DATA-REC that should be sent. Note that if
DATA-REC is a record of a type that does not require a length to be specified, then
LEN is ignored (and may be
0). If
REC-TYPE in
TPTYPE-REC is
SPACES,
DATA-REC and
LEN are ignored and a request with zero length data is sent. If
REC-TYPE is
STRING and
LEN is
0, then the request is sent with no data portion.
If a service routine returns without using either TPRETURN() or
TPFORWAR() or
TPFORWAR() 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
TPFORWAR() are used outside of a service routine (for example, in clients, or in
TPSVRINIT() or
TPSVRDONE()), then these routines simply return having no effect.
TPGBLKTIME() - retrieves
the blocktime value previously set by TPSBLKTIME
TPGBLKTIME() retrieves a previously set, per second, blocktime value and places this value in
BLKTIME in
TBLKDEF-REC. 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.
If TPGBLKTIME() does not specify a
TPBLK-NEXT or
TPBLK-ALL blocktime flag value, it returns the applicable blocktime value for the next blocking API set due to a previous
TPSBLKTIME() call with the
TPBLK-NEXT or
TPBLK-ALL flag blocktime value, or a system-wide default blocktime value.
|
Note:
|
When a workstation client calls TPGBLKTIME() without a TPBLK-NEXT or TPBLK-ALL blocktime flag value, the system-wide default blocktime value cannot be returned. A 0 value is returned instead.
|
Upon successful completion, TPGBLKTIME() sets
TP-STATUS to
[TPOK] and returns the previously set blocktime, if any, in
BLKTIME in
TBLKDEF-REC. A
BLKTIME 0 value indicates that there are no previously set input blocktime 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 in
TPCONTEXTDEF-REC. Typically, a COBOL application:
|
1.
|
Calls TPINITIALIZE() with the TP-MULTI-CONTEXTS flag set.
|
|
2.
|
Calls TPGETCTXT() and saves the TPCONTEXTDEF-REC.
|
|
3.
|
Calls TPINITIALIZE(), again with the TP-MULTI-CONTEXTS flag.
|
|
4.
|
Calls TPGETCTXT() again and saves the returned context.
|
|
5.
|
Calls TPSETCTXT() to switch back to the first context.
|
TPGETCTXT() may be called in single-context applications as well as in multi-context applications.
Upon successful completion, TPGETCTXT sets
TP-STATUS to [
TPOK] and places the program’s context identifier in
CONTEXT in
TPCONTEXTDEF-REC.
CONTEXT is set to the current context ID, which may be represented by either:
|
•
|
TPNULLCONTEXT, indicating that this program is not currently associated with a context
|
|
Note:
|
TPINVALIDCONTEXT cannot be returned in COBOL programs because this value is possible only in multithreaded programs.
|
Upon failure, TPGETCTXT sets
TP-STATUS to one of the following values.
TPGETLEV() - check if an Oracle Tuxedo ATMI transaction is in progress
01 TPTRXLEV-REC.
COPY TPTRXLEV.
01 TPSTATUS-REC.
COPY TPSTATUS.
CALL "TPGETLEV" USING TPTRXLEV-REC TPSTATUS-REC.
TPGETLEV() returns to the caller the current transaction level. Currently, the only levels defined are
TP-NOT-IN-TRAN and
TP-IN-TRAN.
Upon successful completion, TPGETLEV() sets
TP-STATUS to [
TPOK] and sets values in
TPTRXLEV-REC to either a
TP-NOT-IN-TRAN to indicate that no transaction is in progress, or
TP-IN-TRAN to indicate that a transaction is in progress.
When using TPBEGIN(),
TPCOMMIT(), and
TPABORT() to delineate an Oracle Tuxedo ATMI 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 transaction.
01 TPSVCDEF-REC.
COPY TPSVCDEF.
01 TPTYPE-REC.
COPY TPTYPE.
01 DATA-REC.
COPY User data.
01 TPSTATUS-REC.
COPY TPSTATUS.
CALL "TPGETRPLY" USING TPSVCDEF-REC TPTYPE-REC DATA-REC TPSTATUS-REC.
TPGETRPLY() returns a reply from a previously sent request.
TPGETRPLY() either returns a reply for a particular request, or it returns any reply that is available. Both options are described below.
DATA-REC specifies where the reply is to be read into and, on input,
LEN in
TPTYPE-REC indicates the maximum number of bytes that should be moved into
DATA-REC. Also,
REC-TYPE in
TPTYPE-REC must be specified. Upon successful return from
TPGETRPLY(),
LEN contains the actual number of bytes moved into
DATA-REC,
REC-TYPE and
SUB-TYPE, both in
TPTYPE-REC, contain the data’s type and subtype, respectively. If the reply is larger than
DATA-REC, then
DATA-REC will contain only as many bytes as will fit in the record. The remainder of the reply is discarded and
TPGETRPLY() sets
TPTRUNCATE().
If LEN is
0 upon successful return, then the reply has no data portion and
DATA-REC was not modified. It is an error for
LEN to be
0 on input.
This setting signifies that TPGETRPLY() should ignore the communications handle indicated by
COMM-HANDLE in
TPSVCDEF-REC, return any reply available and set
COMM-HANDLE to the communications handle for the reply returned. If no replies exist,
TPGETRPLY() can wait for one to arrive. Either
TPGETANY or
TPGETHANDLE must be set.
This setting signifies that TPGETRPLY() should use the communications handle identified by
COMM-HANDLE and return a reply available for that
COMM-HANDLE. If no replies exist,
TPGETRPLY() can wait for one to arrive. Either
TPGETANY or
TPGETHANDLE must be set.
When this value is set, the type of DATA-REC is not allowed to change. That is, the type and subtype of the reply record must match
REC-TYPE and
SUB-TYPE, respectively. Either
TPNOCHANGE or
TPCHANGE must be set.
TPGETRPLY() does not wait for the reply to arrive. If the reply is available, then
TPGETRPLY() gets the reply and returns. Either
TPNOBLOCK or
TPBLOCK must be set.
When TPBLOCK is specified and no data is available, the caller blocks until the reply arrives or a timeout occurs (either transaction or blocking timeout). Either
TPNOBLOCK or
TPBLOCK must be set.
Upon successful completion, TPGETRPLY() sets
TP-STATUS to [
TPOK]. When
TP-STATUS is set to
TPOK() or
TPESVCFAIL(),
APPL-RETURN-CODE in
TPSTATUS-REC contains an application-defined value that was sent as part of
TPRETURN(). If the size of the incoming message was larger then the size specified in
LEN on input,
TPTRUNCATE() is set and only
LEN amount of data was moved to
DATA-REC, the remaining data is discarded.
Under the following conditions, TPGETRPLY() fails and sets
TP-STATUS as indicated below. Note that if
TPGETHANDLE is set, then
COMM-HANDLE is invalidated unless otherwise stated. If
TPGETANY is set, then
COMM-HANDLE identifies the communications handle for the reply on which the failure occurred; if an error occurred before a reply could be retrieved, then
COMM-HANDLE is
0. Also, the failure does not affect the caller’s transaction, if one exists, unless otherwise stated.
Either the type and subtype of the reply are not known to the caller; or, TPNOCHANGE was set and the
REC-TYPE and
SUB-TYPE do not match the type and subtype of the reply sent by the service. Neither
DATA-REC nor
TPTYPE-REC 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.
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
DATA-REC.
APPL-RETURN-CODE contains an application-defined value that was sent as part of
TPRETURN(). If the reply was received 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.
An error was encountered by a service routine during its completion in TPRETURN() or
TPFORWAR() (for example, bad arguments were passed). No reply data is returned when this error occurs (that is, neither
DATA-REC nor
TPTYPE-REC are changed). If the reply was received 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.
01 TPTYPE-REC.
COPY TPTYPE.
01 DATA-REC.
COPY User data.
01 TPSTATUS-REC.
COPY TPSTATUS.
CALL "TPGETUNSOL" USING TPTYPE-REC DATA-REC TPSTATUS-REC.
TPGETUNSOL() gets unsolicited messages that were sent via
TPBROADCAST() or
TPNOTIFY(). This routine may only be called from an unsolicited message handler.
Upon successful return, LEN IN TPTYPE_REC contains the actual number of bytes moved into
DATA-REC.
REC-TYPE and
SUB-TYPE, both in
TPTYPE-REC, contain the data’s type and subtype, respectively. If the message is larger than
DATA-REC, then
DATA-REC will contain only as many bytes as will fit in the record. The remainder of the message is discarded and sets
TPTRUNCATE(). If
LEN is
0, upon successful completion, then the message has no data portion and
DATA-REC was not modified.
Upon successful completion, TPGETUNSOL() sets
TP-STATUS to [
TPOK]. If the size of the incoming message was larger then the size specified in
LEN on input,
TPTRUNCATE() is set and only
LEN amount of data was moved to
DATA-REC, the remaining data is discarded.
01 TPPRIDEF-REC.
COPY TPPRIDEF.
01 TPSTATUS-REC.
COPY TPSTATUS.
CALL "TPGPRIO" USING TPPRIDEF-REC TPSTATUS-REC.
TPGPRIO() returns the priority for the last request sent or received. 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.
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.
01 TPINFDEF-REC.
COPY TPINFDEF.
01 USER-DATA-REC PIC X(any-length).
01 TPSTATUS-REC.
COPY TPSTATUS.
CALL "TPINITIALIZE" TPINFDEF-REC USER-DATA-REC TPSTATUS-REC.
TPINITIALIZE() allows a client to join an Oracle Tuxedo ATMI application. Before a client can use any of the Oracle Tuxedo communication or transaction routines, it must first join an Oracle Tuxedo ATMI application.
TPINITIALIZE() has two modes of operation: single-context mode and multi-context mode, which will be discussed in greater detail below. Because calling
TPINITIALIE() is optional when in single-context mode, a single-context client may also join an application by calling many ATMI routines (for example,
TPACALL() or
TPCALL()) which transparently call
TPINITIALIZE() with default values for the members of
TPINFDEF-REC. A client may want to call
TPINITIALIZE() directly so that it can set the parameters described below. In addition,
TPINITIALIZE() must be used when multi-context mode is required or when application authentication is required (see the description of the
SECURITY keyword in
UBBCONFIG(5)). After
TPINITIALIZE() successfully returns, the client can initiate service requests and define transactions.
In single-context mode, if TPINITIALIZE() is called more than once (that is, after the client has already joined the application), no action is taken and success is returned.
The TPINFDEF-REC record includes the following members.
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
TPINITIALIZE() time and are used for both broadcast notification and administrative statistics retrieval.
PASSWD is an application password in unencrypted format that is used for validation against the application password. The
PASSWD is significant up to 30 characters.
GRPNAME is used to associate the client with a resource manager group name. If
GRPNAME is
SPACES, then the client is not associated with a resource manager and is in the default client group.
TPINITIALIZE() has two modes of operation: single-context mode and multi-context mode. In single-context mode, a process may join at most one application at any one time. Single-context mode is specified by calling
TPINITIALIZE() with the
TP-SINGLE-CONTEXT setting of
CONTEXTS-FLAG or by calling another function that invokes
TPINITIALIZE() implicitly.
In single-context mode, if TPINITIALIZE() is called more than once (that is, after the client has already joined the application), no action is taken and success is returned.
Multi-context mode is entered by calling TPINITIALIZE() with the
TP-MULTI-CONTEXTS setting of
CONTEXTS-FLAG. In multi-context mode, each call to
TPINITIALIZE() results in the creation of a separate application association.
An application association is a context that associates a process and an Oracle Tuxedo application. A client may have associations with multiple Oracle Tuxedo applications, and may also have multiple associations with the same application. All of a client’s associations must be made to applications running the same release of the Oracle Tuxedo system, and either all associations must be native clients or all associations must be Workstation clients.
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 COBOL process is set to the new association.
The settings of TPINFDEF-REC are used to indicate both the client specific notification mechanism and the mode of system access. These settings may override the application default; however, in the event that they cannot,
TPINITIALIZE() will print a warning in a log file, ignore the setting and return the application default setting in
TPINFDEF-REC upon return from
TPINITIALIZE(). For client notification, the possible settings are as follows:
DATALEN is the length of the application specific data that will be sent to the service. A
SPACES value for
USRNAME and
CLTNAME is allowed for applications not making use of the application authentication feature of the Oracle Tuxedo system. Currently,
GRPNAME must be
SPACES. Clients using this option will get defined in the Oracle Tuxedo system with the following: default values for
USRNAME,
CLTNAME, and
GRPNAME; default settings; and no application data.
Upon successful completion, TPINITIALIZE() sets
TP-STATUS to [
TPOK]. Upon failure,
TPINITIALIZE() leaves the calling process in its original context, returns
-1, and sets
TP-STATUS to indicate the error condition.
TPINITIALIZE() was called improperly. For example: (a) the caller is a server; (b) the
TP-MULTI-CONTEXTS setting was specified in single-context mode; or (c) the
TP-MULTI-CONTEXTS setting was not specified in multi-context mode.
The interfaces described in TPINITIALIZE() are supported on UNIX system and MS-DOS operating systems. However, signal-based notification is not supported on MS-DOS. If it is selected at
TPINITIALIZE() time, then a
USERLOG() message is generated and the method is automatically set to dip-in.
Is used within TPINITIALIZE() when invoked by a non-workstation native client. It indicates the application to which the client should connect. Note that this environment variable is referenced only when
TPINITIALIZE() is called. Subsequent calls make use of the application context.
Is used within TPINITIALIZE() 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 more details on environment variable settings necessary for Workstation clients. Note that this file is processed only when
TPINITIALIZE() is called and not before.
Is used within TPINITIALIZE() when invoked by a Workstation client. It indicates the network address(es) 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 example, the "#.#.#.#" 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 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 TPINITIALIZE() 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.bea.com:30000 and
WSFRANGE is 200, then all native processes attempting to make outbound connections from this
LMID will bind a port on
mymachine.bea.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 TPINITIALIZE()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.bea.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.bea.com between 30000 and 30200. The valid range is 1-65535. The default is 1.
Is used within TPINITIALIZE() 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.
Is used within TPINITIALIZE() 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.
Is used by TPINITIALIZE() to set the maximum amount of core memory that should be used for buffering application replies before they are dumped to file. The default value for this parameter varies with each instantiation. The instantiation specific programmer’s guide should be consulted for further information.
01 TPKEYDEF-REC.
COPY TPKEYDEF.
01
TPSTATUS-REC.
COPY TPSTATUS.
CALL "TPKEYCLOSE" USING
TPKEYDEF-REC TPSTATUS-REC.
TPKEYCLOSE() 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.
Upon failure, TPKEYCLOSE() sets
TP-STATUS in
TPSTATUS-REC to one of the following values.
01 TPKEYDEF-REC.
COPY TPKEYDEF.
01
ATTVALUE-REC.
COPY user data
01
TPSTATUS-REC.
COPY TPSTATUS.
CALL "TPKEYGETINFO" USING
TPKEYDEF-REC ATTVALUE-REC TPSTATUS-REC.
TPKEYGETINFO() reports information about a key handle. A key handle represents a specific principal’s key and the information associated with it.
|
|
|
|
|
|
|
|
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 }
|
|
|
|
|
|
|
|
|
|
|
After TPKEYGETINFO() completes,
ATTRIBUTE-VALUE-LEN is set to the size of the data actually returned (not including padding values). If the number of bytes that need to be returned exceeds
ATTRIBUTE-VALUE-LEN,
TPKEYGETINFO() fails (with the
TPELIMIT error code) and sets
ATTRIBUTE-VALUE-LEN to the required amount of space.
Upon failure, TPKEYGETINFO() sets
TP-STATUS in
TPSTATUS-REC to one of the following values:
TPKEYOPEN() - open a key handle for digital signature generation, message encryption, or message decryption
01 TPKEYDEF-REC.
COPY TPKEYDEF.
01
TPSTATUS-REC.
COPY TPSTATUS.
CALL "TPKEYOPEN" USING
TPKEYDEF-REC TPSTATUS-REC.
TPKEYOPEN() 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 TPKEYOPEN() with the principal’s name and the
TPKEY-SIGNATURE and
TPKEY-AUTOSIGN settings returns a handle to the principal’s public key and enables signature generation in
AUTOSIGN mode. The public key software generates and attaches the digital signature to the message just before the message is sent.
Calling TPKEYOPEN() with the principal’s name and the
TPKEY-ENCRYPT and
TPKEY-AUTOENCRYPT settings returns a handle to the principal’s public key (via the principal’s digital certificate) and enables encryption in
AUTOENCRYPT mode. The public key software encrypts the message and attaches an encryption envelope to the message just before the message is sent; the encryption envelope enables the receiving process to decrypt the message.
Calling TPKEYOPEN() with the principal’s name and the
TPKEY-DECRYPT setting returns a handle to the principal’s private key and digital certificate.
The calling process must supply PRINCIPAL-NAME in
TPKEYDEF-REC, which specifies the key owner’s identity. This name may be padded at the end with
SPACES or
LOW-VALUES. If
PRINCIPAL-NAME is all
SPACES or
LOW-VALUES, 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.
The calling process may have to supply LOCATION in
TPKEYDEF-REC, which specifies the location of a key owner’s identity. If the underlying provider does not require a location field, this field may be populated with
SPACES or
LOW-VALUES.
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 stored in
IDENTITY-PROOF in
TPKEYDEF-REC. Otherwise, this field may be populated with
SPACES or
LOW-VALUES.
Upon successful completion, TPKEYOPEN() sets
TP-STATUS in
TPSTATUS-REC to [
TPOK]. In addition,
KEY-HANDLE in
TPKEYDEF-REC is set to a value that represents this key, for use by other functions such as
TPKEYGETINFO().
Upon failure, TPKEYOPEN() sets
TP-STATUS in
TPSTATUS-REC to one of the following values:
01 TPKEYDEF-REC.
COPY TPKEYDEF.
0
1 ATTVALUE-REC.
COPY user data
01
TPSTATUS-REC.
COPY TPSTATUS.
CALL "TPKEYSETINFO" USING
TPKEYDEF-REC ATTVALUE-REC TPSTATUS-REC.
TPKEYSETINFO() 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 in user-defined ATTVALUE-REC is to be associated with
ATTRIBUTE-NAME. Upon successful completion of
TPKEYSETINFO(), the information in
ATTVALUE-REC is stored or processed in a manner defined by the cryptographic service provider. If the data content of
ATTVALUE-REC is self-describing,
ATTRIBUTE-VALUE-LEN in
TPKEYDEF-REC is ignored (and may be 0). Otherwise,
ATTRIBUTE-VALUE-LEN must contain the length of data in
ATTVALUE-REC.
Upon failure, TPKEYSETINFO() sets
TP-STATUS in
TPSTATUS-REC to one of the following values:
TPNOTIFY() - send notification by client identifier
01 TPSVCDEF-REC.
COPY TPSVCDEF.
01 TPTYPE-REC.
COPY TPTYPE.
01 DATA-REC.
COPY User data.
01 TPSTATUS-REC.
COPY TPSTATUS.
CALL "TPNOTIFY" USING TPSVCDEF-REC TPTYPE-REC DATA-REC TPSTATUS-REC.
TPNOTIFY() allows a server to send an unsolicited message to an individual client.
CLIENTID in
TPSVCDEF-REC contains a client identifier saved from the
TPSVCDEF-REC of a previous or current service invocation.
DATA-REC is the record to be sent and
LEN in
TPTYPE-REC specifies how much of
DATA-REC should be sent. If
DATA-REC is a record of type that does not require a length to be specified, then
LEN is ignored (and may be
0). If
REC-TYPE in
TPTYPE-REC is
SPACES,
DATA-REC and
LEN are ignored and a request is sent with no data portion.
Upon successful return from TPNOTIFY(), the message has been delivered to the system for forwarding to the identified client. If
TPACK() was set, then 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.
TPNOTIFY() was called in an improper context (for example, within a client).
When TPACK() is specified and the target is a client from a prior release of the Oracle Tuxedo system that does not support the acknowledgment protocol.
TPOPEN() - open the Oracle Tuxedo ATMI resource manager
01 TPSTATUS-REC.
COPY TPSTATUS.
CALL "TPOPEN" USING TPSTATUS-REC.
TPOPEN() opens the resource manager to which the caller is linked. At most one resource manager can be linked to the caller. This routine 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.
Upon successful completion, TPOPEN() sets
TP-STATUS to [
TPOK]. More information concerning the reason a resource manager failed to open can be gotten by interrogating the resource manager in its own specific manner. Note that any calls to determine the exact nature of a resource manager’s error hinder portability.
TPOPEN() was called in an improper context (for example, by a client that has not joined an Oracle Tuxedo ATMI server group).
01 TPEVTDEF-REC.
COPY TPEVTDEF.
01 TPTYPE-REC.
COPY TPTYPE.
01 DATA-REC.
COPY User data.
01 TPSTATUS-REC.
COPY TPSTATUS.
CALL "TPPOST" USING TPEVTDEF-REC TPTYPE-REC DATA-REC TPSTATUS-REC.
The caller uses TPPOST() to post an event and any accompanying data. The event is named by
EVENT-NAME in
TPEVTDEF-REC and
DATA-REC contains the data to be posted. The posted event and its data are dispatched by the Oracle Tuxedo EventBroker to all subscribers whose subscriptions successfully evaluate against
EVENT-NAME and whose optional filter rules successfully evaluate against
DATA-REC.
EVENT-NAME must be 31 characters or less, but cannot be
SPACES.
EVENT-NAME’s first character cannot be a dot (“.”) as this character is reserved as the starting character for all events defined by the Oracle Tuxedo system itself.
DATA-REC is the typed record to be posted and
LEN in
TPTYPE-REC specifies the amount of data in
DATA-REC that should be posted with the event. Note that if
DATA-REC is a record of a type that does not require a length to be specified, then
LEN is ignored (and may be 0). If
DATA-REC is a record of a type that does require a length to be specified, then
LEN must not be 0 (if it is 0, no data will be posted). If
REC-TYPE in
TPTYPE-REC is
SPACES,
DATA-REC and
LEN are 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 TPTRAN is 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 had
TPEVTRAN set in
TPEVTDEF-REC when the subscription was made. Client notifications, and those service routine and stable-storage queue subscriptions that had
TPEVNOTRAN set in
TPEVTDEF-REC when the subscription was made, are also dispatched by the EventBroker but not as part of the posting process’ transaction.
Informs TPPOST() not to wait for the EventBroker to process all subscriptions for
EVENT-NAME before returning. When
TPNOREPLY is set,
EVENT-COUNT in
TPEVTDEF-REC is set to zero regardless of whether
TPPOST() returns successfully or not. When the caller is in transaction mode, this setting cannot be used when
TPTRAN is also set. Either
TPNOREPLY or
TPREPLY must be set.
Informs TPPOST() to wait for all subscriptions to be processed before returning. When
TPREPLY is set, the routine returns [
TPOK] on success and sets
EVENT-COUNT in
TPEVTDEF-REC to the number of event notifications dispatched by the EventBroker on behalf of
EVENT-NAME. When the caller is in transaction mode, this setting must be used when
TPTRAN is also set. Either
TPNOREPLY or
TPREPLY must be set.
When TPBLOCK is specified and a blocking condition exists, the caller blocks until the condition subsides or a timeout occurs (either transaction or blocking timeout). Either
TPNOBLOCK or
TPBLOCK must be set.
Upon successful completion, TPPOST() sets
TP-STATUS to [
TPOK]. In addition,
EVENT-COUNT contains the number of event notifications dispatched by the EventBroker on behalf of
EVENT-NAME (that is, postings for those subscriptions whose event expression evaluated successfully against
EVENT-NAME and whose filter rule evaluated successfully against
DATA-REC). Upon return where
TP-STATUS is set to [
TPESVCFAIL],
EVENT-COUNT contains the number of non-transactional event notifications dispatched by the EventBroker on behalf of
EVENT-NAME.
Under the following conditions, TPPOST() fails and sets
TP-STATUS 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, TPTRAN was set, and
TPPOST() contacted an EventBroker that does not support transaction propagation (that is,
TMUSREVT(5) is not running in an Oracle Tuxedo ATMI 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.
TPRECV() - receive a message in a conversational connection
01 TPSVCDEF-REC.
COPY TPSVCDEF.
01 TPTYPE-REC.
COPY TPTYPE.
01 DATA-REC.
COPY User data.
01 TPSTATUS-REC.
COPY TPSTATUS.
CALL "TPRECV" USING TPSVCDEF-REC TPTYPE-REC DATA-REC TPSTATUS-REC.
TPRECV() is used to receive data sent across an open connection from another program.
COMM-HANDLE, specifies on which open connection to receive data.
COMM-HANDLE is a communications handle returned from either
TPCONNECT() or
TPSVCSTART().
DATA-REC specifies where the message is read into, and, on input,
LEN indicates the maximum number of bytes that should be moved into
DATA-REC.
Upon successful and for several event types, LEN contains the actual number of bytes moved into
DATA-REC.
REC-TYPE and
SUB-TYPE contain the data’s type and subtype, respectively. If the message is larger than
DATA-REC, then
DATA-REC will contain only as many bytes as will fit in the record. The remainder of the reply is discarded and
TPRECV() sets
TPTRUNCATE.
If LEN is
0 upon successful return, then the reply has no data portion and
DATA-REC was not modified. It is an error for
LEN to be
0 on input.
TPRECV() can be issued only by the program that does not have control of the connection.
When this setting is used, the type of DATA-REC is not allowed to change. That is, the type and subtype of the message received must match
REC-TYPE and
SUB-TYPE, respectively. Either
TPNOCHANGE or
TPCHANGE must be set.
TPRECV() does wait for data to arrive. If data is already available to receive, then
TPRECV() gets the data and returns. Either
TPNOBLOCK or
TPBLOCK must be set.
When TPBLOCK is specified and no data is available to receive, the caller blocks until data arrives. Either
TPNOBLOCK or
TPBLOCK must be set.
If an event exists for the communications handle, COMM-HANDLE, then
TPRECV() will return setting
TP-STATUS to
TPEEVENT(). The event type is returned in
TPEVENT(). 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 errors 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
COMM-HANDLE is no longer valid. If this event occurred as part of the recipient’s transaction, then the transaction is marked as abort-only.
Upon successful completion, TPRECV() sets
TP-STATUS to [
TPOK]. When
TP-STATUS is set to [
TPEEVENT] and
TPEVENT() is either
TPEV-SVCSUCC or
TPEV-SVCFAIL,
APPL-RETURN-CODE contains an application-defined value that was sent as part of
TPRETURN(). If the size of the incoming message was larger then the size specified in
LEN on input,
TPTRUNCATE() is set and only
LEN amount of data was moved to
DATA-REC, the remaining data is discarded.
Under the following conditions, TPRECV() fails and sets
TP-STATUS to (unless otherwise noted, failure does not affect the caller’s transaction, if one exists):
TPRECV() was called in an improper context (for example, the connection was established such that the calling program can only send data).
01 TPTRXDEF-REC.
COPY TPTRXDEF.
01
TPSTATUS-REC.
COPY TPSTATUS.
CALL "TPRESUME" USING
TPTRXDEF-REC TPSTATUS-REC.
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 contained in
TRANID().
Either TRANID() contains a non-existent transaction identifier (including previously completed or timed-out transactions), or it contains a transaction identifier that the caller is not allowed to resume. The caller’s state with respect to the transaction is not changed.
TRANID() contains a transaction identifier that another program 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 transaction mode is unchanged.
TPRETURN() - returns from an Oracle Tuxedo ATMI service routine
01 TPSVCRET-REC.
COPY TPSVCRET.
01 TPTYPE-REC.
COPY TPTYPE.
01 DATA-REC.
COPY User data.
01 TPSTATUS-REC.
COPY TPSTATUS.
COPY TPRETURN REPLACING TPSVCRET-REC BY TPSVCRET-REC
TPTYPE-REC BY TPTYPE-REC
DATA-REC BY DATA-REC T
PSTATUS-REC BY TPSTATUS-REC.
TPRETURN() indicates that a service routine has completed. Since
TPRETURN() contains an
EXIT PROGRAM statement, it should be called from within the same routine that was invoked to ensure correct return of control to the Oracle Tuxedo ATMI dispatcher (that is,
TPRETURN() should not be invoked in a sub-program of the service routine since control would not return to the Oracle Tuxedo ATMI dispatcher).
TPRETURN() is used to send a service’s reply message. If the service 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 record.
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 conversation 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 a 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 aborted when the transaction is completed. A service may be invoked multiple times as part of the same transaction so it is not necessarily fully committed nor aborted until either
TPCOMMIT() or
TPABORT() is called by the originator of the transaction.
TPRETURN() should be called after receiving all replies expected from request/response 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 communications with the service routine. Any outstanding replies which are not received will automatically be dropped by the Oracle Tuxedo ATMI dispatcher upon receipt. In addition, the communications handle for those replies become invalid.
TPRETURN() should also be called after closing all connections initiated by the service. 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 communications 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 abort-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 abort-only while in the service routine for any reason, then
TP-RETURN-VAL should be set to
TPFAIL(). If
TPSUCCESS() is specified for a conversational service, a
TPEV-SVCSUCC event is generated.
This value is the same as TPFAIL(), with respect to completing the service, but the server will exit after the transaction is marked as abort-only and the reply is sent back to the requester. If the server is restartable, then the server will automatically be restarted.
If TP-RETURN-VAL is not set to one of these three values, then it defaults to
TPFAIL().
An application-defined return code, APPL-CODE in
TPSVCRET-REC, may be sent to the program receiving the service reply. This code is sent regardless of the setting of
TP-RETURN-VAL as long as a reply can be successfully sent (that is, as long as the receiving call returns success or [
TPESVCFAIL], or receives one of the events
TPEV-SVCSUCC or
TPEV-SVCFAIL). The value of
APPL-CODE is available in the receiver in the variable,
APPL-RETURN-CODE in
TPSTATUS-REC.
DATA-REC is a record to be sent and
LEN specifies the amount of
DATA-REC that should be sent. Note that if
DATA-REC is a record of type and subtype that does not require a length to be specified, then
LEN is ignored (and may be
0). If
REC-TYPE is
SPACES,
DATA-REC and
LEN are ignored. In this case, if a reply is expected by the program that invokes the service, then a reply is sent with no data portion. If no reply is expected, then
TPRETURN() ignores any data passed to it and returns sending no reply. If
REC-TYPE is
STRING and
LEN is
0, then the request is sent with no data portion.
|
•
|
If the caller does not have control of the connection, either TPEV-SVCERR or TPEV-SVCFAIL is sent to the originator of the connection as described above. Regardless of which event the originator receives, no data record is transmitted. If the originator receives the TPEV_SVCFAIL event, however, the return code is available in the originator’s APPL-RETURN-CODE in TPSTATUS-REC.
|
Because TPRETURN() contains an
EXIT PROGRAM statement, no value is returned to the caller, nor does control return to the service routine. If a service routine returns without using
TPRETURN() (that is, it uses an
EXIT PROGRAM statement directly or just simply “falls out of the service routine”), the server will 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 abort-only. Note also that if
TPRETURN() is used outside of a service routine (that is, by routines that are not services), then it returns having no effect.
TPRMCLOSE() - Routine for closing a specified RM configured in a multiple RM server group.
TPCLOSERM() closes a specified resource manager by the argument rmid. If current context is in a transaction context, this routine does nothing and returns to caller.
TPCLOSERM () can only close those resource manager opened via TPOPENRM() routine.
Upon failure, TPRMCLOSE() leaves the calling process in it original context and sets TP-STATUS to indicate the error condition.
TPRMCLOSE() was called in a improper context (for example, by a client which has not associated an Oracle Tuxedo multiple resource managers server group, it is invoked by a server which is not in a multiple resource managers server group, the specified resource manager by the parameter rmid is not opened via
TPRMOPEN() routine or current process is not built with
-M option in buildserver).
TPRMCLOSE() is executed in a 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 set
TP-STATUS to error.
Upon failure, TPRMEND() leaves the calling process in it original context and sets TP-STATUS to indicate the error condition.
TPRMEND() was called in a improper context(for example, by a client which has not associated with an Oracle Tuxedo multiple resource managers server group, it is invoked by a server which is not in a multiple resource managers server group, the specified resource manager by the parameter rmid is not opened via TMRMOPEN() routine or current process is not built with "-M" option in buildserver, or current context is not in a transaction mode).
TPRMOPEN() - Routine for opening a specified RM configured in a multiple RM server group.
TPRMOPEN() opens a specified RM configured in a multiple RMs server. If current context is in a transaction, this routine also informs the opened RM to join this transaction work unit on behalf of a transaction branch. If current RM is already opened, then this routine skips the open operation and tries to inform the RM to join this transaction work unit when this routine is invoked in a transaction context.
Upon failure, TPRMOPEN() leaves the calling process in it original context and sets
TP-STATUS to indicate the error condition.
TPRMOPEN() has been called in a improper context(for example, by a client which has not associated with an Oracle Tuxedo Multiple RMs server group? it is invoked by a server which is not in a Multiple RMs server group or current process is not built with "-M" option in buildserver).
TPRMSTART() - Routine for starting work on behalf of a transaction branch of specified RM in a multiple RM server group.
TPRMSTART() informs the opened RM to join current 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 sets
TP-STATUS to error condition.
Upon failure, TPRMSTART() leaves the calling process in it original context and sets
TP-STATUS to indicate the error condition.
TPSBLKTIME() -
routine for setting blocktime in seconds for the next service call or for all service calls
TPSBLKTIME() is used to set the blocktime value, in seconds, 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.
BLKTIME in
TPBLKDEF-REC sets blocking time in seconds. The blocktime range is 0 to 32767. A 0 blocktime 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 blocktime value overrides a
TPBLK-ALL blocktime value for those API calls that immediately follow it.
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, in seconds, 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 that you use
TPSBLKTIME(TPBLK-ALL) with
TPSVRINIT(3cbl).
Under the following conditions, TPSBLKTIME fails and sets
TP-STATUS to one of the following values. The failure does not affect transaction timeout values.
TPSBLKTIME() was called in a client attached to a workstation handler running an earlier Tuxedo release.
TPSCMT() - set when
TPCOMMIT should return
01 TPCMTDEF-REC.
COPY TPCMTDEF.
01 TPSTATUS-REC.
COPY TPSTATUS.
CALL "TPSCMT" USING TPCMTDEF-REC TPSTATUS-REC.
TPSCMT() sets the
TP-COMMIT-CONTROL characteristic to the value specified in
TPCMTDEF-REC. 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 program 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
TPFORWAR() 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 setting 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, aborted) 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 Oracle Tuxedo 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 setting indicates that TPCOMMIT() 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.
TPCMTDEF-REC is not set to
TP-CMT-LOGGED or
TP-CMT-COMPLETE.
When using TPBEGIN(),
TPCOMMIT(), and
TPABORT() to delineate an Oracle Tuxedo ATMI 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 transaction.
TPSEND() - routine to send a message in a conversational connection
01 TPSVCDEF-REC.
COPY TPSVCDEF.
01 TPTYPE-REC.
COPY TPTYPE.
01 DATA-REC.
COPY User data.
01 TPSTATUS-REC.
COPY TPSTATUS.
CALL "TPSEND" USING TPSVCDEF-REC TPTYPE-REC DATA-REC TPSTATUS-REC.
TPSEND() is used to send data across an open connection to another program. The caller must have control of the connection.
COMM-HANDLE specifies the open connection to send data over.
COMM-HANDLE is a communications handle returned from either
TPCONNECT() or
TPSVCSTART().
DATA-REC contains the data to be sent and
LEN specifies how much of the data to send. Note that if
DATA-REC is a record of a type that does not require a length to be specified, then
LEN is ignored (and may be
0). If
REC-TYPE is
SPACES,
DATA-REC and
LEN are ignored and a message is sent with no data (this might be done, for instance, to grant control of the connection without transmitting any data).
When TPBLOCK is specified and a blocking condition exists, the caller blocks until the condition subsides or a timeout occurs (either transaction or blocking timeout). Either
TPNOBLOCK or
TPBLOCK must be set.
If an event exists for COMM-HANDLE, then
TPSEND() will return without sending the caller’s data. The event type is returned in
TPEVENT(). Valid events for
TPSEND() are as follows.
Upon successful completion, TPSEND() sets
TP-STATUS to [
TPOK]. If an event exists and no errors were encountered,
TPSEND() sets
TP-STATUS to [
TPEEVENT]. When
TP-STATUS is set to [
TPEEVENT] and
TP-EVENT is either
TPEV-SVCSUCC or
TPEV-SVCFAIL,
APPL-RETURN-CODE contains an application-defined value that was sent as part of
TPRETURN().
TPSEND() was called in an improper context (for example, the connection was established such that the calling program can only receive data).
TPSETCTXT() - sets a context identifier for the current application association
01 TPCONTEXTDEF-REC.
COPY TPCONTEXTDEF.
01 TPSTATUS-REC.
COPY TPSTATUS.
TPSETCTXT() defines the context in which the current program operates. (Multithreaded COBOL applications are not currently supported.) Subsequent Oracle Tuxedo calls reference the application indicated by
CONTEXT in
TPCONTEXTDEF-REC. The value of
CONTEXT in
TPCONTEXTDEF-REC should have been provided by a previous call to
TPGETCTXT(). If the value of
CONTEXT is
TPNULLCONTEXT, then the program is disassociated from any Oracle Tuxedo context.
TPINVALIDCONTEXT is not a valid input value for
CONTEXT in
TPCONTEXTDEF-REC.
Upon failure, TPSETCTXT() leaves the calling process in its original context and sets
TP-STATUS to indicate the error condition.
Upon failure, TPSETCTXT() sets
TP-STATUS to one of the following values:
The value of CONTEXT in
TPCONTEXTDEF-REC is not a valid context.
TPSETCTXT() has been called in an improper context. For example, it has been called in a process that has not called
TPINITIALIZE() or that has called
TPINITIALIZE() without specifying the
TP-MULTI-CONTEXTS setting.
TPSETUNSOL() - sets method for handling unsolicited messages
01 CURR-ROUTINE PIC S9(9) COMP-5.
01 PREV-ROUTINE PIC S9(9) COMP-5.
01 TPSTATUS-REC.
COPY TPSTATUS.
CALL "TPSETUNSOL" USING CURR-ROUTINE PREV-ROUTINE TPSTATUS-REC.
TPSETUNSOL() allows a client to identify the routine that should be invoked when an unsolicited message is received by the Oracle Tuxedo ATMI libraries. Before the first call to
TPSETUNSOL(), any unsolicited messages received by the Oracle Tuxedo ATMI libraries on behalf of the client are logged and ignored. A call to
TPSETUNSOL() with a function number,
CURR-ROUTINE, set to
0 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
TPINITIALIZE(3cbl)).
The routine number passed, in CURR-ROUTINE, on the call to
TPSETUNSOL() selects one of 16 predefined routines. The routine names must be
_tm_dispatch1 through
_tm_dispatch8 for C routines that provide unsolicited message handling and
TMDISPATCH9 through
TMDISPATCH16 for COBOL routines that provide the same message handling. The C functions (
_tm_dispatch1 through
_tm_dispatch8) must conform to the parameter definition described in
tpsetunsol(3c). The COBOL routines (
TMDISPATCH9 through
TMDISPATCH16) must use
TPGETUNSOL() to receive the data.
Upon successful completion, TPSETUNSOL() sets
TP-STATUS to [
TPOK] and returns the previous setting for the unsolicited message handling routine (
0 in
PREV-ROUTINE is a successful return indicating that no message handling routine had been set previously).
TPSETUNSOL() was called in an improper context (for example, from within a server).
The interfaces described in TPNOTIFY() are supported on native site UNIX-based processors. In addition, the routines
TPBROADCAST() and
TPCHKUNSOL() as well as the routine
TPSETUNSOL() are supported on UNIX and MS-DOS workstation processors.
TPSETUNSOL() is not supported on Windows, due to the way that Dynamic Link Libraries and Shared Libraries work in this environment;
TPEPROTO() is returned . Use the C-language interface
tpsetunsol() to set up a handler function.
01 TPPRIDEF-REC.
COPY TPPRIDEF.
01 TPSTATUS-REC.
COPY TPSTATUS.
CALL "TPSPRIO" USING TPPRIDEF-REC TPSTATUS-REC.
TPSPRIO() sets the priority for the next request sent or forwarded. 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 management facility is installed.) By default, the setting of
PRIORITY in
TPPRIDEF-REC 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 accept the system default of 50.
TPSPRIO() has no effect on messages sent via
TPCONNECT() or
TPSEND().
01 TPEVTDEF-REC.
COPY TPEVTDEF.
01 TPQUEDEF-REC.
COPY TPQUEDEF.
01 TPSTATUS-REC.
COPY TPSTATUS.
CALL "TPSUBSCRIBE" USING TPEVTDEF-REC TPQUEDEF-REC TPSTATUS-REC.
The caller uses TPSUBSCRIBE() to subscribe to an event or set of events named by
EVENT-EXPR in
TPEVTDEF-REC. Subscriptions are maintained by the Oracle Tuxedo EventBroker,
TMUSREVT(), 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 setting of the
TPEV-METHOD-FLAG in
TPEVTDEF-REC.
The event or set of events being subscribed to is named by the regular expression, EVENT-EXPR in
TPEVTDEF-REC, and cannot be
SPACES. Regular expressions are of the form specified in
tpsubscribe(3c). For example, if
EVENT-EXPR is
"\e\e..*", the caller is subscribing to all system-generated events; if
EVENT-EXPR is
"\e\e.SysServer.*", the caller is subscribing to all system-generated events related to servers. If
EVENT-EXPR is
"[A-Z].*", the caller is subscribing to all user events starting with A-Z; if
EVENT-EXPR is
".*(ERR|err).*", the caller is subscribing to all user events containing either the substring "
ERR" or the substring "
err" in the event name (for example, "
account_error" and "
ERROR_STATE" events would both qualify).
EVENT-FILTER in
TPEVTDEF-REC 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 client process and TPEVNOTIFY in
TPEVTDEF-REC is set, 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
EVENT-EXPR, the EventBroker tests the posted data against the filter rule associated with
EVENT-EXPR. 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 server process calls
TPSUBSCRIBE() with
TPEVNOTIFY set, then
TPSUBSCRIBE() fails and sets
TP-STATUS in
TPSTATUS-REC to [
TPEPROTO].
When TPEVNOTIFY is set,
TPEVNOTRAN and
TPEVNOPERSIST must also be set; otherwise
TPSUBSCRIBE() fails and sets
TP-STATUS to [
TPEINVAL]. That is, an event subscription for a client having the unsolicited notification method cannot be transactional nor can it be persistent.
If the subscriber (regardless of process type) sets TPEVSERVICE() in
TPEVTDEF-REC, then event notifications are sent to the Oracle Tuxedo ATMI service routine named by
NAME-1 in
TPEVTDEF-REC. That is, when an event name is posted that evaluates successfully against
EVENT-EXPR, the EventBroker tests the posted data against the filter rule associated with
EVENT-EXPR. If the data passes the filter rule or if there is no filter rule for the event, then a service request is sent to
NAME-1 along with any data posted with the event. The service name in
NAME-1 can be any valid Oracle Tuxedo ATMI 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
REC-TYPE in
TPTYPE-REC set to SPACES. Any data passed to
TPRETURN() will be dropped.
If TPEVTRAN in
TPEVTDEF-REC is also set, 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(), and the subscribed service routine must belong to server groups that support transactions (see
UBBCONFIG(5) for details). If
TPEVNOTRAN is set, then the EventBroker calls the subscribed service routine such that it will not be part of the poster’s transaction.
If the subscriber (regardless of process type) sets TPEVQUEUE() in
TPEVTDEF-REC, then event notifications are enqueued to the queue space named by
NAME-1 in
TPEVTDEF-REC and the queue named by
NAME-2 in
TPEVTDEF-REC. That is, when an event name is posted that evaluates successfully against
EVENT-EXPR, the EventBroker tests the posted data against the filter rule associated with
EVENT-EXPR. 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 by
NAME-1 and the queue named by
NAME-2 along with any data posted with the event. The queue space and queue name can be any valid Oracle Tuxedo ATMI queue space and queue name, either of which may or may not exist at the time the subscription is made.
TPQUEDEF-REC can contain options further directing the EventBroker’s enqueuing of the posted event. If the caller has no options to specify, then
TPQUEDEF-REC should be set to
LOW-VALUE. Otherwise, options can be set as described in the “Control Parameter” subsection of the
TPENQUEUE() reference page (specifically, see the section describing the valid list of settings controlling input information for
TPENQUEUE()).
If TPEVTRAN in
TPEVTDEF-REC is also set, 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(), must belong to a server group that supports transactions (see
UBBCONFIG(5) for details). If
TPEVNOTRAN is set, then the EventBroker enqueues the posted event and its data such that it will not be part of the poster’s transaction.
If TPEVPERSIST 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 TPEVNOTIFY is set, then the caller’s system-defined client identifier (known as a
CLIENTID) is also used to detect matches. That is,
TPSUBSCRIBE() fails if
EVENT-EXPR,
EVENT-FILTER, and the caller’s
CLIENTID match those of a subscription already known to the EventBroker.
If TPEVSERVICE() is set, then
TPSUBSCRIBE() fails if
EVENT-EXPR,
EVENT-FILTER, and the service name set in
NAME-1 match those of a subscription already known to the EventBroker.
If TPEVQUEUE() is set, then EventBroker uses the queue space, queue name, and correlation identifier, in addition to
EVENT-EXPR and
EVENT-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 both
TPEVQUEUE() and
TPQNOCOORID(), then
TPSUBSCRIBE() fails if
EVENT-EXPR,
EVENT-FILTER, the queue space name set in
NAME-1, and the queue name set in
NAME-2 match those of a subscription (which also does not have a correlation identifier specified) already known to the EventBroker. Further, if
TPQCOORID() is set, then
TPSUBSCRIBE() fails if
EVENT-EXPR,
EVENT-FILTER,
NAME-1,
NAME-2, and
CORRID in
TPQUEDEF-REC match those of a subscription (which has the same correlation identifier specified) already known to the EventBroker.
When TPBLOCK is specified and a blocking condition exists, the caller blocks until the condition subsides or a timeout occurs (either transaction or blocking timeout). Either
TPNOBLOCK or
TPBLOCK must be set.
Upon successful completion, TPSUBSCRIBE() sets
TP-STATUS to [
TPOK]. In addition,
TPSUBSCRIBE() sets
SUBSCRIPTION-HANDLE in
TPEVTDEF-REC to the handle for this subscription.
SUBSCRIPTION-HANDLE can be used when calling
TPUNSUBSCRIBE() to remove this subscription from the EventBroker’s list of active subscriptions. Either the subscriber or any other process is allowed to use the returned handle to delete this subscription.
Under the following conditions, TPSUBSCRIBE() fails and sets
TP-STATUS to one of the following values. (Unless otherwise noted, failure does not affect the caller’s transaction, if one exists.)
buffer(3c),
tpsubscribe(3c),
TPENQUEUE(3cbl),
TPPOST(3cbl),
TPSETUNSOL(3cbl),
TPUNSUBSCRIBE(3cbl),
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)
01 TPTRXDEF-REC.
COPY TPTRXDEF.
01
TPSTATUS-REC.
COPY TPSTATUS.
CALL "TPSUSPEND" USING
TPTRXDEF-REC TPSTATUS-REC.
TPSUSPEND() is used to suspend the transaction active in the caller’s program. A transaction begun with
TPBEGIN() may be suspended with
TPSUSPEND(). Either the suspending program or another program 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() populates
TRANID with the transaction identifier being suspended.
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 handles remain valid. Communication handles not associated with the caller’s transaction remain valid regardless of the outcome of
TPSUSPEND().
TPSUSPEND() was called in an improper context (for example, the caller is not in transaction mode). The caller’s state with respect to transaction mode is unchanged.
01 TPSVCDEF-REC.
COPY TPSVCDEF.
01 TPTYPE-REC.
COPY TPTYPE.
01 DATA-REC.
COPY User data.
01 TPSTATUS-REC.
COPY TPSTATUS.
CALL "TPSVCSTART" USING TPSVCDEF-REC TPTYPE-REC DATA-REC TPSTATUS-REC.
TPSVCSTART() is the first Oracle Tuxedo ATMI routine to be called when writing a service routines. In fact, it is an error to issue any other call within a service routine before calling
TPSVCSTART().
TPVCSTART() is used to retrieve the service’s parameters and data. This routine is used for services that receive requests via
TPCALL() or
TPACALL() routines as well as by services that communicate via
TPCONNECT(),
TPSEND(), and
TPRECV() routines.
DATA-REC specifies where the service’s data is read into, and, on input,
LEN in
TPTYPE-REC indicates the maximum number of bytes that should be moved into
DATA-REC. Upon successful return from
TPSVCSTART,
LEN contains the actual number of bytes moved into
DATA-REC.
REC-TYPE and
SUB-TYPE, both in
TPTYPE-REC, contain the data’s type and subtype, respectively. If the message is larger than
DATA-REC, then
DATA-REC will contain only as many bytes as will fit in the record. The remainder of the message is discarded and
TPSVCSTART() sets
TPTRUNCATE().
If LEN is
0 upon successful return, then the service has no incoming data and
DATA-REC was not modified. It is an error for
LEN to be
0 on input.
Upon successful return, SERVICE-NAME in
TPSVCDEF-REC is populated with the service name that the requesting program used to invoke the service.
The service was invoked with TPCONNECT(). The communications handle for the conversation is available in
COMM-HANDLE in
TPSVCDEF-REC. This setting is mutually exclusive with
TPREQRSP.
APPKEY in
TPSVCDEF-REC is set to the application key assigned to the requesting client program 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. This includes clients of an earlier release level interoperating with a security application.
Upon successful completion, TPSVCSTART() sets
TP-STATUS to [
TPOK]. If the size of the incoming message was larger then the size specified in
LEN on input,
TPTRUNCATE() is set and only
LEN amount of data was moved to
DATA-REC, the remaining data is discarded.
TPSVRDONE() - Oracle Tuxedo ATMI server termination routine
01 TPSTATUS-REC.
COPY TPSTATUS.
PROCEDURE DIVISION.
* User code
EXIT PROGRAM.
The Oracle Tuxedo ATMI 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 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 system will close its connections, ignore any pending replies and roll back the transaction before the server exits.
If either TPRETURN() or
TPFORWAR() are called in
TPSVRDONE(), then these routines simply return having no effect.
TPSVRINIT() - Oracle Tuxedo ATMI server initialization routine
LINKAGE SECTION.
01 CMD-LINE.
05 ARGC PIC 9(4) COMP-5.
05 ARGV.
10 ARGS PIC X OCCURS 0 TO 9999 DEPENDING ON ARGC.
01 TPSTATUS-REC.
COPY TPSTATUS.
PROCEDURE DIVISION USING CMD-LINE TPSTATUS-REC.
* User code
EXIT PROGRAM
The Oracle Tuxedo ATMI server abstraction calls TPSVRINIT() during its initialization. This routine is called after the program has become a server but before it handles any service requests; thus, Oracle Tuxedo ATMI 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 system closes the connections, ignores any pending replies, and aborts the transaction before the server exits.
If successful, TPSVRINIT() returns [
TPOK] in
TP-STATUS and the service can start accepting requests. If an error occurs in
TPSVRINIT, the application can cause the server to exit gracefully (without taking any service requests) by returning any value other than [
TPOK] in
TP-STATUS.
When TPSVRINIT() returns any value other than [
TPOK], the system does not restart the server. Instead, the administrator must run
tmboot to restart the server.
When TPRETURN()or
TPFORWAR() is used outside a service routine (for example, in a client,
TPSVRINIT(), or
TPSVRDONE()), then the routine returns with no effect.
When called in TPSVRINIT(), the
TPRETURN() and
TPFORWAR() routines simply return with no effect.
01 TPSTATUS-REC.
COPY TPSTATUS.
CALL "TPTERM" USING TPSTATUS-REC.
TPTERM() removes a client from an Oracle Tuxedo ATMI 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 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.
After invoking TPTERM(), a program is placed in the
TPNULLCONTEXT context. Most ATMI functions invoked by a program in the
TPNULLCONTEXT context perform an implicit
TPINITIALIZE(). Whether or not the call to
TPINITIALIZE() succeeds depends on the usual determining factors, unrelated to context-specific issues.
Upon successful completion, TPTERM() sets
TP-STATUS to [
TPOK]. Upon success in a multi-contexted application, the application’s current context is changed to
TPNULLCONTEXT. It is the user’s responsibility to use
TPSETCTXT() to change the context subsequently, as desired.
Upon failure, TPTERM() returns -1 and sets
TP-STATUS to indicate the error condition.
Upon failure, TPTERM() sets
TP-STATUS to one of the following values:
TPTERM() was called in an improper context (for example, the caller is a server).
01 SVC-NAME PIC X(127).
01 TPSTATUS-REC.
COPY TPSTATUS.
CALL "TPUNADVERTISE" USING SVC-NAME TPSTATUS-REC.
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
SVC-NAME as an advertised service for the server (or the set of servers sharing the caller’s MSSQ set).
SVC-NAME cannot be
SPACES. Also,
SVC-NAME 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.
SVC-NAME is not currently advertised by the server.
TPUNADVERTISE() was called in an improper context (for example, by a client).
01 TPEVTDEF-REC.
COPY TPEVTDEF.
01 TPSTATUS-REC.
COPY TPSTATUS.
CALL "TPUNSUBSCRIBE" USING TPEVTDEF-REC TPSTATUS-REC.
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-HANDLE in
TPEVTDEF-REC is an event subscription handle returned by
TPSUBSCRIBE(). Setting
SUBSCRIPTION-HANDLE 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 with
TPEVNOPERSIST set when
TPSUBSCRIBE() was called. Persistent subscriptions can be deleted only by using the handle returned by
TPSUBSCRIBE().
Note that the -1 handle removes only those subscriptions made by the calling process and not any made by previous instantiations of the caller (for example, a server that dies and restarts cannot use the wildcard to unsubscribe to any subscriptions made by the original server).
When TPBLOCK is specified and a blocking condition exists, the caller blocks until the condition subsides or a timeout occurs (either transaction or blocking timeout). Either
TPNOBLOCK or
TPBLOCK must be set.
Upon successful completion, TPUNSUBSCRIBE() sets
TP-STATUS to [
TPOK]. In addition,
TPUNSUBSCRIBE() sets
EVENT-COUNT in
TPEVTDEF-REC to the number of subscriptions deleted (zero or greater) from the EventBroker’s list of active subscriptions.
EVENT-COUNT may contain a number greater than 1 only when the wildcard handle, -1, is used. Also,
EVENT-COUNT 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).
Under the following conditions, TPUNSUBSCRIBE() fails and sets
TP-STATUS to one of the following values. (Unless otherwise noted, failure does not affect the caller’s transaction, if one exists.)
01 TX-RETURN-STATUS.
COPY TXSTATUS.
CALL "TXBEGIN" USING TX-RETURN-STATUS.
TXBEGIN() 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
TXOPEN()) before it can start transactions.
TXBEGIN fails (with a
TX-STATUS value of [
TX-PROTOCOL-ERROR]) if the caller is already in transaction mode or
TXOPEN() has not been called.
Once in transaction mode, the calling thread must call TXCOMMIT() or
TXROLLBACK() to complete its current transaction. There are certain cases related to transaction chaining where
TXBEGIN() does not need to be called explicitly to start a transaction. See
TXCOMMIT() and
TXROLLBACK() for details.
TX-RETURN-STATUS is the record used to return a value.
DATA DIVISION.
* Include TX definitions.
01 TX-RETURN-STATUS.
COPY TXSTATUS.
PROCEDURE DIVISION.
CALL "TXCLOSE" USING TX-RETURN-STATUS.
TXCLOSE() 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.
TXCLOSE() 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.
TXCLOSE() should be called when an application thread of control no longer wishes to participate in global transactions.
TXCLOSE() 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 TXCLOSE() returns success (
TX-OK), all resource managers linked to the calling thread are closed.
DATA DIVISION.
* Include TX definitions.
01 TX-RETURN-STATUS.
COPY TXSTATUS.
PROCEDURE DIVISION.
CALL "TXCOMMIT" USING TX-RETURN-STATUS.
TXCOMMIT() is used to commit the work of the transaction active in the caller’s thread of control.
If the transaction_control characteristic (see
TXSETTRANCTL()) is
TX-UNCHAINED, then when
TXCOMMIT() returns, the caller is no longer in transaction mode. However, if the
transaction_control characteristic is
TX-CHAINED, then when
TXCOMMIT() returns, the caller remains in transaction mode on behalf of a new transaction (see the
RETURN VALUE and
ERRORS sections below).
TXINFORM() - return global transaction information
DATA DIVISION.
* Include TX definitions.
01 TX-RETURN-STATUS.
COPY TXSTATUS.
01 TX-INFO-AREA.
COPY TXINFDEF.
PROCEDURE DIVISION.
CALL "TXINFORM" USING TX-INFO-AREA, TX-RETURN-STATUS.
TXINFORM() returns global transaction information in
TX-INFO-AREA. In addition, this function returns a value indicating whether the caller is currently in transaction mode or not.
TXINFORM() populates the
TX-INFO-AREA record with global transaction information. The contents of the
TX-INFO-AREA record are described under
INTRO().
If TXINFORM is called in transaction mode, then
TX-IN-TRAN is set,
XID-REC 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,
TX-NOT-IN-TRAN is set and
XID-REC will be populated with the NULL XID (see
TXINTRO for details). In addition, regardless of whether the caller is in transaction mode,
COMMIT-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.
TXOPEN() - open a set of resource managers
DATA DIVISION.
* Include TX definitions.
01 TX-RETURN-STATUS.
COPY TXSTATUS.
PROCEDURE DIVISION.
CALL "TXOPEN" USING TX-RETURN-STATUS.
TXOPEN() 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.
TXOPEN() 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 TXOPEN() returns
TX-ERROR, then no resource managers are open. If
TXOPEN() 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.
TXOPEN() must successfully return before a thread of control participates in global transactions.
Once TXOPEN() returns success, subsequent calls to
TXOPEN (before an intervening call to
TXCLOSE()) are allowed. However, such subsequent calls will return success, and the TM will not attempt to reopen any RMs.
DATA DIVISION.
* Include TX definitions.
01 TX-RETURN-STATUS.
COPY TXSTATUS.
PROCEDURE DIVISION.
CALL "TXROLLBACK" USING TX-RETURN-STATUS.
TXROLLBACK() is used to roll back the work of the transaction active in the caller’s thread of control.
If the transaction_control characteristic (see
TXSETTRANCTL()) is
TX-UNCHAINED, then when
TXROLLBACK() returns, the caller is no longer in transaction mode. However, if the
transaction_control characteristic is
TX-CHAINED, then when
TXROLLBACK() returns, the caller remains in transaction mode on behalf of a new transaction (see the
RETURN VALUE and
ERRORS sections below).
DATA DIVISION.
* Include TX definitions.
01 TX-RETURN-STATUS.
COPY TXSTATUS.
*
01 TX-INFO-AREA.
COPY TXINFDEF.
PROCEDURE DIVISION.
CALL "TXSETCOMMITRET" USING TX-INFO-AREA TX-RETURN-STATUS.
TXSETCOMMITRET() sets the
commit_return characteristic to the value specified in
COMMIT-RETURN. This characteristic affects the way
TXCOMMIT() behaves with respect to returning control to its caller.
TXSETCOMMITRET() may be called regardless of whether its caller is in transaction mode. This setting remains in effect until changed by a subsequent call to
TXSETCOMMITRET().
This flag indicates that TXCOMMIT() 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
TXCOMMIT(). 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
TXCOMMIT(). 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 TXCOMMIT() should return after the two-phase commit protocol has finished completely. This setting allows the caller of
TXCOMMIT() to see return codes that indicate that a transaction had or may have had heuristic results.
COMMIT-RETURN is not one of
TX-COMMIT-DECISION-LOGGED or
TX-COMMIT-COMPLETED.
DATA DIVISION.
* Include TX definitions.
01 TX-RETURN-STATUS.
COPY TXSTATUS.
01 TX-INFO-AREA.
COPY TXINFDEF.
PROCEDURE DIVISION.
CALL "TXSETTRANCTL" USING TX-INFO-AREA TX-RETURN-STATUS.
TXSETTRANCTL() sets the
transaction_control characteristic to the value specified in
TRANSACTION-CONTROL. This characteristic determines whether
TXCOMMIT() and
TXROLLBACK() start a new transaction before returning to their caller.
TXSETTRANCTL() 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
TXSETTRANCTL().
This flag indicates that TXCOMMIT() and
TXROLLBACK() should not start a new transaction before returning to their caller. The caller must issue
TXBEGIN() to start a new transaction.
Under the following conditions, TXSETTRANCTL() does not change the setting of the
transaction_control characteristic and returns one of these negative values:
DATA DIVISION.
* Include TX definitions.
01 TX-RETURN-STATUS.
COPY TXSTATUS.
*
01 TX-INFO-AREA.
COPY TXINFDEF.
PROCEDURE DIVISION.
CALL "TXSETTIMEOUT" USING TX-INFO-AREA TX-RETURN-STATUS.
TXSETTIMEOUT() sets the
transaction_timeout characteristic to the value specified in
TRANSACTION-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
TXBEGIN() and
TXCOMMIT() or
TXROLLBACK().
TXSETTIMEOUT() may be called regardless of whether its caller is in transaction mode or not. If
TXSETTIMEOUT() 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).
TRANSACTION-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 an S9(9)
COMP-5 as defined by the system. A
TRANSACTION-TIMEOUT value of zero disables the timeout feature.
Under the following conditions, TXSETTIMEOUT() does not change the setting of the
transaction_timeout characteristic and returns one of these negative values:
USERLOG() - write a message to the Oracle Tuxedo ATMI central event log
01 LOG-REC.
COPY User data.
01 LOGREC-LEN PIC S9(9) COMP-5.
01 TPSTATUS-REC.
COPY TPSTATUS.
CALL "USERLOG" USING LOG-REC LOGREC-LEN TPSTATUS-REC.
USERLOG() places
LOG-REC into a fixed output file—the Oracle Tuxedo ATMI central event log.
|
•
|
If the shell variable ULOGPFX is set, its value 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.
|
|
•
|
USERLOG() is used by the Oracle Tuxedo system to record a variety of events.
|
|
•
|
The USERLOG mechanism is entirely independent of any database transaction logging mechanism.
|
The USERLOG interface is supported on UNIX and MS-DOS operating systems. The system name produced as part of the log message is not available on MS-DOS systems; therefore, the value
PC is used as the system name for MS-DOS systems.
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:
01 LOG-REC PIC X(15) VALUE “UNKNOWN USER”.
01 LOGREC-LEN PIC S9(9) VALUES IS 13.
CALL “USERLOG” USING LOG-REC LOGREC-LEN TPSTATUS-REC.
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 values 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.
