Db2 10.5 for Linux, UNIX, and Windows
SQLCA (SQL 連絡域)
SQLCA は、すべての SQL ステートメントのそれぞれ実行の終了時に更新される変数の集まりです。
実行可能な SQL ステートメントを収めていて、 オプション LANGLEVEL SAA1 (デフォルト) または MIA を指定してプリコンパイルされたプログラムは、 1 つだけの SQLCA を用意する必要があります。 ただし、マルチスレッドのアプリケーションでは、スレッドごとに 1 つの SQLCA を用意し、 その結果 SQLCA が複数になることがあります。
オプション LANGLEVEL SQL92E を指定してプログラムをプリコンパイルした場合、 SQLCODE 変数または SQLSTATE 変数を SQL 宣言セクションで宣言することができ、 また SQLCODE 変数をプログラムで宣言することができます。
LANGLEVEL SQL92E を使用すると、SQLCA は用意されません。 REXX 以外のすべての言語では、 SQL INCLUDE ステートメントを使用して SQLCA を宣言することができます。 REXX では、自動的に SQLCA が用意されます。
コマンド行プロセッサーでそれぞれのコマンドを実行した後に SQLCA を表示するには、 コマンド db2 -a を実行します。 これにより、SQLCA は後続のコマンドの出力の一部として表示されます。 同時に SQLCA は db2diag ログ・ファイルにダンプされます。
SQLCA フィールド記述
| 名前 | データ・タイプ | フィールドの値 |
|---|---|---|
| sqlcaid | CHAR(8) | SQLCA の入ったストレージ・ダンプの「目印」。 SQL ルーチン、SQL トリガー、または動的コンパウンド SQL ステートメントの解析から行番号情報が返される場合、6 番目のバイトは L になります。コンパイル済み SQL ルーチン、コンパイル済み SQL トリガー、または動的コンパウンド SQL (コンパイル済み) ステートメントの実行から行番号およびオブジェクト ID の情報が返される場合、6 番目のバイトは M になります。 |
| sqlcabc | INTEGER | SQLCA の長さ (136) が入ります。 |
| sqlcode | INTEGER | SQL 戻りコードが入ります。
|
| sqlerrml | SMALLINT | sqlerrmc の長さ標識 (0 から 70 の範囲)。 0 は、sqlerrmc の値が関係ないことを示します。 |
| sqlerrmc | VARCHAR (70) | エラー条件の説明の中の変数を置き換える 1 つまたは複数のトークンが入り、各トークンは X'FF' で区切られます。 このフィールドは、正常に接続が完了した場合にも使用されます。 NOT ATOMIC コンパウンド SQL ステートメントが発行されると、7 つ以下のエラーに関する情報を入れることができます。 最後のトークンの後に X'FF' が続くことがあります。 sqlerrml の値には、後続の X'FF' が含まれます。 |
| sqlerrp | CHAR(8) | 製品を示す 3 文字の ID の後に、製品のバージョン、リリース、および修正レベルを示す 5 つの英数字が続きます。文字 A から Z までは 9 より高い修正レベルを示します。「A」は修正レベル 10 を示し、「B」は修正レベル 11 を示し、以後同様です。
 例えば、SQL0907C は DB2® バージョン 9、リリース 7、修正レベル 12 を意味します。 SQLCODE がエラー条件を示している場合、 そのエラーを戻したモジュールがこのフィールドに示されます。 このフィールドは、正常に接続が完了した場合にも使用されます。 |
| sqlerrd | ARRAY | 診断情報の提供に使用される 6 個の INTEGER 変数。 これらの値は、エラーがない場合は通常は空ですが、パーティション・データベースの sqlerrd(6) は例外です。 |
| sqlerrd(1) | INTEGER | 接続が正常に起動された場合、
アプリケーションのコード・ページからデータベースのコード・ページに変換する際に予想される
混合文字データ (CHAR データ・タイプ) の長さの差の最大値が入ります。
0 または 1 の値は、長さが変わらないことを示し、1 より大きい値は長さが長くなることを、
負の値は切り捨てが生じることを示します。
SQL プロシージャーから正常に戻された場合、その SQL プロシージャーからの戻り状況値が入ります。 |
| sqlerrd(2) | INTEGER | 接続が正常に起動された場合、 データベースのコード・ページからアプリケーションのコード・ページに変換する際に予想される 混合文字データ (CHAR データ・タイプ) の長さの差の最大値が入ります。 0 または 1 の値は、長さが変わらないことを示し、1 より大きい値は長さが長くなることを、 負の値は切り捨てが生じることを示します。 SQLCA がエラーの発生した NOT ATOMIC コンパウンド SQL ステートメントの結果である場合、 この値はエラーの発生したステートメントの番号に設定されます。 |
| sqlerrd(3) | INTEGER | PREPARE を呼び出して正常に実行した場合は、
戻される行の数の見積もりが入ります。
INSERT、UPDATE、DELETE、または MERGE を実行した後は、
実際にその操作のために修飾された行の数になります。
TRUNCATE ステートメントの場合、値は -1 になります。 コンパウンド SQL を呼び出した場合は、すべてのサブステートメント行の累計が入ります。
CONNECT が呼び出され、データベースが更新可能な場合は 1、
データベースが読み取り専用の場合は 2 が入ります。
OPEN ステートメントが呼び出され、カーソルに SQL データ変更ステートメントが入っている場合、 このフィールドには、組み込まれた挿入、更新、削除、 またはマージ操作のために修飾された行の合計が入ります。 SQL ルーチン、トリガー、または動的コンパウンド SQL (インライン化またはコンパイル済み) ステートメントのコンパイル中にエラーが発生した場合、sqlerrd(3) には、エラーが発生した行番号が含まれます。有効な行番号を表すために、この項目の sqlcaid の 6 バイト目は必ず 'L' になります。 コンパイル済み SQL ルーチン、トリガー、または動的 SQL (コンパイル済み) ステートメントの実行中にエラーが発生した場合、sqlerrd(3) には、エラーが発生した行番号が含まれます。この場合、有効な行番号を表すために、sqlcaid の 6 バイト目は必ず 'M' になります。 |
| sqlerrd(4) | INTEGER | PREPARE が正常に呼び出された場合、ステートメントを処理するのに必要なリソースの 相対コスト見積もりが入ります。 コンパウンド SQL を呼び出した場合は、 正常に実行されたサブステートメントの数のカウントが入ります。 CONNECT を呼び出した場合は、 最新レベルにないクライアントからの 1 フェーズ・コミットなら 0、 1 フェーズ・コミットなら 1、1 フェーズの読み取り専用コミットなら 2、 2 フェーズ・コミットなら 3 が入ります。 コンパイル済み SQL ルーチンまたはトリガーの実行中にエラーが発生した場合、sqlerrd(4) には、エラーが発生したルーチンまたはトリガーを一意的に識別する整数が含まれます。有効な行番号を表すために、この項目の sqlcaid の 6 バイト目は必ず 'M' になります。 |
| sqlerrd(5) | INTEGER | 以下の両方の結果として削除、挿入、または更新された行の合計数が入ります。
|
| sqlerrd(6) | INTEGER | パーティション・データベースの場合、エラーまたは警告が出されたデータベース・パーティションのパーティション番号が入ります。 エラーまたは警告が出されなかった場合は、 このフィールドにはコーディネーター・パーティションのパーティション番号が入ります。 このフィールドに入る番号は、 db2nodes.cfg ファイルでデータベース・パーティションに対して指定されたものと同じです。 |
| sqlwarn | 配列 | 一連の警告標識で、それぞれの標識はブランクか W です。 コンパウンド SQL を呼び出した場合は、 すべてのサブステートメントについての警告標識の累積が入ります。 |
| sqlwarn0 | CHAR(1) | 他の標識がすべてのブランクの場合はブランク、 1 つでもブランクでない標識があれば「W」。 |
| sqlwarn1 | CHAR(1) | ホスト変数への割り当て時にストリング列の値が切り捨てられた場合は「W」になります。 NULL 終止符が切り捨てられた場合は「N」になります。 CONNECT または ATTACH が正常に実行され、 その接続の許可名が 8 バイトを超える場合は「A」になります。 sqlerrd(4) 内に保管されている PREPARE ステートメントの相対コスト見積もりが、 INTEGER 内に保管できたであろう値を超える場合や、1 より小さかった場合に、 CURRENT EXPLAIN MODE または CURRENT EXPLAIN SNAPSHOT 特殊レジスターが NO 以外の値に設定されていると、 「P」になります。 |
| sqlwarn2 | CHAR(1) | 集約関数の引数から NULL 値が削除された場合、「W」が入ります。a CONNECT が呼び出されて正常に実行された場合に、データベースが静止状態であれば「D」が入り、インスタンスが静止状態であれば「I」が入ります。 |
| sqlwarn3 | CHAR(1) | 列の数とホスト変数の数が等しくない場合、「W」が入ります。 ASSOCIATE LOCATORS ステートメントに指定されている結果セット・ロケーターが、 プロシージャーから戻された結果セットの数より少ない場合、「Z」が入ります。 |
| sqlwarn4 | CHAR(1) | 準備された UPDATE または DELETE ステートメントに WHERE 節が指定されていない場合に、 「W」が入ります。 |
| sqlwarn5 | CHAR(1) | SQL ステートメントの実行中にエラーが許容された場合、「E」が入ります。 |
| sqlwarn6 | CHAR(1) | 存在しない日付を避けるために日付演算の結果が調整された場合に「W」が入ります。 |
| sqlwarn7 | CHAR(1) | 将来の利用のために予約済み。 |
| sqlwarn8 | CHAR(1) | 変換できなかった文字が置換文字に置き換えられた場合に「W」になります。トラステッド接続の確立の試行に失敗した場合に「Y」になります。 |
| sqlwarn9 | CHAR(1) | エラーのある算術式が集約関数の処理時に無視された場合に「W」になります。 |
| sqlwarn10 | CHAR(1) | SQLCA 内のフィールドのいずれかで、 文字データ値の変換時に変換エラーが起きた場合、「W」が入ります。 |
| sqlstate | CHAR(5) | 直前に実行された SQL ステートメントの結果を示す戻りコード。 |
| a 一部の関数では、NULL 値が除去されても SQLWARN2 が W にならないことがあります。 これは、結果が NULL 値の除去によるものでない場合に生じます。 |
||
エラー報告
エラー報告の順序は、以下のとおりです。
- 重大エラー条件は必ず報告されます。 重大エラーが報告される場合、SQLCA に追加されるものはありません。
- 重大エラーが発生しなかった場合、 デッドロック・エラーはその他のエラーよりも優先します。
- その他のエラーの場合、最初の負の SQL コードの SQLCA が戻されます。
- 負の SQL コードが検出されない場合、
最初の警告の SQLCA (つまり正の SQL コード) が戻されます。
パーティション・データベース・システムで、あるデータベース・パーティションでは空で、他のデータベース・パーティションにはデータがある表に対してデータ操作コマンドが呼び出される場合は、この規則の例外です。 すべてのデータベース・パーティションで表が空であるため、または UPDATE ステートメントの WHERE 節の条件を満たす行がもうないために、すべてのデータベース・パーティションのエージェントが SQL0100W を返した場合のみ、アプリケーションに SQLCODE +100 が返されます。
パーティション・データベース・システムでの SQLCA の使用法
パーティション・データベース・システムでは、異なるデータベース・パーティションにある多くのエージェントが 1 つの SQL ステートメントを実行する場合があり、それぞれのエージェントが異なるエラーまたは警告についての異なる SQLCA を戻す場合があります。 また、コーディネーターのエージェントには独自の SQLCA があります。
- エラーと警告のすべてについて、sqlwarn フィールドには すべてのエージェントから受け取った警告標識が入ります。
- 行カウントを表示する sqlerrd フィールドの値は、 すべてのエージェントからの累計です。
トリガーにより実行された SQL ステートメントの処理中に発生したエラーのケースによっては、 SQLSTATE 09000 が戻されないことがあるので注意してください。