XLL+ Class Library

Function attribute: cacheresults

The cacheresults attribute controls whether the results of a function are cached.

You can control the value of the attribute with the Cache Results command on the Function menu of the XLL+ AppWizard. This item also appears on the drop-down menu of the Edit Function Attributes tool-button.

You can also edit the value for the current function in the Edit Function Attributes window. The window can also be used to set the default value of the attribute, which will then be applied to all new functions.

Impact

If the flag is set to true the function header will include lines like the following:

    CXlCacheBinding<XLP_CACHE_CLASS> bind__(XllGetTypedApp()->m_cache, 
        xloResult, "FunctionName", &FirstArg, true);
    if (bind__.Find())
        return bind__.Ret();

The impact of this code is as follows:

  1. An object of type CXlCacheBinding is constructed at local function scope. The constructor is passed a pointer to the function's first argument and uses this pointer to iterate through the function's arguments, serializing them all into a single byte array. The lifetime of the object is important: it will be destroyed just before the function returns.
  2. The CXlCacheBinding::Find() method searches the cache for a result matching the supplied serialized inputs. If the function has been called before with precisely these inputs then Find() will return true, and will populate the attached CXlOper (xloResult) with the contents of the stored result.
  3. If Find() succeeds, then the function returns immediately, using the CXlCacheBinding::Ret() method. This method is important, since it disables the destructor of the CXlCacheBinding object, which will otherwise take further action before the function returns.
  4. At the very end of the function, after CXlOper::Ret(), CXlOper::RetString() or CXlOper::RetError() has been called, but before the function returns, the destructor of the CXlCacheBinding object will add the result of the function to the cache.

Adding a cache with the AppWizard

You can add a cache to a new add-in project by selecting the "Results cache" option in the XLL+ AppWizard. See XLL+ AppWizard for Visual Studio 6 or XLL+ AppWizard for Visual Studio .NET & Visual Studio 2005 for more information.

Adding a cache using code

If you have already created a project, and you wish to add a cache, follow these steps:

  1. Include xlserialize.h in your project header file, after the line that includes xllplus.h.

    #include <xlserialize.h>
    
  2. Add a public variable m_cache of type CXlOperCache to your project class.

    class CAvgOptApp : public CXllApp
    {
    public:
        CAvgOptApp();
    
    // Names
    public:
        static LPCSTR m_pszDefName;
    
    // Data                   
        CXlOperCache m_cache; 
    
    // Overrides
        // ClassWizard generated virtual function overrides
        ...
    };
  3. If your header file does not contain a definition of XllGetTypedApp(), then add one, as in the following example.

    CAvgOptApp* XllGetTypedApp() { return (CAvgOptApp*)::XllGetApp(); }
    

    The function will be used by code generated by the XLL+ Function Wizard.

See Also

Function Wizard | Cache Results command | CXlOperCache class