External Function Prototypes

Define the API by a header file named extfnapiv3.h (extfnapiv4.h for the v4 API) in the subdirectory of your SAP Sybase IQ installation directory. This header file handles the platform-dependent features of external function prototypes.

To notify the database server that the library is not written using the old API, provide a function as follows:

uint32 extfn_use_new_api( )

This function returns an unsigned 32-bit integer. If the return value is nonzero, the database server assumes that you are using the new API.

If the DLL does not export this function, the database server assumes that the old API is in use. When using the new API, the returned value must be the API version number defined in extfnapi.v4h.

Each library should implement and export this function as:

unsigned int extfn_use_new_api(void)
	{
		return EXTFN_V4_API;
	}

The presence of this function, and that it returns EXTFN_V4_API informs the SAP Sybase IQ engine that the library contains UDFs written to the new API documented in this book.

Function prototypes

The name of the function must match that referenced in the CREATE PROCEDURE or CREATE FUNCTION statement. Declare the function as:

void function-name ( an_extfn_api *api, void *argument-handle )

The function must return void, and must take as arguments a structure used to pass the arguments, and a handle to the arguments provided by the SQL procedure.

The an_extfn_api structure has this form:

typedef struct an_extfn_api {
short (SQL_CALLBACK *get_value)(
				    void *          arg_handle,
				    a_sql_uint32    arg_num,
				    an_extfn_value *value
				    );
 short (SQL_CALLBACK *get_piece)(
				    void *          arg_handle,
				    a_sql_uint32    arg_num,
				    an_extfn_value *value,
				    a_sql_uint32    offset
				    );
 short (SQL_CALLBACK *set_value)(
				    void *          arg_handle,
				    a_sql_uint32    arg_num,
				    an_extfn_value *value
				    short          append
				    );
void (SQL_CALLBACK *set_cancel)(
				    void *	arg_handle,
				    void *	cancel_handle
				    );
} an_extfn_api;

Note: The get_piece callback is valid in v3 and v4 scalar and aggregate UDFs. For v4 table UDFs and TPFs, use the Blob (a_v4_extfn_blob) and Blob Input Stream (a_v4_extfn_blob_istream) structures instead.

The an_extfn_value structure has this form:

typedef struct an_extfn_value {
void *				data;
  a_sql_uint32 		piece_len;
  union {
  a_sql_uint32	total_len; 
  a_sql_uint32	remain_len; 
} len;
  a_sql_data_type		type;
} an_extfn_value;

Notes

Calling get_value on an OUT parameter returns the data type of the argument, and returns data as NULL.

The get_piece function for any given argument can be called only immediately after the get_value function for the same argument.

To return NULL, set data to NULL in an_extfn_value.

The append field of set_value determines whether the supplied data replaces (false) or appends to (true) the existing data. You must call set_value with append=FALSE before calling it with append=TRUE for the same argument. The append field is ignored for fixed-length data types.

The header file itself contains additional notes.