7.3.4 コールバック関数

機能

コールバック関数の関数定義です。コールバック関数は以下の書式に従って利用者が作成します。

記述形式

SQLRETURN コールバック関数名 (  SQLHDBS          ses_id,
                                        char     *SQLSTATE,
                                        char     *SQLMSG,
                                        void     *user_area,
                                        SQLCALL_T  *SQLData )

一般規則

コールバック関数名は、ユーザが任意に指定できます。
SQLRETURNは、2バイトの整数型です。
入口コールバック関数がSQLRDB_NOCONTINUEを返した場合は、SQL文の処理は実行されません。
入口コールバック関数がSQLRDB_NOCONTINUE以外を返した場合は、SQLRDB_CONTINUEが返されたものと見なします。
マルチスレッドで動作するアプリケーションの場合は、ses_idにセションIDが設定されます。シングルスレッドで動作するアプリケーションの場合は、ses_idに0が設定されます。
SQLSTATEおよびSQLMSGには、以下の値が設定されます。
- 入口コールバック関数の場合は、NULLが設定されます。
- 出口コールバック関数の場合は、SQL文の実行結果が設定されます。ただし、入口コールバック関数がSQLRDB_NOCONTINUEを返した場合は、NULLが設定されます。
アプリケーションにホスト変数SQLMSGが定義されていない場合は、SQLMSGにはNULLが設定されます。
SQLMSGには、アプリケーションの埋込みSQL宣言節で指定した領域長の後にNULL終端文字を付加したものを設定します。
user_areaには、SQLSetCallback関数でユーザが指定したアドレスが設定されます。
sqlrdbei.hを組み込む必要があります。

SQLDataが指す領域は以下の形式です。

struct SQLCALL_T {
    long                    total_size;
    char                    *application;
    long                    sql_line; 
    long                    sql_kind;
    long                    sql_length;
    char                    *sql_stmt;
    long                    sql_variable_length;
    char                    *sql_variable_stmt;
    void                    *reserve;
    long                    data_num;
    struct SQLDATA_T        data[1];
};

struct SQLDATA_T {
    long                    length;
    short                   type;
    short                   precision;
    short                   scale;
    short                   rsv;
    void                    *area;
    short                   *indicator;
    void                    *reserve;
}

SQLCALL_T 構造体のパラメタの意味

パラメタ名	意味
total_size	構造体の全体の長さ
application	SQL埋込みプログラムのソースファイル名のアドレス
sql_line	SQL埋込みプログラムのソースファイルの行番号
sql_kind	SQL文の種別
sql_length	SQL文の長さ
sql_stmt	SQL文
sql_variable_length	被準備文の長さ
sql_variable_stmt	被準備文
reserve	将来のために予約されています。
data_num	入出力データの個数
data	データ構造体のポインタ

applicationは以下のようになります。
- NULL終端文字を付加した、SQL埋込みプログラムのソースファイル名のアドレスが設定されます。
- SQL埋込みプログラムのソースファイル名は、拡張子を含みません。
- SQL文がINCLUDE文で指定したファイルに記述されている場合、applicationには、NULL終端文字を付加した、INCLUDE文で指定したソースファイル名のアドレスが設定されます。
sql_lineは以下のようになります。
- SQL文が記述されているSQL埋込みプログラムのソースファイルの行番号が設定されます。
- SQL文が複数の行で構成されている場合は、先頭の行番号が設定されます。
- SQL文がINCLUDE文で指定したファイルに記述されている場合、sql_lineには、INCLUDE文で指定したソースファイルの行番号が設定されます。
sql_kindに設定される値は、“7.3.3 SQLSetCallback”を参照してください。
sql_lengthはNULL終端文字を含みます。
sql_stmtは、実行したSQL文のアドレスが設定されます。
SQL文の値指定にホスト変数または標識変数が指定されている場合は、コールバック関数に通知されるSQL文では動的パラメタ指定の表記に変更されます。
SQL埋込みプログラムソースでSQL文の途中にタブ文字、改行またはコメントが存在する場合は、これらは空白文字に置き換えられます。
sql_variable_lengthは以下のようになります。
- EXECUTE文、EXECUTE IMMEDIATE文およびPREPARE文の場合は、NULL終端文字を含む被準備文の長さが設定されます。
- OPEN文の場合は、カーソル宣言に指定した問合せ式のNULL終端文字を含む長さが設定されます。
sql_variable_stmtは以下のようになります。
- EXECUTE文、EXECUTE IMMEDIATE文およびPREPARE文の場合は、NULL終端文字を付加した被準備文のアドレスが設定されます。
- OPEN文の場合は、カーソル宣言に指定した問合せ式にNULL終端文字を付加した問合せ式のアドレスが設定されます。
reserveは将来のために予約されています。
data_numには、入出力データの個数が設定されます。
dataは以下のようになります。
- 入口コールバック関数の場合は、入力データの情報が設定されます。また、出口コールバック関数の場合は、出力データの情報になります。
- SQLDATA_T構造体のアドレスが設定されます。SQLDATA_T構造体は以下のパラメタが設定されます。

SQLDATA_T 構造体のパラメタの意味

パラメタ名	意味
length	データの領域長
type	データの型
precision	データの精度
scale	データの位取り
rsv	将来のために予約されています。
area	データ領域のアドレス
indicator	標識変数のアドレス
reserve	将来のために予約されています。

入力データが入力ホスト変数の場合の順番は、SQL文の中に出てくる動的パラメタ指定の順番になります。また、出力データが出力ホスト変数の場合は、SQL文の中の相手指定の順番になります。

各データ型に対応する個々の値は、以下の通りです。

データの型	type	length	precision	scale
文字列型	SQLRDB_CHAR	1～32000 (注1)	0	0
可変長文字列型	SQLRDB_VARCHAR	3～32002 (注1)	0	0
拡張可変長文字列型	SQLRDB_EXTVARCHAR	5～32004 (注1)	0	0
各国語文字列型	SQLRDB_NCHAR	1～32000 (注1)	0	0
可変長各国語文字列型	SQLRDB_NVARCHAR	4～32002 (注1)	0	0
拡張可変長各国語文字列型	SQLRDB_EXTNVARCHAR	6～32004 (注1)	0	0
short	SQLRDB_SHORT	2	15	0
int	SQLRDB_INT	4	31	0
float	SQLRDB_FLOAT	4	23	0
double	SQLRDB_DOUBLE	8	52	0
NUMERIC	SQLRDB_NUMERIC	1～19	1～18	0～18
DECIMAL	SQLRDB_DECIMAL	1～10	1～18	0～18
BLOB	SQLRDB_BLOB	n*1024 (注2)	0	0
ROW_ID	SQLRDB_LOW_ID	24	0	0

注1) 単位はバイトです。
注2) nは1～2097150を示します。

各SQL文ごとにdataに設定される値は、以下の通りです。

SQL文種別	SQL文領域	被準備文	入力データ	出力データ
ALLOCATE DESCRIPTOR文 (注1)	SQL文	－	－	－
CALL文	SQL文	－	データ	データ
CLOSE文	SQL文	－	－	－
COMMIT文	SQL文	－	－	－
CONNECT文 (注2)、(注3)	SQL文	－	－	－
DEALLOCATE DESCRIPTOR文 (注4)	SQL文	－	－	－
DEALLOCATE PREPARE文	SQL文	－	－	－
DELETE文:位置づけ	SQL文	－	データ	－
DELETE文:探索	SQL文	－	データ	－
DESCRIBE文 (注4)	SQL文	－	－	－
DISCONNECT文 (注2)	SQL文	－	－	－
EXECUTE IMMEDIATE文	SQL文	被準備文	－	－
EXECUTE文	SQL文	被準備文	データ	データ
FETCH文	SQL文	－	－	データ
GET DESCRIPTOR文 (注5)	SQL文	－	－	取得識別子のデータ
INSERT文	SQL文	－	データ	－
OPEN文	SQL文	問合せ指定	データ	－
PREPARE文	SQL文	被準備文	－	－
RELEASE文	SQL文	－	－	－
ROLLBACK文	SQL文	－	－	－
SET CATALOG文 (注6)	SQL文	－	－	－
SET CONNECTION文 (注2)	SQL文	－	－	－
SET DESCRIPTOR文 (注7)	SQL文	－	設定識別子のデータ	－
SET ROLE文	SQL文	－	－	－
SET SCHEMA文 (注8)	SQL文	－	－	－
SET SESSION AUTHORIZATION文 (注2)、(注3)	SQL文	－	－	－
SET TRANSACTION文	SQL文	－	－	－
SET USER PASSWORD文(注3)	SQL文	－	－	－
UPDATE文:位置づけ	SQL文	－	データ	－
UPDATE文:探索	SQL文	－	データ	－
単一行SELECT文	SQL文	－	データ	データ

注1) 記述子名または実現値をホスト変数で指定した場合は、設定されるSQL文の中にはホスト変数の値が埋め込まれます。

注2) SQLサーバ名、コネクション名またはユーザ指定をホスト変数で指定した場合は、設定されるSQL文の中にはホスト変数の値が埋め込まれます。

注3) セキュリティ上、指定されたパスワードはSQL文中には表示しません。

注4) 記述子名をホスト変数で指定した場合は、設定されるSQL文の中にはホスト変数の値が埋め込まれます。

注5) 記述子名またはSQLVAR取得番号をホスト変数で指定した場合は、設定されるSQL文の中にはホスト変数の値が埋め込まれます。また、SQLVAR取得情報は動的パラメタ指定の表記に変更されます。

注6) データベース名をホスト変数で指定した場合は、設定されるSQL文の中にはホスト変数の値が埋め込まれます。

注7) 記述子名またはSQLVAR設定番号をホスト変数で指定した場合は、設定されるSQL文の中にはホスト変数の値が埋め込まれます。また、SQLVAR設定情報は動的パラメタ指定の表記に変更されます。

注8) スキーマ名をホスト変数で指定した場合は、設定されるSQL文の中にはホスト変数の値が埋め込まれます。

異常時の対処

復帰コード	意味	対処
SQLRDB_CONTINUE	正常終了	－
SQLRDB_NOCONTINUE	異常終了	SQL文の処理を実行しません。

使用例

単一行SELECT文を実行した場合のデータ構造

EXEC SQL BEGIN DECLARE SECTION;
    char    SQLSTATE[6];
    char    SQLMSG[256];
    short   data1;
    short   ind1;
    char    data2[21];
EXEC SQL END DECLARE SECTION;
                    ・
                    ・
EXEC SQL SELECT COL01, COL02 INTO :data1 :ind1, :data2
            FROM SCHEMA1.TABLE1
            WHERE COL_KEY = 5;
                    ・
                    ・