WebSphere Message Service Clients for C/C++ and .NET, Version 1.2 Operating Systems: Linux, Windows

Destination

A destination is where an application sends messages, or it is a source from which an application receives messages, or both.

For a list of the XMS defined properties of a Destination object, see Properties of Destination.

Related concepts
Connection factories and connections
Connecting to a WebSphere service integration bus
Destinations
Destination wildcards
Topic uniform resource identifiers (URIs)
Queue uniform resource identifiers (URIs)
Temporary destinations
Related tasks
Creating administered objects

Functions

Summary of functions:
Function Description
xmsDestCreate Create a destination using the specified uniform resource identifier (URI).
xmsDestCreateByType Create a destination using the specified destination type and name.
xmsDestCreateTemporaryByType Create a temporary destination.
xmsDestDispose Delete the destination.
xmsDestGetName Get the name of the destination.
xmsDestGetTypeId Get the type of the destination.
xmsDestToString Get the name of the destination in the format of a uniform resource identifier (URI).

xmsDestCreate – Create Destination (using a URI)

Interface:
xmsRC xmsDestCreate(xmsCHAR *URI,
                    xmsHDest *destination,
                    xmsHErrorBlock errorBlock);

Create a destination using the specified uniform resource identifier (URI). Properties of the destination that are not specified by the URI take the default values.

For a destination that is a queue, this function does not create the queue in the messaging server. You must create the queue before an application can call this function.

Parameters:
URI (input)
The URI in the format of a null terminated string.
destination (output)
The handle for the destination.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

xmsDestCreateByType – Create Destination (specifying a type and name)

Interface:
xmsRC xmsDestCreateByType(xmsDESTINATION_TYPE destinationType,
                          xmsCHAR *destinationName,
                          xmsHDest *destination,
                          xmsHErrorBlock errorBlock);

Create a destination using the specified destination type and name.

For a destination that is a queue, this function does not create the queue in the messaging server. You must create the queue before an application can call this function.

Parameters:
destinationType (input)
The type of the destination, which must be one of the following values:
  • XMS_DESTINATION_TYPE_QUEUE
  • XMS_DESTINATION_TYPE_TOPIC
destinationName (input)
The name of the destination, which can be the name of a queue or the name of a topic. The name is in the format of a null terminated string.
If the destination is a WebSphere MQ queue, you can specify the name of the destination in either of the following ways:
  • QName
  • QMgrName/QName
where QName is the name of a WebSphere MQ queue, and QMgrName is the name of a WebSphere MQ queue manager. The WebSphere MQ queue name resolution process uses the values of QName and QMgrName to determine the actual destination queue. For more information about the queue name resolution process, see the WebSphere MQ Application Programming Guide.
destination (output)
The handle for the destination.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

xmsDestCreateTemporaryByType – Create Temporary Destination

Interface:
xmsRC xmsDestCreateTemporaryByType(xmsDESTINATION_TYPE destinationType,
                                   xmsHSess session,
                                   xmsHDest *destination,
                                   xmsHErrorBlock errorBlock);

Create a temporary destination.

The scope of the temporary destination is the connection. Only the sessions created by the connection can use the temporary destination.

The temporary destination remains until it is explicitly deleted, or the connection ends, whichever is the sooner.

For more information about temporary destinations, see Temporary destinations.

Parameters:
destinationType (input)
The type of the temporary destination, which must be one of the following values:
  • XMS_DESTINATION_TYPE_QUEUE
  • XMS_DESTINATION_TYPE_TOPIC
session (input)
The handle for the session.
destination (output)
The handle for the temporary destination.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

xmsDestDispose – Delete Destination

Interface:
xmsRC xmsDestDispose(xmsHDest *destination,
                     xmsHErrorBlock errorBlock);

Delete the destination.

For a destination that is a queue, this function does not delete the queue in the messaging server unless the queue was created for an XMS temporary queue.

If an application tries to delete a destination that is already deleted, the call is ignored.

Parameters:
destination (input/output)
On input, the handle for the destination. On output, the function returns a null handle.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

xmsDestGetName – Get Destination Name

Interface:
xmsRC xmsDestGetName(xmsHDest destination,
                     xmsCHAR *destinationName,
                     xmsINT length,
                     xmsINT *actualLength,
                     xmsHErrorBlock errorBlock);

Get the name of the destination.

For more information about how to use this function, see C functions that return a string by value.

Parameters:
destination (input)
The handle for the destination.
destinationName (output)
The buffer to contain the name of the destination. The name is either the name of a queue or the name of a topic.
length (input)
The length of the buffer in bytes. If you specify XMSC_QUERY_SIZE instead, the name of the destination is not returned, but its length is returned in the actualLength parameter.
actualLength (output)
The length of the name of the destination in bytes. If you specify a null pointer on input, the length is not returned.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

xmsDestGetTypeId – Get Destination Type

Interface:
xmsRC xmsDestGetTypeId(xmsHDest destination,
                       xmsDESTINATION_TYPE *destinationType,
                       xmsHErrorBlock errorBlock);

Get the type of the destination.

Parameters:
destination (input)
The handle for the destination.
destinationType (output)
The type of the destination, which is one of the following values:
  • XMS_DESTINATION_TYPE_QUEUE
  • XMS_DESTINATION_TYPE_TOPIC
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

xmsDestToString – Get Destination Name as URI

Interface:
xmsRC xmsDestToString(xmsHDest destination,
                      xmsCHAR *destinationName,
                      xmsINT length,
                      xmsINT *actualLength,
                      xmsHErrorBlock errorBlock);

Get the name of the destination in the format of a uniform resource identifier (URI).

For more information about how to use this function, see C functions that return a string by value.

Parameters:
destination (input)
The handle for the destination.
destinationName (output)
The buffer to contain the URI. The URI is either a queue URI or a topic URI.
length (input)
The length of the buffer in bytes. If you specify XMSC_QUERY_SIZE instead, the URI is not returned, but its length is returned in the actualLength parameter.
actualLength (output)
The length of the URI in bytes. If you specify a null pointer on input, the length is not returned.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

Reference topic

Terms of Use | Rate this page

Last updated: 7 Dec 2005

© Copyright IBM Corporation 2005. All Rights Reserved.