XLL+ Class Library (7.0)

XlpGen utility

Overview

XLPGEN.EXE is a command line utility that can be used to generate C++ code for XLL add-in functions from XML files containing function definitions. It can be used as part of an automated build process.

The utility can be found in the bin sub-directory of the XLL+ installation.

Usage

XLPGEN options
        

Options

Option Description
-i InputFile Required. File name (including path) of XML file.
-t SettingsFile Optional. Full name of template settings file.
-o OutputFile Optional. Full path of output file. If omitted, the output will be directed to standard output.
-d TargetDirectory Optional. The directory to which output file will be written. Ignored if -o is used and is rooted, or if -o is not used. The default value is the directory containing InputFile. If present and not rooted, it will be treated as relative to directory containing InputFile.
-c HeaderFile Optional. The specified header file will be added to the head of the output file in a #include statement, surrounded by quotes, e.g. #include "myfile.h". Multiple header files can be specified, separated by semi-colons.
-g HeaderFile Optional. The specified header file will be added to the head of the output file in a #include statement, surrounded by angle brackets, e.g. #include <myfile.h>. Multiple header files can be specified, separated by semi-colons.
-e ExtensionFile Optional. The full path to an extension file used by the add-in functions, e.g.: -e "C:\Program Files\Planatech\XllPlus\6.0\VS8.0\Include\Extensions\StringPtrHandles.xpe". Each extension file used by the add-in functions must be supported by a separate -e option.
-a true or false Optional. If false, no header will be written to output file.
-n true or false Optional. If true, no logo will be displayed. If false or omitted, the program version information will be written to standard output.
-h Optional. Shows help. No other action takes place and the C++ code file is not generated.

Exit codes

Exit code Description
0 Program completed successfully.
1 A command line argument contained an error.
2 An error occurred while the program was running.

Example

XLPGEN -i C:\Files\MyAddin\MyLib.xml -o MyLib_gen.cpp

See also the code and the project's custom tool settings in the XlpGenDemo sample project.

Input format

The input file contains definitions of function signatures in the standard export format, and can also optionally contain the code that will be inserted into the generated functions.

The XML code below contains a complete function, including the code that will be inserted into the generated add-in function.

CopyXML
<?xml version="1.0" encoding="utf-8"?> 
<Project xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> 
  <Functions> 
    <XlFunction Flags="HideInFormulaWizard DoNotCatchStructuredExceptions"  
                ExportedName="MyAdd" Category="14" Description="Adds two numbers"  
                SourceFile="C:\Source\XlpGenDemo\XlpGenDemo.cpp" SourceLine="90"  
                CategoryForLocale="User Defined" CategoryUSEnglish="User Defined"  
                SafeName="MyAdd"> 
      <Arguments> 
        <XlArgument Name="x" Description="is a number"> 
          <Signature Type="Double"> 
            <Bounds /> 
            <ExtendedParameters /> 
          </Signature> 
        </XlArgument> 
        <XlArgument Name="y" Description="is a number"> 
          <Signature Type="Double"> 
            <Bounds /> 
            <ExtendedParameters /> 
          </Signature> 
        </XlArgument> 
      </Arguments> 
      <Extensions /> 
      <Enums /> 
    </XlFunction> 
  </Functions> 
  <CodeBodies> 
    <CodeBody ExportedName="MyAdd"> 
      <InsertedCode>    xloResult = x + y;</InsertedCode> 
    </CodeBody> 
  </CodeBodies> 
</Project>

Notice that there are two sections within the main Project element: Functions contains the definitions of the function signatures and CodeBodies contains the actual code that will be inserted within the generated function. The two parts are paired together by their matching ExportedName attribute.

Hint: If you need to see how the XML for a particular feature is expressed, and you cannot find sufficient detail in the schema, you should use the XLL+ Function Wizard to set up a function's signature and features and then use the Export to XML command and inspect the resulting XML.

Generated code

In this case the following code (or something similar) will be generated:

CopyC++
// Generated by XlpGen tool at 21/01/2013 4:32:05 PM. 
#ifdef XLL_LIB_MFC
#include "stdafx.h" 
#endif 
#include <xllplus.h> 
 
// Function:    MyAdd 
// Purpose:     Adds two numbers 
 
//{{XLP_SRC(MyAdd) 
    // NOTE - the FunctionWizard will add and remove mapping code here. 
    //    DO NOT EDIT what you see in these blocks of generated code! 
 
#pragma region MyAdd support code
IMPLEMENT_XLLFN4(MyAdd, MyAdd_4, MyAdd_12, "RBB", "UBB", L"MyAdd", 0, L"x,y", 0,
    L"14", 0, L"Adds two numbers", 0, L"is a number\0is a number\0", 0, 0, 
    L"{MyAdd,,,Adds two numbers,14,1,258,U,{{0,{x,Double,0,,is a number,,,,}},"
    L"{0,{y,Double,0,,is a number,,,,}}},{},3,,0,0,,,,0,0}", 1, 0, 0)
CXlOper* MyAdd_Impl(CXlOper&, double, double);
extern "C" __declspec(dllexport)
LPXLOPER12 MyAdd_12(double x, double y)
{
    XLL_FIX_STATE;
    CXlOper xloResult;
    if (CXllApp::IsInFormulaWizard())
    {
        xloResult = xlerrNA;
        return xloResult.Ret12();
    }
    try {
        xloResult.HandleResult(MyAdd_Impl(xloResult, x, y));
    }
    catch(const CXlRuntimeException& ex) {
        CXllApp::Instance()->DisplayException(xloResult, ex);
    }
    XLP_CATCH_CLR_EXCEPTIONS_TO(xloResult)
    return xloResult.Ret12();
}
extern "C" __declspec(dllexport)
LPXLOPER4 MyAdd_4(double x, double y)
{
    XLL_FIX_STATE;
    CXlOper xloResult;
    if (CXllApp::IsInFormulaWizard())
    {
        xloResult = xlerrNA;
        return xloResult.Ret4();
    }
    try {
        xloResult.HandleResult(MyAdd_Impl(xloResult, x, y));
    }
    catch(const CXlRuntimeException& ex) {
        CXllApp::Instance()->DisplayException(xloResult, ex);
    }
    XLP_CATCH_CLR_EXCEPTIONS_TO(xloResult)
    return xloResult.Ret4();
}

#pragma endregion

CXlOper* MyAdd_Impl(CXlOper& xloResult, double x, double y)
{

    xloResult = x + y;
    return xloResult.Ret();
}
    // End of generated code 
//}}XLP_SRC

The first few lines of the generated code contain header information, which is included once only at the top of an output file. The source for this code can be found in the header template, XlpGen_Header.tpl. Note that any additional header files which are specified on the command line (using the -c or -p options) will be included here.

The header lines are followed by the code for each function. Notice that the code from the matching CodeBody element is inserted into the body of the implementation function (MyAdd_Impl).

Requirements

Visual Studio version: 2005 or above
XLL+ version: 7.0.4 or above