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.

Note: When running iOS platforms, the C-Extensions are linked statically to the GMI application.

Directories are searched for the C-Extensions libraries according to the FGLLDPATH environment variable rules. See the environment variable definition for more details.

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.
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.

The compiler and the runtime system automatically know which C-Extensions must be loaded, based on the 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

All modules using a function from a C-Extension should now use the IMPORT instruction, however this could be 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 it is 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 group of programs, so you can't use the default userextension solution. However, you don't want to review all your sources in order to use the IMPORT instruction.

You can specify the C-Extensions to be loaded by using the -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 next 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.