Call the Function Call Manager function FCMRegisterFunctionCall from C_ExtensionInit to register each of your custom functions and corresponding package(s) with the Forms System.
- The FCI allows you to assign a version number to each function that you create. This allows you to provide upgrades to single functions in extensions you have already distributed to users. For more information see About Function Version Numbers, below.
- When registering your package(s) of functions with the Function Call Manager, be aware of the API package naming conventions. For more information see Package Naming Conventions, below.
- You must register each of your custom functions separately. So, if you are registering three functions with the Function Call Manager, you must call FCMRegisterFunctionCall three times.
- In the following example C_ExtensionInit uses the FCMRegisterFunctionCall function to register the multiply function with the Function Call Manager:
if ((theError = FCMRegisterFunctionCall(theFunctionCall, PACKAGE_NAME,
"multiply", FCI_MULTIPLY_ID, FCI_FOLLOWS_STRICT_CALLING_PARAMETERS,
"S,S", FCI_MULTIPLY_VERSION, FCI_MULTIPLY_DESCRIPTION)) != OK)
/* Finished */
About Function Version Numbers
Along with registering your package(s) of custom functions with the Function Call Manager, the FCMRegisterFunctionCall function is also used to specify a version number for each function that you create. In the previous example the multiply function is registered with the version number 0x01000300.
Assigning a version number to each function allows you to provide upgrades to single functions in extensions you have already distributed to users.
For example, if you distributed an extension containing a package of 50 functions for your application and then wanted to change the behavior of one of the functions you could:
- Write a new extension containing just the upgraded function.
- Register the new function using FCMRegisterFunctionCall, with the same package name and function name as the original function but with a higher version number.
- Distribute the new extension to users.
When the API initialized all of the extensions it would find two functions with the same package name and function name. It would deregister the one with the lower version number thereby updating your application.
Package Naming Conventions
The main purpose of package names is to distinguish the functions in a package from those in other packages that could potentially have the same names. All packages you create must contain an underscore in their names. For example the beep function belongs to a package called my_funcs.
- Choose a name that aptly describes the set of functions you are creating and that is distinct enough to be unique within its realm of usage.
- Since the package name is an internal logical element of the application, the 8-character naming restriction and case-insensitivity of Windows® files do not exist.
A group of functions is provided with the Forms System software as the system package. The system package is reserved for system functions that are defined in the XFDL Specification. You may not add to the system package or call your packages by the name system. Instead, ensure your package names contain an underscore.
Parent topic: Setting up the Extension Initialization function