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

C functions that return a string by value

This topic describes the interface used by C functions that return a string by value.

In the C API, certain functions return a string as a parameter. Each of these functions uses the same interface for retrieving a string. Here is an example of one of these functions, xmsGetStringProperty() in the PropertyContext class:
xmsRC xmsGetStringProperty(xmsHObj object,
                           xmsCHAR *propertyName,
                           xmsCHAR *propertyValue,
                           xmsINT length,
                           xmsINT *actualLength,
                           xmsHErrorBlock errorBlock);
Three parameters control the retrieval of a string:
propertyValue
This parameter is a pointer to a buffer provided by the application into which XMS copies the characters in the string. If data conversion is required, XMS converts the characters into the code page used by the application before copying them into the buffer.
length
This parameter is the length of the buffer in bytes. This is an input parameter that must be set by the application before the call. If you specify XMSC_QUERY_SIZE instead, the string is not returned, but its length is returned in the actualLength parameter.
actualLength
This output parameter is the length of the string that XMS copies into the buffer. If data conversion is required, this is the length after conversion. The length is measured in bytes. XMS always returns a null terminated string, and the length reported to the application includes the terminating null character. If you specify a null pointer for this parameter on input, the length of the string is not returned.

If the buffer is not large enough to store the whole string, including the terminating null character, XMS returns the string truncated to the length of the buffer, sets the actualLength parameter to the length of the whole string, and returns error code XMS_E_DATA_TRUNCATED.

Note that, if an XMS application receives a message sent by a JMS application, strings in the header fields, properties, and body of the message might contain embedded null characters. You cannot use the standard C string manipulation functions to process strings containing embedded nulls because these functions assume that the first null character in a string marks the end of the string.


Concept topic

Terms of Use | Rate this page

Last updated: 7 Dec 2005

© Copyright IBM Corporation 2005. All Rights Reserved.