Syntax

  define external result-type? function
         funcion-name argument-list?
         as external-name
         (in function-library library-name)?

External functions are functions written in other languages that you call from your OmniMark program. External functions must be defined in your program, just like regular functions, except that the definition will point to an external function library that contains the function, instead of containing the body of the function. Generally speaking, the person who wrote the external function will provide an OmniMark include file or module that contains the necessary function definitions. All you have to do is include or import the appropriate file and call the function normally.

The form of an external function definition is as follows:

  define external switch function test-some-condition
  as "TestCond"
  in function-library "TestLib"

The in function-library parameter can be omitted if you provide a declare function-library statement to identify the function library in which the function is found.

  declare function-library "TestLib"

  define external switch function test-some-condition
  as "TestCond"

External output functions

An external output function establishes a sink for an OmniMark program so that data can be written to a destination that OmniMark cannot address itself. In the example below, the external output function establishes a sink for writing to a TCP/IP connection.

  define external output function create-writer
       to value stream destination-name
  as "CreateWriter"

To write to an external sink, open a stream with the function call after the as in the open statement, and then establish the stream as current output:

  local stream my-response
  open my-response as create-writer to "response"
  using output as my-response
   output "Mary had a little lamb.%n"

External source functions

An external source function establishes a source for an OmniMark program so that data can be read from a source that OmniMark cannot address itself. In the example below, the external source function establishes a source for reading from a TCP/IP connection.

  define external source function get-data
         from     value stream    source-name
  as "GetData"

To read data from the external source, use using input as, submit, scan, or matches with the function as the argument:

  submit get-data from "myrequest"

Value source parameters

Value source parameters allow data to be efficiently streamed externally from OmniMark, and is most usefully used in creating external filter functions.

Value source parameters may only be used with external functions, and are retrieved as persistent sources in the external function API.

Any data of type stream which is not a referent may be passed as a value source parameter.

  define external source function ToUpper
        value source in-src
  as "UpperCaseIn"

The following example efficiently reads in a file while transforming it to uppercase:

     local stream s

     set s to ToUpper file "infile.txt"

Value output parameters

Value output parameters allow data to be efficiently streamed externally to OmniMark, and is most usefully used in creating external filter functions.

Value output parameters may only be used with external functions, and are retrieved as persistent sinks in the external function API.

Only files and external outputs may be passed as value output parameters.

  define external output function ToUpper
        value output dest
  as "UpperCaseOut"

The following example writes data to a file while transforming it to uppercase:

     local stream s

     open s as ToUpper file "outfile.txt"
     put s "Some Data%n"
     close s

Related Syntax    define function

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