Summary

This document describes what you have to do and configure to access WordLink functionality when accessing upCast via its API. Note that WordLink is only available when running on Windows with a copy of Word (Word 97 or later, preferably Word 2000 or later) installed!

WordLink components

WordLink relies on a single application to be accessible from upCast: il-gw.exe (short for "infinity-loop gateway"). This application handles the interaction with Word as COM object. In order for WordLink to work, it is therefore necessary that upCast knows where this application is located.

Testing the environment

First, let's make sure you have got everything installed needed for WordLink. This is done easiest by running upCast in GUI mode once under the same login you'll running the API later (if possible):

Launch upCast. You may do this by double-clicking the upcast.jar file or by using java -jar upcast.jar at the commandline.
Choose Extras > Install WordLink.
Convert a .doc (Word binary) file to see if everything works.

If the conversion fails, check the log files and see if they provide any further information as to what the problem may be.

Storing components in the file system

As we have seen, WordLink relies on three things:

The il-gw.exe application distributed with(in) upCast.
The necessary runtime environment for il-gw.exe, which is the Microsoft VisualBasic Runtime 5.0. This software component should be installed by default on systems running Windows 2000 or later.
( A download link to this package can be found at the bottom of this page.)
An installed copy of Word 97 or later (Word 2000 or later preferred).

After your testing of the environment, you should be left with the required il-gw.exe application here: ~\loginname\infinity-loop\upCast\Application Support\EXEs\il-gw.exe . You can simply use this file an copy it anywhere you like on your storage system, as long as it remains accessible and executable by the user that will run your custom application (that integrates upCast via its Java API) later on. Make a note of the absolute path to this location.

Telling upCast where components are located

When running in GUI mode, the location is predefined as ~\loginname\infinity-loop\upCast\Application Support\EXEs\il-gw.exe . This is where upCast copies the file when you run the Install WordLink command.

Java system property: `de.infinityloop.exe.location`

When running in API mode, however, upCast cannot rely on the usual layout of its support files in the directory hierarchy. Therefore, you need to tell upCast where to look for the il-gw.exe application. This is done by specifying the Java property de.infinityloop.exe.location . It should contain the absolute path to the directory where the il-gw.exe resides. For example,

java -Dde.infinityloop.exe.location=C:\app-support\upcast -jar upcast.jar

launches upCast telling it that il-gw.exe resides under C:\app-support\upcast\il-gw.exe .

For upCast to find the il-gw.exe application at runtime of your application, you need to set this Java system property at launch time of your application to the path you noted in the previous step.

Testing the installation

This is all that needs to be done. Now is the time to test your installation. Run your application, and pass the absolute path to a .doc (Word binary) file to the UpcastEngine.importFile(…) method. The call to this method should now succeed and not throw an Exception. If all works well, you're done - congratulations, WordLink now works even from the API!

importFile() throws an ILException

If this happens, inspect the error message within the ILException, and check the log file. To see extensive startup debug information in the log, you should set another Java property at startup: de.infinityloop.debug.

java -Dde.infinityloop.debug=true -Dde.infinityloop.exe.location=C:\app-support\upcast -jar upcast.jar

This will, among other information, show where upCast is trying to find il-gw.exe, what version it has (assuming it was found). Then, it will try to access Word via the gateway, and will tell you either the version of Word it found or an error message. Try to see if anything in the logs does not correspond to where and what you expect things to be and work from there.

If you can't find a solution, contact infinity-loop support.

Accessing Word as COM object in a restricted environment

WordLink must access and launch Word to do what it needs to do. However, when running in a server environment, rights of running processes are usually tightly restricted. For example, Word might no be allowed to be accessed by the server process as COM object.

To make WordLink work in such restricted environments, you need to explicitly grant the user running the server access to the Word COM object. You can check and do this as follows:

On the Windows commandline, start dcomcnfg.exe .
Choose the component "Microsoft Word Document" (or similar, depending on localization) and click Properties... .
Under Security > Use custom launch permissions, add the account that runs the server using Edit... – Add... . (On my machine, this e.g. was "ASPNET (ASP.NET Machine Account)").

After this modification, WordLink should also work in the restricted environment.

back to upCast Support Page

Author: Christian Roth
Last revised: 2005-09-16 11:14