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

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

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(), all T_APPQMSG objects in all queues of the specified queue space will be retrieved.

Attribute Table

Table 8 APPQ_MIB(5): T_APPQMSG Class Definition Attribute Table

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

`TA_STATE`^c	string	`rw-r--r--`	`GET`: `"VAL"` `SET`: `"INV"`	N/A N/A

`TA_NEWAPPQNAME`	string	`-w--w----`	`string`[1..15]	N/A
`TA_PRIORITY`	long	`rw-rw-r--`	{ 1 <= `num` <= 100 \| -1 }	N/A
`TA_TIME`	string	`rw-rw-r--`	{`YY`[`MM`[`DD`[`hh`[`mm`[`ss`]]]]] \| +`seconds`}	N/A
`TA_EXPIRETIME`	string	`rw-rw-r--`	{`YY`[`MM`[`DD`[`hh`[`mm`[`ss`]]]]] \| +`seconds`}	N/A

`TA_CORRID`(k)	string	`r--r--r--`	`string`[0..32]	N/A
`TA_PERSISTENCE` (k)	string	`r--r--r--`	{`PERSIST`\|`NONPERSIST`}	N/A
`TA_REPLYPERSISTENCE`	string	`r--r--r--`	{`PERSIST` \| `NONPERSIST` \| `DEFAULT`}	N/A
`TA_LOWPRIORITY`(k)	long	`k--k--k--`	1 <= `num` <= 100	1
`TA_HIGHPRIORITY`(k)	long	`k--k--k--`	1 <= `num` <= 100	100
`TA_MSGENDTIME`(k)	string	`k--k--k--`	{ `YY`[`MM`[`DD`[`hh`[`mm`[`ss`]]]]] \| +`seconds`}	`MAXLONG`
`TA_MSGSTARTTIME`(k)	string	`k--k--k--`	{ `YY`[`MM`[`DD`[`hh`[`mm`[`ss`]]]]] \| +`seconds`}	0
`TA_MSGEXPIREENDTIME`(k)	string	`k--k--k--`	{ `YY`[`MM`[`DD`[`hh`[`mm`[`ss`]]]]] \| +`seconds\|NONE`}	`MAXLONG`
`TA_MSGEXPIRESTARTTIME`(k)	string	`k--k--k--`	{ `YY`[`MM`[`DD`[`hh`[`mm`[`ss`]]]]] \| +`seconds`}	0

`TA_CURRETRIES`	long	`r--r--r--`	0 <= `num`	N/A
`TA_MSGSIZE`	long	`r--r--r--`	0 <= `num`	N/A
( k )—`GET` key field^d( * )—required `SET` key field

^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

TA_APPQMSGID: string[1..32]

A unique identifier for the queue message, which can be used to select the message for GET or SET operations. No significance should be placed on this value beyond using it for equality comparisons.

TA_APPQNAME: string[1..15]

Name of the application queue in which the message is stored.

TA_APPQSPACENAME: string[1..15]

Name of the application queue space containing the message.

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 messages. The following list describes the meaning of the TA_STATE attribute returned in response to a GET request.

VALid

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

SET: {INValid}

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

`INValid`	The message is deleted from its queue space. The message must be in state `VALid` before attempting this operation. Successful return leaves the object in the `INValid` state.
`unset`	Modify a message. Successful return leaves the state unchanged.

TA_CURRETRIES: 0 <= num

The number of retries that have been attempted so far on this message.

TA_CORRID: string[0..32]

The correlation identifier for this message provided by the application in the tpenqueue(3c) request. The empty string indicates that a correlation identifier is not present.

TA_EXPIRETIME:

This attribute specifies the time at which a message expires (that is, the time at which the message should be removed from the queue if it has not already been dequeued or administratively deleted). When a message expires, all resources used by it 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.

Expiration times cannot be added to messages enqueued by versions of the BEA Tuxedo system that do not support message expiration, even when the queue manager responsible for changing this value supports message expiration. Attempts to add an expiration time fail.

The empty string is returned by a GET operation if the expiration time is not set. The TA_EXPIRETIME format is one of the following:

+seconds

Specifies that the message will be removed after the specified number of seconds. If the value of seconds is set to zero (0), the message is removed immediately from the queue. Relative expiration time is calculated on the basis of the time at which the MIB request arrives and has been processed by the corresponding queue manager.

YY[MM[DD[hh]mm[ss]]]]

Specifies the year, month, day, hour, minute, and second when the message will be removed if it has not been dequeued or administratively deleted already. Omitted units default to their minimum possible values. For example, 9506 is equivalent to 950601000000. The years 00 through 37 are treated as 2000 through 2037, 70 through 99 are treated as 1970 through 1999, and 38 through 69 are invalid. An absolute expiration time is determined by the clock on the machine where the queue manager process resides.

NONE

Specifies that the message will never expire.

TA_LOWPRIORITY: 1 <= num <= 100
TA_HIGHPRIORITY: 1 <= num <= 100

The lowest and highest priority within which to search for occurrences of T_APPQMSG objects. These attributes may only be used as key fields with GET operations.

TA_MSGEXPIRESTARTTIME:
TA_MSGEXPIREENDTIME:

The expiration start and end times within which to search for occurrences of T_APPQMSG objects. The range is inclusive. A start or end time must be specified as an absolute time value; see TA_EXPIRETIME for the format. These attributes may only be used as key fields with GET operations.

TA_MSGSIZE: 0 <= num

The size of the message, in bytes.

TA_MSGSTARTTIME:
TA_MSGENDTIME:

The start and end time within which to search for occurrences of T_APPQMSG objects. The range is inclusive. A start or end time must be specified as an absolute time value; see TA_TIME for the format. These attributes may only be used as key fields with GET operations.

TA_NEWAPPQNAME: string[1..15]

Name of the queue into which to move the selected message. This queue must be an existing queue in the same queue space. The message must be in state VALid for this operation to succeed. This attribute is not returned by a GET operation. The delivery quality of service of messages that are moved will not be changed as a result of the default delivery policy of the new queue. When messages with an expiration time are moved, the expiration time is considered an absolute expiration time in the new queue, even if it was previously specified as a relative expiration time.

TA_PERSISTENCE:

The quality of service with which the message is being delivered. This read-only state is set to NONPERSIST for non-persistent messages and PERSIST for persistent messages.

TA_PRIORITY: 1 <= num <= 100

The priority of the message.

TA_REPLYPERSISTENCE:

The quality of service with which replies to the message should be delivered. This read-only state is set to NONPERSIST for non-persistent, PERSIST for persistent, and DEFAULT when the reply is to use the default persistence established for the queue where the reply is to be enqueued.

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.

TA_TIME:

The time when the message will be made available. The format is one of the following:

+seconds

Specifies that the message will be processed seconds in the future. The value zero (0) specifies that the message should be processed immediately.

YY[MM[DD[hh[mm[ss]]]]]

Specifies the year, month, day, hour, minute, and second when the message should be processed. Omitted units default to their minimum possible values. For example, 9506 is equivalent to 950601000000. The years 00 through 37 are treated as 2000 through 2037, 70 through 99 are treated as 1970 through 1999, and 38 through 69 are invalid.