qmadmin-Queue manager administration program
[QMCONFIG=<device>]qmadmin[<device>]
With the commands listed below, qmadmin provides for creation, inspection and modification of message queues. The name of the device (file) on which the universal device list resides (or will reside) for the queue space may either be specified as a command line argument or via the environment variable QMCONFIG. If both are specified, the command option is used.
As a system-provided server, qmadmin does not go through normal initialization, so it does not pick up the value of ULOGPFX. As a result, any log entries generated by qmadmin commands are written to the current working directory. This is corrected by setting and exporting the ULOGPFX environment variable to the pathname of the directory where the userlog is located.
qmadmin uses the greater than sign, >, as a prompt. Arguments are entered separated by white space (tabs and/or spaces). Arguments that contain white space may be enclosed within double quotes; if an argument enclosed within double quotes contains a double quote, the internal double quote must be escaped with a backslash. Commands will prompt for the information if it is not given on the command line. A warning message is displayed and the prompt shown again, if a required argument is not entered.
The user can exit the program by entering q or CTRL-d> when prompted for a command. Output from a command may be terminated by hitting BREAK; the program then prompts for the next command. Hitting return when prompted for a command repeats the previously executed command, except after a break.
Note that there is no way to effectively cancel a command once you press RETURN; hitting BREAK only terminates output from the command, if any. Therefore, be sure that you type a command exactly as you intended before pressing RETURN.
Output from qmadmin commands is paginated according to the pagination command in use (see the paginate subcommand below).
When first entering qmadmin, no queue space is opened. A queue space is created using qspacecreate and is opened using qopen. The qaborttrans, qclose, qchangeprio, qchangequeue, qchangetime, qcommittrans, qchange, qcreate, qdeletemsg, qinfo, qlist, qprinttrans and qset commands can only be executed when a queue space is open.
Commands may be entered either by their full name or their abbreviation (if available, the abbreviation is listed below in parentheses following the full name), followed by any appropriate arguments. Arguments appearing in square brackets, [], are optional; those in curly braces, {}, indicate a selection from mutually exclusive options.
chdl [dlindex [newdevice]]
Change the name for a universal device list entry. The first argument is the index of the device on the universal device list that is to be changed (device indexes are returned by lidl). The program will prompt for it if not provided on the command line. The second argument is the new device name. If not provided on the command line, the program prints the current device name and then prompts for a new one. The name is limited to 64 characters in length. Files or data will no longer be accessible via the old name after the device name is changed so this command must be used cautiously. A more detailed description of the Universal Device List and Volume Table of Contents are provided in Administering the BEA TUXEDO System.
crdl [device [offset [size]]]
QMCONFIG and must have an offset of 0. If arguments are not provided on the command line, the program will prompt for them. The arguments are the device name, the block number at which space may begin to be allocated, and the number of physical pages (disk sectors) to be allocated. More than one extent can be allocated to a given file (for example, allocate /Dave/waifs 0 500 and then allocate /Dave/waifs 1000 500 for a total of 1000 blocks allocated but blocks 500 through 999 are unused). Several blocks from the first device entry are used by the device list and table of contents. Up to 25 entries may be created on the device list.
dsdl [-y] [dlindex]
dlindex argument is the index on the universal device list of the device that is to be removed from the device list. If not provided on the command line, the program will prompt for it. Entry 0 cannot be removed until all VTOC files and other device list entries are destroyed first (since entry 0 contains the device which holds the device list and table of contents, destroying it also destroys these two tables.) VTOC files can be removed only by removing the associated entities (for example, by destroying a queue space that resides on the device). The program prompts for confirmation unless -y is specified.
echo (e) [{off | on}]
on. If no option is given, then the current setting is toggled, and the new setting is printed. The initial setting is off.
help (h) [{command | all}]
command is specified, the abbreviation, arguments, and description for that command are printed. all causes a description of all commands to be displayed. Omitting all arguments causes the syntax of all commands to be displayed.
ipcrm [-f] [-y] [queue_space_name]
ipcrm removes the IPC data structures used for the specified queue space. If not provided on the command line, the program prompts for the queue space name. If the specified queue space is open in qmadmin, it will be closed. ipcrm knows all IPC resources used by the queue space and is the only way that the IPC resources should be removed. qmadmin ensures that no other processes are attached to the queue space before removing the IPC resources. The -f option can be specified to force removal of IPC resources even if the other processes are attached. This command prompts for confirmation before execution if the -f option is specified, unless the -y option is specified.
ipcs [queue_space_name]
ipcs lists the IPC data structures used for a queue space, if any (none may be used if the queue space is not opened by any process). If not provided on the command line, the program prompts for the queue space name.
lidl [dlindex]
dlindex is specified, then only the information for that device list entry is printed.
livtoc
VTOC table entries. The information printed for each entry includes the name of the VTOC table, the device on which it is found, the offset of the VTOC table from the beginning of the device and the number of pages allocated for that table. There are a maximum of 100 entries in the VTOC.
paginate (page) [{off|on}]
PAGER may be used to override the default command used for paging output. The default paging command is the pager indigenous to the native operating system environment, e.g., the command pg is the default on UNIX System operating environments.
qaborttrans (qabort) [-y] [tranindex]
tranindex. The program will prompt for the transaction index if not specified on the command line. If the transaction is known to be decided and the decision was to commit, qaborttrans will fail. The index is taken from the previous execution of the qprinttrans command. Confirmation is requested unless the -y option is specified. This command should be used with care.
qaddext [queue_space_name [pages]]
qmadmin, it will be closed. The number of pages will be rounded down to the nearest multiple of bits-per-byte divided by 2 (normally 4). Space will be allocated from extents defined in the UDL associated with the QMCONFIG device. Each new queue space extent uses an additional entry in the VTOC (a maximum of 100 entries are available). The queue manager names the extents such that they can be quickly identified and associated with the queue space.
qchange [queue_name [out-of-order [retries [delay [high [low [cmd]]]]]]]
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. 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. 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 down to 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. 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 it does not exist, the message is dropped. The queue ordering values for the queue cannot be changed.
qchangeprio (qcp) [-y] [newpriority]
qset command and the selection criteria for limiting the messages to be updated are set using the qscan command. If no selection criteria are set, then all messages on the queue will be changed: confirmation is requested before this is done unless the -y option is specified. It is recommended that the qlist command be executed to see what messages will be modified (this reduces typographical errors). The newpriority value specifies the new priority which will be used when the message(s) are forwarded for processing. It must be in the range 1 to 100, inclusive. If not provided on the command line, the program will prompt for it.
qchangequeue (qcq) [-y] [newqueue]
qset command and the selection criteria for limiting the messages to be moved are set using the qscan command. If no selection criteria are set, then all messages on the queue will be moved: confirmation is requested before this is done unless the -y option is specified. It is recommended that the qlist command be executed to see what messages will be moved (this reduces typographical errors). The newqueue value specifies the new queue name to which the message(s) will be moved. If not provided on the command line, the program will prompt for it.
qchangetime (qct) [-y] [newtime]
qset command and the selection criteria for limiting the messages to be updated are set using the qscan command. If no selection criteria are set, then all messages on the queue will be changed: confirmation is requested before this is done unless the -y option is specified. It is recommended that the qlist command be executed to see what messages will be modified (this reduces typographical errors). The newtime value can be either relative to the current time or an absolute value. If not provided on the command line, the program will prompt for it. The format of a relative onetime is +seconds> where seconds> is the number of seconds from now that the message is to be executed (0 implies immediately). The format of an absolute newtime is YY[MM[DD[HH[MM[SS]]]]] which is described in qscan.
qclose
qcommittrans (qcommit) [-y] [tranindex]
tranindex. The program will prompt for the transaction index if not specified on the command line. If the transaction is known to be decided and the decision was to abort, qcommittrans will fail. The index is taken from the previous execution of the qprinttrans command. Confirmation is requested unless the -y option is specified. This command should be used with care.
qcreate (qcr) [queue_name [qorder [out-of-order [retries [delay
[high [low [cmd]]]]]]]]
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. The queue ordering values are fifo, lifo, priority and time. When specifying the queue ordering, the most significant sort value must be specified first, followed by the next most significant sort value, etc.; fifo or lifo can only be specified 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. 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. 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. 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 it does not exist, the message is dropped.
qdeletemsg (qdltm) [-y]
qset command and the selection criteria for limiting the messages to be deleted are set using the qscan command. If no selection criteria are set, then all messages on the queue will be deleted: confirmation is requested before this is done. It is recommended that the qlist command be executed to see what messages will be deleted (this reduces typographical errors). This command prompts for confirmation unless the -y option is specified.
qdestroy (qds) [{ -p | -f }] [-y] [queue_name]
-p option can be specified to "purge" any messages from the queue and destroy it, if no processes are attached to the queue space. The -f option can be specified to "force" deletion of a queue, even if messages or processes are attached to the queue space; if a message is currently involved in a transaction the command fails and an error is written to userlog. This command prompts for confirmation before proceeding unless the -y option is specified.
qinfo [queue_name]
qlist (ql)
qset command and the selection criteria for limiting the messages to be listed are set using the qscan command. If no selection criteria are set, then all messages on the queue will be listed. For each message selected, the message identifier is printed. The scheduled processing time is printed if execution time is among the sort criteria for the queue, and for messages that have a scheduled retry time (due to rollback of a transaction). The correlation identifier is printed if present and if verbose mode is on.
qopen [queue_space_name]
qmadmin, it is closed.
qprinttrans (qpt)
qaborttrans or qcommittrans, and transaction status are printed.
qscan [{ [-t time1[-time2]] [-p priority1[-priority2]] [-m msgid] -i corrid] | none }]
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 (fpr example, -t 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, 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 like 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 "hello20world"). 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 like 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 "my20id20value").
set [queue_name]
qchangeprio, qchangequeue, qchangetime, qdeletemsg, and qlist commands. Executing this command with no argument prints the current queue name.
qsize [pages [queues [transactions [processes [messages]]]]]
pages, queues, concurrent transactions, processes, and queued messages. If the values are not provided on the command line, the program will prompt for them. The number of system semaphores needed will also be printed.
qspacechange (qspch) [queue_space_name [ipckey [trans [procs
[messages [errorq [inityn [blocking]]]]]]
qspacecreate. If the specified queue space is open in qmadmin, it will be closed. To add new extents, qaddext must be used. The number of queues cannot be modified.
qspacecreate (qspc) [queue_space_name [ipckey [pages [queues [trans
[procs [messages [errorq [inityn [blocking]]]]]]]]
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 will be rounded down to the nearest multiple of bits-per-byte divided by 2 (normally 4). 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 done as a multiple of the disk page size as specified by the blocking factor.
qspacedestroy (qspds) [-f] [-y] [queue_space_name]
qmadmin, it will be closed. By default, an error is returned if processes are attached to the queue space or if requests exist on any queues in the queue space. See the qdestroy command for destroying queues that contain requests. The -f option can be specified to "force" deletion of all queues, even if they may have messages or processes are attached to the queue space. This command prompts for confirmation before proceeding unless the -y option is specified.
qspacelist (qspl) [queue_space_name]
qspacecreate or as they were last changed with qspacechange), the sizes for all queue space extents are printed.
quit (q)
verbose (v) [{off | on}]
off.
! shellcommand
shellcommand.
!!
# [text]
<CR>
The following sequence shows how to set up a queue.
$ QMCONFIG=/dev/rawfs qmadmin
qmadmin - Copyright (c) 1987 ATT; 1991 USL. All rights reserved.
QMCONFIG=/dev/rawfs
# create the list of devices on which the queue space
# can exist; specify two devices, 80000 and 600
# blocks, respectively
# NOTE: the first one will actually contain the device list
#
# create first device on a raw slice
#
> crdl /dev/rawfs 0 80000
Created device /dev/rawfs, offset 0, size 80000 on /dev/rawfs
#
# create another device on a UNIX file
#
> crdl /home/queues/FS 0 600
Created device /home/queues/FS, offset 0, size 600 on /dev/rawfs
#
# if you want a list of the device list
#
> v Verbose mode is now on
> lidl
universal device index. 0:
name: /dev/rawfs
start: 0
size: 20000
free space map(1 entry used 47 available):
size[1]: 79974 addr[1]: 26
universal device index. 1:
name: /home/queues/FS
start: 0
size: 600
free space map(1 entry used 47 available):
size[1]: 600 addr[1]: 0
#
# create a queue space
#
> qspacecreate
Queue space name: myqueuespace
IPC Key for queue space: 42000
Size of queue space in disk pages: 50000
Number of queues in queue space: 30
Number of concurrent transactions in queue space: 20
Number of concurrent processes in queue space: 30
Number of messages in queue space: 20000
Error queue name: ERRORQ
Initialize extents (y, n [default=n]): y
Blocking factor [default=16]: 16
....................
#
# open queue space
#
> qopen myqueuespace
#
# use queue space defaults for queue
> qcreate
Queue name: service1
queue order (priority, time, fifo, lifo): fifo
out-of-ordering enqueuing (top, msgid, [default=none]): top,msgid
retries [default=0]: 1
retry delay in seconds [default=0]: 30
High limit for queue capacity warning (b for bytes used, B for blocks used,
% for percent used, m for messages [default=100%]): 100m
Reset (low) limit for queue capacity warning [default=0m]: 50
queue capacity command: /usr/app/bin/mailadmin myqueuespace service1
#
# get out of the program
#
> q
The administrator for the queue must be the same as the BEA TUXEDO administrator. The device on which the queue resides must be owned by the administrator and qmadmin can only be run as the administrator for the queue. All IPC resources allocated for the queue will be owned by the queue administrator and will be created with mode 0600.
qmadmin is supported as a BEA TUXEDO-supplied administrative tool on UNIX operating systems only. It cannot be run from a workstation.
Administering the BEA TUXEDO System