Home > Products > upCast > Support > TechNote 2
Using WordLink in API mode
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 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.
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):
upcast.jarfile or by using
java -jar upcast.jarat the commandline.
.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.
As we have seen, WordLink relies on three things:
il-gw.exeapplication distributed with(in) upCast.
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.
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.
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.
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
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.
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
) 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!
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:
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.
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:
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
© 2003-2007 infinity-loop GmbH Send mail to Webmaster Anbieterkennzeichnung §6 TDG