External functions

You can declare and call functions written in a programming language other than OmniMark. The external function declaration defines the calling sequence and initially specifies where these external functions are to be found on the system on which OmniMark is running. You can redefine where to find the external functions at any time.

The interface that external functions use to access the OmniMark environment is designed to make it easy to write external functions that behave just like internal functions. In particular, external function programmers are urged to make use of the current output scope and the currently selected items of function arguments wherever applicable.

You can use a declare function-library declaration to declare a default function library. This is useful in programs where multiple declared external functions come from the same library.

Declaring external functions

An external function definition starts out looking like an OmniMark function definition: it has an optional result type, a function name, and an argument list. The keyword external follows define to make it clear that an external function is being declared, but it's what follows the as that really differentiates an external function from internal functions.

For an external function, OmniMark requires an external function name and an optional external function library name, specifying where to find the function. How the external function name and the external function library name are interpreted depends on the system on which the OmniMark program is being run.

The in function-library part of an external function definition can only be omitted when the declare function-library declaration is used to specify a default library.

The following is an example of such a function definition:

  define external function
     set-db-record  (value string key, 
                     value string value)
     "set_db_record" in function-library "db"

Determining and setting external function and library names

You can determine the external function name or external function library name currently associated with an external function, using the external-function or function-library of external-function enquiries. The function and library name have to be constant string expressions in the function definition, but they can be changed by the actions set external-function and set function-library of external-function.

It is possible to declare an external function without specifying the function's name and library name. This is not an error, since the name and library name can be determined and specified at a later point in the program using set external-function and set function-library of external-function.

The set external-function and set function-library of external-function actions could be used as follows:

  set external-function get-db-record to "gdbrec"
  set function-library of external-function get-db-record to "mylib.so"

More information

For more information about externally defined sources, see "Writing External Functions in C" or "Writing External Functions in C++", two guides included when you purchased the OmniMark SDK.