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 or byte array by reference

This topic describes the interface used by C functions that return a string or byte array by reference.

When a C application calls one of the functions described in C functions that return a string by value or C functions that return a byte array by value, XMS must copy the string or byte array into the buffer provided by the application. If an application is processing a large volume of messages, and the strings or byte arrays in the messages are very large, then the time taken to copy them might affect performance.

The C API has functions to deliver better performance. When an application calls one of these functions, one parameter returns a pointer to a string or byte array that is stored in memory owned by XMS, and another parameter returns the length of the string or byte array. Examples of these functions are xmsBytesMsgReadBytesByRef() and xmsGetStringPropertyByRef().

If data conversion is required for a string, XMS converts the characters into the code page of the application and returns a pointer to the converted string. The length returned to the application is the length of the converted string.

If data conversion is required, the first time an application retrieves a string by reference might take as long as retrieving the string by value. However, XMS caches the converted string and so subsequent calls to retrieve the same string do not take as long.

Note: These functions return a pointer to memory owned by XMS. You must not attempt to free or modify the contents of this memory as doing so will cause unpredictable results.

The pointer returned to the application remains valid until the next time that the application adds a new piece of data to the bytes message.


Concept topic

Terms of Use | Rate this page

Last updated: 18 Jun 2008

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