Community articleIFSInitializeWithLocale function
Added by IBM contributorIBM on August 16, 2011
Rate this article 1 starsRate this article 2 starsRate this article 3 starsRate this article 4 starsRate this article 5 stars

No abstract provided.



Description

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

Function

r_error IFSInitializeWithLocale(
   r_charP progName,
   r_charP progVer,
   r_charP apiVer
   r_charP theLocale);


Parameters

ExpressionTypeDescription
progNamer_charPThe name of the application calling IFSInitializeWithLocale. This name is used to identify the application within the .ini file. It also sets the name that is returned by the XFDL applicationName function.
progVerr_charPThe version number of the application calling IFSInitializeWithLocale. If the .ini file has an entry for this version of the applicaton, the application will bind to the version of the API listed in that entry.
apiVerr_charPThe version number of the API the application should use by default. If the .ini file does not contain an entry for the specific application, the application will bind to the API specified by this parameter.
theLocaler_charPThe default locale of the application.


Returns

OK on success or an error code on failure.

Notes

About Binding Your Applications to the API
When you initialize the API, the IFSInitializeWithLocale function 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”).
IFSInitializeWithLocale 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. Refer to the IBM Forms Server – API Installation and Setup Guide for the exact location of the file.
Note: You should redistribute the PureEdgeAPI.ini file with any applications that use the API. See the IBM Forms Server – API Installation and Setup Guide for more information about redistributing applications.
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> = <folder containing appropriate version of API>

For example, the configuration file might look like this:
    [API]
   3.0 = 75
   2.7 = 71
   2.6.0 = 70
    [CustomApplication]
   1.2.0 = 75
   1.1.0 = 71
   1.0.0 = 70

In this case, the folder indicated on the right hand side of each statement is part of the relative path to the API, and assumes the API was installed in the default folder. For example, under Windows® “71” would resolve to:
   C:\Program Files\IBM\Workplace Forms\Server\27\API\redist
      \msc32\PureEdge\26

You can also specify an absolute path by placing a drive letter before the path. For example, “c:\71” would resolve to:
   c:\71\

When you initialize the API, you include three parameters in the initialization call:
  • The name of your application (as it would appear in the configuration file).
  • The version of your application.
  • The version of the API that your application should bind to by default.
The initialization call will first check the configuration file to see if your application is listed. For example, using the configuration file above, if you make an initialization call for “CustomApplication” version “1.1.0”, then the application binds to the API in the “71” folder.
If your application is not listed in the configuration file, the initialization call will use the default version of the API. For example, using the configuration file above, if you declare “2.7” as the default API, then your application binds to the API in the “71” folder.
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.

Example

   r_error initialize(void *theInstance)
   {
   r_error error;
      error = IFSInitializeWithLocale("SampleAp", "1.0 .0", 
         "5.1.0", "fr-FR");
         if (error != OK)
         {
            fprintf(stderr, "IFSInitializeWithLocale error %hd.\n", error);
            return(NOTOK);
         }
      return(OK);
}