Creating Destinations

After creating a session, you can create destinations or temporary destinations for the messages you want to send. Table 2–5 lists the functions you use to create and to get information about destinations.

Table 2–5 Functions Used to Work with Destinations

Functions	Description
MQCreateDestination	Creates a destination and initializes a handle to it.
MQCreateTemporaryDestination	Creates a temporary destination and initializes a handle to it.
MQGetDestinationType	Returns the type (queue or topic) of the specified destination.

A destination refers to where a message is destined to go. A physical destination is a JMS message service entity (a location on the broker) to which producers send messages and from which consumers receive messages. The message service provides the routing and delivery for messages sent to a physical destination.

When a Message Queue C client creates a destination programmatically using the MQCreateDestination function, a destination name must be specified. The function initializes a handle to a destination data type that holds the identity (name) of the destination. The important thing to remember is that this function does not create the physical destination on the broker; this must be done by the administrator. The destination that is created programmatically however must have the exact same name and type as the physical destination created on the broker. For example, if you use the MQCreateDestination function to create a queue destination called myMailQDest, the administrator has to create a physical destination on the broker named myMailQDest.

Destination names starting with “mq” are reserved and should not be used by client programs.

Programming Domains

When you create a destination, you must also specify its type: MQ_QUEUE_DESTINATION or MQ_TOPIC_DESTINATION. See Messaging Domains in Sun GlassFish Message Queue 4.4 Technical Overviewfor a discussion of these two types of destinations and how to choose the type that suits your needs.

Auto-Created Destinations

By default, the imq.autocreate.topic and imq.autocreate.queue broker properties are turned on. In this case, which is more convenient in a development environment, the broker automatically creates a physical destination whenever a message consumer or message producer attempts to access a non-existent destination. The auto-created physical destination will have the same name as that of the destination you created using the MQCreateDestination function.

Temporary Destinations

You use the MQCreateTemporaryDestination function to create a temporary destination. You can use such a destination to implement a simple request/reply mechanism. When you pass the handle of a temporary destination to the MQSetMessageReplyTo function, the consumer of the message can use that handle as the destination to which it sends a reply.

Temporary destinations are explicitly created by client applications and are automatically deleted when the connection is closed. They are maintained (and named) by the broker only for the duration of the connection for which they are created. Temporary destinations are system-generated uniquely for their connection and only their own connection is allowed to create message consumers for them.

Getting Information About Destinations

Use the MQGetDestinationType function to determine the type of a destination: queue or topic. There may be times when you do not know the type of the destination to which you are replying: for example, when you get a handle from the MQGetMessageReplyTo function. Because the semantics of queue and topic destinations differ, you need to determine the type of a destination in order to reply appropriately.