IBM Support

Receiving 'Unable to initialize the API' error after installing one of the Forms Server components

Technote (troubleshooting)


After installing one of the Lotus Forms™ server components (API, Webform Server, IDS), you receive the following error when trying to run one of the samples or your own custom application:

"Unable to initialize the API"

Resolving the problem

An initialization error can occur for many reasons. Use the information below to troubleshoot the API error.

First, it is important to know the context in which the API is being used, namely, a stand-alone application (C, Java, etc.), a servlet or portlet running within a Web container, and so on.

Check C Runtime (only on AIX)

Before checking your API install, check that your server meets the minimum requirements. The most commonly missed requirement is the C Runtime version. Workplace Forms 2.7 requires version 7 of the C/C++ runtime and Lotus Forms 3.5 requires version 8 of the runtime. You can check which version you have installed by executing the following command:

    lslpp -La | grep -i xlC

This command returns an output that looks like the following:

xlC.aix50.rte C F C Set ++ Runtime for AIX 5.0
xlC.cpp C F C for AIX Preprocessor
xlC.msg.en_US.cpp C F C for AIX Preprocessor
xlC.msg.en_US.rte C F C Set ++ Runtime
xlC.rte C F C Set ++ Runtime

If your output matches the one above (the bold values are of main concern), then you need to apply a patch to your operating system. To obtain the AIX patch, refer to " Latest updates for supported IBM C/C++ compilers".

Once your C Runtime meets the minimum specification, proceed to the next troubleshooting step.

Stand-alone API installation

There are four main components to check when working with your API in a stand-alone environment:

1. The main API files are located in the redist folder. These files must appear on the system PATH variable. You do not have to move them from their current location, but you do need to update the PATH environment variable with the full path to the redist folder.

    You can update the PATH variable using the following command:
      export PATH=$PATH:<pathToAdd>*
    * You can add as many items to the PATH variable as you like. The $PATH tells the shell to include the current PATH variable, then you use a colon (:) to separate all the other paths added to this statement.

    The user must have read-write-execute permissions on the .../redist/PureEdge folder and read-write permissions on the,, and (which are all in the .../redist directory).

    - Right-click the 'My Computer' icon on your desktop and select 'Properties'.
    - Click the 'Advanced' tab.
    - Click the 'Environment Variables' button in the bottom left-hand corner.
    - In the 'System variables' section locate the 'Path' variable and click the 'Edit' button.
    - Add the full path to the API redist folder.

2. The PureEdgeAPI.ini contains the path to the location of the API files from the redist directory (that is a sub folder of the installation directory). Therefore, your .ini file should contain the following lines:

    * = /opt/IBM/Lotus Forms/3.5/Server/API/redist/PureEdge/xx
  • This file is case sensitive
  • It should be placed into /etc/

    * = C:\Program Files\IBM\Lotus Forms\3.5\Server\API\redist\PureEdge\xx
  • This file is case sensitive
  • It should be placed into C:\WINDOWS
  • Note that depending on the product version the path may be different ("Lotus Forms/3.5/Server" is "Forms Server/8.0" in version 8)

Replace "xx" with the appropriate number, based on the version you are working with:

2.5.x = 65
2.6.x = 70
2.7.x = 71
3.0.x = 75
3.5.0 = 76
3.5.1 = 77
4.0.x = 80
8.0.x = 80

**Note: If installing on Windows, skip Steps 3 and 4 below. The javaPath property in the prefs.config is not valid, and the correct JVM is located automatically.

3. The prefs.config is the file that allows you to configure the API. You must set the javaPath variable, when installing the API on a UNIX system, to the path of a JVM installed on the server. The prefs.config should be created at:
    if using API version 3.0 = /etc/PureEdge/API 7.5/prefs/
    if using API version 3.5 = /etc/PureEdge/API 7.6/prefs/
These folders are not created during the installation procedure and therefore you may have to create them manually.

4. The LIBPATH Environment Variable must be set for the API to initialize properly. The variable should contain the following entries:
    /opt/IBM/Lotus Forms/3.5/Server/API/redist
    /opt/IBM/Lotus Forms/3.5/Server/API/redist/PureEdge/xx/system
    < path to JVM> /jre/bin/classic
    < path to JVM> /jre/bin
    < path to directory containing the Netscape Security Libraries >

IBM Support recommends installing the API locally and testing it with one of the sample applications provided (for example, calculateAge) prior to installing the API within a Web container.

Servlet/Portlet API Installation

In a servlet/portlet install, the procedure changes. Any version prior to 3.x requires you to manually configure a few WebSphere variables to properly register the API with your Web container. All Web containers are different and therefore the steps may differ. The API Installation Guide outlines how to register the API with WebSphere Application Server. If you are using any other Web container, contact IBM Support for direction. The 3.x and 4.x installation gives you the option to deploy the API to WebSphere; this will register the API for you. During the installation process you are given the option to choose the WebSphere server instance where the API will be deployed. At that time you can select any existing WebSphere or Portal server instance.

Is your WebSphere Application Server a 64-bit Install?
Only version 4.x supports 64-bit architecture. Therefore if you are using a 64-bit web container, you must use 4.0 otherwise the API will not initialize. If you are using a pre-4.0 version then you must install the 32-bit version of WebSphere Application Server.

Which JVM? (Unix only)
Which JVM are you pointing to in your prefs.config? When using the API within the context of a Web container, you must force the API to use the JVM that is included within that container. WebSphere Application Server is one example of a Web container the ships with a JVM. The javaPath variable in the prefs.config must point to this JVM and not the "stand-alone" JVM that may be installed separately. If the Web container does not contain a JVM, then use the one that is currently installed. We have found that Web Containers may ship with more than one version of the JVM .dll or .so. The following example was created with WAS 6.0.2 which uses IBM's 1.4.2 JVM:

    WAS_HOME = opt/IBM/WebSphere/AppServer

    The prefs.config's javaPath will look something similar to the example below:
    javaPath = WAS_HOME/java/jre/bin/

    WAS_HOME = usr/IBM/WebSphere/AppServer

    The prefs.config's javaPath will look something similar to the example below:
    javaPath = WAS_HOME/java/jre/bin/classic/

**Note: Do not reference the in the j9vm folder. Our API does not work with this particular library.

Gathering Debug Information

If the above steps do not resolve the issue, use the following procedure to gather debug information before contacting IBM support. Provide the debug as part of the Problem Description.

1. Create the trigger file wpf.pel that will enable logging.

    Create an empty file in the /etc directory called wpf.pel. Then try to run your application. When a wpf.pel file exists, Workplace Forms generates log files in the current working directory. The file is named debug.log.
    • If you are running a stand-alone application, then the current working directory is the location of the stand-alone application (that is, the Java class files).
    • If you are running an application within a Web container, then the current working directory will be specific to the Web container.

    Create an empty file in the C:\ directory called wpf.pel. Then try to run your application. The file will be created in the same directory as the wpf.pel and shares the name of the executable that initialized the API. Commonly named log files are: java.log, javaw.log, tomcat.log.
2. Gather the log file and provide it to IBM Support.

3. Capture the stacktrace for the error that you are encountering when trying to run your application, and send it to IBM Support.

Many of the steps described in this document are included in the API Installation Manual. This manual can be downloaded from the IBM Web site. You can refer to it for more detail. The address for the Lotus Forms documentation is The address for the Info Center article on the API installation procedure is

    Cross reference information
    Segment Product Component Platform Version Edition
    Messaging Applications Lotus End of Support Products Workplace Forms AIX, Linux, Solaris, Windows 2.7, 2.6, 2.5 All Editions

Document information

More support for: IBM Forms

Software version: 3.0, 3.5, 4.0, 8.0

Operating system(s): AIX, Linux, Solaris, Windows

Reference #: 1248549

Modified date: 14 September 2012

Translate this page: