3.1.7.1.5 Open Queue

  • Article

This event MUST be generated with the following arguments:

  • iFormatName: The format name of the queue to be opened.

  • iRequiredAccess: A QueueAccessType value that specifies the type of access required.

  • iSharedMode: A QueueShareMode value that specifies the sharing mode.

Return Values:

  • rStatus: A status code that can be one of the following:

    • MQ_OK (0x00000000)

    • MQ_ERROR_QUEUE_NOT_FOUND (0xC00E0003)

    • MQ_ERROR_SHARING_VIOLATION (0xC00E0009)

    • MQ_ERROR_UNSUPPORTED_FORMATNAME_OPERATION (0xC00E0020)

    • MQ_ERROR_UNSUPPORTED_ACCESS_MODE (0xC00E0045)

  • rOpenQueueDescriptor: An OpenQueueDescriptor (section 3.1.1.16) ADM element value.

The queue manager MUST perform the following actions to process this event:

  • Generate an Expand Format Name (section 3.1.7.3.8) event with the following argument:

    • iInputFormatName := iFormatName

  • If the rStatus returned by the Expand Format Name event is FALSE, set rStatus to an error code, and take no further action.

  • Set iFormatName to the rOutputFormatName returned by the Expand Format Name event.

  • If iFormatName is a multiple-element format name ([MS-MQMQ] section 2.1.7):

    • If the iRequiredAccess argument is not SendAccess:

      • Set rStatus to MQ_ERROR_UNSUPPORTED_FORMATNAME_OPERATION.

      • Take no further action.

    • If the iSharedMode argument is not DenyNone:

      • Set rStatus to MQ_ERROR_UNSUPPORTED_ACCESS MODE.

      • Take no further action.

    • Create a new OpenQueueDescriptor ADM element instance, referred to as newDesc, and:

      • Set newDesc.AccessType to SendAccess.

      • Set newDesc.SharedMode to DenyNone.

      • Set newDesc.FormatName to iFormatName.

      • Set newDesc.Multiple to TRUE.

      • Set newDesc.QueueReference to NULL.

      • Set newDesc.RemoteReadState to None.

      • Set newDesc.Handle to an implementation-specific value that can be used to reference this OpenQueueDescriptor ADM element instance.

      • Set newDesc.ContextValue to an implementation-specific value that can be used to reference this OpenQueueDescriptor ADM element instance.

    • For each element in iFormatName, referred to as SingleFormatName:

      • Generate an Open Queue event with the following arguments:

        • iFormatName := SingleFormatName

        • iRequiredAccess := SendAccess

        • iSharedMode := DenyNone

      • If the rStatus returned is not MQ_OK:

        • Generate a Close Queue (section 3.1.7.1.6) event with iQueueDesc set to newDesc.

        • Set rStatus to the value returned by the failed Open Queue event.

        • Take no further action.

      • Place the OpenQueueDescriptor ADM element instance referenced by the rOpenQueueDescriptor returned from the Open Queue event in newDesc.OpenQueueDescriptorCollection.

    • Set rStatus to MQ_OK.

    • Set rOpenQueueDescriptor to the OpenQueueDescriptor ADM element instance referenced by newDesc.

    • Take no further action.

  • If iFormatName is a direct format name ([MS-MQMQ] section 2.1.2) that specifies HTTP or HTTPS as the protocol:

    • If the iRequiredAccess argument is not SendAccess:

      • Set rStatus to MQ_ERROR_UNSUPPORTED_FORMATNAME_OPERATION.

      • Take no further action.

  • If iFormatName is a machine format name ([MS-MQMQ] section 2.1.6):

    • If the iRequiredAccess argument is SendAccess:

      • Set rStatus to MQ_ERROR_UNSUPPORTED_FORMATNAME_OPERATION.

      • Take no further action.

  • If iFormatName is a multicast format name ([MS-MQMQ] section 2.1.6):

    • If the iRequiredAccess argument is not SendAccess:

      • Set rStatus to MQ_ERROR_UNSUPPORTED_FORMATNAME_OPERATION.

      • Take no further action.

  • Find the Queue (section 3.1.1.2) ADM element instance in LocalQueueManager.QueueCollection, referred to as queueObj, which matches the specified iFormatName argument.

  • If the Queue ADM element instance is not found:

    • If the iRequiredAccess argument is not SendAccess:

      • Set rStatus to MQ_ERROR_QUEUE_NOT_FOUND.

      • Take no further action.

    • If iFormatName is a direct format name ([MS-MQMQ] section 2.1.2):

      • Let machineName be a string representing the name or address of the computer that hosts the queue manager.

      • Extract the ProtocolAddressSpecification and Protocol substrings from iFormatName.

      • If Protocol is HTTP or HTTPS:

        • Extract the Host from ProtocolAddressSpecification and set machineName to the Host.

      • Else:

        • Set machineName to ProtocolAddressSpecification.

      • If machineName matches LocalQueueManager.ComputerName, perform the following steps:

        • Set rStatus to MQ_ERROR_QUEUE_NOT_FOUND.

        • Take no further action.

    • If iFormatName is a public format name ([MS-MQMQ] section 2.1.3):

      • Let PublicQueueGuid be a GUID that is initialized to the QueueGuid element of iFormatName.

      • Generate a Read Directory (section 3.1.7.1.20) event with the following arguments:

        • iDirectoryObjectType := "Queue"

        • iFilter := An array of the following attribute-filter expressions:

          • "Identifier" EQUALS PublicQueueGuid

        • If rStatus returned by the Read Directory event is not equal to DirectoryOperationResult.Success:

          • Set rStatus to MQ_ERROR_UNSUPPORTED_FORMATNAME_OPERATION (0xC00E0020) and take no further action.

        • Define iQueue as a reference to a Queue ADM element instance and set it to the returned rDirectoryObject.

        • If iQueue.QueueManager.ComputerName matches LocalQueueManager.ComputerName, perform the following steps:

          • Set rStatus to MQ_ERROR_QUEUE_NOT_FOUND.

          • Take no further action.

    • If iFormatName is a private format name ([MS-MQMQ] section 2.1.4):

      • If the ComputerGuid element of iFormatName matches LocalQueueManager.Identifier:

        • Set rStatus to MQ_ERROR_QUEUE_NOT_FOUND.

        • Take no further action.

    • Create a new OutgoingQueue (section 3.1.1.3) ADM element instance, referred to as newQueue, with the following attributes:

      • newQueue.Identifier := a new GUID generated by the queue manager

      • newQueue.Label := iFormatName

      • newQueue.DestinationFormatName := iFormatName

      • newQueue.NextHops := NULL

      • newQueue.State := Inactive

    • If the iFormatName argument is a public format name ([MS-MQMQ] section 2.1.3):

      • Let PublicQueueGuid be a GUID that is initialized to the QueueGuid element of iFormatName.

      • Generate a Read Directory event with the following arguments:

        • iDirectoryObjectType := "Queue"

        • iFilter := An array of the following attribute-filter expressions:

          • "Identifier" EQUALS PublicQueueGuid

      • If rStatus returned by the Read Directory event is equal to DirectoryOperationResult.Success:

        • Set newQueue.BasePriority to the returned rDirectoryObject.BasePriority.

      • Else:

        • Set rStatus to MQ_ERROR_QUEUE_NOT_FOUND.

        • Take no further action.

    • If iFormatName specifies a non-HTTP format name and the LocalQueueManager.HardenedSecurity ADM attribute is True:

      • Set newQueue.State := Locked

    • If iFormatName specifies a multicast format name:

      • Set newQueue.Multicast to TRUE

    •  Set the Queue ADM element instance referenced by queueObj to the OutgoingQueue ADM element instance referenced by newQueue.

  • If queueObj.OpenQueueDescriptorCollection contains an OpenQueueDescriptor ADM element instance with the ShareMode ADM attribute set to DenyReceive and the AccessType ADM attribute set to ReceiveAccess:

    • If the iSharedMode argument is DenyReceive:

      • Set rStatus to MQ_ERROR_SHARING_VIOLATION.

      • Take no further action.

    • Else if the iSharedMode argument is DenyNone and iRequiredAccess is ReceiveAccess:

      • Set rStatus to MQ_ERROR_SHARING_VIOLATION.

      • Take no further action.

  • Else if queueObj.OpenQueueDescriptorCollection contains an OpenQueueDescriptor ADM element instance with the ShareMode attribute set to DenyReceive and the AccessType attribute set to PeekAccess or PeekAdminAccess:

    • If the iRequiredAccess argument is ReceiveAccess:

      • Set rStatus to MQ_ERROR_SHARING_VIOLATION.

      • Take no further action.

  • Else if queueObj.OpenQueueDescriptorCollection contains an OpenQueueDescriptor ADM element instance with the ShareMode attribute set to DenyNone and the AccessType attribute set to ReceiveAccess:

    • If the iSharedMode argument is DenyReceive:

      • Set rStatus to MQ_ERROR_SHARING_VIOLATION.

      • Take no further action.

  • Create a new OpenQueueDescriptor ADM element instance, referred to as newDesc, and:

    • Set newDesc.AccessType to iRequiredAccess.

    • Set newDesc.QueueReference to the Queue ADM element instance referenced by queueObj.

    • Set newDesc.FormatName to iFormatName.

    • Set newDesc.Multiple to FALSE.

    • Set newDesc.Handle to an implementation-specific value that can be used to reference this OpenQueueDescriptor ADM element instance.

    • Set newDesc.ContextValue to an implementation-specific value that can be used to reference this OpenQueueDescriptor ADM element instance.

    • Add newDesc to queueObj.OpenQueueDescriptorCollection.

  • Set rStatus to MQ_OK.

  • Set rOpenQueueDescriptor to the newDesc ADM element instance.