関連項目:
ここで説明するすべての文の詳細は、埋込みSQL文およびディレクティブを参照してください。
用途
この文は、SQL記述子領域を割り当てるために使用します。記述子、ホスト・バインド項目発生数の最大値および配列サイズを指定します。この文は、ANSI動的SQLでのみ使用できます。
構文
EXEC SQL [FOR [:]array_size] ALLOCATE DESCRIPTOR [GLOBAL | LOCAL] {:desc_nam | string_literal} [WITH MAX occurrences] ;
変数
array_size
これは配列処理をサポートするオプション句(Oracle拡張機能)です。この句により、配列処理で記述子が使用可能であることがプリコンパイラに通知されます。
GLOBAL | LOCAL
デフォルトでは、オプション句のスコープはLOCALに設定されています。ローカル記述子は、その記述子を割り当てたファイル内でのみアクセス可能です。グローバル記述子は、コンパイル・ユニット内のどのモジュールでも使用できます。
desc_nam
記述子の名前。ローカル記述子は、モジュール内で一意にしてください。前回の割当てを解除せずに記述子を割り当てた場合は、ランタイム・エラーが生成されます。グローバル記述子は、アプリケーション全体で一意にしてください。そうでない場合はランタイム・エラーが発生します。
occurrences
記述子で使用可能なホスト変数の最大数です。この値は、0から64KBの整数定数にする必要があります。それ以外の場合はエラーが戻されます。デフォルトは100です。この句はオプションです。これらの規則に違反するとプリコンパイラ・エラーが戻されます。
例
EXEC SQL ALLOCATE DESCRIPTOR 'SELDES' WITH MAX 50 ; EXEC SQL FOR :batch ALLOCATE DESCRIPTOR GLOBAL :binddes WITH MAX 25 ;
用途
以前に割り当てられたSQL記述子の割当てを解除してメモリーを解放する場合に、この文を使用します。この文は、ANSI動的SQLでのみ使用できます。
構文
EXEC SQL DEALLOCATE DESCRIPTOR [GLOBAL | LOCAL] {:desc_nam | string_literal} ;
変数
GLOBAL | LOCAL
デフォルトでは、オプション句のスコープはLOCALに設定されています。ローカル記述子は、その記述子を割り当てたファイル内でのみアクセス可能です。グローバル記述子は、コンパイル・ユニット内のどのモジュールでも使用できます。
desc_nam
同じ名前およびスコープの記述子が割り当てられていない場合、または割当てが解除されている場合は、ランタイム・エラーが発生します。
例
EXEC SQL DEALLOCATE DESCRIPTOR GLOBAL 'SELDES' ; EXEC SQL DEALLOCATE DESCRIPTOR :binddes ;
用途
この文は、SQL記述子領域からの情報の取得に使用します。
構文
EXEC SQL [FOR [:]array_size] GET DESCRIPTOR [GLOBAL | LOCAL] {:desc_nam | string_literal} { :hv0 = COUNT | VALUE item_number :hv1 = item_name1 [ {, :hvN = item_nameN}] } ;
変数
array_size
FOR array_size
は、オプションのOracle拡張機能です。array_size
は、FETCH文のarray_size
フィールドと等しくする必要があります。
COUNT
バインド変数の合計数。
desc_nam
記述子の名前。
GLOBAL | LOCAL
デフォルトでは、オプション句のスコープはLOCALに設定されています。ローカル記述子は、その記述子を割り当てたファイル内でのみアクセス可能です。グローバル記述子は、コンパイル・ユニット内のどのモジュールでも使用できます。
VALUE item_number
SQL文内での項目の位置。item_number
には変数または定数を指定できます。item_number
の値がCOUNT
より大きい場合、「データが見つかりません。」という条件が戻されます。item_number
には0より大きい値を指定する必要があります。
hv1 .. hvN
値の転送先のホスト変数。
item_name1 .. item_nameN
ホスト変数に対応付けられた記述子項目名。使用可能なANSI記述子項目名は次のとおりです。
表14-4 GET DESCRIPTORの記述子項目名の定義
記述子項目名 | 意味 |
---|---|
|
ANSIデータ型が表にない場合およびTYPE_CODE=ANSIの場合は、負の値のOracle型コードを使用してください。 |
|
列データの長さ。NCHARでは文字数、その他の場合はバイト数で表されます。DESCRIBE OUTPUTによって設定されます。 |
|
バイト単位でのデータの長さ。 |
|
FETCH後の実際のデータ長。 |
|
戻されたデータのバイト単位での長さ。 |
|
桁数。 |
|
真数値型での小数点の右側の桁数。 |
|
1のときは、列にNULL値を使用できます。0の場合、列にはNULL値を指定できません。 |
|
対応付けられたインジケータ値。 |
|
データの値。 |
|
列の名前。 |
|
列のキャラクタ・セット。 |
表14-5 Oracle拡張機能により追加されたGET DESCRIPTORの記述子項目名の定義
記述子項目名 | 意味 |
---|---|
|
2はNCHARまたはNVARCHAR2を示します。1は文字を示します。0は文字以外を示します。 |
|
内部でのバイト単位の長さ。 |
|
ホスト構造体のサイズ。バイト数で表します。 |
|
インジケータ構造体のサイズ。バイト数で表します。 |
|
戻された長さの構造体のサイズ。バイト数で表します。 |
|
オブジェクト型バージョンを表す文字。 |
|
オブジェクト型の名前。 |
|
オブジェクト型の名前の長さ。 |
|
オブジェクト・スキーマを表す文字。 |
|
|
|
2はNCHARまたはNVARCHAR2を示します。1は文字を示します。0は文字以外を示します。 |
使用上の注意
FOR句は、DATA、INDICATORおよびRETURNED_LENGTH項目のみを含むGET DESCRIPTOR文で使用してください。
内部型は、DESCRIBE OUTPUT文によって設定されます。入力および出力のどちらでも、ホスト変数の外部型に使用する型を設定する必要があります。
TYPEはANSI SQLデータ型のコードです。ANSIの型が表に含まれていない場合は、負の値のOracle型コードを使用してください。
LENGTHには、固定幅の各国語キャラクタ・セットを持つフィールドの列の長さを表す文字数が含まれます。それ以外のキャラクタ列ではバイト単位になります。LENGTHはDESCRIBE OUTPUTによって設定されます。
RETURNED_LENGTHは、FETCH文によって設定される実際のデータ長です。LENGTHと同様にバイト単位または文字単位になります。フィールドOCTET_LENGTHおよびRETURNED_OCTET_LENGTHは、バイト単位の長さです。
NULLABLE = 1は、列にNULLを使用できることを示します。NULLABLE = 0は、列にNULLを使用できないことを示します。
CHARACTER_SET_NAMEは、キャラクタ列の場合にのみ意味があります。他の型では未定義になります。DESCRIBE OUTPUT文によって値が設定されます。
DATAおよびINDICATORは、その列のデータ値およびインジケータ・ステータスです。データがNULLでインジケータが要求されなかった場合は、実行時にエラーが発生します(DATA EXCEPTION, NULL VALUE, NO INDICATOR PARAMETER)。
Oracle固有の記述子項目名
列がNCHARまたはNVARCHAR2列の場合は、NATIONAL_CHARACTER = 2になります。列がキャラクタ(ただし、各国語キャラクタではない)列の場合、項目は1に設定されます。キャラクタ以外の列の場合、DESCRIBE OUTPUTの実行後にこの項目は0に設定されます。
INTERNAL_LENGTHは、Oracle動的方法4との互換性があるため、Oracle記述子領域の長さメンバーと同じ値に設定されます。この項目にはOracle SQL記述子領域の長さメンバーと同じ値が設定されています。
関連項目:
次の3つの項目はDESCRIBE OUTPUT文によって戻されません。
ホスト変数構造体のサイズを示すHOST_STRIDE_LENGTH。
標識変数の構造体のサイズを示すINDICATOR_STRIDE_LENGTH。
戻された長さの変数構造体のサイズを示すRETURNED_LENGTH_STRIDE
次の項目は、プリコンパイラ・オプションOBJECTSがYESに設定されているときにのみオブジェクト型に適用されます。
タイプ・バージョンを表す文字を含むUSER_DEFINED_TYPE_VERSION。
型の名前を表す文字を示すUSER_DEFINED_TYPE_NAME。
型の名前の長さをバイト数で示すUSER_DEFINED_TYPE_NAME_LENGTH。
型のスキーマ名を表す文字を示すUSER_DEFINED_TYPE_SCHEMA。
型のスキーマ名の長さを文字数で示すUSER_DEFINED_TYPE_SCHEMA_LENGTH。
例
EXEC SQL GET DESCRIPTOR :binddes :n = COUNT ; EXEC SQL GET DESCRIPTOR 'SELDES' VALUE 1 :t = TYPE, :l = LENGTH ; EXEC SQL FOR :batch GET DESCRIPTOR LOCAL 'SELDES' VALUE :sel_item_no :i = INDICATOR, :v = DATA ;
用途
この文は、ホスト変数からの記述子領域の情報を設定するために使用します。SET DESCRIPTOR文では、項目名のホスト変数のみサポートされます。
構文
EXEC SQL [FOR array_size] SET DESCRIPTOR [GLOBAL | LOCAL] {:desc_nam | string_literal} {COUNT = :hv0 | VALUE item_number [REF] item_name1 = :hv1 [{, [REF] item_nameN = :hvN}]} ;
変数
array_size
このOracleオプション句で配列を使用できるのは、記述子項目DATA、INDICATORおよびRETURNED_LENGTHの設定時のみです。FOR句を含むSET DESCRIPTORでは他の項目を使用できません。ホスト変数配列サイズはすべて一致している必要があります。FETCH文で使用するのと同じ配列サイズをSET文で使用してください。
GLOBAL | LOCAL
デフォルトでは、オプション句のスコープはLOCALに設定されています。ローカル記述子は、その記述子を割り当てたファイル内でのみアクセス可能です。グローバル記述子は、コンパイル・ユニット内のどのモジュールでも使用できます。
desc_nam
記述子名。ALLOCATE DESCRIPTORでの規則が適用されます。
COUNT
バインド(入力)変数または定義(出力)変数の数。
VALUE item_number
動的SQL文でのホスト変数の位置。
hv1 .. hvN
設定するホスト変数(定数ではありません)。
item_nameI
desc_item_name
では、GET DESCRIPTOR構文と同様の方法でこれらの値が使用されます。
関連項目:
表14-6 SET DESCRIPTORの記述子項目名
記述子項目名 | 意味 |
---|---|
|
対応するANSI型がない場合は、負の値のOracle型を使用します。 |
|
列内のデータの最大長。 |
|
対応付けられたインジケータ値。参照セマンティクスのために設定します。 |
|
設定するデータの値。参照セマンティクスのために設定します。 |
|
列のキャラクタ・セット。 |
|
対応するANSI型がない場合は、負の値のOracle型を使用します。 |
表14-7 Oracle拡張機能により追加されたSET DESCRIPTORの記述子項目名の定義
記述子項目名 | 意味 |
---|---|
|
FETCH後に戻される長さ。参照セマンティクスを使用する場合に設定します。 |
|
入力ホスト変数がNCHARまたはNVARCHAR2型のときは、2に設定します。 各国語キャラクタ設定が設定されていない場合、0に設定します。 |
|
ホスト変数構造体のサイズ。バイト数で表します。 |
|
標識変数のサイズ。バイト数で表します。 |
|
戻された長さの構造体のサイズ。バイト数で表します。 |
|
オブジェクト型の名前。 |
|
オブジェクト型の名前の長さ。 |
|
オブジェクト・スキーマを表す文字。 |
|
|
使用上の注意
参照セマンティクスは、パフォーマンス向上のために使用する別のオプションのOracle拡張機能です。記述子項目名がDATA、INDICATORおよびRETURNED_LENGTHの場合にのみ、それらの前にREFキーワードを指定します。REFキーワードを使用した場合は、GET文を使用する必要はありません。複合データ型(オブジェクト型、コレクション型、構造体の配列およびDML RETURNING句)はすべて、SET DESCRIPTORのREF形式を必要とします。
関連項目:
プログラムで別のSQLのDESCRIPTORを再利用する場合、DESCRIPTORの古い値は残ります。
REFを使用すると、対応付けられたホスト変数自体がSETで使用されます。この場合、GETは必要ありません。値構文ではなく、REFセマンティクスを使用するときにのみ、RETURNED_LENGTHを設定できます。
SETまたはGET文の配列サイズは、FETCHで使用する配列サイズと同じにしてください。
NCHARホスト変数には、NATIONAL_CHARフィールドを2に設定します。
古いSQLでNCHARホスト入力値用にDESCRIPTORが使用されるとき、NATIONAL_CHARACTERフィールドを0に設定します。
オブジェクト型の特性を設定するときは、USER_DEFINED_TYPE_NAMEおよびUSER_DEFINED_TYPE_NAME_LENGTHを設定する必要があります。
省略した場合は、USER_DEFINED_TYPE_SCHEMAおよびUSER_DEFINED_TYPE_SCHEMA_LENGTHはデフォルトで現行の接続に設定されます。
クライアント側でUnicodeをサポートするには、CHARACTER_SET_NAMEにUTF16を設定します。データはUCS2エンコーディングになり、RETURNED_LENGTHはCHARSです。
例
int bindno = 2 ; short indi = -1 ; char data = "ignore" ; int batch = 1 ; EXEC SQL FOR :batch ALLOCATE DESCRIPTOR 'binddes' ; EXEC SQL SET DESCRIPTOR GLOBAL :binddes COUNT = 3 ; EXEC SQL FOR :batch SET DESCRIPTOR :bindes VALUE :bindno INDICATOR = :indi, DATA = :data ; ...
関連項目:
バルク配列の例は、配列を使用したバルク操作についてを参照してください。
用途
この方法で使用されているPREPARE文は、他の動的SQL方法で使用されているPREPARE文と同じです。Oracle拡張機能によって、変数と同様にSQL文で引用符付き文字列を使用できます。
構文
EXEC SQL PREPARE statement_id FROM :sql_statement ;
変数
statement_id
これを宣言しないでください。これは未宣言のSQL識別子です。
sql_statement
埋込みSQL文を格納する文字列(定数または変数)。
例
char* statement = "SELECT ENAME FROM emp WHERE deptno = :d" ; EXEC SQL PREPARE S1 FROM :statement ;
用途
この文はバインド変数についての情報を戻します。
構文
EXEC SQL DESCRIBE INPUT statement_id USING [SQL] DESCRIPTOR [GLOBAL | LOCAL] {:desc_nam | string_literal} ;
変数
statement_id
PREPAREおよびDESCRIBE OUTPUTで使用するものと同じです。これを宣言しないでください。これは未宣言のSQL識別子です。
GLOBAL | LOCAL
デフォルトでは、オプション句のスコープはLOCALに設定されています。ローカル記述子は、その記述子を割り当てたファイル内でのみアクセス可能です。グローバル記述子は、コンパイル・ユニット内のどのモジュールでも使用できます。
desc_nam
記述子名。
使用上の注意
DESCRIBE INPUTでは、COUNTおよびNAME項目のみが設定されます。
例
EXEC SQL DESCRIBE INPUT S1 USING SQL DESCRIPTOR GLOBAL :binddes ; EXEC SQL DESCRIBE INPUT S2 USING DESCRIPTOR 'input' ;
用途
PREPAREされた文の出力列についての情報を取得する場合は、この文を使用します。ANSI構文は、旧バージョンのOracle構文と異なります。SQL記述子領域に格納される情報は、戻された値の個数、および関連する情報(型、長さ、名前など)です。
構文
EXEC SQL DESCRIBE [OUTPUT] statement_id USING [SQL] DESCRIPTOR [GLOBAL | LOCAL] {:desc_nam | string_literal} ;
変数
statement_id
PREPAREで使用するものと同じです。これを宣言しないでください。これは未宣言のSQL識別子です。
GLOBAL | LOCAL
デフォルトでは、オプション句のスコープはLOCALに設定されています。ローカル記述子は、その記述子を割り当てたファイル内でのみアクセス可能です。グローバル記述子は、コンパイル・ユニット内のどのモジュールでも使用できます。
desc_nam
記述子名。
OUTPUTがデフォルト設定で、これは省略できます。
例
char* desname = "SELDES" ; EXEC SQL DESCRIBE S1 USING SQL DESCRIPTOR 'SELDES' ; /* Or, */ EXEC SQL DESCRIBE OUTPUT S1 USING DESCRIPTOR :desname ;
用途
EXECUTEは、準備済のSQL文の入力変数および出力変数を照合し、文を実行します。EXECUTEのANSIバージョンは、1つの文中に2つの記述子を割り当てることでDML RETURNING句をサポートできる点で、旧バージョンのEXECUTE文とは異なります。
構文
EXEC SQL [FOR :array_size] EXECUTE statement_id [USING [SQL] DESCRIPTOR [GLOBAL | LOCAL] {:desc_nam | string_literal}] [INTO [SQL] DESCRIPTOR [GLOBAL | LOCAL] {:desc_nam | string_literal}] ;
変数
array_size
文が処理する行数。
statement_id
PREPAREで使用するものと同じです。これを宣言しないでください。これは未宣言のSQL識別子です。リテラルを指定できます。
GLOBAL | LOCAL
デフォルトでは、オプション句のスコープはLOCALに設定されています。ローカル記述子は、その記述子を割り当てたファイル内でのみアクセス可能です。グローバル記述子は、コンパイル・ユニット内のどのモジュールでも使用できます。
desc_nam
記述子名。
使用上の注意
INTO句により、INSERT、UPDATEおよびDELETEのDML RETURNING句が実装されます。
関連項目:
例
EXEC SQL EXECUTE S1 USING SQL DESCRIPTOR GLOBAL :binddes ; EXEC SQL EXECUTE S2 USING DESCRIPTOR :bv1 INTO DESCRIPTOR 'SELDES' ;
用途
リテラルまたはSQL文を含むホスト変数文字列を実行します。この文のANSI SQL形式は、旧バージョンのOracle動的SQLと同じです。
構文
EXEC SQL EXECUTE IMMEDIATE {:sql_statement | string_literal}
変数
sql_statement
文字列内のSQL文またはPL/SQLブロック。
例
EXEC SQL EXECUTE IMMEDIATE :statement ;
用途
問合せ文に対応付けられたカーソルを宣言します。これは、一般的なカーソル宣言部です。
構文
EXEC SQL DECLARE cursor_name CURSOR FOR statement_id;
変数
cursor_name
カーソル変数(SQL識別子であり、ホスト変数ではありません)。
statement_id
未宣言のSQL識別子。
例
EXEC SQL DECLARE C1 CURSOR FOR S1 ;
用途
OPEN文は、入力パラメータとカーソルとを対応付け、カーソルをオープンします。
構文
EXEC SQL [FOR :array_size] OPEN dyn_cursor [[USING [SQL] DESCRIPTOR [GLOBAL | LOCAL] {:desc_nam1 | string_literal}] [INTO [SQL] DESCRIPTOR [GLOBAL | LOCAL] {:desc_nam2 | string_literal}]] ;
変数
array_size
この変数は、記述子を割り当てた時に指定した数と等しいか、それよりも小さい数に制限されます。
dyn_cursor
カーソル変数。
GLOBAL | LOCAL
デフォルトでは、オプション句のスコープはLOCALに設定されています。ローカル記述子は、その記述子を割り当てたファイル内でのみアクセス可能です。グローバル記述子は、コンパイル・ユニット内のどのモジュールでも使用できます。
desc_nam
記述子名。
使用上の注意
カーソルに対応付けられた準備済の文にコロンまたは疑問符が含まれる場合は、USING句を指定する必要があります。指定しない場合は、ランタイム・エラーが発生します。DML RETURNING句がサポートされています。
関連項目:
例
EXEC SQL OPEN C1 USING SQL DESCRIPTOR :binddes ; EXEC SQL FOR :limit OPEN C2 USING DESCRIPTOR :b1, :b2 INTO SQL DESCRIPTOR :seldes ;
用途
動的DECLARE文で宣言されたカーソルの行をフェッチします。
構文
EXEC SQL [FOR :array_size] FETCH cursor INTO [SQL] DESCRIPTOR [GLOBAL | LOCAL] {:desc_nam | string_literal} ;
変数
array_size
文が処理する行数。
cursor
事前に宣言された動的カーソル。
GLOBAL | LOCAL
デフォルトでは、オプション句のスコープはLOCALに設定されています。ローカル記述子は、その記述子を割り当てたファイル内でのみアクセス可能です。グローバル記述子は、コンパイル・ユニット内のどのモジュールでも使用できます。
desc_nam
記述子の名前。
使用上の注意
FOR句のarray_size
オプションは、ALLOCATE DESCRIPTOR文で指定された数以下にする必要があります。
例
EXEC SQL FETCH FROM C1 INTO DESCRIPTOR 'SELDES' ; EXEC SQL FOR :arsz FETCH C2 INTO DESCRIPTOR :desc ;
用途
動的カーソルをクローズします。構文は、旧バージョンのOracle方法4から変更されていません。
構文
EXEC SQL CLOSE cursor ;
変数
cursor
事前に宣言された動的カーソル。
例
EXEC SQL CLOSE C1 ;
ANSI動的SQLインタフェースは、Oracle動的方法4がサポートしたすべてのデータ型に加え、次の機能をサポートしています。
ANSI動的SQLによるオブジェクト型、結果セットおよびLOB型を含むすべてのデータ型のサポート。
ANSIモードでは、内部のSQL記述領域が使用されますが、これは、Oracleの以前の動的方法4で入力および出力情報の格納に使用される外部SQLDAを拡張したものです。
ALLOCATE DESCRIPTOR、DEALLOCATE DESCRIPTOR、DESCRIBE、GET DESCRIPTORおよびSET DESCRIPTORという新しい埋込みSQL文が導入されています。
ANSI動的SQLでは、DESCRIBE文は標識変数の名前を戻しません。
ANSI動的SQLでは、戻される列名または式の最大サイズを指定できません。デフォルト・サイズは128に設定されます。
記述子名は、引用符で囲んだ識別子、または先頭にコロンをつけたホスト変数のどちらかであることが必要です。
出力時に、DESCRIBE文のSELECT LIST FOR句はオプション・キーワードOUTPUTに置き換えられます。INTO句はUSING DESCRIPTOR句に置き換えられます。この句には、オプション・キーワードSQLを含めることができます。
入力時に、DESCRIBE文のオプションのBIND VARIABLES FOR句をキーワードINPUTに置き換えることができます。INTO句はUSING DESCRIPTOR句に置き換えられます。この句には、オプション・キーワードSQLを含めることができます。
EXECUTE、FETCHおよびOPEN文でUSING句のキーワードDESCRIPTORの前にオプション・キーワードSQLを指定できます。