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 have an impact on performance.
To deliver better performance in this situation, the C API provides another set of functions. 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.
Because these functions return a pointer to memory owned by XMS, the application must not attempt to free or modify the contents of this memory. Attempting to do so might cause unpredictable results.
The pointer returned to the application remains valid until the XMS object, with which the string or byte array is associated, is deleted. The application must copy the string or byte array if it needs the data after the object is deleted.