Altova MapForce Server 2024 Advanced Edition

The following example illustrates how to run a mapping execution file (.mfx) from C++ code. On Windows, the example files are available at the following path: C:\Program Files\Altova\MapForceServer2024\etc\Examples.



Before running the code below, ensure the following prerequisites are met:


MapForce Server is installed and licensed

MapForce Server is available as a COM server object (normally, this process takes place automatically during MapForce Server installation; to check if registration was successful, see About the COM Interface).


Running the mapping code

The code below runs three server execution files (.mfx). The table below lists the input files expected by each .mfx file, and the output that will be created after execution.


Execution file (.mfx)













If you have Altova MapForce, you can optionally take a look at the original mappings from which the .mfx files were compiled in order to understand them better. These are called TokenizeString1.mfd, SimpleTotal.mfd, and ClassifyTemperatures.mfd, respectively. You can find the mappings in the following directory: C:\users\<user>\Altova\MapForce2024\MapForceExamples.


The example below does the following:


It creates a new instance of Altova.MapForceServer.Server. This is the object you will subsequently be working with.

It sets a working directory where execution takes place. Input files are expected to exist in this directory if you referred to them using a relative path. Output files will also be created in this directory (see the table above).

It runs TokenizeString.mfx. The file path is supplied as argument to the Run method (notice that the path is relative to the working directory that was set previously). Upon successful execution, a .csv file representing the mapping output will be created in the working directory.

It runs SimpleTotal.mfx. Again, the file path is relative to the working directory. This mapping produces a string output, so we call the GetOutputParameter method to get the string output.

It runs ClassifyTemperatures.mfx. This mapping expects a parameter as input, which was supplied with the help of the AddParameter method.


// MapForceServerAPI_sample.cpp : Defines the entry point for the console application.
#include <iostream>
#include "atlbase.h"
#ifndef _WIN64
// 32-bit MapForce Server
#import "progid:MapForce.Server"
// 64-bit MapForce Server
#import "progid:MapForce_x64.Server"
int _tmain(int argc, _TCHAR* argv[])
  CoInitialize( NULL );
    // Create a MapForce Server object
    MapForceServerLib::IServerPtr pMFS;
    CoCreateInstance( __uuidof( MapForceServerLib::Server ), NULL, CLSCTX_ALL, __uuidof( MapForceServerLib::IServer ), reinterpret_cast< void** >( &pMFS ) );
    //Set a working directory - used as a base for relative paths (you may need to adapt the path to the installation folder)
    pMFS->WorkingDirectory = "..";   // this is relative to this applications' working directory (the project folder)
    // Default path to the MapForce Server executable is the installation path (same dir with the MapForceServer.dll)
    // In case you moved the binaries on the disk, you need to explicitly set the path to the .exe file
    // pMFS.ServerPath = "C:\\Program Files (x86)\\Altova\\MapForceServer2024\\bin\\MapForceServer.exe";
    // pMFS.ServerPath = "C:\\Program Files\\Altova\\MapForceServer2024\\bin\\MapForceServer.exe";
    //Set global resource file and configuration, if your mapping uses global resources
    //pMFS->SetOption( "globalresourcefile", "GlobalResources.xml" ); // "gr" can be used as short name for "globalresourcefile"
    //pMFS->SetOption( "globalresourceconfig", "Default" ); // "gc" can be used as short name for "globalresourceconfig"
                // ----------------------------------------------------------------------------------
          // An example with input and output paths stored inside the MFX file
    std::cout << "\nExecuting TokenizeString.mfx..." << std::endl;
    if ( pMFS->Run( "TokenizeString.mfx" ) == VARIANT_TRUE )
        std::cout << "Successfully generated file 'AltovaToolFeatures.csv'." << std::endl;
        // execution failed. maybe no write permissions in working directory? Run this program as administrator.
        std::cout << pMFS->LastExecutionMessage << std::endl;
    // ----------------------------------------------------------------------------------
    // An example creating a simple output so that we can retrieve the result explicitly
    std::cout << "\nExecuting SimpleTotal.mfx..." << std::endl;
    if ( pMFS->Run( "SimpleTotal.mfx" ) )
        std::cout << "Mapping result is: " + pMFS->GetOutputParameter( "total" ) << std::endl;
        // execution failed (e.g. somebody deleted file ipo.xml)
        std::cout << pMFS->LastExecutionMessage << std::endl;
    // ----------------------------------------------------------------------------------
    // an example with parameterized input
    // the default of 'lower = 5' gets changed to the value '10'
    // mfx reads file Temperatures.xml and writes its output to Temperatures_out.xml.
    std::cout << "\nExecuting ClassifyTemperatures.mfx with parameter 'lower' set to '10' ..." << std::endl;
    pMFS->AddParameter("lower", "10");
    if ( pMFS->Run( "ClassifyTemperatures.mfx" ) )
        std::cout << "File Temperatures_out.xml has been written successfully." << std::endl;
        // execution failed. maybe no write permissions in working directory? Run this program as administrator.
        std::cout << pMFS->LastExecutionMessage << std::endl;
  catch (_com_error& err )
    BSTR bstrMessage;
    (err).ErrorInfo()->GetDescription( &bstrMessage );
    std::cout << "Exception occurred: " << _com_util::ConvertBSTRToString( bstrMessage ) << std::endl;
  return 0;

© 2018-2024 Altova GmbH