Corporate Info  |  News  |  Solutions  |  Products  |  Partners  |  Services  |  Events  |  Download  |  How To Buy
	http://www.oracle.com/technology/documentation/index.html   |   Site Map   |   Search   |   PDF Files   |   Contact   |   Glossary
WebLogic Enterprise Doc Home   |   Tuxedo ATMI Topics   |   Previous Topic   |   Next Topic   |   Contents   |   Index

The T_APPQTRANS class represents run-time attributes of transactions associated with application queues.

It is not possible to retrieve all instances of this class by leaving all key fields unset. Instead, sufficient key fields must be specified to explicitly target a single application queue space. For example, if all key fields except TA_XID are set in an request using tpcall(3), then all T_APPQTRANS objects associated with the specified queue space will be retrieved.

It is important to keep in mind that transactions represented by objects of this class are not necessarily associated with the application in which they are retrieved. Care must be taken when heuristically committing or aborting a transaction because the transaction may actually belong to or have an effect on another application. The value of the TA_XID attribute is not guaranteed to be unique across applications.

Table 0-9 APPQ_MIB(5): T_APPQTRANS Class Definition Attribute Table

Attribute1	Type	Permissions	Values	Default
TA_XID( k )( * ) TA_APPQSPACENAME(k)(*) TA_QMCONFIG( k )( * ) TA_LMID( k )( * )	string string string string	R--R--R-- r--r--r-- r--r--r-- r--r--r--	string[1..78] string[1..15] string[1..78] string[1..30]	N/A N/A N/A N/A
TA_STATE2	string	R-XR-XR--	GET:{ACT|ABY |ABD|COM|REA |DEC|HAB|HCO} SET:{HAB|HCO}	N/A N/A
( k ) - GET key field3 ( * ) - Required SET key field

1 All attributes of class T_APPQTRANS are local attributes. 2 All operations on T_APPQTRANS objects (both GET and SET) silently open the associated queue space (that is, implicitly set the state of the queue space to OPEn if it is not already OPEn or ACTive). This may be a time-consuming operation if the queue space is large. 3 Sufficient key fields must be supplied in a GET operation to explicitly target a single application queue space.

Attribute Semantics

TA_XID: string[1..78]

Transaction identifier as returned by tx_info(3) and mapped to a string representation. The data in this field should not be interpreted directly by the user except for equality comparison.

TA_APPQSPACENAME: string[1..15]

Name of the application queue space associated with the transaction.

TA_QMCONFIG: string[1..78]

Absolute pathname of the file or device where the application queue space is located.

TA_LMID: string[1..30] (no comma)

Identifier of the logical machine where the application queue space is located.

TA_STATE:

GET: {ACTive|ABortonlY|ABorteD|COMcalled|REAdy|DECided|HAbord|HCommit}

A GET operation retrieves run-time information about the selected transactions. The following list describes the meaning of the TA_STATE attribute returned in response to a GET request. States not listed will not be returned. All states are ACTive equivalent for purposes of permissions checking.

ACTive	The transaction is active.
ABortonlY	The transaction has been identified for rollback.
ABorteD	The transaction has been identified for rollback and rollback has been initiated.
COMcalled	The initiator of the transaction has called tpcommit(3) and the first phase of 2-phase commit has begun.
REAdy	All of the participating groups on the retrieval site have successfully completed the first phase of two-phase commit and are ready to be committed.
DECided	The second phase of the 2-phase commit has begun.
SUSpended	The initiator of the transaction has suspended processing on the transaction.

SET: {HABort|HCOmmit}

A SET operation updates the state of the selected transactions. The following list describes the meaning of the TA_STATE attribute returned by a SET request. States not listed cannot be set.

HABort	Heuristically abort the transaction. Successful return leaves the object in the HABort state.
HCOmmit	Heuristically commit the transaction. Successful return leaves the object in the HCOmmit state.

The existing FML32 and ATMI functions necessary to support administrative interaction with BEA Tuxedo system MIBs, as well as the header file and field table mentioned on this reference page, are available on all supported native and workstation platforms.

This MIB is provided only on BEA Tuxedo sites and later, both native and Workstation.

If a site running a BEA Tuxedo release earlier than Release 6.0 is active in the application, then administrative access through this MIB is limited as follows.

• SET operations are not allowed.

• Local information access for sites earlier than Release 6.0 is not available. If the class being accessed also has global information, then the global information only is returned. Otherwise, an error is returned.

If sites of differing releases, both greater than or equal to Release 6.0, are interoperating, then information on the older site is available for access and update as defined on the MIB reference page for that release and may be a subset of the information available in the later release.

Following is a set of code fragments that illustrate how to perform various operations on application queue spaces, queues, messages, and transactions.

Each fragment should be preceded by code that allocates an FML32 typed buffer, such as the following:

rqbuf = tpalloc("FML32", NULL, 0);

After the buffer is populated, each fragment should be followed by code that sends the request and receives the reply, such as the following:

flags = TPNOTRAN | TPNOCHANGE | TPSIGRSTRT;
rval = tpcall(".TMIB", rqbuf, 0, rpbuf, rplen, flags);

See MIB(5) for additional information.

The field table tpadm must be available in the environment to allow access to attribute field identifiers. This can be done at the shell level as follows:

$ FIELDTBLS=tpadm 
$ FLDTBLDIR=${TUXDIR}/udataobj
$ export FIELDTBLS FLDTBLDIR

The following header files are needed.

#include <atmi.h> 
#include <fml32.h>
#include <tpadm.h>

Creating an application queue space typically involves two operations: the first to create the BEA Tuxedo system device in which the queue space will be allocated, and the second to create the queue space itself.

/* Allocate the buffer; see above */ 
 
/* Build the request to create a new device on SITE1 */
Fchg32(rqbuf, TA_OPERATION, 0, "SET", 0);
Fchg32(rqbuf, TA_CLASS, 0, "T_DEVICE", 0);
Fchg32(rqbuf, TA_STATE, 0, "NEW", 0);
Fchg32(rqbuf, TA_CFGDEVICE, 0, "/dev/q/dsk001", 0);
Fchg32(rqbuf, TA_LMID, 0, "SITE1", 0);
size = 500;
Fchg32(rqbuf, TA_DEVSIZE, 0, (char *)size, 0);
 
/* Make the request; see above */
 
/* Reinitialize the same buffer for reuse */
Finit32(rqbuf, (FLDLEN) Fsizeof32(rqbuf));
 
/* Build the request to create the queue space */
Fchg32(rqbuf, TA_OPERATION, 0, "SET", 0);
Fchg32(rqbuf, TA_CLASS, 0, "T_APPQSPACE", 0);
Fchg32(rqbuf, TA_STATE, 0, "NEW", 0);
Fchg32(rqbuf, TA_APPQSPACENAME, 0, "QSPACE1", 0);
Fchg32(rqbuf, TA_QMCONFIG, 0, "/dev/q/dsk001", 0);
Fchg32(rqbuf, TA_LMID, 0, "SITE1", 0);
Fchg32(rqbuf, TA_ERRORQNAME, 0, "errque", 0);
ipckey = 123456;
Fchg32(rqbuf, TA_IPCKEY, 0, (char *)ipckey, 0);
maxmsg = 100;
Fchg32(rqbuf, TA_MAXMSG, 0, (char *)maxmsg, 0);
maxpages = 200;
Fchg32(rqbuf, TA_MAXPAGES, 0, (char *)maxpages, 0);
maxproc = 50;
Fchg32(rqbuf, TA_MAXPROC, 0, (char *)maxproc, 0);
maxqueues = 10;
Fchg32(rqbuf, TA_MAXQUEUES, 0, (char *)maxqueues, 0);
maxtrans = 100;
Fchg32(rqbuf, TA_MAXTRANS, 0, (char *)maxtrans, 0);
 
/* Make the request; see above */

The following code creates a new queue in the queue space created in the previous example.

/* Build the request */ 
Fchg32(rqbuf, TA_OPERATION, 0, "SET", 0);
Fchg32(rqbuf, TA_CLASS, 0, "T_APPQ", 0);
Fchg32(rqbuf, TA_STATE, 0, "NEW", 0);
Fchg32(rqbuf, TA_APPQNAME, 0, "errque", 0);
Fchg32(rqbuf, TA_APPQSPACENAME, 0, "QSPACE1", 0);
Fchg32(rqbuf, TA_QMCONFIG, 0, "/dev/q/dsk001", 0);
Fchg32(rqbuf, TA_LMID, 0, "SITE1", 0);
Fchg32(rqbuf, TA_APPQORDER, 0, "PRIO", 0);
 
/* Make the request; see above */

To list the application queue spaces known to an application, a two-level search is used. First, the groups using the /Q transaction manager TMS_QM are retrieved from the application configuration, and then the queue space referenced by each group is retrieved. The following code fragment assumes that each GROUP entry involving a queue space has a single logical machine associated with it (i.e., server migration is not used).

/* Build the request to retrieve all TMS_QM groups */
Fchg32(rqbuf, TA_OPERATION, 0, "GET", 0);
Fchg32(rqbuf, TA_CLASS, 0, "T_GROUP", 0);
Fchg32(rqbuf, TA_TMSNAME, 0, "TMS_QM", 0);
fldid1 = TA_OPENINFO;
fldid2 = TA_LMID;
Fchg32(rqbuf, TA_FILTER, 0, (char *)fldid1, 0);
Fchg32(rqbuf, TA_FILTER, 0, (char *)fldid2, 1);
 
/* Make the request, assuming we are joined to the application */
rval = tpcall(".TMIB", rqbuf, 0, rpbuf, rplen, flags);
 
/* For each TMS_QM group, build the request to retrieve its queue space */
rval = Fget32(*rpbuf, TA_OCCURS, 0, (char *)occurs, NULL);
for (i = 0; i occurs; i++) {
 
 
  /* Reinitialize the buffer and set all common attributes */
  Finit32(rqbuf, (FLDLEN) Fsizeof32(rqbuf));
  Fchg32(rqbuf, TA_OPERATION, 0, "GET", 0);
  Fchg32(rqbuf, TA_CLASS, 0, "T_APPQSPACE", 0);
 
  /* Get the OPENINFO to determine device and queue space name */
  /* OPENINFO has the format <resource-mgr>:<qmconfig>:<appqspacename> */
  /* or on NT/Netware    <resource-mgr>:<qmconfig>;<appqspacename> */
  rval = Fget32(rpbuf, TA_OPENINFO, i, openinfo, NULL);
 
  /* The device is the 2nd field in OPENINFO */
  qmconfig = strchr(openinfo, ':') + 1;
  /* The queue space name is the 3rd field in OPENINFO */
 
#if defined(_TMDOWN) || defined(_TM_NETWARE)
#define pathsep ";" /* separtor for PATH */
#else
#define pathsep ":" /* separtor for PATH */
#endif
  appqspacename = strchr(qmconfig, pathsep);
  appqspacename[0] = '\e0'; /* null-terminate qmconfig */
  appqspacename++; /* bump past the null */
 
  /* Set the APPQSPACENAME and QMCONFIG keys */
  Fchg32(rqbuf, TA_APPQSPACENAME, 0, appqspacename, 0);
  Fchg32(rqbuf, TA_QMCONFIG, 0, qmconfig, 0);
 
  /* Get the LMID (assume no migration for this group) */
  rval = Fget32(rpbuf, TA_LMID, i, lmid, NULL);
  Fchg32(rqbuf, TA_LMID, 0, lmid, 0);
 
  /* Make the request */
  rval = tpcall(".TMIB", rqbuf, 0, rpbuf2, rplen2, flags);
}

The above technique does not find any queue space that has been created but does not yet have a corresponding GROUP entry in the application configuration. Such queue spaces must be retrieved by knowing a priori the key fields (i.e., TA_APPQSPACENAME, TA_QMCONFIG, and TA_LMID) for the queue space.

The following code retrieves all messages in the queue STRING in the queue space QSPACE1 in device /dev/q/dsk001 on logical machine SITE1.

/* Build the request */ Fchg32(rqbuf, TA_OPERATION, 0, "GET", 0);
Fchg32(rqbuf, TA_CLASS, 0, "T_APPQMSG", 0);
Fchg32(rqbuf, TA_APPQNAME, 0, "STRING", 0);
Fchg32(rqbuf, TA_APPQSPACENAME, 0, "QSPACE1", 0);
Fchg32(rqbuf, TA_QMCONFIG, 0, "/dev/q/dsk001", 0);
Fchg32(rqbuf, TA_LMID, 0, "SITE1", 0);
/* Make the request; see above */

The following fragment retrieves all transactions involving (any queue in) the queue space QSPACE1.

/* Build the request */ Fchg32(rqbuf, TA_OPERATION, 0, "GET", 0);
Fchg32(rqbuf, TA_CLASS, 0, "T_APPQTRANS", 0);
Fchg32(rqbuf, TA_APPQSPACENAME, 0, "QSPACE1", 0);
Fchg32(rqbuf, TA_QMCONFIG, 0, "/dev/q/dsk001", 0);
Fchg32(rqbuf, TA_LMID, 0, "SITE1", 0);
/* Make the request; see above */

${TUXDIR}/include/tpadm.h
${TUXDIR}/udataobj/tpadm

Fintro(3), Fadd32(3), Fchg32(3), Ffind32(3), tpalloc(3), tprealloc(3), tpcall(3), tpacall(3), tpgetrply(3), tpadmcall(3), tpenqueue(3), tpdequeue(3), MIB(5), TM_MIB(5), BEA Tuxedo Administrator's Guide, BEA Tuxedo Programmer's Guide