機能
被準備文中の動的パラメタ指定または選択リストについての情報を取り出します。
記述形式
一般規則
キーワードINPUTを指定したDESCRIBE文を、“入力DESCRIBE文”と呼びます。
入力DESCRIBE文は、記述子域に被準備文である動的SELECT文、動的単一行SELECT文、DELETE文:探索、UPDATE文:探索、INSERT文、UPDATE文:位置づけの動的パラメタ指定の情報が取り込まれます。結果は、記述子域に次のように格納されます。格納する内容については、“表4.1 取得(設定)識別子に設定される値”を参照してください。
被準備文中にある動的パラメタ指定の個数が、SQLDA構造体のメンバSQLNの数を超えている、またはALLOCATE DESCRIPTOR文で指定した実現値の数を超えていると、項目記述子域には値が設定されません。そうでなければ、項目記述子域の先頭から、動的パラメタ指定が記述されている順序に対応して値が設定されます。
キーワードOUTPUTを指定した、またはキーワードを省略したDESCRIBE文を、“出力DESCRIBE文”と呼びます。
出力DESCRIBE文は、記述子域に被準備文である動的SELECT文または動的単一行SELECT文の選択リストの情報が取り込まれます。結果は、記述子域に次のように格納されます。格納する内容については、“表4.1 取得(設定)識別子に設定される値”を参照してください。
選択リストの個数が、SQLDA構造体のメンバSQLNの数を超えている、またはALLOCATE DESCRIPTOR文で指定した実現値の数を超えていると、項目記述子域には値が設定されません。そうでなければ、項目記述子域の先頭から、選択リストの順序に対応して値が設定されます。
設定識別子 | 出力DESCRIBE | 入力DESCRIBE | OPEN,EXECUTE | FETCH,EXECUTE | |
|---|---|---|---|---|---|
SQLDA構造体 | SQL記述子域 | ||||
SQLD | COUNT | 選択リストの個数 | 被準備中にある動的パラメタ指定の個数 | 動的パラメタ指定の個数を設定する。 (注1) | 相手指定の個数を設定する。 |
SQLTYPE | TYPE | データ型のコード | 動的パラメタ指定のデータ型に対応するコード (注2) | 動的パラメタ指定のデータ型に対応するコードを設定する。 (注1) | 相手指定のデータ型に対応するコードを設定する。 |
－ | LENGTH |
|
| (注1) | |
SQLLEN | OCTET_LENGTH |
|
| (注1) | |
SQLPRECISION.PRECISION | PRECISION |
|
| (注1) | |
SQLSCALE (注2) | SCALE |
|
| (注1) | |
SQLNULLABLE | NULLABLE |
|
|
| |
－ | INDICATOR | なし |
| 相手指定に対する標識変数が設定される。 | |
－ | DATA | なし | 動的パラメタ指定に対する値を設定する。(注5) | 相手指定に対する値が設定される。 | |
SQLNAME | NAME | 選択リストの値式の列指定の列名が設定される。列指定でない場合は値は設定されない。値式にAS句が指定された場合は、AS句の列名が設定される。 | 動的パラメタ指定に対応する列指定の列名、または動的パラメタ指定に対応する値式の列指定の列名が設定される。動的パラメタ指定に対応する値式が列指定でない場合は、または動的パラメタ指定が演算式中に含まれる場合は、値は設定されない。 | 無視 |
|
－ | CHARACTER_SET_NAME | 選択リストの値式のデータ型が文字列型または各国語文字列型の場合、データ型に対応する文字セット名が設定される。そうでない場合は、空白が設定される。 | 動的パラメタ指定のデータ型が文字列型または各国語文字列型の場合、データ型に対応する文字セット名が設定される。そうでない場合は、空白が設定される。 | 動的パラメタ指定のデータ型が文字列型または各国語文字列型の場合、データ型に対応する文字セット名を設定する。 (注1) | 相手指定のデータ型が文字列型または各国語文字列型の場合、データ型に対応する文字セット名を設定する。 (注1) |
SQLSCALE (注2) | DATETIME_INTERVAL_CODE | 日時型、時間隔型以外
時間隔型
| 日時型、時間隔型以外 (注1)
時間隔型(注1)
| ||
SQLPRECISION.INTERVAL | DATETIME_INTERVAL_PRECISION | 精度(時間隔型の場合)
| 精度を設定する。(時間隔型の場合) (注1)
| ||
注1) 入力DESCRIBE文または出力DESCRIBE文で設定される値
注2) SQLTYPE=10(INTERVAL)の場合、SQLSCALEにDATETIME_INTERVAL_CODEの値が格納されます。
注3) 日時型、時間隔型は文字列で表現したデータ長
注4) 日時型・時間隔型は、文字列として設定します。
注5) 利用者が設定する値
備考1.(注1)、(注5)の項目は、SQL文を実行する前に設定しておく必要のある項目です。
備考2.(注1)、(注5)のない項目は、SQL文の実行時に設定される項目です。
備考3.動的パラメタ指定のデータ型は、以下のように決定されます。
動的パラメタ指定が演算式中に含まれる場合、動的パラメタ指定のデータ型は演算の相手の値式のデータ型となります。
動的パラメタ指定が演算式中に含まれない場合、動的パラメタ指定のデータ型は比較や代入の相手の値式のデータ型となります。たとえば、C2=?の場合、動的パラメタ指定のデータ型はC2のデータ型となります。
情報を取り出す被準備文の名前を指定します。
情報を取り出す被準備文を準備したPREPARE文がSQL文識別子を指定している場合は、SQL文識別子を指定します。
情報を取り出す被準備文を準備したPREPARE文が拡張SQL文識別子を指定している場合は、拡張SQL文識別子を指定し、拡張SQL文識別子の値に被準備文の名前を指定します。
拡張SQL文識別子は、文字列型の埋込み変数で指定します。拡張SQL文識別子の値に空白を含む場合は、前後の空白を取り除いた値が被準備文の名前になります。
SQL文識別子を指定した場合、SQL文識別子は、同一コンパイル単位に含まれるPREPARE文で定義されていることが必要です。
SQL文識別子と拡張SQL文識別子の値が同じでも、異なる被準備文として区別されます。
同一の記述子名のUSING記述子が動的OPEN文に指定されている場合は、動的OPEN文に指定しているカーソルは、閉じられた状態であることが必要です。
同一の記述子名のUSING記述子が動的OPEN文、動的FETCH文、EXECUTE文に指定され、これらの文の実行が終了している場合にDESCRIBE文を実行すると、先のSQL記述子域の内容は失われます。
記述子名には、ALLOCATE DESCRIPTOR文で割当てを行ったSQL記述子域の名前またはSQLDA構造体の変数名を指定します。
SQL記述子域の値は、DESCRIPTOR取得文とDESCRIPTOR設定文で、それぞれ取得と設定を行います。
SQL記述子域の名前は、文字列定数または文字列型の埋込み変数で指定します。
SQLDA構造体は、動的パラメタ指定または相手指定に関する情報を示します。
SQLDA構造体は、項目記述子域(SQL記述子域の各要素)SQLVAR、SQLVARの最大要素数SQLNおよび有効要素数SQLDで構成されています。SQLNおよびSQLDのデータ型は2進の精度を持つ真数です。
SQLDA構造体の形式を以下に示します。
#define SQL_DESC_ENT_NUM 1
typedef struct sqlextinf {
int SQLPOSITION; /* CALL文のパラメタ位置 */
char SQLSYSTEMRSV[252]; /* 予約域 */
} sqlextinf;
typedef struct sqlvar {
char *SQLDATA; /* 変数データ域 */
short *SQLIND; /* 標識変数データ域 */
int SQLLEN; /* データ長 */
short SQLTYPE; /* データ型のコード */
short SQLSCALE; /* 位取り */
union{
short PRECISION;
struct {
char PRECISION;
char DATETIME_INTERVAL_PRECISION;
} INTERVAL;
} SQLPRECISION; /* 精度 */
short SQLNULLABLE; /* NULL可能性 */
struct {
short SQLNAMEL; /* 列名長 */
char SQLNAMEC[128]; /* 列名 */
} SQLNAME;
sqlextinf *SQLEXTINF; /* 拡張情報 */
} sqlvar;
typedef struct SQLDA {
short SQLN; /* SQLVARの実配列数 */
short SQLD; /* SQLVARのデータの設定数 */
sqlvar SQLVAR[SQL_DESC_ENT_NUM];
} SQLDA;SQL記述子域は動的パラメタ指定または相手指定に関する情報を示します。SQL記述子域は識別子COUNTと0以上の項目記述子域(SQL記述子域の各要素)で構成されています。COUNTはSQL記述子域の動的パラメタ指定または相手指定の数を示し、そのデータ型は2進の精度を持つ真数です。
項目記述子域は以下の内容で構成されています。
項目記述子域 | 意味 | データ型 | |
|---|---|---|---|
SQLDA構造体のメンバ名 | SQL記述子域の識別子 | ||
SQLDATA | － | ホスト変数のアドレス | － |
SQLIND | － | 標識変数のアドレス | － |
－ | DATA | データ値 | TYPE, LENGTH, OCTET_LENGTH, PRECISION, SCALE, CHARACTER_SET_NAME, DATETIME_INTERVAL_CODEで指定されるデータ型に一致 |
－ | INDICATOR | 標識変数の値 | 2進の精度を持つ真数 |
SQLLEN | OCTET_LENGTH | 長さ(バイト数) | 2進の精度を持つ真数 |
－ | LENGTH | 長さ(文字数) | 2進の精度を持つ真数 |
SQLTYPE | TYPE | データ型のコード | 2進の精度を持つ真数 |
SQLSCALE | SCALE | 位取りまたは日時型・時間隔型のコード | 2進の精度を持つ真数 |
SQLPRECISION.PRECISION | PRECISION | 精度 | 2進の精度を持つ真数 |
SQLPRECISION.INTERVAL | DATETIME_INTERVAL_PRECISION | 時間隔先行フィールド精度 | 2進の精度を持つ真数 |
－ | DATETIME_INTERVAL_CODE | 日時型・時間隔型のコード | 2進の精度を持つ真数 |
SQLNULLABLE | NULLABLE | NULL値を許すかどうか | 2進の精度を持つ真数 |
SQLNAME | NAME | 列指定の列名 | SQLDA構造体の場合: |
－ | CHARACTER_SET_NAME | 文字セット名 | 長さ38バイト以上108バイト以下の文字列型 |
SQLEXTINF | － | 拡張情報 | － |
SQLDA構造体のSQLTYPEの値（データ型のコード）またはSQL記述子域のTYPEの値(データ型のコード)とSQLのデータ型の対応は以下の通りです。
コード | データ型 |
|---|---|
1 | CHARACTERまたはNATIONAL CHARACTER (注1) |
2 | NUMERIC |
3 | DECIMAL |
4 | INTEGER |
5 | SMALLINT |
7 | REAL |
8 | DOUBLE PRECISION |
9 | DATE、TIMEまたはTIMESTAMP |
10 | INTERVAL |
11 | NATIONAL CHARACTER (注1) |
12 | CHARACTER VARYING |
13 | NATIONAL CHARACTER VARYING (注1) |
30 | BLOB |
31 | (注2) |
50 | ROW_ID |
注1) データ型がNATIONAL CHARACTER、NATIONAL CHARACTER VARYINGの場合、SQLDA構造体の場合は、コードが11と13になります。 SQL記述子域の場合は、コードが1と12になります。CHARACTERとNATIONAL CHARACTERの区別は、CHARACTER_SET_NAMEの値で識別します。
注2) SQL埋込みCプログラムにおいて、8バイトの整数型(long long型など)と対応します。DESCRIBE文では、コードに31は返却されません。
SQLDA構造体のSASQLTYPEの値が9を示す場合は、メンバSQLSCALEには以下のDATE_TIME_INTERVAL_CODEを格納します。また、SQL記述子域のTYPEの値が9を示す場合は、以下のDATETIME_INTERVAL_CODEを格納します。
コード | データ型 |
|---|---|
1 | DATE |
2 | TIME |
3 | TIMESTAMP |
SQLDA構造体のSQLTYPEの値が10を示す場合は、メンバSQLSCALEには以下のDATE_TIME_INTERVAL_CODEを格納します。また、SQL記述子域のTYPEの値が10を示す場合は、以下のDATETIME_INTERVAL_CODEを格納します。
コード | 時間隔修飾子 |
|---|---|
1 | YEAR |
2 | MONTH |
3 | DAY |
4 | HOUR |
5 | MINUTE |
6 | SECOND |
7 | YEAR TO MONTH |
8 | DAY TO HOUR |
9 | DAY TO MINUTE |
10 | DAY TO SECOND |
11 | HOUR TO MINUTE |
12 | HOUR TO SECOND |
13 | MINUTE TO SECOND |
TYPEの値が1または12のとき、CHARACTER_SET_NAMEの値(文字セット名)は文字列型と各国語文字列型で以下のように異なります。
BASIC
NCHAR
SQLDA構造体の場合、DESCRIBE文を実行すると、選択リストまたは動的パラメタ指定のデータ型に対応する精度、位取りおよび長さが、それぞれのSQLDA構造体のメンバSQLPRECISION、SQLSCALEおよびSQLLENに設定されます。
また、SQL記述子域の場合は、DESCRIBE文を実行すると、動的パラメタ指定または選択リストのデータ型に対応する精度、位取り、長さ(文字数)および長さ(バイト数)が、それぞれのSQL記述子域の識別子のPRECISION、SCALE、LENGTH、OCTET_LENGTH、DATETIME_INTERVAL_PRECISIONに設定されます。
SQLDA構造体の場合、データ型に対応するそれぞれの値は、以下のとおりです。
SQLのデータ型(注1) | SQLTYPE | SQLPRECISION | SQLSCALE | SQLLEN | DATETIME_INTERVAL_PRECISION |
|---|---|---|---|---|---|
CHARACTER | 1 | 0 | 0 | 1～32000 | 0 |
NUMERIC | 2 | 1～18 | 0～18 | 1～19 | 0 |
DECIMAL | 3 | 1～18 | 0～18 | 1～10 | 0 |
INTEGER | 4 | 31 | 0 | 4 | 0 |
SMALLINT | 5 | 15 | 0 | 2 | 0 |
REAL | 7 | 23 | 0 | 4 | 0 |
DOUBLE PRECISION | 8 | 52 | 0 | 8 | 0 |
DATE | 9 | 0 | 1 (注2) | 10 | 0 |
TIME | 9 | 0 | 2 (注2) | 8 | 0 |
TIMESTAMP | 9 | 0 | 3 (注2) | 19 | 0 |
INTERVAL | 10 | (注3) | (注4) | 2～19 | 1～19 |
NATIONAL CHARACTER | 11 | 0 | 0 | 2～32000 | 0 |
CHARACTER VARYING | 12 | 0 | 0 | 3～32002 (注5) | 0 |
NATIONAL CHARACTER VARYING | 13 | 0 | 0 | 4～32002 (注5) | 0 |
BLOB | 30 | 0 | 0 | n*1024 (注6) | 0 |
(注7) | 31 | 63 | 0 | 8 | 0 |
ROW_ID | 50 | 0 | 0 | 24 | 0 |
注1) SQLデータ型に対応するCの変数定義については“6.3 SQL埋込みCプログラム”を参照してください。SQLデータ型に対応するCOBOLの変数定義については“6.4 SQL埋込みCOBOLプログラム”を参照してください。
注2) DATE、TIMEまたはTIMESTAMPでは、SQLSCALE=0ですがDATETIME_INTERVAL_CODE値を代替として利用します。
注3) INTERVALでのSQLPRECISIONはPRECISION値(0)とDATETIME_INTERVAL_PRECISIONとなります。
注4) INTERVALでは、SQLSCALE=0ですがDATETIME_INTERVAL_CODE値を代替として利用します。
注5) 先頭に2バイトの長さが含まれます。
注6) n=1～2097150を示します。
注7) SQL埋込みCプログラムにおいて、8バイトの整数型(long long型など)と対応します。DESCRIBE文では、コードに31は返却されません。
SQL記述子域の場合、データ型に対応するそれぞれの値は、以下のとおりです。
SQLのデータ型(注1) | TYPE | PRECISION | SCALE | OCTET_LENGTH | LENGTH | DATETIME_INTERVAL_PRECISION |
|---|---|---|---|---|---|---|
CHARACTER | 1 | 0 | 0 | 1～32000 | 1～32000 | 0 |
NATIONAL CHARACTER | 1 | 0 | 0 | 2～32000 | 2～32000 | 0 |
NUMERIC | 2 | 1～18 | 0～18 | 1～19 | 1～19 | 0 |
DECIMAL | 3 | 1～18 | 0～18 | 1～10 | 1～10 | 0 |
INTEGER | 4 | 31 | 0 | 4 | 4 | 0 |
SMALLINT | 5 | 15 | 0 | 2 | 2 | 0 |
REAL | 7 | 23 | 0 | 4 | 4 | 0 |
DOUBLE PRECISION | 8 | 52 | 0 | 8 | 8 | 0 |
DATE | 9 | 0 | 0 | 10 | 10 | 0 |
TIME | 9 | 0 | 0 | 8 | 8 | 0 |
TIMESTAMP | 9 | 0 | 0 | 19 | 19 | 0 |
INTERVAL | 10 | 0 | 0 | 2～19 | 2～19 | 1～19 |
CHARACTER VARYING | 12 | 0 | 0 | 1～32000 | 1～32000 | 0 |
NATIONAL CHARACTER VARYING | 12 | 0 | 0 | 2～32000 | 1～16000 | 0 |
BLOB | 30 | 0 | 0 | n*1024 (注2) | n*1024 (注2) | 0 |
(注3) | 31 | 63 | 0 | 8 | 8 | 0 |
ROW_ID | 50 | 0 | 0 | 24 | 24 | 0 |
注1) SQLデータ型に対応するCの変数定義については“6.3 SQL埋込みCプログラム”を参照してください。SQLデータ型に対応するCOBOLの変数定義については“6.4 SQL埋込みCOBOLプログラム”を参照してください。
注2) n=1～2097150を示します。
注3) SQL埋込みCプログラムにおいて、8バイトの整数型(long long型など)と対応します。DESCRIBE文では、コードに31は返却されません。
使用例
SQLDA構造体を使用して、SQL文識別子CMDに対応する被準備文の動的パラメタ指定および選択リストの情報を取得します。なお、可変長文字型の展開規則は、“6.3 SQL埋込みCプログラム”を参照してください。
#include "qdbnosis.h"
EXEC SQL BEGIN DECLARE SECTION;
VARCHAR CMDAREA[100];
SQLDA *sqlda_in;
SQLDA *sqlda_out;
EXEC SQL END DECLARE SECTION;
：
size = sizeof(SQLDA) + sizeof(sqlvar) * (50-1);
sqlda_in = (SQLDA *)malloc(size); (1)
memset(sqlda_in, 0x00, size);
sqlda_in->SQLN = 50;
sqlda_out = (SQLDA *)malloc(size); (2)
memset(sqlda_out, 0x00, size);
sqlda_out->SQLN = 50;
EXEC SQL DECLARE CU1 CURSOR FOR CMD; (3)
strcpy(CMDAREA.sqlvar,"SELECT COL1,COL2,COL3 FROM S1.TBL WHERE COL4=?"); (4)
CMDAREA.sqllen = strlen(CMDAREA.sqlvar);
EXEC SQL PREPARE CMD FROM :CMDAREA; (5)
EXEC SQL DESCRIBE INPUT CMD USING SQL DESCRIPTOR :sqlda_in; (6)
EXEC SQL DESCRIBE OUTPUT CMD USING SQL DESCRIPTOR :sqlda_out; (7)
：
(SQLDA構造体に必要な情報を設定)
：
EXEC SQL OPEN CU1 USING SQL DESCRIPTOR :sqlda_in;
EXEC SQL FETCH CU1 INTO SQL DESCRIPTOR :sqlda_out; (8)
：
EXEC SQL CLOSE CU1;(1) SQLDA構造体sqlda_inの領域を割り当てます。
(2) SQLDA構造体sqlda_outの領域を割り当てます。
(3) 動的カーソル宣言によりCU1のカーソルを宣言します。
(4) ホスト変数CMDAREAに動的SELECT文を設定します。
(5) ホスト変数CMDAREAが示すSQL文をSQL文識別子CMDに対応づけます。
(6) SQL文識別子CMDに対応する被準備文の動的パラメタ指定の情報をSQLDA構造体sqlda_inに取り込みます。
(7) SQL文識別子CMDに対応する被準備文の選択リストの情報をSQLDA構造体sqlda_outに取り込みます。
(8) 動的OPEN文、動的FETCH文、動的CLOSE文によりカーソルの操作を行います。
SQL記述子域を使用して、SQL文識別子CMDに対応する被準備文の動的パラメタ指定および選択リストの情報を取得します。なお、可変長文字型の展開規則は、“6.3 SQL埋込みCプログラム”を参照してください。
EXEC SQL BEGIN DECLARE SECTION;
VARCHAR CMDAREA[100];
EXEC SQL END DECLARE SECTION;
：
EXEC SQL ALLOCATE DESCRIPTOR 'DESC1' WITH MAX 50; (1)
EXEC SQL ALLOCATE DESCRIPTOR 'DESC2' WITH MAX 50; (2)
EXEC SQL DECLARE CU1 CURSOR FOR CMD; (3)
strcpy(CMDAREA.sqlvar,"SELECT COL1,COL2,COL3 FROM S1.TBL WHERE COL4 = ?"); (4)
CMDAREA.sqllen = strlen(CMDAREA.sqlvar);
EXEC SQL PREPARE CMD FROM :CMDAREA; (5)
EXEC SQL DESCRIBE INPUT CMD USING SQL DESCRIPTOR 'DESC1'; (6)
EXEC SQL DESCRIBE OUTPUT CMD USING SQL DESCRIPTOR 'DESC2'; (7)
：
(SQL記述子域に必要な情報を設定)
：
EXEC SQL OPEN CU1 USING SQL DESCRIPTOR 'DESC1'; (8)
EXEC SQL FETCH CU1 INTO SQL DESCRIPTOR 'DESC2'; (8)
：
EXEC SQL CLOSE CU1;(1) 記述子名DESC1のSQL記述子域を割り当てます。
(2) 記述子名DESC2のSQL記述子域を割り当てます。
(3) 動的カーソル宣言によりCU1のカーソルを宣言します。
(4) ホスト変数CMDAREAに動的SELECT文を設定します。
(5) ホスト変数CMDAREAが示すSQL文をSQL文識別子CMDに対応づけます。
(6) SQL文識別子CMDに対応する被準備文の動的パラメタ指定の情報を記述子名DESC1のSQL記述子域に取り込みます。
(7) SQL文識別子CMDに対応する被準備文の選択リストの情報を記述子名DESC2のSQL記述子域に取り込みます。
(8) 動的OPEN文、動的FETCH文、動的CLOSE文によりカーソルの操作を行います。