If the return value is a string, then there is a technique for converting the "Pointer to a Null terminated string" into an Esl string, this technique is demonstrated in the OSUTIL routine "OS_QueryEnvironment". To complete the conversion, two functions from the ESLLIB.DLL are required;

•EslPtrStrLen

•EslSetStringValue

The first task is to determine the length of the string being returned using EslPtrStrLen, then the copy the characters to the Esl string using EslSetStringValue function. Below is a sample routine which demonstrates the technique:

Please note the use of the OS_ prefix to the function name, this matches the function prototypes defined in the OSUTIL.INC.

When a function returns a string, it is important that the memory allocated to the string is freed once it has been copied to an Esl string. In the routine "OS_QueryEnvironment", you will notice that a call to "OS_FreeEnvironmentStrings" is performed once the environment strings have been copied. Failure to free the memory associated with a string will result in a memory leak, which could be significant if the calls to the function are repeated.