Sample C/C++ header for external loader callback interface
Use the following C/C++ header to define an interface for callback functions to be run by an external load application called by the SYSPROC.ACCEL_LOAD_TABLES stored procedure. Make sure to compile your interface as a 31-bit XPLINK application.
C/C++ header
//------------------------------------------------------------------------------
//
// (C) COPYRIGHT International Business Machines Corp. 2018, 2019.
// All Rights Reserved
// Licensed Materials - Property of IBM
// 5697-DAA
// US Government Users Restricted Rights - Use, duplication or
// disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
//
// Function = Include file defining a C callback interface for the
// SYSPROC.ACCEL_LOAD_TABLES stored procedure.
//
//------------------------------------------------------------------------------
#if !defined(__AQT_Load_Callback_hpp__)
#define __AQT_Load_Callback_hpp__
extern "C" {
typedef struct CallbackMessage {
unsigned int length; //maxmimum length if passed to callback,
//actual length must be set on return by the callback
char* text; //buffer provided by stored procedure
};
typedef unsigned int (*version_callback_t) ();
/** Callback that returns the interface version for other callbacks
* run from ACCEL_LOAD_TABLES.
* ATTENTIION: THE INTERFACE OF THIS VERSION CALLBACK MUST NEVER CHANGE
* Other callback function might be added, existing callback function may be modified.
* All such changes would require an increase of the callback interface version
* returned by this version callback.
* Furthermore, the associated new or modified function types must be supported
* by the ACCEL_LOAD_TABLES procedure.
* If this is not the case ACCEL_LOAD_TABLES will errror out.
* @return 1, if the expected callback interface is
* according to the specification in this header
* (version_callback_t, init_callback_t, load_callback_t, term_callback_t)
*/
typedef unsigned int (*init_callback_t) (char const * const callerid,
unsigned int degreeOfParallelism,
unsigned int lockMode,
unsigned int* allowChangeOfParallelism,
CallbackMessage* message);
/** Callback that provides information about load seetings from ACCEL_LOAD_TABLES.
*
* @param[in] callerid: identifies the load request to the caller of
* ACCEL_LOAD_TABLES. The procedure is obliged to
* use the callerid value specified in its
* <externalTool> XML provided in the
* TABLE_LOAD_SPECIFICATION parameter.
* @param[in] callbackid: associates the request with a load request
* (see load_callback_t).
* @param[in] degreeOfParallelism: specifies the degree of parallelism
* used for loading partitions.
* In version 1 of this interface
* this number remains unchanged during a load.
* @param[in] lockmode specifies the lock mode requested by the user
* when calling ACCEL_LOAD_TABLES:
* 1=TABLESET, all tables in input are locked globally
* 2=TABLE, only current table being unloaded is locked
* 3=PARTITIONS, only the set of partitions
* currently being unloaded is locked
* 4=CSROW, only committed data is read.
* If a row is locked by another app it is not skipped
* 5=NONE, no locking,
* only committed rows are read, locked rows are skipped
* @param[out] allowChangeOfParallelism specifies, if degree of parallelism may be
* changed while the ACCEL_LOAD_TABLES procedures proceeds.
* 0: changes are not allowed
* 1 or any other value: changes are allowed
* @param[inout] message: message (UTF-8) is returned in a SP message
* AQT10513I - severity informational for returncode 0,
* if message is not empty.
* AQT10514W - severity warning returncode 4.
* AQT10515E - severity error for other returncodes.
* As input parameter, the maximum message length in bytes is
* passed together with a pointer to a messagetext buffer.
* As output parameter, the length is modified to the actual
* message length and the text buffer is modified.
* @return 0, if the callback succeeded.
* 8, if the terminate operation did not succeed (for any reason)
* message might be also transferred to SP in an output parameter
*/
typedef int (*load_callback_t) (char const * const callerid,
char const * const callbackid,
char const * const tableSchema,
char const * const tableName,
unsigned int partNum,
char const * const pipeName,
unsigned long long *numRows,
CallbackMessage* message);
/** Callback interface for ACCEL_LOAD_TABLES.
* This callback interface allows to provide data from non-DB2
* sources into an accelerated table. If the caller of
* SYSPROC.ACCEL_LOAD_TABLES uses an extension of the input XML
* to specify tables to load, the callback will be used rather
* than calling DSNUTILU(UNLOAD).
* Example:
* <externalTool name =
* "third-party tool name"
* enforceTableLoadSequence = "true"
* <callback
* callerid = "0x4e353456"
* libary = "TPCALLB"
* versionFunction="VersionCallback"
* initFunction="InitCallback"
* loadFunction="LoadCallBack"
* terminateFunction="TermCallBack" />
* </externalTool>
*
* Prerequisites:
* 1. The implementation of the LoadCallBack function has to be 31bit C/C++
* using XPLINK.
* 2. The imlementation must emulate the DSNUTILU(UNLOAD)
* behaviour related to opening, writing and closing the pipe
* (also in error cases)
*
* @param[in] callerid: identifies the load request to the caller of
* ACCEL_LOAD_TABLES. The procedure is obliged to
* use the callerid value specified in its
* <externalTool> XML provided in the
* TABLE_LOAD_SPECIFICATION parameter.
* @param[in] callbackid: identifies the callback invocation for possible
* later termination.
* @param[in] tableSchema: creator/schema of the table to load according to
* SYSIBM.SYSTABLES(CREATOR), UTF-8 null terminated.
* @param[in] tableName: name of the table to load according to
* SYSIBM.SYSTABLES(NAME), UTF-8 null terminated.
* @param[in] partNum: physical partition number.
* @param[in] pipeName: name of a USS pipe where the data is to be written to.
* UTF-8, null terminated. Pipe is owned by
* ACCEL_LOAD_TABLES.
* @param[out] numRows: the number of rows written to the pipe
* @param[inout] message: message (UTF-8) is returned in a SP message
* AQT10513I - severity informational for returncode 0,
* if message is not empty.
* AQT10514W - severity warning returncode 4.
* AQT10515E - severity error for other returncodes.
* As input parameter,
* the maximum message length in bytes is passed together
* with a pointer to a messagetext buffer.
* As output parameter,
* the length is modified to the actual message length
* and the text buffer is modified.
*
* @return 0, if the callback succeeded.
* 4, if the callback indicates a warning
* (whose accompanied message is returned by the SP),
* unload operation was successful.
* 8, if the unload operation failed,
* i.e. the data were not sent completely to the pipe.
*/
typedef int (*term_callback_t) (char const * const callerid,
char const * const callbackid,
CallbackMessage* message);
/** Termination of a callback run from ACCEL_LOAD_TABLES.
* Terminates a load request and returns if the termination is done.
* This means that an opened pipe in a running load request is closed.
* In case there is no active load requestfor the specified callbackid,
* return immediately with a non-zero return code.
* @param[in] callerid: identifies the load request to the caller of
* ACCEL_LOAD_TABLES. The procedure is obliged to
* use the callerid value specified in its
* <externalTool> XML provided in the
* TABLE_LOAD_SPECIFICATION parameter.
* @param[in] callbackid: associates the request with a load request
* (see load_callback_t).
* @param[inout] message: message (UTF-8) is returned in a SP message
* AQT10513I - severity informational for returncode 0,
* if message is not empty.
* AQT10514W - severity warning for other returncodes.
* As input parameter,
* the maximum message length in bytes is passed together
* with a pointer to a messagetext buffer.
* As output parameter,
* the length is modified to the actual message length
* and the text buffer is modified.
* @return 0, if the termination succeeded.
* 8, if the terminate operation did not succeed (for any reason)
*
*/
}#endif // __AQT_Load_Callback_hpp__