Detail Design: Administrative Interface
12-Sept-96
Dcecp is the interface that users and administrators use to operate
with the queuing system. We supply the new code and updated main code in
our release, so that licensees can re-make dcecp with the new queuing
support.
Access Control Lists
All operations are guarded with DCE access control lists (ACLs). As long as
one has the right permissions, he can use the following dcecp commands to
perform on queues and messages.
Permissions for a queue manager's ACL
The following permission bits are supported for the Q-mgr's ACL manager
interface:
i | queue creation
|
m | queue manager server management (enable and disable server, etc)
|
r | read queue manager attributes and status
|
c | control (change ACL)
|
t | test
|
Permissions for a queue's ACL
The following permission bits are supported for queue operations:
D | delete queue
|
M | manage queue
(enable/disable queue, modify attr., move, etc.)
|
R | read queue attributes
|
e | enqueue an element (message)
|
d | dequeue an element (message)
|
r | read message attributes
|
p | purge/delete an element (without reading data)
|
c | control (change ACL)
|
t | test
|
The upper case permission bits apply to the "queue" as a container, while
the lower case permission bits apply to all messages in the queue.
Variables
Default Queue Manager
When a user does not explicitly specify a queue manager for certain
operations that require a queue manager's name, it is assumed that he
wants to use the default queue manager.
A default queue manager can be specified by the following ways:
1. by environment variable MOS_DFLT_QUEMGR_NAME
2. by a per-host specification that is statically configured
3. by a cell wide specification that is statically configured
This also specifies the order for searching a default queue manager.
With dcecp, we also allow the user to set a variable to
specify a default queue manager: mos_default_qmgr
.
For any operations that require a queue manager and the command is
missing the queue manager specification, this variable is checked
first to see if it has been set. If so, the queue manager specified
there is used. Otherwise the above search happens.
Security Group
In order to perform mutual authentication between the user and the
queue manager, we require that the security group name that the queue
manager belongs to be given. To simply the command typing, we define
a variable: mos_qmgr_group
.
When a command is missing the group specification, "queue" commands
will first check whether this variable is set. If so, this group is
used. If this variable is not set either, the command will use one
way authentication to talk to the queue manager: it has to trust CDS
(if used), as well as the server contacted.
Message Encoded Body
When showing a message body, the encoded body (binary) cannot be
shown correctly on screen. Instead, we save it to a
variable mos_encoded_msg
in hexadecimal format.
Operations
Queue Creation
queue create queue
[-attribute attribute_list]
[ [-qmaxlength queue_max_length]
[-msgmaxsize message_max_size]
[-persistent msgpersistence|persistent|volatile
]
[-enqueue yes|no
]
[-dequeue yes|no
]
[-annotation string]
[-timeout empty_idle_timeout] ]
[-group sec_group_name]
This command creates a new queue with the given name.
If the queue name is "", a queue will be created on the default queue manager,
and the default queue manager will assign a name for the queue.
If the name is a relative name, the queue will be created on the default
queue manager with the given relative name. The complete name for the queue
(used later to reference this queue) is a junction name with the queue
manager's name followed by the relative name.
If the name is a fully qualified name, it is assumed that a junction
name is given and the name will be resolved into two parts. The first
part is taken as the queue manager's name, the second part as the
relative name for the new queue. If the second part is missing, a new
queue will be created on the queue manager with a queue manager
assigned name.
In any case, if the named queue exists, an error will return.
When a queue is first created, both enqueue and dequeue operations are
enabled. The creator can disable either one operation.
A queue has a persistency attribute. An "persistent" queue
saves all messages. A "volatile" queue never saves any
messages, sending a persistent message to such a queue will result in
an error. A "msgpersistence" queue saves only the persistent
messages. This is the default behavior if not set.
A queue has an attribute which controls how long the queue should be kept
alive when there is nothing in it before it should be deleted by the queue
manager. The default is 24 hours.
The fully qualified name of the newly created queue will be retuned.
- Permission required:
- "i" bit on the Q-mgr acl
- Options:
-
- -attribute attribute_list
-
specify the attributes in a list of {name value} pair(s).
- -qmaxlength queue_max_length
-
specify the queue maximum length in term of number of messages that
the queue can keep. "0" means an unlimited queue.
- -msgmaxsize message_max_size
-
specify the maximum message size in term of number of
bytes. "0" means unlimited.
- -persistent msgpersistence|persistent|volatile
-
specify the queue persistency. The valid values are:
- msgpersistence. Message persistence dictates. The queue saves persistent messages only.
- persistent. The queue always saves messages.
- volatile. The queue never saves any message. Sending a persistent message
to such a queue will result in an error.
- -enqueue
yes|no
-
specify whether enqueue operation is enabled or disabled.
The default is to enable it.
- -dequeue
yes|no
-
specify whether dequeue operation is enabled or disabled.
The default is to enable it.
- -annotation string
-
specify a string for the queue annotation.
- -timeout empty_queue_idle_timeout
-
specify how long the queue should be kept when it is empty
before it will be deleted by the queue manager. The default
is 24 hours.
The format should be in the relative utc format. Specify
"0" for forever (never expire). To specify 22 hours and 30
minutes, enter "+0-22:30:00.000".
- -group sec_group_name
-
specify the security group name which the queue manager belongs to.
- Variables used:
-
mos_default_qmgr
-
specify the default queue manager.
mos_qmgr_group
-
specify the sec group name for the queue manager.
Queue Listing
queue catalog q-mgr
[-simplename]
[-group sec_group_name]
This command lists all queues on the named queue manager. If the
queue manager is empty, this command will list queues on the default
queue manager.
By default, this command returns queue names in their fully qualified
format (starting with the queue manager's name). If "-simplename" is
specified, this command returns just the relative simple names for
the queues.
- Permission required:
- "s" bit on the Q-mgr acl
- Option:
-
- -simplename
-
specify that only the relative simple names should be returned.
- -group sec_group_name
-
specify the security group name which the qmgr belongs to.
- Variables used:
-
mos_default_qmgr
-
specify the default queue manager.
mos_qmgr_group
-
specify the sec group name for the queue manager.
Queue Deletion
queue delete queue [-force]
[-group sec_group_name]
This command causes the named queue to be deleted. If the queue is not
empty and the [-force] option is specified, all the outstanding messages
are removed first. If the [-force] is not present, an error is
returned.
The queue name has to be a fully qualified name.
- Permission required:
- "D" bit on the queue.
- Options:
-
- -force
-
remove all outstanding messages first.
- -group sec_group_name
-
specify the security group name which the qmgr belongs to.
- Variables used:
-
mos_qmgr_group
-
specify the sec group name for the queue manager.
Queue/Message Show
queue show queue
[ [-mid message_id]
[-body]
[-all] ]
[-group sec_group_name]
If "-mid" is not present, this command shows the queue's attributes.
When "-mid" is present, it shows the message. If neither "-body" nor
"-all" is present, this command shows the message attributes. If
"-body" is present, this command shows the message body, it saves the
message encoded body into a variable mos_encoded_msg
in
hexadecimal format. If "-all" is present, it shows both the message
attributes and the message body.
For queue attributes, its current length, not to be confused with its
maximum length,
its creation time, and its last activity time, are to be displayed as
read-only attributes.
The queue name has to be a fully qualified name.
- Permission required:
- "R" bit on the queue acl for a queue's attributes.
"r" bit on the queue acl for a message's attributes.
"d" bit on the queue acl for a message's body.
- Options for message showing:
-
- -mid message_id
-
specify the message.
- -body
-
specify that the message body should be shown.
- -all
-
specify that both the message attributes and body are to be
shown.
- Option for all:
-
- -group sec_group_name
-
specify the security group name which the qmgr belongs to.
- Variables used:
-
mos_qmgr_group
-
specify the sec group name for the queue manager.
mos_encoded_msg
-
the variable holding the encoded message body in hexadecimal format.
Queue Attribute Modification
queue modify queue
[-attribute attribute_list]
[[-qmaxlength new_queue_max_length]
[-msgmaxsize new_message_max_size]
[-persistent msgpersistence|persistent|volatile
]
[-enqueue yes|no
]
[-dequeue yes|no
]
[-annotation string]
[-alias list of {cds_link relative_name}]
[-timeout empty_idl_timeout]]
[-group sec_group_name]
This command modifies a queue's attribute(s).
The queue name has to be a fully qualified name.
- Permission required:
- "M" bit on the queue acl for a queue
- Option:
-
- -attribute attribute_list
-
a list of {attribute_name attribute_value}
- -qmaxlength new_queue_max_length
-
specify the new queue maximum length in term of number of messages that
the queue can keep. "0" means an unlimited queue.
- -msgmaxsize new_message_max_size
-
specify the new maximum message size. "0" means unlimited.
- -persistent
msgpersistence|persistent|volatile
-
specify the new queue persistency. The valid values are:
- msgpersistence. Message persistence dictates. The queue saves persistent messages only.
- persistent. The queue always saves messages.
- volatile. The queue never saves any message. Sending a persistent message
to such a queue will result in an error.
- -enqueue
yes|no
-
specify whether to enable or disable enqueue operation.
- -dequeue
yes|no
-
specify whether to enable or disable dequeue operation.
- -annotation string
-
specify a new annotation for the queue.
- -alias a list of {cds_link relative_name}
-
specify a new set of alias(es) for this queue. An alias is composed of two
parts, a cds link part which is to be pointed to the queue manager name,
and a relative name part. If the link exists already, it will check to
make sure that it does point to the queue manager. if the link does not
exist, the link will be created to point to the queue manager. The link
part can be empty (""). To add or delete one alias, one needs to
get the current alias set, add or delete, then use this command
to reset the alias set.
- -timeout empty_queue_idle_timeout
-
specify how long the queue should be kept when it is empty
before it will be deleted by the queue manager. "0" means
forever.
The format should be in the relative utc format.
To specify 22 hours and 30
minutes, enter "+0-22:30:00.000".
- -group sec_group_name
-
specify the security group name which the qmgr belongs to.
- Variables used:
-
mos_qmgr_group
-
specify the sec group name for the queue manager.
Queue Rename
queue rename queue
-to new_relative_name
[-referral]
[-group sec_group_name]
This command renames a queue. The queue will stay with the same queue
manager. In other words, only the relative name of the queue is renamed.
If the option specifies that a referral should
be maintained in the original Q-mgr, it will keep the old queue
name and its new name.
The queue name has to be a fully qualified name. The new name has to
a relative name.
- Permission required:
- "M" bits on the source queue acl
- Option:
-
- -to new_relative_name
-
specify the new name for the queue (relative name)
- -referral
-
specify to keep the referral
- -group sec_group_name
-
specify the security group name which the qmgr belongs to.
- Variables used:
-
mos_qmgr_group
-
specify the sec group name for the queue manager.
Queue Move and Message Relocation
queue move queue
[ -to new_queue
[-referral] ]
[ -mid message_id
-to destination_queue ]
[-oldgroup sec_group_name_for_old_queue]
[-newgroup sec_group_name_for_new_queue]
If "-mid" is absent, this command causes the named queue to be moved
to a new queue manager, with the given new name. If "-mid" is
present, this command causes the specified message to be relocated
from the source queue to a new queue.
In the queue move case, a new queue will be created first with the
same queue attributes as the original one. Refer to queue
creation page for more information regarding queue name convention.
If the new queue name is empty, a new queue will be created on the
default queue manager with a queue manager generated name. If the new
queue name is a relative name, a new queue will be created on the
default queue manager with this name. If the new queue name is a
fully qualified name, it is taken as a junction name, and will be
resolved into two parts: the resolved part is used to find the queue
manager, and the second part is used as the new queue's relative
name. In the case when the second part is empty, a new queue will be
created on the given queue manager with a queue manager generated
name.
Once the new queue is created, every message on the original message will be
moved to the new queue.
If the option specifies that a referral should
be maintained in the original Q-mgr, it will keep the old queue
name and its new name.
If no referral is asked, the old queue will be deleted.
The source queue name has to be a fully qualified name.
In the case for message relocation, the destination queue should
exist already, and is given with its fully qualified name. The
specified message will be moved from the source queue to the
destination queue.
- Permission required for queue move:
- "D" and "M" bits on the source queue acl
"i" bit on the destination Q-mgr acl
- Permission required for message relocate:
- "d" bit on the source queue acl
"e" bit on the destination queue acl
- Options for queue move:
-
- -to new_queue
-
specify the new queue name
- -referral
-
specify keep the referral
- Options for message relocation:
-
- -mid message_id
-
specify the message to be moved
- -to destination_queue
-
specify the destination queue
- Options for both:
-
- -oldgroup sec_group_name_for_old_queue
-
specify the security group name which the source queue manager belongs to.
- -newgroup sec_group_name_for_new_queue
-
specify the security group name which the new queue manager belongs to.
- Variables used:
-
mos_default_qmgr
-
specify the default queue manager.
mos_qmgr_group
-
specify the sec group name for the queue manager.
Listing Messages On A Queue
queue list queue
[-attribute attribute_list]
[-ttrmsg]
[[-mid message_id]
[-msgtype message_type]
[-datatype data_type]
[-sender principal_name]
[-plevel protection_level]
[-priority priority]
[-poperator priority_operation]]
[-group sec_group_name]
This command returns a list of message id's of the messages from the queue
that match the given selection filters.
If "-ttrmsg" is not specified, only the normal available messages
are searched for matching messages. If "-ttrmsg" is specified, only
the ttr messages (messages whose available time has not arrived yet) are
searched.
If a specific message id is specified, all other options are ignored except
for the "-ttrmsg". This can be used to check whether a particular message
is in the queue.
When no specific option is given, the commands returns all messages' ids.
The queue name has to be a fully qualified name.
- Permission required:
- "r" bit on the queue acl for normal messages
"M" bit on the queue acl for ttr messages
- Option:
-
- -attribute attribute_list
-
a list of {attribute_name attribute_value}
- -ttrmsg
-
specify that ttr messages are to be searched.
- -mid message_id
-
return the specified message. All other options have no effect.
- -msgtype message_type
-
name the message type. Valid values are:
- data. Normal data messages.
- notice. Notice messages.
- -datatype data_type
-
name the data type (a uuid)
- -sender principal_name
-
name the sender in its principal name
- -priority priority
-
specify the priority for search
- -poperator priority_operation
-
specify the priority operation. The possible values are:
- equal. Match the message with the priority equal to the specified
priority.
- not. Match the message with the priority not equal to the
specified priority.
- less. Match the message with the priority less than the
specified priority.
- greater. Match the message with the priority greater than the
specified priority.
- less_equal. Match the message with the priority less than or
equal to the specified priority.
- greater_equal. Match the message with the priority greater
than or equal to the specified priority.
- -plevel protection_level
-
specify the end-to-end protection level. The valid values are:
- none: no protection. Unauthenticated operation.
- authn: Authenticated operation.
- integrity: Authenticated operation with data integrity.
- privacy: Authenticated operation with privacy.
- -group sec_group_name
-
specify the security group name which the qmgr belongs to.
- Variables used:
-
mos_qmgr_group
-
specify the sec group name for the queue manager.
Enqueue a Message
queue add queue
[-attribute attribute_lists]
[[-priority priority]
[-msgtype message_type]
[-datatype data_type]
[-notice {notice_type notice_type ...}]
[-reply reply_queue]
[-replygroup reply_group]
[-persistent]
[-expire expiration_time]
[-ttr receive_time]
[-waitmode wait_mode]
[-plevel protection_level]
[-body "message body"]]
[-group sec_group]
This command creates a new message with the specified attributes. The
message will then be enqueued into the given queue.
When there is a data type specified, the message body part will be treated
as an encoded buffer in hexadecimal format, no further encoding will be
performed. If there is no data type specified, it is assumed to be a text
string.
This is useful when used to take a message returned from "queue show
-mid -all" operation and enqueue it to another queue.
The queue name has to be a fully qualified name.
- Permission required:
- "e" bit on the queue acl
- Options:
-
- -attribute attribute_list
-
a list of {attribute_name attribute_value}
- -priority priority
-
specify the message priority
- -msgtype message_type
-
specify the message type. Valid values are:
- data. Normal data messages.
- notice. Notice messages.
- -datatype data_type
-
specify the data type in uuid.
- -notice notice_type
-
specify the notice(s) required. The possible values are:
- none. No notice is sent back to the sender.
- enqueued. A notice is sent back when the message is queued.
- dequeued. A notice is sent back when the message is received.
- -reply reply_queue
-
specify the reply queue where the notice is sent to.
- -replygroup reply_group
-
specify the reply queue's security group name. If this one
is not specified, dcecp will try to use the one specified
by the variable mos_qmgr_group.
- -persistent
-
specify that this is a persistent message
- -expire expiration_time
-
specify the expiration time in either relative or absolute utc
format. For example, to specify 10 hours and 30 minutes from now, enter
"+0-10:30:00.000". To specify 1997/4/5 11:30am, enter
"1997-04-05-11:30:00.000".
- -ttr receive_time
-
specify the future receive time (time to receive) in either
relative or absolute utc
format. For example, to specify 10 hours and 30 minutes from now, enter
"+0-10:30:00.000". To specify 1997/4/5 11:30am, enter
"1997-04-05-11:30:00.000".
- -waitmode wait_mode
-
specify the wait mode. The valid values are:
- none. don't wait if the queue is full
- enqueued. wait until the message is enqueued; if the queue is full, wait
- dequeued. wait until the message is dequeued
- -plevel protection_level
-
specify the end-to-end protection level. The valid values are:
- none. no protection. Unauthenticated operation.
- authn. Authenticated operation.
- integrity. Authenticated operation with data integrity.
- privacy. Authenticated operation with privacy.
- -body "message body"
-
specify the message body.
- -group group
-
specify the group name that the queue manager should belong to.
When authentication is required, this option has to be specified
so that mutual authentication can happen.
- Variables used:
-
mos_qmgr_group
-
specify the sec group name for the queue manager.
Message Removal
queue remove queue
-mid message_id
[-group sec_group_name]
This command causes the named message to be deleted from the named queue.
The queue name has to be a fully qualified name.
- Permission required:
- "p" bit on the queue acl to delete a message
- Options:
-
- -mid message_id
-
specifies the message from the queue
- -group sec_group_name
-
specify the security group name which the qmgr belongs to.
- Variables used:
-
mos_qmgr_group
-
specify the sec group name for the queue manager.
[
Detailed Design TOC |
Messaging
]