WebSphere WebSphere Business Integration Message Service Clients for C/C++ Version 1.2.7 and .NET Version 1.2.6 Operating Systems: AIX, Linux, Solaris, 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. The following example C code illustrates the function, 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.

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. Strings containing embedded nulls cannot be manipulated using the standard C string manipulator because they read the first null character to be the end of the string.


Concept topic

Terms of Use | Rate this page

Last updated: 18 Jun 2008

© Copyright IBM Corporation 2005, 2008. All Rights Reserved.