xlFree

This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This page may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.

Used to free memory resources allocated by Microsoft Office 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. In Microsoft Office 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;
}

See Also

Concepts

C API Functions That Can Be Called Only from a DLL or XLL