Sun Java System Message Queue 4.3 Developer's Guide for C Clients

Working With Properties

When you create a connection, set message header properties, or set user-defined message properties, you must pass a handle to a properties object. You use the MQCreateProperties function to create this object and to obtain a handle to it. When you receive a message, you can use specific MQGet...Property functions to obtain the type and value of each message property.

This section describes the functions you use to set and get properties. A property is defined as a key-value pair.

Setting Connection and Message Properties

You use the functions listed in Table 2–1 to create a handle to a properties object, and to set properties. You can use these functions to create and define properties for connections or for individual messages.

Set message properties and message header properties using the same procedure you use to set connection properties. You can set the following message header properties for sending a message:

For more information, see the description of the MQSetMessageProperties() function.

Table 2–1 Functions Used to Set Properties

Function 

Description 

MQCreateProperties

Creates a properties object and passes back a handle to it. 

MQSetBoolProperty

Sets an MQBool property.

MQSetStringProperty

Sets an MQString property.

MQSetInt8Property

Sets an MQInt8 property.

MQSetInt16Property

Sets an MQInt16 property.

MQSetInt32Property

Sets an MQInt32 property.

MQSetInt64Property

Sets an MQInt64 property.

MQSetFloat32Property

Sets an MQFloat32 property.

MQSetFloat64Property

Sets an MQFloat64 property.

ProcedureTo Set Properties for a Connection

  1. Call the MQCreateProperties function to get a handle to a newly created properties object.

  2. Call one of the MQSet...Property functions to set one of the connection properties described in Table 4–2 . At a minimum, you must specify the name of the host of the broker to which you want to connect and its port number.

    Which function you call depends on the type of the property you want to set; for example, to set an MQString property, you call the MQSetStringProperty function; to set an MQBool property, you call the MQSetBoolProperty function; and so on. Each function that sets a property requires that you pass a key name and value; these are listed and described in Table 4–2.

  3. When you have set all the properties you want to define for the connection, you can then create the connection, by calling the MQCreateConnection function.

    Once the connection is created with the properties you specify, you cannot change its properties. If you need to change connection properties after you have created a connection, you will need to destroy the old connection and its associated objects and create a new one with the desired properties. It is a good idea to think through the desired behavior before you create a connection.

    The code sample below illustrates how you create a properties handle and how you use it for setting connection properties.


    MQStatus status;
    MQPropertiesHandle propertiesHandle = MQ_INVALID_HANDLE;
    
    status = (MQCreateProperties(&propertiesHandle);
    
    status = (MQSetStringProperty(propertiesHandle,
               MQ_BROKER_HOST_PROPERTY, “localhost”));
    
    status = (MQSetInt32Property(propertiesHandle,
               MQ_BROKER_PORT_PROPERTY, 7676));
    
    status = MQSetStringProperty(propertiesHandle,
              MQ_CONNECTION_TYPE_PROPERTY, “TCP”));
                      

    The Message Queue C client runtime sets the connection properties that specify the name and version of the Message Queue product; you can retrieve these using the functionMQGetMetaData(). These properties are described at the end of Table 4–2, starting with MQ_NAME_PROPERTY.

Getting Message Properties

When you receive a message, if you are interested in the message properties, you need to obtain a handle to the properties object associated with that message:

Having obtained the handle, you can iterate through the properties and then use the appropriate MQGet...Property function to determine the type and value of each property.

Table 2–2 lists the functions you use to iterate through a properties handle and to obtain the type and value of each property.

Table 2–2 Functions Used to Get Message Properties

Function 

Description 

MQPropertiesKeyIterationStart

Starts the iteration process through the specified properties handle. 

MQPropertiesKeyIterationHasNext

Returns MQ_TRUE if there are additional property keys left in the iteration.

MQPropertiesKeyIterationGetNext

Passes back the address of the next property key in the referenced property handle. 

MQGetPropertyType

Gets the type of the specified property. 

MQGetBoolProperty

Gets the value of the specified MQBool type property.

MQGetStringProperty

Gets the value of the specified MQString type property.

MQGetInt8Property

Gets the value of the specified MQInt8 type property.

MQGetInt16Property

Gets the value of the specified MQInt16 type property.

MQGetInt32Property

Gets the value of the specified MQInt32 type property.

MQGetInt64Property

Gets the value of the specified MQInt64 type property.

MQGetFloat32Property

Gets the value of the specified MQFloat32 type property.

MQGetFloat64Property

Gets the value of the specified MQFloat64 type property.

ProcedureTo Iterate Through a Properties Handle

  1. Start the process by calling the MQPropertiesKeyIterationStart() function.

  2. Loop using the MQPropertiesKeyIterationHasNext() function.

  3. Extract the name of each property key by calling the MQPropertiesKeyIterationGetNext() function.

  4. Determine the type of the property value for a given key by calling the MQGetPropertyType() function.

  5. Use the appropriate MQGet...Property function to find the value of the specified property key and type.

    If you know the property key, you can just use the appropriate MQGet...Property function to get its value. The code sample below illustrates how you implement these steps.


    MQStatus status;
    
    MQPropertiesHandle headersHandle = MQ_INVALID_HANDLE;
    
    MQBool redelivered;
    
    ConstMQString my_msgtype;
    
    status = (MQGetMessageHeaders(messageHandle, &headersHandle));
    
    status = (MQGetBoolProperty(headersHandle,
               MQ_REDELIVERED_HEADER_PROPERTY, &redelivered));
    
    status = MQGetStringProperty(headersHandle,
              MQ_MESSAGE_TYPE_HEADER_TYPE_PROPERTY, &my_msgtype);