Reference Guide

     Previous  Next    Open TOC in new window    View as PDF - New Window  Get Adobe Reader - New Window
Content starts here

Oracle Tuxedo Message Queue Command Reference

Table 1 Oracle Tuxedo Message Queue UBB Commands
Name
Description
Used to construct an OTMQ client module.
Used to construct an OTMQ load module which can run as an Oracle Tuxedo application server.
Utility used to upgrade/migrate existing /Q Qspace to OTMQ Qspace.
Queue manager administration program

 


buildqclient

Name

buildqclient—Used to construct an OTMQ client module.

Synopsis

buildqclient [ -v ] [ {-r rmname | -w } ] [ -o name] [ -f firstfiles] [ -l lastfiles]

Description

buildqclient is used to construct an OTMQ client module. The command combines the files supplied by the -f and -l options with the standard Oracle Tuxedo ATMI libraries to form a load module. The load module is built by buildqclient using the default C language compilation command defined for the operating system in use. The default C language compilation command for the UNIX system is the cc command described in UNIX system reference manuals.

It takes the following options:

-v

Specifies that buildqclient should work in verbose mode. In particular, it writes the compilation command to its standard output.

-w

Specifies that the client is to be built using the workstation libraries. The default is to build a native client if both native mode and workstation mode libraries are available. This option cannot be used with the -r option.

-r rmname

Specifies the resource manager associated with this client. The value rmname must appear in the resource manager table located in $TUXDIR/udataobj/RM. Each line in this file is of the form: rmname:rmstructure_name:library_names.
Using the rmname value, the entry in $TUXDIR/udataobj/RM is used to include the associated libraries for the resource manager automatically and to set up the interface between the transaction manager and resource manager properly. Other values can be specified as they are added to the resource manager table. If the -r option is not specified, the default is that the client is not associated with a resource manager.

-o name

Specifies the filename of the output load module. If not supplied, the load module is named a.out.

-f firstfiles

Specifies one or more user files to be included in the compilation and link edit phases of buildqclient first, before the Oracle Tuxedo ATMI libraries and OTMQ libraries. If more than one file is specified, filenames must be separated by white space and the entire list must be enclosed in quotation marks. This option may be specified multiple times. The CFLAGS environment variable, described below, should be used to include any compiler options and their arguments.

-l lastfiles

Specifies one or more user files to be included in the compilation and link edit phases of buildqclient last, after the Oracle Tuxedo ATMI libraries and OTMQ libraries. If more than one file is specified, filenames must be separated by white space and the entire list must be enclosed in quotation marks. This option may be specified multiple times.

Environment Variables

TUXDIR

buildclient uses the environment variable TUXDIR to find the Oracle Tuxedo ATMI libraries and include files to use during compilation of the client process.

CC

buildqclient normally uses the default C language compilation command to produce the client executable. The default C language compilation command is defined for each supported operating system platform and is defined as cc(1) for UNIX system. In order to allow for the specification of an alternate compiler, buildqclient checks for the existence of an environment variable named CC. If CC does not exist in the buildqclient environment, or if it is the string "", buildqclient will use the default C language compiler. If CC does exist in the environment, its value is taken to be the name of the compiler to be executed.

CFLAGS

The environment variable CFLAGS is taken to contain a set of arguments to be passed as part of the compiler command line. This is in addition to the command line option "-I${TUXDIR}/include" passed automatically by buildqclient. If CFLAGS does not exist in buildqclient's environment, or if it is the string "", no compiler command line arguments are added by buildqclient.

LD_LIBRARY_PATH (UNIX systems)

The environment variable LD_LIBRARY_PATH indicates which directories contain shared objects in addition to the Oracle Tuxedo system shared objects. Some UNIX systems require different environment variables: for HP-UX systems, use the SHLIB_PATH environment variable; for AIX, use LIBPATH.

LIB (Windows NT systems)

Indicates a list of directories within which to find libraries. A semicolon (;) is used to separate the list of directories.

 


buildqserver

Name

buildqserver—Used to construct an OTMQ load module which can run as a Tuxedo application server.

Synopsis

buildqserver [-s { @filename | service[,service . . . ] [:func]| :func } ] [-v] [-o outfile] [-f firstfiles] [-l lastfiles] [-r rmname] [-t]

Description

buildqserver is used to construct an OTMQ load module which can run as a Tuxedo application server. The command combines the files supplied by the -f and -l options with the standard server main routine and the standard OTMQ libraries to form a load module. The load module is built by the cc command, which buildqserver invokes.

It takes the following options:

-v

Specifies that buildqserver should work in verbose mode. In particular, it writes the compilation command to its standard output.t.

-o outfile

Specifies the name of the file the output load module is to have. If not supplied, the load module is named SERVER.

-f firstfiles

Specifies one or more user files to be included in the compilation and link edit phases of buildqserver first, before the Oracle Tuxedo ATMI libraries and OTMQ libraries. If more than one file is specified, filenames must be separated by white space and the entire list must be enclosed in quotation marks. This option may be specified multiple times. The CFLAGS environment variable, described below, should be used to include any compiler options and their arguments.

-l lastfiles

Specifies one or more user files to be included in the compilation and link edit phases of buildqserver last, after the Oracle Tuxedo ATMI libraries and OTMQ libraries. If more than one file is specified, filenames must be separated by white space and the entire list must be enclosed in quotation marks. This option may be specified multiple times.

-r rmname

Specifies the resource manager associated with this server. The value rmname must appear in the resource manager table located in $TUXDIR/udataobj/RM. Each line in this file is of the form:
rmname:rmstructure_name:library_names. Using the rmname value, the entry in $TUXDIR/udataobj/RM is used to include the associated libraries for the resource manager automatically and to set up the interface between the transaction manager and resource manager properly. Other values can be specified as they are added to the resource manager table. If the -r option is not specified, the default is to use the null resource manager.

-s { @filename | service[,service...][:func] | :func }

Specifies the names of services that can be advertised when the server is booted. Service names (and implicit function names) must be less than or equal to 127 characters in length. An explicit function name (that is, a name specified after a colon) can be up to 128 characters in length. Names longer than these limits are truncated with a warning message. When retrieved by tmadmin or TM_MIB, only the first 15 characters of a name are displayed. All functions that can be associated with a service must be specified with this option. In the most common case, a service is performed by a function that carries the same name; that is, the x service is performed by function x. For example, the following specification builds the associated server with services x, y, and z, each to be processed by a function of the same name: "-s x,y,z".
In other cases, a service (or several services) may be performed by a function of a different name. The following specification builds the associated server with services x, y, and z, each to be processed by the function abc: "-s x,y,z:abc". Spaces are not allowed between commas. Function name is preceded by a colon. In another case, the service name may not be known until run time. Any function that can have a service associated with it must be specified to buildqserver. To specify a function that can have a service name mapped to it, put a colon in front of the function name. For example, the following specification builds the server with a function pqr, which can have a service association. tpadvertise could be used to map a service name to the pqr function. "-s :pqr". A filename can be specified with the -s option by prefacing the filename with the '@' character. Each line of this file is treated as an argument to the -s option. You may put comments in this file. All comments must start with the '#' character. This file can be used to specify all the functions in the server that may have services mapped to them. The -s option may appear several times. Note that services beginning with the '.' character are reserved for system use, and buildqserver will fail if the -s option is used to include such a service in the server.

-t

Specifies multithreading. If you want your servers to be multithreaded, this option is mandatory. If this option is not specified and you try to boot a server with a configuration file in which the value of MAXDISPATCHTRHREADS is greater than 1, a warning message is printed in the user log and the server reverts to single-threaded operation.
The purpose of this option is to prevent an administrator from trying to boot, as a multithreaded server, a server that is not programmed in a thread-safe manner.

Environment Variables

TUXDIR

buildclient uses the environment variable TUXDIR to find the Oracle Tuxedo ATMI libraries and include files to use during compilation of the client process.

CC

buildqclient normally uses the default C language compilation command to produce the client executable. The default C language compilation command is defined for each supported operating system platform and is defined as cc(1) for UNIX system. In order to allow for the specification of an alternate compiler, buildqclient checks for the existence of an environment variable named CC. If CC does not exist in thr buildqclient environment, or if it is the string "", buildqclient will use the default C language compiler. If CC does exist in the environment, its value is taken to be the name of the compiler to be executed.

CFLAGS

The environment variable CFLAGS is taken to contain a set of arguments to be passed as part of the compiler command line. This is in addition to the command line option "-I${TUXDIR}/include" passed automatically by buildqclient. If CFLAGS does not exist in buildqclient's environment, or if it is the string "", no compiler command line arguments are added by buildqclient.

LD_LIBRARY_PATH (UNIX systems)

The environment variable LD_LIBRARY_PATH indicates which directories contain shared objects in addition to the Oracle Tuxedo system shared objects. Some UNIX systems require different environment variables: for HP-UX systems, use the SHLIB_PATH environment variable; for AIX, use LIBPATH.

LIB (Windows NT systems)

Indicates a list of directories within which to find libraries. A semicolon (;) is used to separate the list of directories.

 


ConvertQSPACE

Name

ConvertQSPACE—Queue manager administration program.

Synopsis

ConvertQSPACE -d device -s qspace -i ipckey -h

Description

Upgrade to OTMQ to have many new benefits, saying faster enque/deque speed, asynch communication, recovery message storage, online and/or offline trade, pub/sub mode, auto failed message handling, and so on.

This utility allows you toupgrade existed /Q Qspace to OTMQ Qspace, so that the data can be migrated smoothly too. The existing /Q queues is mapped to unlimited queues to keep consistency with old behavior.

Notes: Pay close attention to the following:

It takes the following options:

-d device

Specifies the name of new OTMQ device. If existed, we will try to reuse it unless it has been already opened.

-s qspace

Specifies the name of the /Q Qspace to be converted to OTMQ Qspace.

-i ipckey

Specifies the ipc key for the new OTMQ Qspace, which cannot be the same as the original /Q Qspace ipc key.

-h

Prints this usage.

 


tmqadmin

Name

tmqadmin—Queue manager administration program.

Synopsis

[QMCONFIG=<device>] tmqadmin [<device>]

Description

With the commands listed in this entry, tmqadmin 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 Oracle 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, tmqadmin 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 tmqadmin 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.

tmqadmin 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 tmqadmin commands is paginated according to the pagination command in use (see the paginate subcommand below).

When tmqadmin is initially entered, no queue space is opened. To create a queue space, run qspacecreate; to open it, run qopen. The qaborttrans, qclear, 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.

It takes the following commands:

General Commands

! shellcommand

Escapes to shell and execute shellcommand.

!!

Repeats previous shell command.

# [text]

Lines beginning with # are comment lines and are ignored.

<CR>

Repeats the last command.

echo (e) [{off | on}]

Echoes input command lines when set to on. If no option is given, the current setting is toggled, and the new setting is printed. The initial setting is off.

help (h) [{command | all}]

Prints help messages. If a command is specified, the abbreviation, arguments, and description for that command are printed. The all argument causes a description of all commands to be displayed.
If no arguments are specified on the command line, the syntax of all commands is displayed.

paginate (page) [{off|on}]

Paginates output. If no option is given, the current setting is 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 be turned on only when both standard input and standard output are terminal devices.
The default paging command is the pager indigenous to the native operating system environment. The command pg, for example, is the default command on the UNIX operating system. The shell environment variable PAGER may be used to override the default command used for paging output.

quit (q)

Terminates the session.

verbose (v) [{off | on}]

Produces output in verbose mode. If no option is given, the current setting is toggled, and the new setting is printed. The initial setting is off.

Queue Space Commands

chdl [dlindex [newdevice]]

Changes 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 prompts for it if it is not provided on the command line.
The second argument is the new device name. If a device name is 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. Use this command cautiously; files and data are not accessible via the old name after the device name is changed. For more information about printing the Universal Device List (UDL) and Volume Table of Contents (VTOC), see Administering an Oracle Tuxedo Application at Run Time.

crdl [device [offset [size]]]

Creates an entry in the universal device list. Note: The first entry in the device list must correspond to the device that is referenced by QMCONFIG and must have an offset of 0. If arguments are not provided on the command line, the program prompts 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. You can, for example, allocate /app/queues/myspace 0 500, and then allocate /app/queues/myspace 1000 500, for a total of 1000 blocks allocated with blocks 500 through 999 not being used. 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.
For OTMQ, this command can support large size. The max value of this command is 2147483647, the basic unit is block size.

dsdl [-y] [dlindex]

Destroys 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 it is not provided on the command line, the program prompts for it. Entry 0 cannot be removed until all VTOC files and other device list entries are destroyed. (Because entry 0 contains the device that 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.

ipcrm [-f] [-y] [queue_space_name]

Removes the IPC data structures used for the specified queue space. If a queue space name is not provided on the command line, the program prompts for one. If the specified queue space is open in tmqadmin, 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.
tmqadmin 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 other processes are attached. This command prompts for confirmation before execution if the -f option is specified, unless the -y option is specified. All non-persistent messages in the specified queue space are permanently lost when this command completes successfully.

ipcs [queue_space_name]

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 a queue space name is not provided on the command line, the program prompts for one.

lidl [dlindex]

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

qaddext [queue_space_name [pages]]

Adds an extent to the queue space. The queue space must not be active (no processes can be attached to the queue space). If a queue space name and the number of additional physical pages to allocate for the queue space are not specified on the command line, the program prompts for them. If the specified queue space is open in tmqadmin, it will be closed. The number of physical pages is rounded down to the nearest multiple of four pages (see qspacecreate for clarification and examples). Space is 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 identified quickly and associated with the queue space. All non-persistent messages in the specified queue space are permanently lost when this command completes successfully.

qclose

Closes the currently open queue space. All non-persistent messages in the specified queue space are permanently lost when this command completes successfully.

qopen [queue_space_name]

Opens and initializes the internal structures for the specified queue space. If a queue space is not specified on the command line, the program prompts for it. If a queue space is already open in tmqadmin, it is closed.

qsize [-A actions] [-H handles] [-C cursors] [ -O owners] [-Q tmp_queues] [-f filter_memory] [-n nonpersistent_msg_memory[b,B]] [-o overflow_memory][pages [queues [transactions [processes [messages]]]]]

Computes 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 prompts for them. The number of system semaphores needed is also printed. Valid values for the remaining options are described in the qspacecreate option.

qspacechange (qspch) [-A actions] [-C cursors] [-H handles] [-O owners] [-Q temp_queues] [-f filter_memory] [-T first_temp_queue_No.] [-N queue_alias_file ] [-n nonpersistent_msg_memory[b,B]] [-o overflow_memory] [queue_space_name [ipckey [trans [ procs [ messages [errorq [inityn [blocking]]]]]]]

Changes the parameters for a queue space. The queue space must not be active (that is, no processes can be attached to it). If the required information is not provided on the command line, the program prompts for it. Valid values are described in the qspacecreate section of this page. If the specified queue space is open in tmqadmin, it is closed. To add new extents, qaddext must be used. The number of queues cannot be modified.

qspacecreate (qspc) [-A actions] [-n nonpersistent_msg_memory[b,B]] [-o overflow_memory][-C max cusor][-O max owner][-f maximum filter memory size][-H max handle] [-Q qNum] [-T first temp queue] [-L max linkdriver table][-R max linkdirver route table][-N alias file][queue_space_name [ipckey [pages [queues [trans [procs [messages [errorq [inityn [blocking [SAF_and_DQF_queue [PCJ_journaling [Dead_Letter_Journal ]]]]]]]]]]]]]

Creates 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; the blocking factor for doing queue space initialization and warm start disk input/output; SAF and DQF queue to create or not (by defaut, it is); PCJ Journaling to enable or not (by default, it is); and Dead letter Journal to enable or not (by default it is).
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,' 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, the file will be initialized if it is 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.
SAF (Store And Forward) and DQF (Destination Queue File) are message recovery journals respectively on the local system and on remote system. If SAF and DQF queues are created by default, the recoverable delivery feature using SAF and DQF are enabled.
PCJ (Post Confirmation Journal) stores successfully confirmed recoverable messages. PCJ is created by default as permanent active queue.
DLJ ((Dead Letter Journal) provides disk storage for messages that could not be stored for automatic recovery. DLJ is created by default as permanent active queue.
- A actions
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.
-n nonpersistent_msg_memory
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. The [bB] max value is 2147483647, 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.
- o overflow_memory
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.
-C
Specifies the maximum cusor.
-f
Specifies the maximum filter memory size. If not specified, the default value 32768 is used.
-H
Specifies the maximum handle.
-Q
Specifies the maximum temporary queues. If not specified, the default value 100 is used.
-T
Specifies the first temporary queue. If not specified, the default value 200 is used.
-L
Specifies themaximum linkdriver table. If not specified, the default value 200 is used.
-R
Specifies the maximum linkdriver route table. If not specified, the default value 200 is used.

qspacedestroy (qspds) [-f] [-y] [queue_space_name]

Destroys 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 tmqadmin, 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. All non-persistent messages in the specified queue space are lost when this command completes successfully

qspacelist [queue_space_name]

Lists the creation parameters for the queue space. If it is not specified on the command line, the program will prompt for it. If a queue space name is not entered, 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 when creating the queue space with qspacecreate or when they were last changed with qspacechange), this command shows the sizes for all queue space extents. It also shows the amount of system-reserved memory as well as the total amount of configured shared memory. The amount of memory allocated for shared memory resources may not match the amount requested when the amount of memory is requested in bytes (b); see the -n nonpersistent_msg_memory option in qspacecreate for clarification and examples.

Queue Commands

qchange [-d default_delivery_policy] [-n mhigh,mlow,mcmd][-e default_relative_expiration_time][-t default_queue_property] [-o owner] [-a PERM_ACTIVE] [-c confirm_style] [-f][queue_name [qorder [out-of-order [retries [delay [high [low [cmd]]]]]]]]

Modifies 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. (For more information, see qspacecreate and qspacechange for 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 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.
The valid values for the -t "type" option are "PQ", "SQ" and "MRQ". The default value is "unlimited queue".
The -o "owner" option is used for secondary queues. And defines the primary queue with which this queue is to be associated. The valid values for it is primary queue name.
The valid values for the -a "active" option are "Y" or "N". The default value is "N". This is to define if the queue is permanent active. If yes, then the queue always can receive and store message unless the quota is exceeded. If not, the queue cannot receive and store message before it is attached, and will report invalid queue in the sender side. This feature doesn't make impact for MRQ and unlimited queue(inherited from /Q).
-c [confirm style]
Set queue property of confirm style, the valid values for -c "confirm style" option are EO ( means confirm un-order) and II (implicit confirm).
-f:
Some queue name are reserved for internal use, which will be prevented by qcreate: 74-76,90-100,150-199,4000-6000, unless the -f parameter is specified.
When create these internal queue name by qcreate -f or MIB, warning is given in ULOG.
-e[exptime]
The default expiration time specified by -e option does not take effect for recoverable message (SAF/DQF/CONF). Instead, the SAF/DQF queue default expiration time (none by default) takes effect.
-q [nhigh[m/b/a/n],nlow,ncmd]
If the -q 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.

qclear [-y]

Clears attached client information on a queue and resets the queue to unattached status. The queue is specified using the qset command.
This command prompts for confirmation unless the '-y' option is specified.

qcreate (qcr) [-d default_delivery_policy] [-n mhigh,mlow,mcmd][-e default_relative_expiration_time][-t default_queue_property] [-o owner] [-a PERM_ACTIVE] [-c confirm_style] [-f][queue_name [qorder [out-of-order [retries [delay [ high [ low [ cmd]]]]]]]]

Creates 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, 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.
qcreate supports the following options:
-d
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.
-n
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.
-e default_relative_expiration_time
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.
-t "type"
The valid values for the -t "type" option are PQ (primary queue), SQ (secondary queue) and MRQ (MRQ). The default value is "unlimited queue".
-o "owner"
is used for secondary queues. And defines the primary queue with which this queue is to be associated. The valid values for it is primary queue's name.
The valid values for the -a "active" option are "Y" or "N".
The default value is "N". This is to define if the queue is permanent active. If yes, then the queue always can receive and store message unless the quota is exceeded. If not, the queue cannot receive and store message before it is attached, and will report invalid queue in the sender side. This feature doesn't make impact for MRQ and unlimited queue(inherited from /Q).
c [confirm style]
Set queue property of confirm style, the valid values for -c "confirm style" option are EO (confirm un-order), II (implicit confirm).
-f:
Some queue name are reserved for internal use, which will be prevented by qcreate: 74-76,90-100,150-199,4000-6000, unless the -f parameter is specified.
When create these internal queue name by qcreate -f or MIB, warning is given in ULOG.
-e[exptime]
The default expiration time specified by -e option does not take effect for recoverable message (SAF/DQF/CONF). Instead, the default expiration time of SAF/DQF queue (none by default) will take effect.
-q [nhigh[m/b/a/n],nlow,ncmd]
If the -q 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.

qdestroy (qds) [{ -p | -f }] [-y] [queue_name]

Destroys 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 the userlog. This command prompts for confirmation before proceeding unless the -y option is specified.

qinfo [queue_name]

Lists information for associated queue or for all queues. This command lists the following: the number of messages on the specified queue (or all queues if no argument is given); the amount of space used by the messages associated with the queue (both persistent and non-persistent); the number of messages being delivered persistently and non-persistently; the total number of messages in the specified queues, and the amount of space used by the persistent and non-persistent messages. In verbose mode, this command also lists the queue creation parameters for each queue, the default expiration for the queue (if any), the sort criteria, and the default delivery policy for the queue.

Message Commands

qchangeexp (qce) -y [newtime]

Changes 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, 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 Oracle Tuxedo ATMI 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 Oracle Tuxedo ATMI 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.

qchangeprio (qcp) [-y] [newpriority]

Changes the priority for 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 updated are set using the qscan command.
If no selection criteria are set, all messages on the queue are 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]

Moves 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, all messages on the queue are 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 name of the queue to which messages will be moved. If newqueue is not specified on the command line, the program prompts for it. The delivery quality of service of a message is not changed to match the default delivery policy of newqueue.
When messages with an expiration time are moved, the expiration time is considered an absolute expiration time in the new queue, even if it was previously specified as a relative expiration time.

qchangetime (qct) [-y] [newtime]

Changes the message availability time for messages on a queue. The queue is specified using the qset command. The selection criteria for limiting the messages to be updated are set using the qscan command.
If no selection criteria are set, all messages on the queue are 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]]]]], as described in qscan.

qdeletemsg (qdltm) [-y]

selection criteria for limiting the messages to be deleted are set using the qscan command. If no selection criteria are set, all messages on the queue are 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.

qlist (ql)

Lists messages on a queue. The queue is specified using the qset command. The selection criteria for limiting the messages to be listed are set using the qscan command. If no selection criteria are set, all messages on the queue will be listed.
For each message selected, the message identifier is printed along with the message priority, the number of retries already attempted, message length, delivery quality of service, the quality of service for any replies, and the expiration time (if any). The message availability time is printed if one is associated with the message, or for messages that have a scheduled retry time (due to rollback of a transaction). The correlation identifier is printed if present and verbose mode is on.

qscan [{ [-t time1[-time2]] [-p priority1[-priority2]] [-m msgid] [-i corrid][-d delivery_mode] [-e time1[-time2]] | none }]

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

qset [queue_name]

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.

Transaction Commands

qaborttrans (qabort) [-y] [tranindex]

Heuristically aborts the precommitted transaction associated with the specified transaction index, tranindex. If the transaction index is not specified on the command line, the program prompts for it. If the transaction is known to be decided and the decision was to commit, qaborttrans fails.
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.

qcommittrans (qcommit) [-y] [tranindex]

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

qprinttrans (qpt)

Prints transaction table information for currently outstanding transactions. The information includes the transaction identifier, an index used for aborting or committing transactions with qaborttrans or qcommittrans, and the transaction status.

  Back to Top       Previous  Next