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:

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

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

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

-plevel protection_level
specify the end-to-end protection level. The valid values are:

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

-datatype data_type
specify the data type in uuid.

-notice notice_type
specify the notice(s) required. The possible values are:

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

-plevel protection_level
specify the end-to-end protection level. The valid values are:

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