SQL プリプロセッサでは、次の 2 つのデータ構造体を使用します。
| データ構造体 | 説明 | 機能 |
|---|---|---|
| SQLCA | SQL 通信領域 | ステータスとエラーの情報を返します。 |
| SQLDA | SQL 記述子領域 | 動的 SQL 文で使用される変数を記述します。 |
埋め込み SQL 文を実行するたびに、エラーおよびステータスの情報が SQLCA (SQL communications area; SQL 通信領域) に返されます。
Oracle、Sybase、および Informix では、SQLCA のバージョンがそれぞれ異なっています。Oracle、Sybase、および Informix の SQLCA にはどれも、SQLCODE、SQLERRML、SQLERRMC、および SQLWARN フィールドが存在します。フィールドのサイズや位置は、プリコンパイラの種類によって異なる場合があります。
SQLCA データ構造体のレイアウトの詳細は、ヘルプトピックの『SQLCA データ構造体』を参照してください。
SQLCA には 2 つの変数 (SQLCODE および SQLSTATE) の他、前回実行した SQL 文でエラーが発生したかどうかを示す一連の警告フラグが含まれています。
COBSQL
COBSQL では、SQLSTATE は独立したデータ項目です。現在サポートされているバージョンの Oracle と Sybase では、SQLSTATE 変数よりも SQLCA を優先して使用してください。将来的には、データベースとクライアントアプリケーション間でのデータの受け渡しの方法として、SQLCA ではなく SQLSTATE 変数が使用されるようになりますが、まだ実現されていません。
埋め込み SQL 文が正常に実行できたかどうかを確認する手段としては、SQLCODE 変数の値をチェックするのが最も一般的です。
SQLCODE 値の詳細は、ヘルプトピックの『SQLCODE 値』を参照してください。
COBSQL および DB2
COBSQL と DB2 の場合には、上記以外にも正の値が返される可能性があります。これは、SQL 文は実行されたが、警告が生成されたということを意味します。
COBSQL
SQLSTATE 変数は SQL-92 標準に導入された、将来のアプリケーションの推奨機構です。この変数は、次の 2 つの構成要素からなります。
値「00000」は、前の埋め込み SQL 文が正常に実行されたことを示します。
Oracle、Sybase、または Informix 使用時の SQLSTATE に格納される値の詳細は、関連のデータベースエラー メッセージマニュアルを参照してください。 SQLSTATE 値の詳細は、ヘルプトピックの『SQLSTATE 値』を参照してください。
DB2
DB2 ユニバーサルデータベースでは、SQL-92 準拠の SQLSTATE 値を返します。DB2 バージョン 2.1 では異なります。
文を実行すると警告が生成されることがあります。警告の種類を確認するには、アプリケーションで SQLWARN フラグの値を確認する必要があります。
このフラグには、特定の警告が発生すると「W」、それ以外の場合には空白文字が設定されます。
各 SQLWARN フラグにはそれぞれ特定の意味があります。SQLWARN フラグの意味については、ヘルプトピックの『SQLCA データ構造体』を参照してください。
埋め込み SQL 文を実行するたびに SQLCODE または SQLSTATE の値を明確に確認するには、多くのコードを記述する必要があります。この問題を回避するには、アプリケーションで WHENEVER 文を使用して、SQL 文のステータスを確認します。
WHENEVER 文は実行文ではありません。埋め込み SQL 文が実行されるたびに、コンパイラ指令として、コンパイラにエラー処理コードを自動生成させます。
WHENEVER 文では、次の各条件に対して 3 つのデフォルト動作 (CONTINUE、GOTO、PERFORM) のいずれかを登録できます。
| 条件 | SQLCODE の値 |
|---|---|
| NOT FOUND | 100 |
| SQLWARNING | +1 |
| SQLERROR | < 0 (負の値) |
ある特定の条件に対する WHENEVER 文は、その条件に対する以前の WHENEVER 文をすべて置き換えます。
WHENEVER 文の範囲は、実行シーケンス内の論理位置ではなく、原始プログラム内の物理位置に関連します。たとえば、次のコードで、最初の SELECT 文が何も戻さない場合には、段落 C ではなく段落 A が処理されます。
EXEC SQL
WHENEVER NOT FOUND PERFORM A
END-EXEC.
perform B.
EXEC SQL
SELECT col1 into :host-var1 FROM table1
WHERE col2 = :host-var2
END-EXEC.
A.
display "最初の項目が見つかりません".
B.
EXEC SQL
WHENEVER NOT FOUND PERFORM C.
END-EXEC.
C.
display "2 番目の項目が見つかりません".
Oracle、Sybase、および Informix では、SQLWARN0 が「W」に設定されると、「SQLWARNING」句がトリガーされます。
Oracle
Oracle プリコンパイラ指令 MODE の設定に関わらず、SELECT 文または FETCH 文からデータが戻されなかった場合には、常に NOT FOUND 条件がトリガーされます。
Informix
Informix では、WHENEVER 文内から STOP または CALL を実行できます。これは ANSI 標準に追加され、『INFORMIX-ESQL/COBOL Programmer's Manual』で説明されています。
SQLERRM データ領域は、データベースサーバーからアプリケーションにエラー メッセージを渡すために使用されます。 SQLERRM データ領域は、次の 2 つの部分で構成されています。
エラールーチン内では、次のコードを使用して、SQL エラー メッセージを表示できます。
if (SQLERRML > ZERO) and (SQLERRML < 80)
display 'エラー メッセージ : ', SQLERRMC(1:SQLERRML)
else
display 'エラー メッセージ : ', SQLERRMC
end-if.
SQLERRD データ領域は、6 つの整数の状態値をもつ配列です。
Oracle、Sybase、および Informix では、SQLERRD 配列内に 6 つの値のうちの 1 つ (またはそれ以上) が設定される場合があります。これらは、直前に実行した SQL 文により影響を受ける行数を示します。たとえば、SQLERRD(3) には、SELECT 文または一連の FETCH 文で返された行の合計数が格納されています。
SQLDA の SQLERRD の第 3 要素 (SQLERRD(3)) には、INSERT、UPDATE、DELETE、および SELECT INTO の各文で処理された行数が記録されます。FETCH 文の場合は、SQLERRD(3) に処理済み行の累計数が記録されます。
SQLERRD(3)
DB2 では、SQLERRD(3) に次の内容が格納されます。
SQLERRD(4)
DB2 では、SQLERRD(4) に次の内容が格納されます。
SQLERRD(5)
DB2 では、SQLERRD(5) に次の内容が格納されます。
SQLDA (SQL descriptor area; SQL 記述子領域) は、プリコンパイラごとに一意です。Oracle SQLDA は、Sybase、OpenESQL、または DB2 で使用される SQLDA と互換性がありません。同様に、Sybase、OpenESQL、または DB2 で使用される SQLDA は、Oracle SQLDA と互換性がありません。
多数のパラメーターを渡す場合や、コンパイル時にデータ型が不明な場合は、ホスト変数ではなく、SQL 記述子領域 (SQLDA) を使用します。
SQLDA には、入力パラメーターや出力カラムの詳細情報が格納されます。詳細情報には、カラム名、データ型、長さ、または各入力パラメーターや出力パラメーターで使用するデータバッファーへのポインターが含まれます。SQLDA はパラメーターマーカーと併用して、PREPARE 文で定義した SQL 文への入力値を指定します。ただし、PREPARE 文で定義した SELECT 文からデータを取得するには、DESCRIBE 文 (または PREPARE 文の INTO オプション) を使用することもできます。
静的 SQL 文の SQLDA は使用できませんが、カーソル FETCH 文の SQLDA は使用できます。
Oracle、Sybase、および Informix では、プログラムが動的 SQL を使用する場合に限り SQLDA が必要です。SQLDA を標準の COBOL コピーファイルとして定義する必要があります。そのため、次の構文を使用してプログラムにインクルードできません。
EXEC SQL INCLUDE SQLDA END-EXEC
Oracle には、動的 SQL と使用する特別なコピーファイル ORACA が用意されています。これは、次の構文を使用してプログラムにインクルードできます。
EXEC SQL INCLUDE ORACA END-EXEC
ORACA コピーファイルを使用するには、Oracle プリコンパイラオプション ORACA=YES を設定する必要があります。Oracle プリコンパイラオプションの設定の詳細は、『ORACLE プリコンパイラ プログラマーズ ガイド』を参照してください。
Oracle では SQLDA が提供されません。SQLDA に関する内容や ORACA コピーファイルの詳細は、『ORACLE プリコンパイラ プログラマーズ ガイド』を参照してください。
Sybase では SQLDA コピーファイルは提供されません。Sybase プリコンパイラのマニュアルでは、SQLDA のレイアウトと、そのレイアウト内の各種項目に値を割り当てる方法が説明されています。また、このマニュアルでは、Sybase を使用して COBOL データ形式と Sybase データ型の変換を行う方法も説明されています。
Informix では SQLDA コピーファイルは提供されません。Informix プリコンパイラのマニュアルでは、Informix の動的 SQL を使用するために定義するデータ項目のレイアウトが説明されています。
SQLCA 構造体は、システムの基本インストールディレクトリにある source ディレクトリ内の sqlca.cpy ファイルで定義されています。次の文をデータ部に追加して、COBOL プログラムに SQLDA 構造体をインクルードできます。
EXEC SQL INCLUDE SQLDA END-EXEC
OpenESQL SQLDA の詳細は、ヘルプトピックの『SQLDA データ構造体』を参照してください。
SQLDA 構造体を使用する前に、アプリケーションで次のフィールドを初期化する必要があります。
| SQLN | このフィールドは、SQLDA 構造体で保持できる SQLVAR 項目の最大数に設定します。 |
| SQLDABC |
SQLDA の最大サイズ。
|
DESCRIBE 文 (または INFO オプションを指定した PREPARE 文) を使用して、SQLDA 構造体の適切なフィールドにカラム名やデータ型などの情報を入力できます。
これらの文を実行するには、前述したように SQLN フィールドと SQLDABC フィールドを初期化する必要があります。
文を実行する場合は、PREPARE で定義された文のパラメーター数が SQLD フィールドに含まれます。パラメーターごとに SQLTYPE と SQLLEN フィールドが設定され、SQLVAR レコードが設定されます。
SQLN にどの位の大きさの値を設定すればよいかわからない場合には、SQLN に 1、SQLD に 0 を設定して DESCRIBE 文を実行できます。この場合は、詳細なカラム情報が SQLDA 構造体に転記されませんが、結果集合に含まれるカラム数が SQLD に挿入されます。
SQLDA 構造体を使用して FETCH 文を実行するには、次の処理を実行します。
データ型フィールド (SQLTYPE) とデータ長 (SQLLEN) は、PREPARE INTO または DESCRIBE 文で取り込まれた情報が格納されます。これらの値は、FETCH 文の実行前にアプリケーションで上書きできます。
SQLDA 構造体を使用して、OPEN 文または EXECUTE 文への入力データを指定するには、アプリケーションで SQLDA 構造体の全フィールドのデータを設定する必要があります。この場合は、各変数の SQLN、SQLD、SQLDABC、SQLTYPE、SQLLEN、および SQLDATA フィールドも含めて設定します。
SQLTYPE フィールドの値が奇数の場合は、SQLIND フィールドにもインジケーター変数のアドレスを設定する必要があります。
PREPARE 文の後に DESCRIBE 文を実行する場合は、指定の PREPARE 文で定義した文によって戻される各カラムのデータ型、データ長、および名前を取り出すことができます。この情報は SQL 記述子領域 (SQLDA) に戻されます。
EXEC SQL DESCRIBE stmt1 INTO :sqlda END-EXEC
PREPARE 文の実行後すぐに DESCRIBE 文を実行する場合には、次のように PREPARE 文と INFO オプションを使用する場合に、両方の操作を同時に実行できます。
EXEC SQL PREPARE stmt1 INTO :sqlda FROM :stmtbuf END-EXEC