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.

External functions can now be predefined using the elsewhere form.

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. The only other difference between an external function definition and an internal function definition is that external functions cannot have optional arguments.

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

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.

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 following is an example of such a function definition:

  define external function get-db-record
     (value stream key, value stream value)
     as "*" in function-library "*"

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

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

External output functions

An external output function is a function to which a stream item can be attached. Such a stream is called an external output stream. Any data written to the stream item is processed by the function.

External output functions are defined using the define external output declaration.

The set action can be used directly on external output functions in the same way that it can be used on files and referents.

For example, the following illustrates using the set action directly on external output functions.

  define external output function http-connection
        (value stream requesting-id) as "http_con"
        in function-library "http.dll"
  ...
  find ...
     local stream requesting-id
     local stream requested-file-name
     ...
     set http-connection (requesting-id) to
        file (requested-file-name)

External source functions

OmniMark allows functions to be declared as externally defined sources with the define external source declaration. An externally defined source is an external function that returns its data incrementally, (much like the built-in file operator).

These types of functions can be very useful for external functions that establish a "session-based" communication line with another application, or for functions that return a potentially large amount of data.

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

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.

Related Syntax    define function

[ INDEX ] [ CONCEPTS ] [ TASKS ] [ SYNTAX ] [ LIBRARIES ] [ LEGACYLIBRARIES ] [ ERRORS ]