Edit

Using the Queue Moniker

  • Article

The queue moniker is used to activate a queued component programmatically. The queue moniker requires that it receive the class ID (CLSID) of the object to be invoked from the new moniker directly to the right of it. When left-prefixed, the new moniker passes the CLSID to the moniker to the left of it.

Component Services Administrative Tool

Does not apply.

Visual Basic

The GetObject display name parameter is "queue:/new:", followed by the program ID or string-form GUID, with or without braces, of the server object to be instantiated. The following examples show three valid activations of a component with the queue moniker:

  1. Set objMyQC = GetObject ("queue:/new:QCShip.Ship")

  2. Set objMyQC = GetObject ("queue:/new:{812DF40E-BD88-11D0-8A6D-00C04FC340EE}")

  3. Set objMyQC = GetObject ("queue:/new:812DF40E-BD88-11D0-8A6D-00C04FC340EE")

C/C++

The CoGetObject display name parameter is "queue:/new:", followed by the program ID or string-form GUID, with or without braces, of the server object to be instantiated. The following examples show three valid activations of a component with the queue moniker:

  1. hr = CoGetObject (
  L"queue:/new:QCShip.Ship",
  NULL, IID_IShip, (void**)&pShip);

  2. hr = CoGetObject (
  L"queue:/new:{812DF40E-BD88-11D0-8A6D-00C04FC340EE}", 
  NULL, IID_IShip, (void**)&pShip);

  3. hr = CoGetObject (
  L"queue:/new:812DF40E-BD88-11D0-8A6D-00C04FC340EE",
  NULL, IID_IShip, (void**)&pShip);

Remarks

The queue moniker accepts optional parameters that alter the properties of the message sent to Message Queuing. For example, to cause the Message Queuing message to be sent with a priority 6, the queued component would be activated as follows:

hr = CoGetObject (
  L"queue:Priority=6,ComputerName=MyComp/new:QCShip.Ship",
  NULL, IID_IShip, (void**)&pShip);

The following table lists the queue moniker parameters that affect the destination queue.

Parameter Description
ComputerName
 Specifies the computer name portion of a Message Queuing queue path name. The Message Queuing queue path name is formatted as ComputerName<em>QueueName. If not specified, the computer name associated with the configured application is used.
QueueName
 Specifies the Message Queuing queue name. The Message Queuing queue path name is formatted as ComputerName<em>QueueName. If not specified, the queue name associated with the configured application is used.
To get a non-transactional queue, you can specify the queue name first and then create a COM+ application of the same name.
PathName
 Specifies the complete Message Queuing queue path name. If not specified, the Message Queuing queue path name associated with the configured application is used. To override the destination name, the path can be specified in the following form for a Message Queuing workgroup installation:
Queue:PathName=ComputerName\PRIVATE$\AppName/new:Myproject.CMyClass
Note: Both the C and Microsoft Visual C++ programming languages require two backslashes to represent one backslash within string literals for example, chicago\payroll.
FormatName
 When you mark a COM+ application as queued, COM+ creates a Message Queuing queue whose name is the same as the application. The Message Queuing format name of that queue is in the COM+ catalog, associated with the COM+ application. To override the destination name, the format name can be specified in the following form for a Message Queuing workgroup installation:
Queue:FormatName=DIRECT=OS:ComputerName\PRIVATE$\AppName/new:ProgId
In an Active Directory configuration, "PRIVATE$" is not specified as part of the queue name.

Note

Optional queue moniker parameters are processed left-to-right. Specify each keyword only one time. Specifying the PathName parameter replaces both the ComputerName and QueueNameparameters. A specific FormatName parameter deletes prior knowledge of a ComputerName, QueueName, and PathName parameter.

Associating the Queued Components Listener with a Specific Private Queue

The COM+ Queued Components listener receives only from queues associated with the COM+ application marked queued. When you mark a COM+ application as queued, COM+ creates a Message Queuing queue whose name is the same as the application. The Message Queuing format name of that queue is in the COM+ catalog, associated with the COM+ application. When the COM+ application is started and marked as listen, a listener in the COM+ application process is started and the queue is opened. The following table lists the queue moniker parameters that affect the Message Queuing message.

Parameter Description
AppSpecific
 Specifies an unsigned integer for example, AppSpecific=12345.
AuthLevel
 Specifies the message authentication level. An authenticated message is digitally signed and requires a certificate for the user sending the message. Acceptable values:
  • MQMSG_AUTH_LEVEL_NONE,0
  • MQMSG_AUTH_LEVEL_ALWAYS,1
Delivery
 Specifies the message delivery option. This value is ignored for transactional queues. Acceptable values:
  • MQMSG_DELIVERY_EXPRESS,0
  • MQMSG_DELIVERY_RECOVERABLE,1
EncryptAlgorithm
 Specifies the encryption algorithm to be used by Message Queuing to encrypt and decrypt the message. Acceptable values:
  • CALG_RC2, CALG_RC4
  • Any integer value that is acceptable to Message Queuing for an EncryptAlgorithm.
HashAlgorithm
 Specifies a cryptographic hash function. Acceptable values:
  • CALG_MD2, CALG_MD4, CALG_MD5, CALG_SHA, CALG_SHA1, CALG_MAC, CALG_SSL3_SHAMD5, CALG_HMAC, CALG_TLS1PRF
  • Any integer value that is acceptable to Message Queuing for a HashAlgorithm.
Journal
 Specifies the Message Queuing message journal option. Acceptable values:
  • MQMSG_JOURNAL_NONE,0
  • MQMSG_DEADLETTER,1
  • MQMSG_JOURNAL,2
Label
 Specifies a message label string up to MQ_MAX_MSG_LABEL_LEN characters.
MaxTimeToReachQueue
 Specifies a maximum time, in seconds, for the message to reach the queue.
Acceptable values:
  • INFINITE
  • LONG_LIVED
  • Number of seconds
MaxTimeToReceive
 Specifies a maximum time, in seconds, for the message to be received by the target application. Acceptable values:
  • INFINITE
  • LONG_LIVED
  • Number of seconds
Priority
 Specifies a message priority level, within the Message Queuing values permitted.
Acceptable values:
  • MQ_MIN_PRIORITY,0
  • MQ_MAX_PRIORITY,7
  • MQ_DEFAULT_PRIORITY,3
  • Number between 0 and 7
PrivLevel
 Specifies a privacy level, used to encrypt messages.
Acceptable values:
  • MQMSG_PRIV_LEVEL_NONE, NONE, 0
  • MQMSG_PRIV_LEVEL_BODY, BODY,
  • MQMSG_PRIV_LEVEL_BODY_BASE, BODY_BASE, 1
  • MQMSG_PRIV_LEVEL_BODY_ENHANCED, BODY_ENHANCED, 3
Trace
 Specifies trace options, used in tracing Message Queuing routing.
Acceptable values:
  • MQMSG_TRACE_NONE,0
  • MQMSG_SEND_ROUTE_TO_REPORT_QUEUE,1

The complete set of COM+ Administrative SDK functions is available by using COM objects. This allows any program to start and stop COM+ applications as required.

Note

When a COM+ application is started, it is the application that is running, not the individual components within the application. If an application calls a non-queued component, the COM+ application that contains the component is started. If the listener check box is enabled, the listener also starts and begins processing for messages for queued components. While the queued components service can be started in this way, if you package queued and non-queued components into a single COM+ application, be sure that you really want queued components to start if a non-queued component is executed. If this is not the case, package the queued components into a COM+ application that is separate from the other components.

Activating Component Queues