an_extfn_api structure

Used to communicate with the calling SQL environment.

Syntax

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;

Properties

get_value Use this callback function to get the specified parameter's value. The following example gets the value for parameter 1.

result = extapi->get_value( arg_handle, 1, &arg ) if( result == 0 || arg.data == NULL ) { return; // no parameter or parameter is NULL }

get_piece Use this callback function to get the next chunk of the specified parameter's value (if there are any). The following example gets the remaining pieces for parameter 1.

cmd = (char *)malloc( arg.len.total_len + 1 ); offset = 0; for( ; result != 0; ) { if( arg.data == NULL ) break; memcpy( &cmd[offset], arg.data, arg.piece_len ); offset += arg.piece_len; cmd[offset] = '\0'; if( arg.piece_len == 0 ) break; result = extapi->get_piece( arg_handle, 1, &arg, offset ); }

set_value Use this callback function to set the specified parameter's value. The following example sets the return value (parameter 0) for a RETURNS clause of a FUNCTION.

an_extfn_value retval; int ret = -1; // set up the return value struct retval.type = DT_INT; retval.data = (void*) &ret; retval.piece_len = retval.len.total_len = (a_sql_uint32) sizeof( int ); extapi->set_value( arg_handle, 0, &retval, 0 );

set_cancel Use this callback function to establish a pointer to a variable that can be set by the extfn_cancel method. The following is example.

short canceled = 0; extapi->set_cancel( arg_handle, &canceled );

Remarks

A pointer to the an_extfn_api structure is passed by the caller to your external function. Here is an example.

extern "C" __declspec( dllexport )
void my_external_proc( an_extfn_api *extapi, void *arg_handle )
{
    short               result;
    short               canceled;
    an_extfn_value      arg;

    canceled = 0;
    extapi->set_cancel( arg_handle, &canceled );

    result = extapi->get_value( arg_handle, 1, &arg );
    if( canceled || result == 0 || arg.data == NULL )
    {
        return; // no parameter or parameter is NULL
    }
.
.
.
}

Whenever you use any of the callback functions, you must pass back the argument handle that was passed to your external function as the second parameter.