Loading C-Extensions at runtime
The runtime system can load several C-Extensions libraries, allowing you to properly split your libraries by defining each group of functions in separate C interface files.
Directories are searched for the C-Extensions libraries based on the FGLLDPATH environment variable rules.
If the C-Extension library depends on other shared libraries, make sure that the library loader of the operating system can find theses shared objects. You may need to set the LD_LIBRARY_PATH environment variable on UNIX™ or the PATH environment variable on Windows® to point to the directory where these other libraries are located.
There are three ways to bind a C-Extension with the runtime system:
- Using the
IMPORT
instruction in sources. - Using the default C-Extension name: userextension (.so or .DLL)
- Using the
-e
option of fglrun.
Using the IMPORT instruction
The IMPORT
instruction allows you to declare an external module in a
.4gl source file. It must appear at the beginning of the source file.
The name of the module specified after the IMPORT
keyword is converted to
lowercase by the compiler. Therefore it is recommended to use lowercase file names only.
IMPORT
instruction:IMPORT mylib1
MAIN
CALL myfunc1("Hello World") -- C function defined in mylib1
END MAIN
When the IMPORT
instruction is used, no other action has to be taken at runtime.
The module name is stored in the 42m p-code and is automatically loaded when
needed.
Using the default C-Extension name
It is recommended that all modules using a function from a C-Extension now use the IMPORT
instruction. However, this can mean
a major change to existing sources.
To simplify migration of existing C-Extensions, the runtime system loads by default a module with
the name userextension
. Create this shared library with your existing C-Extensions,
and the runtime system will load it automatically if found in the directories specified by
FGLLDPATH.
Using the -e fglrun option
In some cases you need several C-Extension libraries, which are used by different groups of
programs, so you cannot use the default userextension
solution. However, you don't
want to review all your sources in order to use the IMPORT
instruction.
-e
option of fglrun. The -e
option takes a comma-separated
list of module names, and can be specified multiple times in the command line. The following example
loads five extension
modules:fglrun -e myext1,myext2,myext3 -e myext4,myext5 myprog.42r
By using the -e
option, the runtime system loads the modules specified in the
command line instead of loading the default userextension
module.