Accept all the default choices in the Wizard's pages.

Transcription

1 XLL+ Overview XLL+ is a C++ add-in which assists users in creating Excel add-in components. Two key components assist developers in creating Excel add-ins more quickly and requiring less debugging: AppWizard creates complete Visual Studio projects, ready to compile and run XLL+ Function Wizard helps you write and maintain Excel add-in functions, and generates most of the code for you Getting Started 1. Start Microsoft Visual C Use the XLL+ AppWizard to create a new project (Click File -> New). Choose the XLL+ AppWizard 4, and type in a Project Name. Accept all the default choices in the Wizard's pages.

2 3. Use the New XLL+ Function ( ) tool to create a new add-in function. Fill in the function's name and description, and press OK. 4. In the XLL+ Function Wizard, add the names types and descriptions of your function's arguments, and press OK.

3 5. In DevStudio, add your own code to the skeleton generated by the Wizard, then build and test your project. For example, you might add the line of code shown below: extern "C" declspec( dllexport ) LPXLOPER EDateDiff(double StartDate, double EndDate, const char* Country) CXlOper xloresult; //XLP_SRC // TODO - Set the value of xloresult xloresult = 99.9; return xloresult.ret(); Writing an XLL+ Function The next step is to add an Excel Add-in function, using the XLL+ Function Wizard. In this example, we're going to write a function to return the cumulative normal (Gaussian) distribution. Note: Readers familiar with Excel may ask why we are writing a cumulative normal distribution function when Excel already contains the NORMSDIST() function. There are two reasons: 1. NORMSDIST() is inaccurate at extreme values, and the inverse function NORMSINV() fails beyond 5 standard deviations. 2. It makes a good example function. It is good practise to put all important business functions in separate functions that are not Excel-dependent. If you do this, you will be able to reuse the code unchanged in other environments. That is what we will do here. The code for 'stand-alone' implementations of the cumulative normal distribution and its inverse is shown below. Code for stand-alone functions The Normal() and CumNormal() functions cannot fail, so they simply return their result. InverseCumNormal() can fail if the input is out of range, so it returns 1 for success and 0 for failure. The inverted value is passed back via the pointer result. #include <math.h> // Normal distribution function double Normal(double x) #define SQRT2PI return exp(-x * x / 2.0) / SQRT2PI; // Cumulative normal distribution function double CumNormal(double x)

4 #define gamma #define a #define a #define a #define a #define a double k; if (x < 0.0 ) return CumNormal(-x); else k = 1.0 / (1.0 + gamma * x); return Normal(x) * ((((a5 * k + a4) * k + a3) * k + a2) * k + a1) * k; // Inverse cumulative normal function // Returns 1 for success, 0 for failure int InverseCumNormal(double u, double* result) int i; double Y, num, den; static double p[] = , -1.0, , , ; static double q[] = , , , , ; if (u <= 0.0 u >= 1.0) return 0; if (fabs(u - 0.5) < 10e-8) *result = 0.0; return 1;

5 if (u < 0.5) InverseCumNormal(1.0 - u, result); *result *= -1.0; return 1; Y = sqrt(-log((1.0 - u)*(1.0 - u))); num = p[4]; den = q[4]; for (i=3; i>=0; i--) num = num*y + p[i]; den = den * Y + q[i]; *result = Y + num / den; return 1; Adding the stand-alone functions In DevStudio, open the file Tutorial1.cpp, and add the code above at the end of the file. Tip: It is a very bad idea to type in all the code shown above. You can copy it from here and paste into your source file, or you can find all the code for this tutorial in the Samples/Tutorial1 sub-directory. All the important code is now written. All we need to do is to generate the Excel add-in function, and plug it into a stand-alone function. The next step is to use the XLL+ Function Wizard to generate the code for the Excel add-in function NORMSDIST2(). Select a source file Make sure that Developer Studio is open and that Tutorial1 is the active project. Open or activate the file Tutorial1.cpp. Invoke the Function Wizard In Developer Studio, using the XLL+ Toolbar, click on the New Function tool. This will start the Function Wizard. Enter function details

6 In the Add New Function dialog, fill in the name, category and description of the function as follows: Name: NORMSDIST2 Category: Statistical Description: Returns the standard normal cumulative distribution function (has a mean of zero and a standard deviation of one) What do these fields mean? Name The name you enter here will be used as the name of the function visible in Excel and also as the name of the C++ function that implements the add-in function. Category When the function appears in Excel's Formula Wizard, it will appear under the category you enter here. Description This description will appear in Excel's Formula Wizard. It will also be inserted into your C++ code as part of the function's header comment. After you click on OK, the main Function Wizard dialog will appear, so that you can enter the other details of the new add-in function. The Function Wizard Once we enter the function name, category and description, the main Function Wizard dialog will appear, as below. You can see that we've created our new function, but it has no arguments as yet, and still has the wrong return type. Set return type NORMSDIST2 is a very simple function, that takes one numeric argument and returns a numeric result. To reflect this, select the Returns combo-box and set its value to Double (i.e. double-precision floating-point number), as shown below. Add an argument The next thing we need to do is add an argument. In the first column of the empty row in the arguments grid, type the argument name Z, as shown below. As you move off the cell, the rest of the row will be populated with the default values for the new argument, Z.

7 Set argument description Fill in the description column, as follows: Z is the value for which you want the distribution The columns describing the argument should now contain the following: Name: Z Type: Dimensions: Double Scalar Description: Z is the value for which you want the distribution We have now finished specifying our add-in function. Click on the OK button to dismiss the Wizard and update the source code. Code generated by the wizard As you return to DevStudio, you will see that the wizard will has inserted the following source code at the end of your C++ file. // Function: NORMSDIST2 // Purpose: Returns the standard normal cumulative distribution function (has a mean of zero and a standard deviation of one) //XLP_SRC(NORMSDIST2) // NOTE - the FunctionWizard will add and remove mapping code here. // DO NOT EDIT what you see in these blocks of generated code! IMPLEMENT_XLLFN2(NORMSDIST2, "BB", "NORMSDIST2", "Z", "Statistica" "l", "Returns the standard normal cumulative distribution" " function (has a mean of zero and a standard deviation of" " one)", "Z is the value for which you want the distribution", "\0", 1) extern "C" declspec( dllexport ) double NORMSDIST2(double Z) //XLP_SRC // TODO - Calculate and return the result return 0; In the following sections, we'll examine all this code. Delimiters The first thing to notice are the comments that delimit the generated code: //XLP_SRC(NORMSDIST2) // NOTE - the FunctionWizard will add and remove mapping code here.

8 // DO NOT EDIT what you see in these blocks of generated code!... //XLP_SRC The Function Wizard "owns" all the code between the delimiters. Everything between these comments is liable to be written over if you use the Function Wizard again to change the function in any way. Be very careful to make your changes outside these delimiters. Macro The next section of interest is the IMPLEMENT_XLLFN2(...) macro: IMPLEMENT_XLLFN2(NORMSDIST2, "BB", "NORMSDIST2", "Z", "Statistica" "l", "Returns the standard normal cumulative distribution" " function (has a mean of zero and a standard deviation of" " one)", "Z is the value for which you want the distribution", "\0", 1) This macro contains all the information you typed into the Function Wizard. At run-time, the XLL+ runtime library will pass all this data to Excel, in order to register your function and to tell Excel about its arguments. (Again, be careful not to alter it yourself.) Declaration The next line exports the function and ensures that the exported name of the function is not mangled. extern "C" declspec( dllexport ) The declaration of the function follows. We have a complete skeleton of the function; now we need to add some useful code. Adding some useful code Add code to the function to call our stand-alone function, as shown below: extern "C" declspec( dllexport ) double NORMSDIST2(double Z) //XLP_SRC return CumNormal(Z); That's it. We're now ready to build and test our add-in function. Results This topic shows you how to return a 1-dimensional array to Excel. The example is a very simple function for sorting numeric arrays in ascending order. Use the Function Wizard to create a new function with these properties:

9 Name: Category: SORTVECTOR Lookup & Reference Description: Sort a vector of numbers in ascending order Add a single argument with the following properties: Name: Vector Type: Dimensions: Double Vector Description: Unsorted vector of numbers Press OK to return to DevStudio. Add code so that your add-in function looks like this: // Function: SORTVECTOR // Purpose: Sort a vector of numbers in ascending order //XLP_SRC(SORTVECTOR) // NOTE - the FunctionWizard will add and remove mapping code here. // DO NOT EDIT what you see in these blocks of generated code! IMPLEMENT_XLLFN2(SORTVECTOR, "RP", "SORTVECTOR", "Vector", "Lookup & Reference", "Sort a vector of numbers in ascending" " order", "Unsorted vector of numbers", "B()Vector Unsorted" " vector of numbers\0", 1) extern "C" declspec( dllexport ) LPXLOPER SORTVECTOR(const COper* Vector) CXlOper xloresult; BOOL bok = TRUE; std::vector<double> vecvector; bok = bok && Vector->ReadVector(vecVector, "Vector", xloresult); if (!bok) return xloresult.ret(); //XLP_SRC // Use STL algorithm to sort input std::sort(vecvector.begin(), vecvector.end()); // Copy the sorted vector to xloresult xloresult = vecvector; return xloresult.ret(); Yet another overload of the CXlOper assignment operator is used to copy the STL vector into xloresult: xloresult = vecvector; The operator creates an array of values within xloresult and populates it with the values in vecvector. This is one of the most pleasingly simple add-in functions in this tutorial. It is not necessarily very useful - a better implementation would sort a 2-dimensional array by a given column or columns, in ascending and descending order - but it is very short, and does a surprising amount of work in its two lines of hand-written code.

10 To make use of the SORTVECTOR function, you need to know how to enter array formulae in Excel. If you are already familiar with Excel array formulae, please skip to the next section. To enter an array formula in Excel, follow these steps: 1. Select the cells which will jointly contain the array formula. 2. Type in the cells' formula. 3. Press Ctrl+Shift+Enter - i.e. hit the Enter key, while holding down the Control and Shift keys. You can recognize an array formula, because it is shown in Excel surrounded by curly braces... Note: You do not have to type in the curly braces. Excel adds these for you, if you use Ctrl+Shift+Enter to signify an array formula. The example below shows the SORTVECTOR function is use in an array formula. Returning a matrix to Excel is very similar to returning a vector. Add the following stand-alone matrix function to Tutorial1.cpp. Note: This is a very silly add-in function. Transformations of this kind are far easier to do in Excel itself, especially if you use a mixture of relative and absolute addresses. But it makes a reasonably good example function. // Multiplication of two vectors to produce a matrix // aadz should be an array of cx pointers to columns void MatrixMultiply(int cx, double* adx, int cy, double* ady, double** aadz) int i, j; for (i = 0; i < cx; i++) for (j = 0; j < cy; j++) aadz[i][j] = adx[i] * ady[j]; Note that argument aadz is an array of pointers to columns. Use the Function Wizard to create a new function MATRIXMULT: Modify the generated code so that it looks like this: extern "C" declspec( dllexport ) LPXLOPER MATRIXMULT(const COper* X, const COper* Y) CXlOper xloresult;

11 BOOL bok = TRUE; std::vector<double> vecx; bok = bok && X->ReadVector(vecX, "X", xloresult); std::vector<double> vecy; bok = bok && Y->ReadVector(vecY, "Y", xloresult); if (!bok) return xloresult.ret(); //XLP_SRC // Allocate a matrix with initial size rows = vecy.xsize() and cols = vecx.size() xlp::matrix<double> matresult(vecy.size(), vecx.size()); // Get an array of column pointers from the matrix std::vector<double*> vecresult; matresult.get_col_ptrs(vecresult); // Pass the input and output arrays to the stand-alone function MatrixMultiply(vecX.size(), vecx.begin(), vecy.size(), vecy.begin(), vecresult.begin()); // Populate xloresult with the resulting matrix xloresult = matresult; return xloresult.ret(); Here we've made use of the matrix class to manage the output array. The matrix constructor allocates an appropriate number of rows and columns, which are initially filled with zeroes. We also use the matrix::get_col_ptrs() method to populate an array of column pointers, as required by MatrixMultiply(). Populating xloresult with the result of MatrixMultiply() is very simple: we use another CXlOper overloaded assignment operator to allocate the output data and to copy in the contents of matresult. Sometimes your results will not be in ready-made vector or matrix form, and you'll need to use a different CXlOper method to populate xloresult. CXlOper::FromDoubleArray The simplest method to use is CXlOper::FromDoubleArray(), to populate the xloresult, using an array of values or of pointers to rows/columns of values. The various different versions of this method are listed below: FromDoubleArray(double *pd, USHORT cpoints) Create a one-column array and populate it with the supplied data points. FromDoubleArray(double *pd, USHORT crows, USHORT ccols, BOOL bbyrows)

12 Create a two-dimensional array and populate it with the supplied continuous data array. The bbyrows argument will decide whether rows (TRUE) or columns (FALSE) are kept together. FromDoubleArray(double **apd, USHORT crows, USHORT ccols, BOOL bbyrows) Create a two-dimensional array and populate it with the supplied data, which consists of an array of column or row pointers, depending on the value of bbyrows. CXlOper::AllocArray A more complex way to populate an array result is by using CXlOper::AllocArray() to create the array, and then CXlOper::Cell() to populate each cell. While this method involves more programming, it gives you full control over the output, and allows you to have mixed data types in the array. See the CXlOper::AllocArray() example for an example of this technique.