$EXTERNAL
The $EXTERNAL function provides a gateway to user-provided functions,
thereby allowing customized functions tailored specifically to a user's
needs. This function will dynamically load routines from the shared-library
specified in the library parameter, passing the remaining parameters.
If the input_data passed in $EXTERNAL does not reference a column, then
the routine will be called only once and the data will be cached when
possible. Only if the input_data contains a column will the routine be
called on a per-row basis. This is done to allow the greater use of Omnidex
optimization on literals and constants.
Syntax
$EXTERNAL( 'library', 'routine', input_data<column-spec
| expression | constant >[,output_datatype,length])
library
Required. The shared-library containing the routines to executed.
routine
Required. The routine in the share-library that is to be executed.
The routine must have the following function prototype:
int32 routine(char *environment_file, void *input_data, int32 input_datatype,
int32 input_length, char *input_options, void *output_data,
int32 output_datatype, int32 output_length);
Environment_file is provided so that a routine can open its own instance
and cursor if needed.
Input_data may be a column, expression, or literal.
Input_options may be a column, expression, or literal, and must always
result in a character string.
Input_datatype and input_length are determined by OmniAccess from the
data type and length of input_data.
Output_datatype and output_length are required except when using in the
environment file as the definition of a pseudo-column.
Routine must be written so that it always succeeds.
When used in a SQL statement, the $EXTERNAL function returns a value of
type output_datatype and output_length.
input_data
Required. input_data can be a column, expression, or literal. If this
does not reference a column, then the routine will be called only once
and the data will be cached when possible. Only if the input_data contains
a column will the routine be called on a per-row basis. This is done to
allow the greater use of Omnidex optimization on literals and constants.
output_datatype
Optional.
length
Optional.
Example
Top
|