16.20 - SQLCODE - Teradata Vantage NewSQL Engine

Teradata Vantage™ SQL ストアド プロシージャおよび埋め込みSQL

prodname
Teradata Database
Teradata Vantage NewSQL Engine
vrm_release
16.20
category
プログラミング リファレンス
featnum
B035-1148-162K-JPN

ANSIセッション モードでは、SQLCODEは、SQL文のステータス情報を受け取るホスト変数(埋め込みSQL)またはステータス変数(ストアド プロシージャ)です。この情報は、エラー コードや警告コード、および制御文を含めたSQL文の状態です。ステータス コードでは、アプリケーション プログラムは、実行可能な埋め込みSQL文が正常に完了したかどうかテストできます。

Teradataセッション モード(埋め込みSQL用)では、SQLCODEはSQLCA内の1つのフィールドです。

ANSI準拠

SQLCODEは、ANSI/ISO SQL:2011に準拠していません。SQLCODEは、ANSI/ISO SQL-92規格で非推奨になり、SQL:2011規格では定義されていません。ANSI/ISO SQL委員会では、SQLCODEの代わりにSQLSTATEを使用して新しいアプリケーションを作成することを推奨しています。

SQLCODEは、SQLSTATEホスト変数を指定しない、ANSIセッション モードで作成されたすべての埋め込みSQLアプリケーションに必要です。つまり、作成するすべての埋め込みSQLアプリケーションにどちらか(または両方)を指定する必要があり、SQLSTATEを選択するほうが望ましいということです。

ストアド プロシージャ アプリケーションでは、SQLCODEまたはSQLSTATE (またはその両方)のステータスをテストできます。

ANSI/ISO SQL-99規格、SQL:2011規格のいずれにおいても、SQLCA内のSQLCODEフィールドは定義されておらず、SQLCAも定義されていません。ストアド プロシージャでは、SQLCAを使用しません。

ANSIセッション モードのSQLCODE

SQLCODEは、32ビットの符号付き整数として定義されています。

埋め込みSQLアプリケーションのSQL DECLARE SECTION内でSQLCODEが定義されていない場合、Preprocessor2はプログラム内で有効なSQLCODEが定義されているものと見なします。

ストアド プロシージャでは、SQLCODEまたはSQLSTATEのいずれかのステータス値をテストできます。

Teradataセッション モードでのSQLCODE

SQLCA内のSQLCODEフィールドは、SQL文を実行した結果を埋め込みSQLアプリケーション プログラムに送ります。ストアド プロシージャでは、SQLCAを使用しません。

Preprocessor2オプションSQLFLAGGERまたは-sfがNONEにセットされる場合、SQLCODEはSQLCAによって埋め込みSQLアプリケーション プログラム内で定義されます。それ以外の場合、アプリケーション内でSQLCODEを明示的に定義する必要があります。

ストアド プロシージャでは、SQLCODEまたはSQLSTATEのいずれかのステータス値をテストできます。

SQLCODE値のカテゴリ

埋め込みSQLまたはストアド プロシージャの文が実行された後でアプリケーションに戻されるSQLCODE値は、次の表で説明するように、必ず3つのカテゴリのいずれかになります。

SQLCODE値 意味
処理時にエラーが発生した。

エラーの性質は、コードの数値で示されます。

0 処理は正常に行なわれた。
通常どおりに終了した。

0および+100以外の正の値は、システムによる警告を示しています。

例えば、+100のSQLCODE値は、次の結果のいずれかを示します。
  • 行が選択されなかった。
  • 選択されたすべての行が処理された。

SQLCODEの更新

SQLCODEは、各実行可能文が処理された後の実行時に更新されます。SQLCODE変数に書き込まれるステータスコードをテストするため、独自のアプリケーション コードを作成する必要があります。

SQLCODEのテスト

SQL文の実行後には、SQLCODEを毎回テストし、文が正常に完了したこと、または失敗した文が適切に処理されることを確実にします。

やはり、受け入れられないSQLCODE値を解決するために、コードを作成する必要があります。

SQLCODEテストの例

一時テーブルを作成した後、INSERT…SELECT文を使用してそのテーブルに値を入れるアプリケーションについて考えてみましょう。

その場合、CREATE TABLE文の実行直後にSQLCODEの検査を実行するコードを記述してください。

この文がテーブルの正常な作成に失敗すると、その文に続くINSERT…SELECT文を実行する意味がなくなります。そこで、WHENEVER文のコードを記述して、INSERT…SELECTの実行を防止したり、予定どおりで問題がなければ処理を続けたりするような適切なアクションを実行するようにします。

また、INSERT…SELECT文も検査して、それに続く一時テーブルの参照が有効であることを確認すると良いでしょう。

例えば、SQLCODE値が0であれば、1つ以上の行が正常に選択されて挿入されたことを示します。

値が+100であれば、選択または挿入された行はなく、テーブルが空であることを示します。そのような場合、空の一時テーブルを後で参照しても不正確であるため、これ以降に空の一時テーブルへの参照が行なわれないように、いくらかの処置を取る必要があります。

Teradata Databaseエラー メッセージがSQLCODE値にマッピングする仕組み

SQLCODE値のTeradata Databaseエラー メッセージ番号へのマッピングについては、SQLコミュニケーション領域(SQLCA)を参照してください。

ストアド プロシージャでのSQLCODE使用上の制約

ストアド プロシージャ内では、次のようなSQLCODEの使用は可能です。
  • SET文のオペランドとして指定する場合。

    例えば、次の文は可能です。

    SET h1 = - SQLCODE;
    IF SQLCODE = h1 THEN
    ...
    ...
    END IF;
  • ストアド プロシージャ内のSQL文の式として指定する場合。

    例えば、次のような文が可能です。

    INSERT INTO table_1 (column_1)
    VALUES (:SQLCODE);
    UPDATE table_1
    SET column_1 = column_1 + :SQLCODE;
ストアド プロシージャ内では、次のようなSQLCODEの使用は無効です。
  • SQLCODEは明示的に宣言できない。
  • SQLCODEは値または式にSETできない。

    例えば、次の文は無効です。

    SET SQLCODE = h1 + h2;
  • SQLCODEは、SELECT文のINTO句には指定できない。

    例えば、次の文は無効です。

    SELECT column_1 INTO :SQLCODE FROM table_1;
  • SQLCODEは、CALL文のINOUTおよびOUTパラメータの代わりには指定できない。

関連トピック

以下に関する詳細な情報