Section 5 - File Formats, Data Descriptions, MIBs, and System Processes Reference

File Formats, Data Descriptions, MIBs, and System Processes Reference

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(), all T_APPQ objects within the specified queue space will be retrieved.

Attribute Table

Table 7 APPQ_MIB(5): T_APPQ Class Definition Attribute Table

Attribute ^a	Type	Permissions	Values	Default
`TA_APPQNAME`(k)(r)(*)	string	`ru-r--r--`	`string`[1..15]	N/A
`TA_APPQSPACENAME`(k)(r)(*)	string	`ru-r--r--`	`string`[1..15]	N/A
`TA_QMCONFIG`(k)(r)(*)	string	`ru-r--r--`	`string`[1..78]	N/A
`TA_LMID`(k)(r)(*) ^b	string	`ru-r--r--`	`string`[1..30]	N/A

`TA_STATE` ^c	string	`rw-r--r--`	`GET`: `"VAL"` `SET`: `"`{`NEW` \| `INV`}`"`	N/A N/A

`TA_APPQORDER` ^d	string	`rw-r--r--`	{`PRIO` \| `TIME` \| `LIFO` \| `FIFO` \| `EXPIR`}	`FIFO`
`TA_DEFEXPIRATIONTIME`	string	`rw-r--r--`	{+`seconds` \| `NONE`}	N/A
`TA_DEFDELIVERYPOLICY`	string	`rw-r--r--`	{`PERSIST` \| `NONPERSIST`}	`PERSIST`
`TA_CMD`	string	`rw-r--r--`	`shell-command -string`[0..127] ^e	`""`
`TA_CMDHW`	string	`rw-r--r--`	0 <= `num` [`bBm%`]	`100%`
`TA_CMDLW`	string	`rw-r--r--`	0 <= `num` [`bBm%`]	`0%`
`TA_CMDNONPERSIST`	string	`rw-r--r--`	`shell-command-string`[0..127] ^e	`""`

`TA_CMDNONPERSISTHW`	string	`rw-r--r--`	0 <= `num`[`bB%`]	`100%`
`TA_CMDNONPERSISTLW`	string	`rw-r--r--`	0 <= `num`[`bB%`]	`0%`
`TA_MAXRETRIES`	long	`rw-r--r--`	0 <= `num`	`0`
`TA_OUTOFORDER`	string	`rw-r--r--`	{`NONE` \| `TOP` \| `MSGID`}	`NONE`
`TA_RETRYDELAY`	long	`rw-r--r--`	0 <= `num`	`0`

`TA_CURBLOCKS`	long	`r--r--r--`	0 <= `num`	N/A
`TA_CURMSG`	long	`r--r--r--`	0 <= `num`	N/A
`TA_CURNONPERSISTBYTES`	long	`r--r--r--`	0 <= `num`	N/A
`TA_CURNONPERSISTMSG`	long	`r--r--r--`	0 <= `num`	N/A
( k )—`GET` key field ^f( r )—required field for object creation ( * )—required `SET` key field

^a All attributes of class T_APPQ 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 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_APPQORDER cannot be modified after the application queue is created.
^e Maximum string length for this attribute is 78 bytes for BEA Tuxedo 8.0 or earlier.
^f Sufficient key fields must be supplied in a GET operation to explicitly target a single application queue space.

Attribute Semantics

TA_APPQNAME: string[1..15]

Name of the application queue.

TA_APPQSPACENAME: string[1..15]

Name of the application queue space containing the application queue.

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: {VALid}

A GET operation retrieves information about the selected application queues. The following list describes the meaning of the TA_STATE attribute returned in response to a GET request.

VALid

The specified queue exists. This state is INActive equivalent for purposes of permissions checking.

SET: {NEW | INValid}

A SET operation changes characteristics of the selected application queue or creates a new queue. The following list describes the meaning of the TA_STATE attribute returned by a SET request. States not listed cannot be set.

`NEW`	Create a new queue in the specified queue space. The queue is left in state `VALid` following successful creation.
`INValid`	Delete the specified queue. The queue must be in state `VALid` to be deleted. If the queue space has processes attached to it (that is, it is in the `ACTive` state), the queue will not be deleted unless the `TA_FLAGS` attribute includes the `QMIB_FORCEDELETE` flag. In addition, if the queue has messages in it, it will not be deleted unless `QMIB_FORCEPURGE` is specified. Successful return leaves the object in the `INValid` state.
`unset`	Modify an application queue. Successful return leaves the state unchanged.

TA_APPQORDER:

The order in which messages in the queue are to be processed. Legal values are PRIO, TIME, or EXPIR. A combination of sort criteria may be specified with the most significant criterion specified first, followed by other criteria, and optionally followed by either LIFO or FIFO, which are mutually exclusive. If EXPIR is specified, messages with no expiration time are dequeued after all messages with an expiration time. If neither FIFO nor LIFO is specified, FIFO is assumed. If no order is specified when a queue is created, the default order is FIFO. For example, the following are settings are legal:

PRIO PRIO,TIME,LIFO TIME,PRIO,FIFO TIME,FIFO EXPIR EXPIR,PRIO,FIFO TIME,EXPIR,PRIO,FIFO

TA_CMD: shell-command-string[0..127]

The command to be automatically executed when the high water mark for persistent (disk-based) messages, TA_CMDHW, is reached. The command will be re-executed when the high water mark is reached again after the low water mark, TA_CMDLW, has been reached.

For BEA Tuxedo 8.0 or earlier, the maximum string length for the TA_CMD attribute is 78 bytes.

TA_CMDHW: 0 <= num[bBm%]

TA_CMDLW: 0 <= num[bBm%]

The high and low water marks that control the automatic execution of the command specified in the TA_CMD attribute. Each is an integer greater than or equal to zero. Both TA_CMDHW and TA_CMDLW must be followed by one of the following keyletters and the keyletters must be consistent for TA_CMDHW and TA_CMDLW.

b

The high and low water marks pertain to the number of bytes used by persistent (disk based) messages in the queue.

B

The high and low water marks pertain to the number of blocks used by persistent messages in the queue.

m

The high and low water marks pertain to the number of messages (both persistent and non-persistent) in the queue.

%

The high and low water marks are expressed in terms of a percentage of queue capacity. This pertains only to persistent messages.

For example, if TA_CMDLW is 50m and TA_CMDHW is 100m, the command specified in TA_CMD will be executed when 100 messages are on the queue, and it will not be executed again until the queue has been drained below 50 messages and has filled again to 100 messages.

TA_CMDNONPERSIST: shell-command-string[0..127]

This attribute specifies the command to be executed automatically when the high water mark for non-persistent (memory-based delivery) messages, TA_CMDNONPERSISTHW, is reached. The command is re-executed when the high-water mark is reached again after the low-water mark for non-persistent (memory-based delivery) messages, TA_CMDNONPERSISTLW, has been reached.

For BEA Tuxedo 8.0 or earlier, the maximum string length for the TA_CMDNONPERSIST attribute is 78 bytes.

TA_CMDNONPERSISTHW: 0 <= num[bB%]

TA_CMDNONPERSISTLW: 0 <= num[bB%]

These attributes specify the high and low water marks that control the automatic execution of the command specified in the TA_CMDNONPERSIST attribute. Each is an integer greater than or equal to zero followed by one of the following keyletters. The keyletters must be consistent for TA_CMDNONPERSISTHW and TA_CMDNONPERSISTLW.

b

The high and low water marks are expressed as the number of bytes used by non-persistent (in memory) messages in the queue.

B

The high and low water marks are expressed as the number of blocks used by non-persistent (in memory) messages in the queue.

%

The high and low water marks are expressed as a percentage of the shared memory capacity reserved for non-persistent messages in the queue space used by the queue.

The messages threshold type specified via the TA_CMDHW and TA_CMDLW attributes (when followed by an m) applies to all messages in a queue, including both persistent and non-persistent messages, and therefore is not available as a threshold type for TA_CMDNONPERSISTHW and TA_CMDNONPERSISTLW.

TA_CURBLOCKS: 0 <= num

The number of disk pages currently consumed by the queue.

TA_CURMSG: 0 <= num

The number of persistent messages currently in the queue. To determine the total number of messages in the queue, add TA_CURMEMMSG to this value.

TA_DEFAULTEXPIRATIONTIME:

This attribute specifies an expiration time for messages enqueued with no explicit expiration time. The expiration time may be either a relative expiration time or NONE. The relative expiration time is determined by associating a fixed amount of time with a message after the message arrives at the queue manager process. When a message's expiration time is reached and the message has not been dequeued or administratively deleted, all resources associated with the message are reclaimed by the system and statistics are updated. If a message expires during a transaction, the expiration does not cause the transaction to fail. Messages that expire while being enqueued or dequeued within a transaction are removed from the queue when the transaction ends. There is no notification that the message has expired. If no default expiration time is specified for a queue, messages without an explicit expiration time do not expire. When the queue's expiration time is modified, the expiration times of messages that were in the queue before the modification are not changed.

The format is +seconds where seconds is the number of seconds allowed to lapse between the time that the queue manager successfully completes the operation and the time that the message is to expire. If seconds is set to zero (0) the message expires immediately.

The value of this attribute may also be set to the string NONE. The NONE string indicates that messages enqueued to the queue with no explicit expiration time do not expire. You may change the expiration time for messages already in a queue with the TA_EXPIRETIME attribute of the T_APPQMSG class in the APPQ_MIB.

TA_DEFDELIVERYPOLICY:

This attribute specifies the default delivery policy for the queue when no delivery mode is specified for a message enqueued to the queue. When the value is PERSIST, messages enqueued to the queue without an explicitly specified delivery mode are delivered using the persistent (disk-based) delivery method. When the value is NONPERSIST, messages enqueued to the queue without an explicitly specified delivery mode are delivered using the non-persistent (in memory) delivery method.When a queue's default delivery policy is modified, the delivery quality of service of messages that are in the queue before the modification are not changed. If the queue being modified is the reply queue named for any messages currently in the queue space, the reply quality of service is not changed for those messages as a result of changing the default delivery policy of the queue.

For non-persistent delivery, if the memory area is exhausted or fragmented such that a message cannot be enqueued, the enqueuing operation fails, even if there is sufficient persistent storage for the message. Similarly, if the persistent storage area is exhausted or fragmented such that a message cannot be enqueued, the enqueuing operation fails, even if there is sufficient non-persistent storage for the message. If the TA_MEMNONPERSIST attribute of the T_APPQSPACE class is zero (0) for a queue space, no space is reserved for non-persistent messages. In such a case, any attempt to enqueue a non-persistent message fails. This type of failure results, for example, when no delivery quality of service has been specified for a message and the TA_DEFDELIVERYPOLICY attribute for the target queue has been set to NONPERSIST.

TA_MAXRETRIES: 0 <= num

The maximum number of retries for a failed queue message. When the number of retries is exhausted, the message is placed on the error queue of the associated application queue space. If there is no error queue, the message is dropped. The default is zero.

TA_OUTOFORDER: {NONE | TOP | MSGID}

The way in which out-of-order message processing is to be handled. The default is NONE.

TA_RETRYDELAY: 0 <= num

The delay, in seconds, between retries for a failed queue message. The default is zero.

TA_CURNONPERSISTBYTES: 0 <= num

This attribute specifies the number of shared memory bytes currently consumed by the non-persistent messages on the queue.

TA_CURNONPERSISTMSG: 0 <= num

This attribute specifies the number of non-persistent messages currently in the queue. To determine the total number of messages in the queue, add TA_CURMSG to this value.