qchange [queue_name [out-of-order [retries [delay [high [low [cmd]]]]]]]
[-d persist|nonpersist] [-n nhigh,nlow,ncmd]
[-e default_relative_expiration_time]
Modify a queue in the currently open queue space. The required arguments may be given on the command line or the program will prompt for them. These are the queue name, whether out-of-order enqueuing is allowed (not allowed, top of queue, or before a specified msgid); the number of retries and delay time in seconds between retries; and the high and low limits for execution of a threshold command and the threshold command itself for persistent messaging.
The out-of-order values are none, top, and msgid. Both top and msgid may be specified, separated by a comma.
The threshold values are used to allow for automatic execution of a command when a threshold is reached for persistent messages. The high limit specifies when the command is executed. The low limit must be reached before the command is executed again when the high limit is reached. For example, if the limits are 100 and 50 messages, the command is executed when 100 messages are on the queue, and it is not executed again until the queue is drained down to 50 messages and is filled again to 100 messages. The queue capacity can be specified in bytes or blocks used by the queue (number followed by a b or B suffix), percentage of the queue space used by the queue (number followed by a %), or total number of messages on the queue (number followed by an m). The threshold type for the high and low threshold values must be the same. It is optional whether or not the type is specified on the low value, but if specified, it must match the high value type. The message (m) suffix spans both persistent and non-persistent messages. The other threshold suffixes apply only to persistent messages. Use the -n option to specify threshold values for non-persistent messages. When specified on the command line, the threshold command should be enclosed in double quotation marks if it contains white space. The retry count indicates how many times a message can be dequeued and the transaction rolled back, causing the message to be put back on the queue. A delay between retries can also be specified. When the retry count is reached, the message is moved to the error queue defined for the queue space. If no error queue has been defined, the message is dropped. The queue ordering values for the queue cannot be changed. Low-priority messages are dequeued after every ten messages, even if the queue still contains high-priority messages.
The -d option specifies the default delivery policy for the queue. The valid values for the -d option are persist and nonpersist. When the default delivery policy is persist, enqueued messages with no explicitly specified delivery mode are delivered using the persistent (disk-based) delivery method. When the policy is nonpersist, enqueued messages with no explicitly specified delivery mode are delivered using the non-persistent (in memory) delivery method. If the -d option is not specified, the system does not prompt for information and the default delivery policy is unchanged. When the default delivery policy is modified, the delivery quality of service is not changed for messages already in the queue. 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.
If a non-persistent message cannot be enqueued due to an exhausted or fragmented memory area, the enqueuing operation fails, even if there is sufficient persistent storage for the message. If a persistent message cannot be enqueued due to an exhausted or fragmented disk, the enqueuing operation fails, even if there is sufficient non-persistent storage for the message.
If the amount of memory reserved for non-persistent messages in a queue space is zero (0), no space is reserved for non-persistent messages. (See qspacecreate and qspacechange for information on specifying the non-persistent message memory area.) In this case, attempts to enqueue a non-persistent message fail. This includes messages with no specified delivery quality of service for which the target queue has a default delivery policy of nonpersist.
The -n option specifies the threshold values used for automatic execution of a command when a non-persistent storage area threshold is reached. The nhigh limit specifies when the command ncmd is executed. The nlow limit must be reached before the command will be executed again when the nhigh limit is reached. If the -n option is specified, the nhigh, nlow, and ncmd values must all be supplied, or the command fails. The ncmd value may be specified as an empty string. If the -n option is not specified, the program does not prompt for information.
The memory capacity (amount of non-persistent data in the queue) can be specified as one of the following threshold types: bytes (b), blocks (B), or percentage (number followed by %). The threshold type for the nhigh and nlow values must be the same. For example, if nhigh is set to 100%, then nlow, if specified, must also be specified as a percentage. The threshold type of the nlow value is optional. If the -n option is not specified, the default threshold values for non-persistent messaging are unchanged. If ncmd contains white space, it must be enclosed in double quotation marks.
The m suffix of the [ . . . [high[low[cmd]] . . . ] thresholds applies to all messages in a queue, including both persistent and non-persistent messages, and therefore is not available with nhigh and nlow. The [ . . . [high[low[cmd]] . . . ] thresholds specified without the -m suffix apply to persistent (disk-based) messages only.
The -e default_relative_expiration_time option sets an expiration time for all messages enqueued to the queue that do not have an explicitly specified expiration time. The expiration time may be either a relative expiration time or none. When the expiration time is reached and the message has not been dequeued or administratively deleted, the message is removed from the queue, all resources associated with the message are reclaimed by the system, and statistics are updated. If the expiration time is before the message availability time, the message is not available for dequeuing unless either the availability or expiration time is changed so that the availability time is before the expiration time. In addition, these messages are removed from the queue at expiration time even if they were never available for dequeuing. 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 when a message has expired.
If the -e option is not specified, the default expiration time of the queue is not changed. When the queue's expiration time is modified using qchange, the expiration times for messages already in the queues are not modified. If the -e option is not specified, the program does not prompt for it.
The format of a relative default_relative_expiration_time is +seconds where seconds is the number of seconds from the time that the queue manager successfully completes the operation to the time that the message expires. A value of zero (0) indicates immediate expiration.The value of default_relative_expiration_time may also be set to the string none. The none string indicates that messages that are enqueued with no explicit expiration time will not expire unless an expiration time is explicitly assigned to them.
qchangeexp (qce) -y [newtime]
Change the expiration time for messages on a queue. When a message expires, it is removed from the queue, all resources used by the message are reclaimed by the system, and the relevant statistics are updated. If the expiration time is before the message availability time, the message is not available for dequeuing unless either the availability or expiration time is changed so that the availability time is before the expiration time. In addition, these messages are removed from the queue at expiration time even if they were never available for dequeuing. 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 when a message has expired.
The queue for which an expiration time is set is selected using the qset command. Selection criteria for limiting the messages to be updated are set with the qscan command. If no selection criterion is set, then all messages on the queue are changed. By default, a confirmation is requested before the expiration time is set. The -y option specifies no prompt for confirmation. The newtime value can be relative to either the current time, an absolute value, or none. If the newtime value is not provided on the command line, the program prompts for it.
Messages enqueued by versions of the BEA Tuxedo system that do not support message expiration cannot be modified to have an expiration time even when the queue manager responsible for changing the value supports message expiration. If messages affected by qchangeexp have been enqueued by one of these versions of the BEA Tuxedo system, an error message indicates that some of the selected messages were not modified due to this limitation.
A relative expiration time is relative to when the request arrives at the queue manager process. The format of a relative newtime is +seconds where seconds is the number of seconds from the time that the queue manager successfully completes the operation to the time that the message expires. If seconds is set to zero (0), messages expire immediately. An absolute expiration time is determined by the clock on the machine where the queue manager process resides. The format of an absolute newtime is YY[MM[DD[HH[MM[SS]]]]] as described in qscan. The value of newtime may also be set to the string none, which indicates that affected messages never expire.
qcreate (qcr) [queue_name [qorder [out-of-order [retries [delay
[high [low [cmd]]]]]]]] [-d persist|nonpersist] [-n nhigh,nlow,ncmd]
[-e default_relative_expiration_time]
Create a queue in the currently open queue space. The required arguments may be given on the command line or the program will prompt for them. These are the queue name, the queue ordering (fifo or lifo, by expiration time, by priority, by time); whether out-of-order enqueuing is allowed (not allowed, top of queue, before a specified msgid); the number of retries and delay time in seconds between retries; the high and low limits for execution of a threshold command; and the threshold command itself for persistent messages.
The queue ordering values are fifo, lifo, priority, expiration, and time. When specifying the queue ordering, the most significant sort value must be specified first, followed by the next most significant sort value, and so on; fifo or lifo can be specified only as the least significant (or only) sort value. If neither fifo or lifo is specified, then the default is fifo within whatever other sort criteria are specified. If expiration is specified, messages with no expiration time are dequeued after all messages with an expiration time. Multiple sort values may be specified separated by commas. The out-of-order values are none, top, or msgid. Both top and msgid may be specified, separated by a comma.
The threshold values are used to allow for automatic execution of a command when a threshold is reached for persistent messages. The high limit specifies when the command is executed. The low limit must be reached before the command will be executed again when the high limit is reached. For example, if the limits are 100 and 50 messages, the command will be executed when 100 messages are on the queue, and will not be executed again until the queue has been drained below 50 messages and has filled again to 100 messages.
The queue capacity can be specified in bytes or blocks used by the queue (number followed by a b or B suffix), percentage of the queue space used by the queue (number followed by a %), or total number of messages on the queue (number followed by an m). The threshold type for the high and low threshold values must be the same. The message (m) suffix spans both persistent and non-persistent messages. The other threshold suffixes apply only to persistent messages. Use the -n option to specify threshold values for non-persistent messages. It is optional whether or not the type is specified on the low value, but if specified, it must match the high value type. When specified on the command line, the threshold command should be enclosed in double quotation marks if it contains white space.
The retry count indicates how many times a message can be dequeued and the transaction rolled back, causing the message to be put back on the queue. A delay between retries can also be specified. When the retry count is reached, the message is moved to the error queue defined for the queue space. If an error queue has not been defined, the message is dropped. Low-priority messages are dequeued after every ten messages, even if the queue still contains high-priority messages.
The -d option specifies the default delivery policy for the queue. The valid values for the -d option are persist and nonpersist. When the default delivery policy is persist, enqueued messages with no explicitly specified delivery mode are delivered using the persistent (disk-based) delivery method. When the policy is nonpersist, enqueued messages with no explicitly specified delivery mode are delivered using the non-persistent (in memory) delivery method. If the -d option is not specified, the system does not prompt for information and the default delivery policy for the queue is persist. When the default delivery policy is modified, the delivery quality of service is not changed for messages already in the queue.
If a non-persistent message cannot be enqueued due to an exhausted or fragmented memory area, the enqueuing operation fails, even if there is sufficient persistent storage for the message. If a persistent message cannot be enqueued due to an exhausted or fragmented disk, the enqueuing operation fails, even if there is sufficient non-persistent storage for the message.
If the amount of memory reserved for non-persistent messages in a queue space is zero (0), no space is reserved for non-persistent messages. (See qspacecreate and qspacechange for information on specifying the non-persistent message memory area.) In this case, attempts to enqueue a non-persistent message fail. This includes messages with no specified delivery quality of service for which the target queue has a default delivery policy of nonpersist.
The -n option specifies the threshold values used for automatic execution of a command when a non-persistent storage area threshold is reached. The nhigh limit specifies when the command ncmd is executed. The nlow limit must be reached before the command will be executed again when the nhigh limit is reached. If the -n option is specified, the nhigh, nlow, and ncmd values must all be supplied, or the command fails. The ncmd value may be specified as an empty string. If the -n option is not specified, the program does not prompt for information.
The memory capacity (amount of non-persistent data in the queue) can be specified as one of the following threshold types: bytes (b), blocks (B), or percentage (number followed by %). The threshold type for the nhigh and nlow values must be the same. For example, if nhigh is set to 100%, then nlow, if specified, must also be specified as a percentage. The threshold type of the nlow value is optional. If the -n option is not specified, the default threshold values are used (100% for nhigh and 0% for nlow) and ncmd is set to " ". If ncmd contains white space, it must be enclosed in double quotation marks.
The m suffix of the [ . . . [high[low[cmd]] . . . ] thresholds applies to all messages in a queue, including both persistent and non-persistent messages, and therefore is not available with nhigh and nlow. The [ . . . [high[low[cmd]] . . . ] thresholds specified without the -m suffix apply to persistent (disk-based) messages only.
The -e default_relative_expiration_time option sets an expiration time for all messages enqueued to the queue that do not have an explicitly specified expiration time. The expiration time may be either a relative expiration time or none. When the expiration time is reached and the message has not been dequeued or administratively deleted, the message is removed from the queue, all resources associated with the message are reclaimed by the system, and statistics are updated. If the expiration time is before the message availability time, the message is not available for dequeuing unless either the availability or expiration time is changed so that the availability time is before the expiration time. In addition, these messages are removed from the queue at expiration time even if they were never available for dequeuing. 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 when a message has expired.
If the -e option is not specified, the default expiration time of the queue is set to none. When the queue's expiration time is modified using qchange, the expiration times for messages already in the queues are not modified. If the -e option is not specified, the program does not prompt for it.
The format of a relative default_relative_expiration_time is +seconds where seconds is the number of seconds from the time that the queue manager successfully completes the operation to the time that the message expires. A value of zero (0) indicates immediate expiration.The value of default_relative_expiration_time may also be set to the string none. The none string indicates that messages that are enqueued with no explicit expiration time will not expire unless an expiration time is explicitly assigned to them.
qscan [{ [-t time1[-time2]] [-p priority1[-priority2]] [-m msgid]
[-i corrid][-d delivery_mode] [-e time1[-time2]] | none }]
This command sets the selection criteria used for the qchangeprio, qchangequeue, qchangetime, qdeletemsg, and qlist commands. An argument of none indicates no selection criteria; all messages on the queue will be affected. Executing this command with no argument prints the current selection criteria values. When command-line options give a value range (for example, -t, -e, or -p) the the value range may not contain white space. The -t option can be used to indicate a time value or a time range. The format of time1 and time2 is: YY[MM[DD[HH[MM[SS]]]]] specifying the year, month, day, hour, minute, and second. Units omitted from the date-time value default to their minimum possible values. For example, "7502" is equivalent to "750201000000." The years 00-37 are treated as 2000-2037, years 70-99 are treated as 1970-1999, and 38-69 are invalid. The -p option can be used to indicate a priority value or a priority range. Priority values are in the range 1 to 100, inclusive. The -m option can be used to indicate a message identifier value, assigned to a message by the system when it is enqueued. The message identifier is unique within a queue and its value may be up to 32 characters in length. Values that are shorter than 32 characters are padded on the right with nulls (0x0). Backslash and non-printable characters (including white space characters such as space, newline, and tab) must be entered with a backslash followed by a two-character hexadecimal value for the character (for example, space is \20, as in "hello\20world"). The -i option can be used to indicate an correlation identifier value associated with a message. The identifier value is assigned by the application, stored with the enqueued message, and passed on to be stored with any reply or error message response such that the application can identify responses to particular requests. The value may be up to 32 characters in length. Values that are shorter than 32 characters are padded on the right with nulls (0x0). Backslash and non-printable characters (including white space characters such as space, newline, and tab) must be entered with a backslash followed by a two-character hexadecimal value for the character (for example, space is \20, as in my\20ID\20value).
The valid values for the -d delivery_mode option are persist and nonpersist. This option specifies the delivery mode of messages selected by qscan so that an operator can take action based on the delivery method.
The -e option can be used to indicate an expiration time or an expiration time range. The format of time1 and time2 is the same as time1 and time2 for the -t option.
qspacecreate (qspc) [queue_space_name [ipckey [pages [queues [trans
[procs [messages [errorq [inityn [blocking]]]]]]]] [-A actions]
[-H handles] [-C cursors] [ -O owners] [-Q tmp_queues] [-f filter_memory] [-n nonpersistent_msg_memory[b,B]] [-o overflow_memory]
Create a queue space for queued messages. If not provided on the command line, the program prompts for the following information: the queue space name, the ipckey for the shared memory segment and semaphore; number of physical pages to allocate for the queue space; the number of queues; the number of concurrent transactions; the number of processes concurrently attached to the queue space; the number of messages that may be queued at one time; the name of an error queue for the queue space; whether or not to initialize pages on new extents for the queue space; and the blocking factor for doing queue space initialization and warm start disk input/output.
The number of physical pages requested is rounded down to the nearest multiple of four pages. For example, a request of 50 pages results in a memory allocation of 48 pages, and a request of 52 pages results in a memory allocation of 52 pages. The error queue is used to hold messages that have reached the maximum number of retries (they are moved from their original queue to the error queue). The administrator is responsible for ensuring that this queue is drained.
The number of physical pages allocated must be large enough to hold the overhead for the queue space (one page plus one page per queue). If the initialization option is specified as `y' or `Y,' then the space used to hold the queue space is initialized and this command may run for a while. In verbose mode, a period (.) is printed to the standard output after completing initialization of each 5% of the queue space. If the initialization option is not turned on but the underlying device is not a character special device, then the file will be initialized if it not already the size specified for the extent (that is, the file will be grown to allocate the specified space).
When reading and writing blocks during creation of the queue space and during warm start (restart of the queue space), the size of input and output operations will be calculated as a multiple of the disk page size as specified by the blocking factor.
The -A actions option specifies the number of additional actions that the Queuing Services component can handle concurrently. When a blocking operation is encountered and additional actions are available, the blocking operation is set aside until it can be satisfied. After setting aside the blocking operation, another operation request can be handled. When the blocking operation completes, the action associated with the operation is made available for a subsequent operation. An operation fails if a blocking operation is requested and cannot be immediately satisfied and there are no actions available. The system reserves actions equivalent to the number of processes that can attach to a queue space so that each queue manager process may have at least one blocking action. Beyond the system-reserved number of blocking actions, the administrator may configure the system to be able to accommodate additional blocking actions beyond the reserve. If the -A actions option is not specified, the default is zero. If the -A option is not specified, the program does not prompt for it.
The -H handles option specifies the number of handles that users of that the Queuing Services component may use concurrently. Objects manipulated by the Queuing Services API require handles to access the objects. When an object is opened by a call to the API, a new handle is created and returned to the user. When an object handle is closed, the handle is made available for subsequent open object operations. When the API is used by an application, the administrator must configure the system to accommodate the maximum number of handles that will be opened concurrently. If the -H handles option is not specified, the default is zero. If the -H option is not specified, the program does not prompt for it. An operation fails if a user attempts to open a queuing services object and there are no handles available. This option is not currently used by the BEA Tuxedo system. Adjusting this value has no effect on BEA Tuxedo applications other than unnecessarily consuming shared memory resources.
The -C cursors option specifies the number of cursors that users of that the Queuing Services component may use concurrently. Cursors are used to navigate a queue. When a cursor is destroyed, the cursor resources are made available for subsequent cursor creation operations. When the cursors are used by an application, the administrator must configure the system to accommodate the maximum number of cursors that will be allocated concurrently. If the -C cursors option is not specified, the default is zero. If the -C option is not specified, the program does not prompt for it. An operation fails if a user attempts to create a cursor and there are no cursor resources available. BEA Tuxedo applications need not adjust this value. This option is not currently used by the BEA Tuxedo system. Adjusting this value has no effect on BEA Tuxedo applications other than unnecessarily consuming shared memory resources.
The -O owners option specifies the number of additional BEA Engine authenticated users that may concurrently use the Queuing Services resources. There is one owner record per user, regardless of the number of open handles for the user. When there are no open handles for a user, the owner record is made available for subsequent users. The system reserves owners equivalent to the number of actions so that each action may be initiated by a different owner. Beyond the system-reserved number of owners that may be concurrently using queuing services resources, the administrator may configure the system to accommodate additional owners beyond the reserve. If the -O owners option is not specified, the default is zero. If the -O option is not specified, the program does not prompt for it. An operation fails if a user attempts to open a handle when they currently do not have any open handles, and there are no owners available. This option is not currently used by the BEA Tuxedo system. Adjusting this value has no effect on BEA Tuxedo applications other than unnecessarily consuming shared memory resources.
The -Q tmp_queues option specifies the number of temporary queues that may be opened concurrently in the Queuing Services component of the BEA Engine. Temporary queues reduce the need for administrators to configure each queue used by an application. They are used by dynamic self-configuring applications. Messages enqueued to temporary queues are not persistent. When all handles to a temporary queue are closed, the temporary queue resources are made available for subsequent temporary queue creation. When the temporary queues are used by an application, the administrator must configure the system to accommodate the maximum number of temporary queues that will be active concurrently. If the -Q tmp_queues option is not specified, the default is zero. If the -Q option is not specified, the program does not prompt for it. An open operation fails if a user attempts to open a temporary queue and there are no temporary queue resources available. This option is not currently used by the BEA Tuxedo system. Adjusting this value has no effect on BEA Tuxedo applications other than unnecessarily consuming shared memory resources.
The -f filter_memory option specifies the size of the memory area to reserve in shared memory to hold the compiled representation of user defined filters. The memory size is specified in bytes. Filters are used by the Queuing Services component of the BEA Engine for message selection in dequeuing and cursor operations. Filters may be specified using various grammars but are compiled into an engine normal form and stored in shared memory. Filters are referenced by a handle returned when they are compiled. When a filter is destroyed, the memory used by the filter is made available for subsequent compiled filters. When the filters are defined by an application, the administrator must configure the system to accommodate the maximum number of filters that will be concurrently compiled. If the -f filter_memory option is not specified, the default is zero. If the -f option is not specified, the program does not prompt for it. An operation fails if a user attempts to create a new filter and there is not enough memory allocated for the compiled version of the filter. This option is not currently used by the BEA Tuxedo system. Adjusting this value has no effect on BEA Tuxedo applications other than unnecessarily consuming shared memory resources.
The -n nonpersistent_msg_memory option specifies the size of the area to reserve in shared memory for non-persistent messages for all queues in the queue space. The size may be specified in bytes (b) or blocks (B), where the block size is equivalent to the disk block size. The [bB] suffix is optional and, if not specified, the default is blocks. If the -n option is not specified, the memory size defaults to zero (0). Also, if the -n option is not specified, the program does not prompt for it.
If the value is specified in bytes (b) for nonpersistent_msg_memory, the system divides the specified value by the number of bytes per page (page size is equivalent to the disk page size), rounds down the result to the nearest integer, and allocates that number of pages of memory. For example, assuming a page size of 1024 bytes (1KB), a requested value of 2000b results in a memory allocation of 1 page (1024 bytes), and a requested value of 2048b results in a memory allocation of 2 pages (2048 bytes). Requesting a value less than the number of bytes per page results in an allocation of 0 pages (0 bytes).
If the value is specified in blocks (B) for nonpersistent_msg_memory and assuming that one block of memory is equivalent to one page of memory, the system allocates the same value of pages. For example, a requested value of 50B results in a memory allocation of 50 pages.
If the nonpersistent_msg_memory for a queue space is zero (0), no space is reserved for non-persistent messages. In this case, attempts to enqueue a non-persistent message fail. Persistent and non-persistent storage are not interchangeable. If a non-persistent message cannot be enqueued due to an exhausted or fragmented memory area, the enqueuing operation fails, even if there is sufficient persistent storage for the message. If a persistent message cannot be enqueued due to an exhausted or fragmented disk, the enqueuing operation fails, even if there is sufficient non-persistent storage for the message.
The -o overflow_memory option specifies the size of the memory area to reserve in shared memory to accommodate peek load situations where some or all of the allocated shared memory resources are exhausted. The memory size is specified in bytes. Additional objects will be allocated from this additional memory on a first-come-first-served basis. When an object created in the additional memory is closed or destroyed, the memory is released for subsequent overflow situations. If the -o overflow_memory option is not specified, the default is zero. If the -o option is not specified, the program does not prompt for it. This additional memory space may yield more objects than the configured number, but there is no guarantee that additional memory is available for any particular object at any given point in time. Currently, only actions, handles, cursors, owners, temporary queues, timers, and filters use the overflow memory.