qmadmin(1)

Name

qmadmin—Queue manager administration program.

Synopsis

[QMCONFIG=<device>] qmadmin [<device>]

Description

With the commands listed in this entry, qmadmin supports the creation, inspection, and modification of message queues. The universal device list (UDL) maps the physical storage space on a machine on which the BEA Tuxedo ATMI system is run. An entry in the UDL points to the disk space in which the queues and messages of a queue space are stored. The name of the device (file) on which the UDL resides (or will reside) for the queue space may be specified either as a command line argument or via the environment variable QMCONFIG. If both are specified, the command option is used.

As a system-provided command, qmadmin does not undergo normal initialization, so it does not pick up the value of ULOGPFX from the UBBCONFIG file. 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 in which 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 preceded with a backslash. Commands prompt for required 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. Commands do not prompt for information on optional parameters.

A user can exit the program by entering q or <CTRL-d> when prompted for a command. Output from a command may be terminated by pressing 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 qmadmin is initially entered, no queue space is opened. To create a queue space, run qspacecreate; to open it, run qopen. The qaborttrans, qclose, qchangeprio, qchangequeue, qchangetime, qchangeexptime, qcommittrans, qchange, qcreate, qdeletemsg, qinfo, qlist, qprinttrans and qset commands can be executed only when a queue space is open.

The following table lists the qmadmin commands grouped by functional type.

Command Type	Command	Purpose
General
	echo	Echoes input command lines
	help	Prints help messages
	paginate	Paginates output
	quit	Terminates the session
	verbose	Produces output in verbose mode
	! shellcommand	Escapes to shell and executes shellcommand
	!!	Repeats previous shell command
	#	Indicates comment lines
	<CR>	Repeats the last command
Queue Space
	chdl	Changes the name for a universal device list entry
	crdl	Creates an entry in the universal device list
	dsdl	Destroys an entry found in the universal device list
	ipcrm	Removes IPC data structures used for the queue space
	ipcs	Lists IPC data structures used for the queue space
	lidl	Prints the universal device list
	livtoc	Prints information for all VTOC table entries
	qaddext	Adds an extent to the queue space
	qclose	Closes the currently open queue space
	qopen	Opens and initializes structures for the queue space
	qsize	Computes the size of shared memory needed for a queue space
	qspacechange	Changes the parameters for a queue space
	qspacecreate	Creates a queue space for queued messages
	qspacedestroy	Destroys the named queue space
	qspacelist	Lists the creation parameters for the queue space
Queue
	qchange	Modifies a queue in the currently open queue space
	qcreate	Creates a queue in the currently open queue space
	qdestroy	Destroys the named queue
	qinfo	Lists information for associated queue or for all queues
Message
	qchangeexp	Changes the expiration time for messages on a queue
	qchangeprio	Changes the priority for messages on a queue
	qchangequeue	Moves messages to a different queue within the same queue space
	qchangetime	Changes the execution time for messages on a queue
	qdeletemsg	Deletes messages from a queue
	qlist	Lists messages on a queue
	qscan	Sets selection criteria used by other commands
	qset	Sets the queue name used by other commands
Transaction
	qaborttrans	Aborts a precommitted transaction
	qcommittrans	Commits a precommitted transaction
	qprinttrans	Prints transaction table information for outstanding transactions

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.

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 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.

Portability

qmadmin is supported on any platform on which the BEA Tuxedo ATMI server environment is supported.

Windows Standard I/O

In order to carry out a command that you have configured within a qmadmin() session, such as the qchange ... Queue capacity command, the Windows CreateProcess() function spawns a child process as a DETACHED PROCESS. This type of process does not have an associated console for standard input/output. Therefore, for instance, if you use standard command line syntax to set the qchange ... Queue capacity command to run a built-in command (such as dir or date) and then pipe or redirect the standard output to a file, the file will be empty when the command completes.

As an example of resolving this problem, suppose that for the qchange ... Queue capacity command you want to capture date information in a file using command date /t > x.out. To accomplish this task interactively, you would proceed as follows:

qmadmin
> qopen yourQspace
> qchange yourQname
> go through all the setups... the threshold queue capacity warning,
      and so on
> "Queue capacity command: " cmd /c date /t > x.out

To accomplish this task from a command file, say yourFile.cmd, you would add the command date /t > x.out to yourFile.cmd and then proceed as follows:

qmadmin
> qopen yourQspace
> qchange yourQname
> go through all the setups... the threshold queue capacity warning,
      and so on
> "Queue capacity command: " yourFile.cmd

See Also

Administering BEA Tuxedo Applications at Run Time