WebSphere Message Service Client for C/C++, Version 2.0.2 Operating Systems: AIX, Linux, Solaris, Windows

PropertyContext

The PropertyContext class contains functions that get and set properties. These functions can operate on any object that can have properties.

All objects can have properties except ErrorBlock, Iterator, and Property objects.

Functions

Summary of functions:
Function Description
xmsGetBooleanProperty Get the value of the boolean property identified by name.
xmsGetByteArrayProperty Get the value of the byte array property identified by name.
xmsGetByteArrayPropertyByRef Get a pointer to the value of the byte array property identified by name.
xmsGetByteProperty Get the value of the byte property identified by name.
xmsGetCharProperty Get the value of the 2-byte character property identified by name.
xmsGetDoubleProperty Get the value of the double precision floating point property identified by name.
xmsGetFloatProperty Get the value of the floating point property identified by name.
xmsGetHandleTypeId Get the type of the handle for the object.
xmsGetIntProperty Get the value of the integer property identified by name.
xmsGetLongProperty Get the value of the long integer property identified by name.
xmsGetObjectProperty Get the value and data type of the property identified by name.
xmsGetProperty Get a Property object for the property identified by name.
xmsGetShortProperty Get the value of the short integer property identified by name.
xmsGetStringProperty Get the value of the string property identified by name.
xmsGetStringPropertyByRef Get a pointer to the value of the string property identified by name.
xmsSetBooleanProperty Set the value of the boolean property identified by name.
xmsSetByteProperty Set the value of the byte property identified by name.
xmsSetByteArrayProperty Set the value of the byte array property identified by name.
xmsSetCharProperty Set the value of the 2-byte character property identified by name.
xmsSetDoubleProperty Set the value of the double precision floating point property identified by name.
xmsSetFloatProperty Set the value of the floating point property identified by name.
xmsSetIntProperty Set the value of the integer property identified by name.
xmsSetLongProperty Set the value of the long integer property identified by name.
xmsSetObjectProperty Set the value and data type of a property identified by name.
xmsSetProperty Set the value of a property using a Property object.
xmsSetShortProperty Set the value of the short integer property identified by name.
xmsSetStringProperty Set the value of the string property identified by name.

xmsGetBooleanProperty – Get Boolean Property

Interface:
xmsRC xmsGetBooleanProperty(xmsHObj object,
                            xmsCHAR *propertyName,
                            xmsBOOL *propertyValue,
                            xmsHErrorBlock errorBlock);

Get the value of the boolean property identified by name.

Parameters:
object (input)
The handle for the object.
propertyName (input)
The name of the property in the format of a null terminated string.
propertyValue (output)
The value of the property.
errorBlock (input)
The handle for an error block or a null handle.
Thread context:
Determined by the thread context of the object
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

xmsGetByteArrayProperty – Get Byte Array Property

Interface:
xmsRC xmsGetByteArrayProperty(xmsHObj object
                              xmsCHAR *propertyName,
                              xmsSBYTE *propertyValue,
                              xmsINT length,
                              xmsINT *actualLength
                              xmsHErrorBlock errorBlock) const;

Get the value of the byte array property identified by name.

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

Parameters:
object (input)
The handle for the object.
propertyName (input)
The name of the property in the format of a null terminated string.
propertyValue (output)
The buffer to contain the value of the property, which is an array of bytes.
length (input)
The length of the buffer in bytes. If you specify XMSC_QUERY_SIZE instead, the array of bytes is not returned, but its length is returned in the actualLength parameter.
actualLength (output)
The number of bytes in the array. If you specify a null pointer on input, the length of the array is not returned.
errorBlock (input)
The handle for an error block or a null handle.
Thread context:
Determined by the thread context of the object
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

xmsGetByteArrayPropertyByRef – Get Byte Array Property by Reference

Interface:
xmsRC xmsGetByteArrayPropertyByRef(xmsHObj object
                                   xmsCHAR *propertyName,
                                   xmsSBYTE **propertyValue,
                                   xmsINT *length,
                                   xmsHErrorBlock errorBlock) const;

Get a pointer to the value of the byte array property identified by name.

For more information about how to use this function, see C functions that return a string or byte array by reference.

Parameters:
object (input)
The handle for the object.
propertyName (input)
The name of the property in the format of a null terminated string.
propertyValue (output)
A pointer to the value of the property, which is an array of bytes.
length (output)
The number of bytes in the array.
errorBlock (input)
The handle for an error block or a null handle.
Thread context:
Determined by the thread context of the object
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

xmsGetByteProperty – Get Byte Property

Interface:
xmsRC xmsGetByteProperty(xmsHObj object,
                         xmsCHAR *propertyName,
                         xmsSBYTE *propertyValue,
                         xmsHErrorBlock errorBlock);

Get the value of the byte property identified by name.

Parameters:
object (input)
The handle for the object.
propertyName (input)
The name of the property in the format of a null terminated string.
propertyValue (output)
The value of the property.
errorBlock (input)
The handle for an error block or a null handle.
Thread context:
Determined by the thread context of the object
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

xmsGetCharProperty – Get Character Property

Interface:
xmsRC xmsGetCharProperty(xmsHObj object,
                         xmsCHAR *propertyName,
                         xmsCHAR16 *propertyValue,
                         xmsHErrorBlock errorBlock);

Get the value of the 2-byte character property identified by name.

Parameters:
object (input)
The handle for the object.
propertyName (input)
The name of the property in the format of a null terminated string.
propertyValue (output)
The value of the property.
errorBlock (input)
The handle for an error block or a null handle.
Thread context:
Determined by the thread context of the object
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

xmsGetDoubleProperty – Get Double Precision Floating Point Property

Interface:
xmsRC xmsGetDoubleProperty(xmsHObj object,
                           xmsCHAR *propertyName,
                           xmsDOUBLE *propertyValue,
                           xmsHErrorBlock errorBlock);

Get the value of the double precision floating point property identified by name.

Parameters:
object (input)
The handle for the object.
propertyName (input)
The name of the property in the format of a null terminated string.
propertyValue (output)
The value of the property.
errorBlock (input)
The handle for an error block or a null handle.
Thread context:
Determined by the thread context of the object
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

xmsGetFloatProperty – Get Floating Point Property

Interface:
xmsRC xmsGetFloatProperty(xmsHObj object,
                          xmsCHAR *propertyName,
                          xmsFLOAT *propertyValue,
                          xmsHErrorBlock errorBlock);

Get the value of the floating point property identified by name.

Parameters:
object (input)
The handle for the object.
propertyName (input)
The name of the property in the format of a null terminated string.
propertyValue (output)
The value of the property.
errorBlock (input)
The handle for an error block or a null handle.
Thread context:
Determined by the thread context of the object
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

xmsGetHandleTypeId – Get Handle Type

Interface:
xmsRC xmsGetHandleTypeId(xmsHObj object,
                         xmsHANDLE_TYPE *handleType,
                         xmsHErrorBlock errorBlock);

Get the type of the handle for the object.

Parameters:
object (input)
The handle for the object.
handleType (output)
The type of the handle for the object, which is one of the following values:
  • XMS_HANDLE_TYPE_CONN
  • XMS_HANDLE_TYPE_CONNFACT
  • XMS_HANDLE_TYPE_CONNMETADATA
  • XMS_HANDLE_TYPE_DEST
  • XMS_HANDLE_TYPE_ERRORBLOCK
  • XMS_HANDLE_TYPE_INITIALCONTEXT
  • XMS_HANDLE_TYPE_ITERATOR
  • XMS_HANDLE_TYPE_MSG
  • XMS_HANDLE_TYPE_MSGCONSUMER
  • XMS_HANDLE_TYPE_MSGPRODUCER
  • XMS_HANDLE_TYPE_QUEUEBROWSER
  • XMS_HANDLE_TYPE_PROPERTY
  • XMS_HANDLE_TYPE_REQUESTOR
  • XMS_HANDLE_TYPE_SESS
errorBlock (input)
The handle for an error block or a null handle.
Thread context:
Determined by the thread context of the object
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

xmsGetIntProperty – Get Integer Property

Interface:
xmsRC xmsGetIntProperty(xmsHObj object,
                        xmsCHAR *propertyName,
                        xmsINT *propertyValue,
                        xmsHErrorBlock errorBlock);

Get the value of the integer property identified by name.

Parameters:
object (input)
The handle for the object.
propertyName (input)
The name of the property in the format of a null terminated string.
propertyValue (output)
The value of the property.
errorBlock (input)
The handle for an error block or a null handle.
Thread context:
Determined by the thread context of the object
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

xmsGetLongProperty – Get Long Integer Property

Interface:
xmsRC xmsGetLongProperty(xmsHObj object,
                         xmsCHAR *propertyName,
                         xmsLONG *propertyValue,
                         xmsHErrorBlock errorBlock);

Get the value of the long integer property identified by name.

Parameters:
object (input)
The handle for the object.
propertyName (input)
The name of the property in the format of a null terminated string.
propertyValue (output)
The value of the property.
errorBlock (input)
The handle for an error block or a null handle.
Thread context:
Determined by the thread context of the object
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

xmsGetObjectProperty – Get Object Property

Interface:
xmsRC xmsGetObjectProperty(xmsHObj object,
                           xmsCHAR *propertyName,
                           xmsSBYTE *propertyValue,
                           xmsINT length,
                           xmsINT *actualLength,
                           xmsOBJECT_TYPE *objectType,
                           xmsHErrorBlock errorBlock);

Get the value and data type of the property identified by name.

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

Parameters:
object (input)
The handle for the object.
propertyName (input)
The name of the property in the format of a null terminated string.
propertyValue (output)
The buffer to contain the value of the property, which is returned as an array of bytes. If the value is a string and data conversion is required, this is the value after conversion.
length (input)
The length of the buffer in bytes. If you specify XMSC_QUERY_SIZE instead, the value of the property is not returned, but its length is returned in the actualLength parameter.
actualLength (output)
The length of the value of the property in bytes. If the value is a string and data conversion is required, this is the length after conversion. If you specify a null pointer on input, the length is not returned.
objectType (output)
The data type of the value of the property, which is one of the following object types:
  • XMS_OBJECT_TYPE_BOOL
  • XMS_OBJECT_TYPE_BYTE
  • XMS_OBJECT_TYPE_BYTEARRAY
  • XMS_OBJECT_TYPE_CHAR
  • XMS_OBJECT_TYPE_DOUBLE
  • XMS_OBJECT_TYPE_FLOAT
  • XMS_OBJECT_TYPE_INT
  • XMS_OBJECT_TYPE_LONG
  • XMS_OBJECT_TYPE_SHORT
  • XMS_OBJECT_TYPE_STRING
errorBlock (input)
The handle for an error block or a null handle.
Thread context:
Determined by the thread context of the object
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

xmsGetProperty – Get Property

Interface:
xmsRC xmsGetProperty(xmsHObj object,
                     xmsCHAR *propertyName,
                     xmsHProperty *property,
                     xmsHErrorBlock errorBlock);

Get a Property object for the property identified by name.

Parameters:
object (input)
The handle for the object.
propertyName (input)
The name of the property in the format of a null terminated string.
property (output)
The handle for the Property object.
errorBlock (input)
The handle for an error block or a null handle.
Thread context:
Determined by the thread context of the object
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

xmsGetShortProperty – Get Short Integer Property

Interface:
xmsRC xmsGetShortProperty(xmsHObj object,
                          xmsCHAR *propertyName,
                          xmsLONG *propertyValue,
                          xmsHErrorBlock errorBlock);

Get the value of the short integer property identified by name.

Parameters:
object (input)
The handle for the object.
propertyName (input)
The name of the property in the format of a null terminated string.
propertyValue (output)
The value of the property.
errorBlock (input)
The handle for an error block or a null handle.
Thread context:
Determined by the thread context of the object
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

xmsGetStringProperty – Get String Property

Interface:
xmsRC xmsGetStringProperty(xmsHObj object,
                           xmsCHAR *propertyName,
                           xmsCHAR *propertyValue,
                           xmsINT length,
                           xmsINT *actualLength,
                           xmsHErrorBlock errorBlock);

Get the value of the string property identified by name.

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

Parameters:
object (input)
The handle for the object.
propertyName (input)
The name of the property in the format of a null terminated string.
propertyValue (output)
The buffer to contain the value of the property. If data conversion is required, this is the value after conversion.
length (input)
The length of the buffer in bytes. If you specify XMSC_QUERY_SIZE instead, the value of the property is not returned, but its length is returned in the actualLength parameter.
actualLength (output)
The length of the value of the property in bytes. If data conversion is required, this is the length after conversion. 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.
Thread context:
Determined by the thread context of the object
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

xmsGetStringPropertyByRef – Get String Property by Reference

Interface:
xmsRC xmsMsgGetStringPropertyByRef(xmsHObj object,
                                   xmsCHAR *propertyName,
                                   xmsCHAR **propertyValue,
                                   xmsINT *length,
                                   xmsHErrorBlock errorBlock);

Get a pointer to the value of the string property identified by name.

For more information about how to use this function, see C functions that return a string or byte array by reference.

Parameters:
object (input)
The handle for the object.
propertyName (input)
The name of the property in the format of a null terminated string.
propertyValue (output)
A pointer to the value of the property. If data conversion is required, this is the value after conversion.

Note that the value of the property must be a string. The function makes no attempt to convert a value with another data type into a string. If an application calls this function to get a pointer to a value that is not a string, XMS returns an error.

length (output)
The length of the value of the property in bytes. If data conversion is required, this is the length after conversion.
errorBlock (input)
The handle for an error block or a null handle.
Thread context:
Determined by the thread context of the object
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

xmsSetBooleanProperty – Set Boolean Property

Interface:
xmsRC xmsSetBooleanProperty(xmsHObj object,
                            xmsCHAR *propertyName,
                            xmsBOOL propertyValue,
                            xmsHErrorBlock errorBlock);

Set the value of the boolean property identified by name.

Parameters:
object (input)
The handle for the object.
propertyName (input)
The name of the property in the format of a null terminated string.
propertyValue (input)
The value of the property.
errorBlock (input)
The handle for an error block or a null handle.
Thread context:
Determined by the thread context of the object
Exceptions:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

xmsSetByteProperty – Set Byte Property

Interface:
xmsRC xmsSetByteProperty(xmsHObj object,
                         xmsCHAR *propertyName,
                         xmsSBYTE propertyValue,
                         xmsHErrorBlock errorBlock);

Set the value of the byte property identified by name.

Parameters:
object (input)
The handle for the object.
propertyName (input)
The name of the property in the format of a null terminated string.
propertyValue (input)
The value of the property.
errorBlock (input)
The handle for an error block or a null handle.
Thread context:
Determined by the thread context of the object
Exceptions:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

xmsSetByteArrayProperty – Set Byte Array Property

Interface:
xmsRC xmsSetByteArrayProperty(xmsHObj object,
                              xmsCHAR *propertyName,
                              xmsSBYTE *propertyValue,
                              xmsINT length
                              xmsHErrorBlock errorBlock);

Set the value of the byte array property identified by name.

Parameters:
object (input)
The handle for the object.
propertyName (input)
The name of the property in the format of a null terminated string.
propertyValue (input)
The value of the property, which is an array of bytes.
length (input)
The number of bytes in the array.
errorBlock (input)
The handle for an error block or a null handle.
Thread context:
Determined by the thread context of the object
Exceptions:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

xmsSetCharProperty – Set Character Property

Interface:
xmsRC xmsSetCharProperty(xmsHObj object,
                         xmsCHAR *propertyName,
                         xmsCHAR16 propertyValue,
                         xmsHErrorBlock errorBlock);

Set the value of the 2-byte character property identified by name.

Parameters:
object (input)
The handle for the object.
propertyName (input)
The name of the property in the format of a null terminated string.
propertyValue (input)
The value of the property.
errorBlock (input)
The handle for an error block or a null handle.
Thread context:
Determined by the thread context of the object
Exceptions:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

xmsSetDoubleProperty – Set Double Precision Floating Point Property

Interface:
xmsRC xmsSetDoubleProperty(xmsHObj object,
                           xmsCHAR *propertyName,
                           xmsDOUBLE propertyValue,
                           xmsHErrorBlock errorBlock);

Set the value of the double precision floating point property identified by name.

Parameters:
object (input)
The handle for the object.
propertyName (input)
The name of the property in the format of a null terminated string.
propertyValue (input)
The value of the property.
errorBlock (input)
The handle for an error block or a null handle.
Thread context:
Determined by the thread context of the object
Exceptions:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

xmsSetFloatProperty – Set Floating Point Property

Interface:
xmsRC xmsSetFloatProperty(xmsHObj object,
                          xmsCHAR *propertyName,
                          xmsFLOAT propertyValue,
                          xmsHErrorBlock errorBlock);

Set the value of the floating point property identified by name.

Parameters:
object (input)
The handle for the object.
propertyName (input)
The name of the property in the format of a null terminated string.
propertyValue (input)
The value of the property.
errorBlock (input)
The handle for an error block or a null handle.
Thread context:
Determined by the thread context of the object
Exceptions:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

xmsSetIntProperty – Set Integer Property

Interface:
xmsRC xmsSetIntProperty(xmsHObj object,
                        xmsCHAR *propertyName,
                        xmsINT propertyValue,
                        xmsHErrorBlock errorBlock);

Set the value of the integer property identified by name.

Parameters:
object (input)
The handle for the object.
propertyName (input)
The name of the property in the format of a null terminated string.
propertyValue (input)
The value of the property.
errorBlock (input)
The handle for an error block or a null handle.
Thread context:
Determined by the thread context of the object
Exceptions:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

xmsSetLongProperty – Set Long Integer Property

Interface:
xmsRC xmsSetLongProperty(xmsHObj object,
                         xmsCHAR *propertyName,
                         xmsLONG propertyValue,
                         xmsHErrorBlock errorBlock);

Set the value of the long integer property identified by name.

Parameters:
object (input)
The handle for the object.
propertyName (input)
The name of the property in the format of a null terminated string.
propertyValue (input)
The value of the property.
errorBlock (input)
The handle for an error block or a null handle.
Thread context:
Determined by the thread context of the object
Exceptions:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

xmsSetObjectProperty – Set Object Property

Interface:
xmsRC xmsSetObjectProperty(xmsHObj object,
                           xmsCHAR *propertyName,
                           xmsSBYTE *propertyValue,
                           xmsINT length,
                           xmsOBJECT_TYPE objectType,
                           xmsHErrorBlock errorBlock);

Set the value and data type of a property identified by name.

Parameters:
object (input)
The handle for the object.
propertyName (input)
The name of the property in the format of a null terminated string.
propertyValue (input)
The value of the property as an array of bytes.
length (input)
The number of bytes in the array.
objectType (input)
The data type of the value of the property, which must be one of the following object types:
  • XMS_OBJECT_TYPE_BOOL
  • XMS_OBJECT_TYPE_BYTE
  • XMS_OBJECT_TYPE_BYTEARRAY
  • XMS_OBJECT_TYPE_CHAR
  • XMS_OBJECT_TYPE_DOUBLE
  • XMS_OBJECT_TYPE_FLOAT
  • XMS_OBJECT_TYPE_INT
  • XMS_OBJECT_TYPE_LONG
  • XMS_OBJECT_TYPE_SHORT
  • XMS_OBJECT_TYPE_STRING
errorBlock (input)
The handle for an error block or a null handle.
Thread context:
Determined by the thread context of the object
Exceptions:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

xmsSetProperty – Set Property

Interface:
xmsRC xmsSetProperty(xmsHObj object,
                     xmsHProperty property,
                     xmsHErrorBlock errorBlock);

Set the value of a property using a Property object.

Parameters:
object (input)
The handle for the object.
property (input)
The handle for the Property object.
errorBlock (input)
The handle for an error block or a null handle.
Thread context:
Determined by the thread context of the object
Exceptions:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

xmsSetShortProperty – Set Short Integer Property

Interface:
xmsRC xmsSetShortProperty(xmsHObj object,
                          xmsCHAR *propertyName,
                          xmsSHORT propertyValue,
                          xmsHErrorBlock errorBlock);

Set the value of the short integer property identified by name.

Parameters:
object (input)
The handle for the object.
propertyName (input)
The name of the property in the format of a null terminated string.
propertyValue (input)
The value of the property.
errorBlock (input)
The handle for an error block or a null handle.
Thread context:
Determined by the thread context of the object
Exceptions:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

xmsSetStringProperty – Set String Property

Interface:
xmsRC xmsSetStringProperty(xmsHObj object,
                           xmsCHAR *propertyName,
                           xmsCHAR *propertyValue,
                           xmsINT length,
                           xmsHErrorBlock errorBlock);

Set the value of the string property identified by name.

Parameters:
object (input)
The handle for the object.
propertyName (input)
The name of the property in the format of a null terminated string.
propertyValue (input)
The value of the property as a character array.
length (input)
The length of the value of the property in bytes. If the value of the property is null terminated with no embedded null characters, you can specify XMSC_CALCULATE_STRING_SIZE instead and allow XMS to calculate its length.
errorBlock (input)
The handle for an error block or a null handle.
Thread context:
Determined by the thread context of the object
Exceptions:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_MESSAGE_NOT_WRITABLE_EXCEPTION

Reference topic

Terms of Use | Rate this page

Last updated: 24 May 2011

(C) Copyright IBM Corporation 2005, 2011. All Rights Reserved.