Community articleinitializeWithLocale method
Added by IBM contributorIBM on July 26, 2013
Rate this article 1 starsRate this article 2 starsRate this article 3 starsRate this article 4 starsRate this article 5 stars


This method initializes the API. The parameters specify the default locale, and which version of the API your application should bind with (see the Notes for more details).
You must call this method before calling any of the other methods in the API.


public static void initializeWithLocale(
   String progName,
   String progVer,
   String apiVer
   String theLocale
   ) throws UWIException;


Table 1. Method parameters
progNameStringThe name of the application calling initializeWithLocale. This name is used to identify the application within the PureEdgeAPI.ini file. It also sets the name that is returned by the XFDL applicationName function.
progVerStringThe version and build number of the application calling initializeWithLocale. If the PureEdgeAPI.ini file has an entry for this version of the application, the application will bind to the version of the API listed in that entry.
apiVerStringThe version number of the API the application should use by default. If the PureEdgeAPI.ini file does not contain an entry for the specific application, the application will bind to the API specified by this parameter.
theLocaleStringThe default locale of the application.


Nothing if call is successful or throws a generic exception (UWIException) if an error occurs.


initializeWithLocale is a static method belonging to the DTK class. To use this method call:
   DTK.initializeWithLocale("progName", "progVer", "apiVer", "theLocale")

About binding your applications to the API:
When you initialize the API, the initializeWithLocale method determines which version of the API to use based on the parameters you pass it. This allows you to exercise a great deal of control over which version of the API is used by your applications, and prevents the problems normally associated with common DLL files (often referred to as “DLL hell”).
initializeWithLocale uses a configuration file to determine which version of the API will bind to any application. This allows multiple versions of the API to co-exist on your computer, and ensures that your applications use the correct version of the API.
The configuration file is called PureEdgeAPI.ini and is installed with the API.
Note: You should redistribute the PureEdgeAPI.ini file with any applications that use the API. See Developing and distributing applications API 801 JavaCreate New Article.
The configuration file contains a section for each application that might call the API, plus a default “API” section. Each section contains a list of version numbers in the following format:
   <version of application> = <path to API>

For example, the configuration file on a Windows® system might look like this:
   7.7.* = C:\Program Files\IBM\Forms Server\8.0.1\API\redist\msc32\PureEdge\76
   7.5.* = C:\Program Files\IBM\Forms Server\8.0.1\API\redist\msc32\PureEdge\75
   1.1.0 = C:\Program Files\IBM\Forms Server\8.0.1\API\redist\msc32\PureEdge\76
   1.0.0 = C:\Program Files\IBM\Forms Server\8.0.1\API\redist\msc32\PureEdge\75

The example contains the default [API] section and a section for the formSample application. The asterisk acts as a wildcard. In the example, 7.6.* corresponds to 7.6.0, 7.6.1, and so on.
The initialize method checks the configuration file to see if your application is listed. For example, using the configuration example, if you make an initialization call as follows:
DTK.initialize("formSample", "1.1.0", "7.7.0")

the application binds to the API in C:\Program Files\IBM\Forms Server\4.0\API\redist\msc32\PureEdge\76 because the entry for version 1.1.0 in the formSample section points to C:\Program Files\IBM\Forms Server\4.0\API\redist\msc32\PureEdge\76.
If your application is not listed in the configuration file, the initialization call uses the version of the API in the apiVer parameter. For example, if you make an initialization call as follows:
DTK.initialize("formSample", "2.0.0", "7.6.0")

the application binds to the API in the [API] section that corresponds to 7.6.0 because there is no entry for version 2.0.0 in the formSample section.
You can add your own entries to the configuration file before distributing it to your customers, or you can rely on the default API entries.


In the example, initializeWithLocale initializes the API for the application called formSample.
   private static void initialize( ) throws UWIException
      DTK.initializeWithLocale("formSample", "1.0.0", "5.1.0", "fr-FR");

Parent topic:
DTK class