PURPOSE
qmadmin - Queue manager administration program
SYNOPSIS
[QMCONFIG=<device>] qmadmin [<device>]
DESCRIPTION
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.
qmadmin COMMANDS
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
the TUXEDO Administrator's Guide.
- crdl [device [offset [size]]]
- Create an entry in the universal device list. Note: The
first entry in the device list must correspond to the
device that is pointed to by 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 /dev/rawfs 0 500 and then allocate /dev/rawfs
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]
- Destroy an entry found in the universal device list. The 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}]
- Echo input command lines when set to 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}]
- Print help messages. If 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]
- Print the universal device list. For each device the
following is listed: the index, the name, the starting
block, and the number of blocks on the device. In verbose
mode, a map is printed that shows free space (starting
address and size of free space). If dlindex is
specified, then only the information for that device list
entry is printed.
- livtoc
- Prints information for all 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}]
- Paginate output. If no option is given, then the current
setting will be toggled, and the new setting is printed.
The initial setting is on, unless either standard input
or standard output is a non-terminal device. Pagination
may only be turned on when both standard input and
standard output are terminal devices. The shell
environment variable 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]
- Heuristically abort the precommitted transaction
associated with the specified transaction index, 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]]
- Add an extent to the queue space. The queue space must
not be active (no processes can be attached to the queue
space). If not specified on the command line, the program
prompts for the queue space name and the number of
additional physical pages to allocate for the queue
space. If the specified queue space is open in 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]]]]]]]
- Create a queue in the currently open queue space. The
arguments may be given on the command line or the program
will prompt for them: the queue name, whether or not
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; 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]
- This command can be used to change the message priority
for messages on a queue that allows priority as an
ordering criterion. The queue that is affected is set
using the 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]
- This command can be used to move messages to a different
queue within the same queue space. The queue from which
messages are moved is set using the 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]
- This command can be used to change the execution time for
messages on a queue that allows time as an ordering
criterion. The queue that is affected is set using the 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 newtime
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
- Close the currently open queue space.
- qcommittrans (qcommit) [-y]
[tranindex]
- Heuristically commit the precommitted transaction
associated with the specified transaction index 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]]]]]]]]
- Create a queue in the currently open queue space. The
arguments may be given on the command line or the program
will prompt for them: the queue name, the queue ordering
(fifo or lifo, by priority, by time); whether or not
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; 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]
- This command can be used to delete messages from a queue.
The queue that is affected is set using the 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]
- Destroy the named queue. By default, an error is returned
if requests exist on the queue or a process is attached
to the queue space. The -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]
- List information for associated queue or for all queues.
This command lists the number of messages on the
specified queue or all queues if no argument is given,
and the amount of space used by the messages associated
with the queue. In verbose mode, this command also lists
the queue creation parameters for each queue.
- qlist (ql)
- This command lists messages on a queue. The queue that is
affected is set using the 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]
- Open and initialize the internal structures for the
specified queue space. If not provided on the command
line, the program will prompt for it. If a queue space is
already opened in qmadmin, it is closed.
- qprinttrans (qpt)
- Print transaction table information for currently
outstanding transactions. The transaction identifier, an
index used for aborting or committing transactions with qaborttrans
or qcommittrans, and transaction status are
printed.
- qscan [{ [-t time1[-time2]]
[-p priority1[-priority2]] [-m
msgid] [-i corrid] | 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 (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
"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 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 "my\20id\20value").
- qset [queue_name]
- This command sets the queue name that is used for the qchangeprio,
qchangequeue, qchangetime, qdeletemsg, and qlist
commands. Executing this command with no argument prints
the current queue name.
- qsize [pages [queues [transactions
[processes [messages]]]]]
- Compute the size of shared memory needed for a queue
space with the specified size in 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]]]]]]
- Change the parameters for a queue space. The queue space
must not be active (no processes can be attached to the
queue space). If not provided on the command line, the
program will prompt for the information. The values are
described in 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]]]]]]]]
- Create a queue space for queued messages. If not provided
on the command line, the program will prompt for the
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 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]
- Destroy the named queue space. If not provided on the
command line, the program will prompt for it. If the
specified queue space is open in 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]
- List the creation parameters for the queue space. If not
specified on the command line, the program will prompt
for it. If a queue space name is not entered, then the
parameters for the currently open queue space are printed
(an error occurs if a queue space is not open and a value
is not entered). In addition to printing the values for
the queue space (as set either when creating the queue
space with qspacecreate or as they were last
changed with qspacechange), the sizes for all
queue space extents are printed.
- quit (q)
- Terminate the session.
- verbose (v) [{off | on}]
- Produce output in verbose mode. If no option is given,
then the current setting will be toggled, and the new
setting is printed. The initial setting is off.
- ! shellcommand
- Escape to shell and execute shellcommand.
- !!
- Repeat previous shell command.
- # [text]
- Lines beginning with "#" are comment lines and
are ignored.
- <CR>
- Repeat the last command.
EXAMPLE
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
SECURITY
The administrator for the queue must be the same as
the TUXEDO System/T 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.
PORTABILITY
qmadmin is supported as a TUXEDO
System/T-supplied administrative tool on UNIX operating
systems only. It cannot be run from a workstation.
SEE ALSO
BEA TUXEDO
Administrator's Guide
BEA TUXEDO /Q
Guide