This section describes the API for functions in external libraries.

The API is defined by a header file named extfnapi.h, in the SDK\Include subdirectory of your SQL Anywhere installation directory. This header file handles the platform-dependent features of external function prototypes. The API supercedes a previous API for functions in external libraries.

Declaring the API version

To notify the database server that the external library is written using the new API, your external library must export the following function as follows:

a_sql_uint32 extfn_use_new_api( )

The function returns an unsigned 32-bit integer. The returned value must be the API version number, EXTFN_API_VERSION, defined in extfnapi.h. A return value of 0 means that the old API is being used.

If the function is not exported by the library, the database server assumes that the old API is in use. The new API must be used for all Unix platforms and for all 64-bit platforms, including 64-bit Windows.

A typical implementation of this function follows:

a_sql_uint32 extfn_use_new_api( void )
{
    return( EXTFN_API_VERSION );
}

Declaring the optional cancel processing routine

To notify the database server that the external library supports cancel processing, your external library must export the following function as follows:

void extfn_cancel( void *cancel_handle )

The function uses the cancel_handle to set a flag indicating to the external library functions that the SQL statement has been canceled.

If the function is not exported by the library, the database server assumes that cancel processing is not supported.

A typical implementation of this function follows:

void extfn_cancel( void *cancel_handle )
{
    *(short *)cancel_handle = 1;
}

Function prototypes

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

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

The function must return void, and must take as arguments a pointer to a structure used to call a set of callback functions and a handle to the arguments provided by the SQL procedure.

The an_extfn_api structure has the following 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;

The an_extfn_value structure has the following 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;