This shows you the differences between two versions of the page.
| Both sides previous revision Previous revision | |||
|
dev:sql:functions:external [2010/07/28 20:03] els removed |
— (current) | ||
|---|---|---|---|
| Line 1: | Line 1: | ||
| - | {{page>:top_add&nofooter&noeditbtn}} | ||
| - | <html><div align="center"><span style="color:red">DRAFT</span></div></html> | ||
| - | ====== Omnidex SQL Function: $EXTERNAL ====== | ||
| - | {{page>:sql_bar&nofooter&noeditbtn}} | ||
| - | ===== Description ===== | ||
| - | 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. | ||
| - | |||
| - | {{page>:bottom_add&nofooter&noeditbtn}} | ||