Altova MapForce 2024 Enterprise Edition

Accessing the API

To access the MapForce COM API, a new instance of the Application object must be created in your application (or script). Once this object is created, you can interact with MapForce by invoking its methods and properties as required (for example, create a new document, open an existing document, generate mapping code, etc).

Prerequisites

To make the MapForce COM object available in your Visual Studio project, add a reference to the MapForce type library (.tlb) file. The following instructions are applicable to Visual Studio 2013, but are similar in other Visual Studio versions:

1.On the Project menu, click Add Reference.

2.Click Browse and select the MapForce.tlb file located in the MapForce installation folder.

A sample MapForce API client in C# is available at: C:\Users\<username>\Documents\Altova\MapForce2024\MapForceExamples\API\C#.

In Java, the MapForce API is available through Java-COM bridge libraries. These libraries are available in the MapForce installation folder: C:\Program Files (x86)\Altova\MapForce2024\JavaAPI (note this path is valid when 32-bit MapForce runs on 64-bit Windows, otherwise adjust the path accordingly).

•AltovaAutomation.dll: a JNI wrapper for Altova automation servers

•AltovaAutomation.jar: Java classes to access Altova automation servers

•MapForceAPI.jar: Java classes that wrap the MapForce automation interface

•MapForceAPI_JavaDoc.zip: a Javadoc file containing help documentation for the Java API

To allow access to the MapForce automation server directly from Java code, the libraries above must be in the Java classpath.

A sample MapForce API client in Java is available at: C:\Users\<username>\Documents\Altova\MapForce2024\MapForceExamples\API\Java.

In scripting languages such as JScript or VBScript, the MapForce COM object is accessible through the Microsoft Windows Script Host (see https://msdn.microsoft.com/en-us/library/9bbdkx3k.aspx). Such scripts can be written with a text editor, and do not need compilation, since they are executed by the Windows Script Host packaged with Windows. (To check that the Windows Script Host is running, type wscript.exe /? at the command prompt). Several JScript example files that call the MapForce API are available at: C:\Users\<username>\Documents\Altova\MapForce2024\MapForceExamples\API\JScript.

Note:

For 32-bit MapForce, the registered name, or programmatic identifier (ProgId) of the COM object is MapForce.Application. For 64-bit MapForce, the name is MapForce_x64.Application. Be aware, though, that the calling program will access the CLASSES registry entries in its own registry hive, or group (32-bit or 64-bit). Therefore, if you run scripts using the standard command prompt and Windows Explorer on 64-bit Windows, the 64-bit registry entries will be accessed, which point to the 64-bit MapForce. For this reason, if both MapForce 32-bit and 64-bit are installed, special handling is required in order to call the 32-bit MapForce. For example, assuming that Windows Scripting Host is the calling program, do the following:

1.Change the current directory to C:\Windows\SysWOW64.

2.At the command line, type wscript.exe followed by the path to the script that you would like to run, for example:

wscript.exe "C:\Users\...\Documents\Altova\MapForce2024\MapForceExamples\API\JScript\start.js"

Guidelines

The following guidelines should be considered in your client code:

•Do not hold references to objects in memory longer than you need them. If a user interacts between two calls of your client, then there is no guarantee that these references are still valid.

•Be aware that if your client code crashes, instances of MapForce may still remain in the system. For details on how to avoid error messages, see Error handling.

•Free references explicitly, if using languages such as C++.

Creating the Application object

The syntax to create the starting Application object depends on the programming language, as shown in the examples below:

// Create a new instance of MapForce via its automation interface.
MapForceLib.Application objMapForce = new MapForceLib.Application();

Java

// Start MapForce as COM server.
com.altova.automation.MapForce.Application objMapForce = new Application();
// COM servers start up invisible so we make it visible
objMapForce.setVisible(true);

JScript

// Access a running instance, or create a new instance of MapForce.

try

{

objMapForce = WScript.GetObject ("", "MapForce.Application");

// unhide application if it is a new instance

objMapForce.Visible = true;

}

catch(err) { WScript.Echo ("Can't access or create MapForce.Application"); }

VBA

' Create a new instance of MapForce.
Dim objMapForce As Application
Set objMapForce = CreateObject("MapForce.Application")

VBScript

' Access a running instance, or create a new instance of MapForce.
Set objMapForce = GetObject("MapForce.Application");

Visual Basic

Dim objMapForce As MapForceLib.Application = New MapForceLib.Application