|
|
|
|
|
|
APPQ_MIB(5)
Name
APPQ_MIB - Management Information Base for /Q
Synopsis
#include <fml32.h>
#include <tpadm.h>
Description
The /Q MIB defines classes through which application queues can be managed.
APPQ_MIB(5) should be used in combination with the generic MIB reference page MIB(5) to format administrative requests and interpret administrative replies. Requests formatted as described in MIB(5) using classes and attributes described on this reference page may be used to request an administrative service using any one of a number of existing ATMI interfaces in an active application. Application queues in an inactive application may also be administered using the tpadmcall() function interface.
APPQ_MIB(5) consists of the following classes.
|
Class Name |
Attributes |
|---|---|
|
Application queues within a queue space |
|
|
Messages within an application queue |
|
|
Application queue spaces |
|
|
Transactions associated with application queues |
Note that this MIB refers to application-defined persistent (reliable disk-based) and non-persistent (in memory) queues (that is, /Q queues), and not server queues (the T_QUEUE class of the TM_MIB(5) component).
Each class description section has four subsections:
Attribute Table Format
Each class that is a part of this MIB is documented in four parts. One part is the attribute table. The attribute table is a reference guide to the attributes within a class and how they may used by administrators, operators, and general users to interface with an application.
There are five components to each attribute description in the attribute tables: name, type, permissions, values and default. Each of these components is discussed in MIB(5).
TA_FLAGS Values
MIB(5) defines the generic TA_FLAGS attribute which is a long containing both generic and component MIB-specific flag values. The following flag values are defined for the APPQ_MIB(5) component. These flag values should be or'd with any generic MIB flags.
FML32 Field Table
The field table for the attributes described on this reference page is found in the file udataobj/tpadm relative to the root directory of the BEA Tuxedo software installed on the system. The directory ${TUXDIR}/udataobj should be included by the application in the path list (semi-colon separated on NT and colon separated otherwise) specified by the FLDTBLDIR environment variable and the field table name tpadm should be included in the comma-separated list specified by the FIELDTBLS environment variable.
Limitations
This MIB is provided only on BEA Tuxedo system 6.0 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.
T_APPQ Class Definition Overview
The T_APPQ class represents application queues. One or more application queues may exist in a single application queue space.
Limitations
It is not possible to retrieve all instances of this class by leaving all key fields unset. Instead, sufficient key fields must be supplied to explicitly target a single application queue space. These required key fields are TA_APPQSPACENAME, TA_QMCONFIG, and TA_LMID, except when the application is unconfigured (that is, when the TUXCONFIG environment variable is not set), in which case TA_LMID must be omitted. For example, if the TA_APPQSPACENAME, TA_QMCONFIG, and TA_LMID attributes are set in a request using tpcall(), then all T_APPQ objects within the specified queue space will be retrieved.
Attribute Table
aAll attributes of class T_APPQ are local attributes.
bTA_LMID must be specified as a key field except when the application is unconfigured (that is, the TUXCONFIG environment variable is not set).
cAll operations on T_APPQ 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.
dTA_APPQORDER cannot be modified after the application queue is created.
eSufficient key fields must be supplied in a GET operation to explicitly target a single application queue space.
Attribute Semantics
|
VALid |
The specified queue exists. This state is INActive equivalent for purposes of permissions checking. |
PRIO,TIME,LIFO
TIME,PRIO,FIFO
TIME,FIFO
EXPIR
EXPIR,PRIO,FIFO
TIME,EXPIR,PRIO,FIFO
T_APPQMSG Class Definition
Overview
The T_APPQMSG class represents messages stored in application queues. A message is not created by an administrator; instead, it comes into existence as a result of a call to tpenqueue(). A message can be destroyed either by a call to tpdequeue() or by an administrator. In addition, certain attributes of a message can be modified by an administrator. For example, an administrator can move a message from one queue to another queue within the same queue space or change its priority.
Limitations
It is not possible to retrieve all instances of this class by leaving all key fields unset. Instead, sufficient key fields must be supplied to explicitly target a single application queue space. These required key fields are TA_APPQSPACENAME, TA_QMCONFIG, and TA_LMID, except when the application is unconfigured (that is, the TUXCONFIG environment variable is not set), in which case TA_LMID must be omitted. For example, if the TA_APPQSPACENAME, TA_QMCONFIG, and TA_LMID attributes are set in a request using tpcall(), then all T_APPQMSG objects in all queues of the specified queue space will be retrieved.
Attribute Table
aAll attributes of class T_APPQMSG are local attributes.
bTA_LMID must be specified as a key field except when the application is unconfigured (that is, the TUXCONFIG environment variable is not set).
cAll operations on T_APPQMSG 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.
dSufficient key fields must be supplied in a GET operation to explicitly target a single application queue space.
Attribute Semantics
|
VALid |
The message exists. This state is INActive equivalent for purposes of permissions checking. |
TA_HIGHPRIORITY: 1 <= num <= 100
TA_MSGEXPIREENDTIME:
TA_MSGENDTIME:
T_APPQSPACE Class Definition
Overview
The T_APPQSPACE class represents application queue spaces. An application queue space is an area in a BEA Tuxedo system device; see the T_DEVICE class in TM_MIB(5) for more information about devices and their attributes. Each queue space typically contains one or more application queues, and each queue may have messages stored in it.
A queue space is uniquely identified by several attributes: its name (TA_APPQSPACENAME attribute), the device that contains it (TA_QMCONFIG attribute), and the logical machine where the device is located (TA_LMID attribute).
A queue space is typically associated with exactly one server group in a configured application. The queue space name as well as the device name are components of the TA_OPENINFO attribute of the T_GROUP object.
Limitations
It is not possible to retrieve all instances of this class by leaving all key fields unset. Instead, all three key fields must be supplied to explicitly target a single application queue space. The single exception occurs when accessing a local queue space via tpadmcall() in the context of an unconfigured application (that is, the TUXCONFIG environment variable is not set). In this case the TA_LMID key field must be omitted.
The above limitation regarding accessibility of queue spaces also applies to T_APPQ, T_APPQMSG, and T_APPQTRANS objects because operations on all objects in the /Q MIB implicitly involve queue spaces.
Attribute Table
a.All attributes of class T_APPQSPACE are local attributes.
b.TA_LMID must be specified as a key field except when the application is unconfigured (that is, the TUXCONFIG environment variable is not set).
c.All operations on T_APPQ, T_APPQMSG, and 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.
d.TA_MAXQUEUES cannot be modified after the queue space is created.
Attribute Semantics
T_APPQTRANS Class Definition
Overview
The T_APPQTRANS class represents run-time attributes of transactions associated with application queues.
Limitations
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(), 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.
Attribute Table
a. All attributes of class T_APPQTRANS are local attributes.
b. 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.
c. Sufficient key fields must be supplied in a GET operation to explicitly target a single application queue space.
Attribute Semantics
HAbord | HCommit}
Portability
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.
Interoperability
This MIB is provided only on BEA Tuxedo 6.0 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.
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.
Examples
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.
Field Tables
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
Header Files
The following header files are needed.
#include <atmi.h>
#include <fml32.h>
#include <tpadm.h>
Libraries
${TUXDIR}/lib/libtmib.a, ${TUXDIR}/lib/libqm.a, ${TUXDIR}/lib/libtmib.so.<rel>, ${TUXDIR}/lib/libqm.so.<rel>, ${TUXDIR}/lib/libqm.libThe libraries must be linked manually when using buildclient. The user must use: -L$(TUXDIR)/lib -ltmib -lqm
Create an Application Queue Space
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 */
Add a Queue to an Application Queue Space
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 */
List Application Queue Spaces Known to the Application
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 (that is, server migration is not used).
List Application Queue Spaces Known to the Application
/* 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 <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 (that is, TA_APPQSPACENAME, TA_QMCONFIG, and TA_LMID) for the queue space.
List Messages in an Application Queue
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 */
List Transactions Involving a Queue Space
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 */
Files
${TUXDIR}/include/tpadm.h
${TUXDIR}/udataobj/tpadm
See Also
tpacall(3c), tpadmcall(3c), tpalloc(3c), tpcall(3c), tpdequeue(3c), tpenqueue(3c), tpgetrply(3c), tprealloc(3c), Introduction to FML Functions, Fadd, Fadd32(3fml), Fchg, Fchg32(3fml), Ffind, Ffind32(3fml), MIB(5), TM_MIB(5)
Setting Up a BEA Tuxedo Application
Administering a BEA Tuxedo Application at Run Time
Programming a BEA Tuxedo Application Using C
Programming a BEA Tuxedo Application Using FML
|
|
|
|
|
|
Copyright © 2000 BEA Systems, Inc. All rights reserved.
|