xlFree
Applies to: Excel 2013 | Office 2013 | Visual Studio
Used to free memory resources allocated by Microsoft Excel when creating the return value XLOPER/ XLOPER12 in a call to Excel4, Excel4v, Excel12, or Excel12v. The xlFree function frees the auxiliary memory and resets the pointer to NULL but does not destroy other parts of the XLOPER/ XLOPER12.
Excel4(xlFree, 0, n, LPXLOPER px_1, ..., LPXLOPER px_n);
Excel12(xlFree, 0, n, LPXLOPER12 px_1, ..., LPXLOPER12 px_n);
Parameters
px_1, ..., px_n
One or more XLOPER/ XLOPER12s to be freed. In Excel versions up to 2003, the maximum number of pointers that can be passed is 30. Starting in Excel 2007, this is increased to 255.
Property value/Return value
This function does not return a value.
Remarks
You must free every XLOPER that you get as a return value from Excel4 or Excel4v and every XLOPER12 that you get as a return value from Excel12 or Excel12v if they are one of the following types: xltypeStr, xltypeMulti, or xltypeRef. It is always safe to free other types even if they do not use auxiliary memory, as long as you got them from Excel4 or Excel12.
Where you are returning to Excel a pointer to an XLOPER/ XLOPER12 that still contains Excel-allocated memory to be freed, you must set the xlbitXLFree to ensure Excel releases the memory.
Example
This example calls GET.WORKSPACE(1) to return the platform on which Excel is currently running as a string. The code copies this returned string into a buffer for later use. The code places the buffer back into the XLOPER12 for later use with the Excel function. Finally, the code displays the string in an alert box.
\SAMPLES\EXAMPLE\EXAMPLE.C
short WINAPI xlFreeExample(void)
{
XLOPER12 xRes, xInt;
XCHAR buffer[cchMaxStz];
int i,len;
// Create an XLOPER12 for the argument to Getworkspace.
xInt.xltype = xltypeInt;
xInt.val.w = 1;
// Call GetWorkspace.
Excel12f(xlfGetWorkspace, &xRes, 1, (LPXLOPER12)&xInt);
// Get the length of the returned string
len = (int)xRes.val.str[0];
//Take into account 1st char, which contains the length
//and the null terminator. Truncate if necessary to fit
//buffer.
if (len > cchMaxStz - 2)
len = cchMaxStz - 2;
// Copy to buffer.
for(i = 1; i <= len; i++)
buffer[i] = xRes.val.str[i];
// Null terminate, Not necessary but a good idea.
buffer[len] = '\0';
buffer[0] = len;
// Free the string returned from Excel.
Excel12f(xlFree, 0, 1, &xRes);
// Create a new string XLOPER12 for the alert.
xRes.xltype = xltypeStr;
xRes.val.str = buffer;
// Show the alert.
Excel12f(xlcAlert, 0, 1, (LPXLOPER12)&xRes);
return 1;
}