29.8.1 CBLSQLERROR(Linux(x86),Linux(x64)で有効)

CBLSQLERRORサービスルーチンは,埋め込みSQL文によるODBCインタフェース機能の使用時に,出力された実行時メッセージのエラー情報(COBOLメッセージ番号,SQLSTATE,SQLエラーコード)を取得します。

形式

CALL 'CBLSQLERROR' USING 引数1

引数
  • 引数1は,取得する実行時エラーメッセージのエラー情報を指定します。この項目は次の形式の集団項目とします。

    表29-4 CBLSQLERRORサービスルーチンのインタフェース領域

    記述形式内容

    01 データ名01.

    CALL文のUSINGで指定するエラー情報取得領域の名前を指定する。

    02 データ名02 PIC S9(9)
                   USAGE COMP.

    COBOLメッセージ番号

    02 FILLER    PIC X(7).

    予備。このサービスルーチンを呼び出す前にLOW-VALUE(X'00')を設定しなければならない。

    02 データ名03 PIC X(5).

    SQLSTATE

    02 データ名04 PIC S9(9)
                   USAGE COMP.

    SQLエラーコード

    02 FILLER    PIC X(516).

    予備。このサービスルーチンを呼び出す前にLOW-VALUE(X'00')を設定しなければならない。
戻り値
0:エラー情報が取得できた場合
100:エラー情報がない場合
-1:エラー情報の取得に失敗した場合
規則
  • CBLSQLERRORサービスルーチンを呼び出すと,直前に実行された埋め込みSQL文で出力されたエラーメッセージに対するエラー情報(COBOLメッセージ番号,SQLSTATE,SQLエラーコード)が引数1に設定されます。また,SQL文実行時のエラーメッセージ出力抑止の環境変数を指定した場合でも,抑止されたメッセージのエラー情報が設定されます。引数1に設定されるエラー情報を次に示します。

    表29-5 引数1に設定されるエラー情報の説明

    エラー情報説明
    COBOLメッセージ番号直前に実行された埋め込みSQL文で出力されたKCCC8000R-SからKCCC8026R-Sのメッセージ番号が設定されます。メッセージについては,マニュアル「COBOL2002 メッセージ」を参照してください。
    SQLSTATEODBCドライバマネージャが返す診断コードが設定されます。詳細については,使用しているODBCドライバまたはDBMSのマニュアルを参照してください。
    SQLエラーコードデータソース固有のネイティブエラーコードが設定されます。詳細については,使用しているODBCドライバまたはDBMSのマニュアルを参照してください。
  • CBLSQLERRORサービスルーチンの戻り値は,RETURN-CODE特殊レジスタで参照できます。
  • SQLSTATEおよびSQLエラーコードは,実行時メッセージKCCC8002R-SまたはKCCC8007R-Wが出力された場合に設定されます。それ以外の実行時メッセージの場合は,SQLSTATEには空白,SQLエラーコードには0が設定されます。
  • SQLSTATEおよびSQLエラーコードは,実行時メッセージKCCC8002R-SまたはKCCC8007R-Wが出力された場合に設定されます。それ以外の実行時メッセージの場合は,SQLSTATEには空白,SQLエラーコードには0が設定されます。
  • 直前に実行された埋め込みSQL文で複数のエラーメッセージが出力された場合,CBLSQLERRORサービスルーチンの戻り値が100になるまで繰り返し呼び出すことで,すべてのエラー情報を取得できます。CBLSQLERRORサービスルーチンの戻り値が100の場合,COBOLメッセージ番号,SQLエラーコードは0,SQLSTATEには空白が設定されます。
  • 埋め込みSQL文を実行しないでCBLSQLERRORサービスルーチンを実行すると,戻り値は100を返します。
  • CBLSQLERRORサービスルーチンでエラーが発生し,エラー情報の取得に失敗した場合,戻り値は-1を返します。
  • 暗黙的に実行されるSQL文(DISCONNECT文での暗黙的なCOMMIT文など)でエラーが発生した場合でも,CBLSQLERRORサービスルーチンはエラー情報を取得します。暗黙的に実行されるSQL文は,マニュアル「COBOL2002 言語 拡張仕様編 9. データベースアクセス機能」の各SQL文の一般規則を参照してください。
注意事項
引数の指定,および形式が「表29-4 CBLSQLERRORサービスルーチンのインタフェース領域」と異なる場合の動作は保証しません。
使用例

      IDENTIFICATION DIVISION.
      PROGRAM-ID. SAMPLE1.
               :
      DATA DIVISION.
      WORKING-STORAGE SECTION.
               :
      01  OP-1.
        02 ERR-MSGNUMBER     PIC S9(9) USAGE COMP.
        02 FILLER            PIC X(7)   VALUE LOW-VALUE.
        02 ERR-SQLSTATE      PIC X(5).
        02 ERR-SQLERRORCODE  PIC S9(9) USAGE COMP.
        02 FILLER            PIC X(516) VALUE LOW-VALUE.
      01  STMT-PROC          PIC X(20).
      01  戻り値             PIC S9(9) USAGE COMP.
               :
      EXEC SQL BEGIN DECLARE SECTION END-EXEC.
      01 ODBC-DSN            PIC X(10) VALUE 'SAMPLE'.
      01 ODBC-UID            PIC X(10) VALUE 'USER1'.
      01 ODBC-PWD            PIC X(10) VALUE 'USER1'.
      EXEC SQL END DECLARE SECTION END-EXEC.
           :
      PROCEDURE DIVISION.
               :
     *>SQL文を実行できたかどうかを<埋め込み例外宣言>にて判断します。
          EXEC SQL
               WHENEVER SQLERROR PERFORM :エラー処理  … 1.
          END-EXEC.
               :
     *>データソースに接続する。
          MOVE 'データソースへの接続' TO STMT-PROC.  … 2.
          EXEC SQL
               CONNECT :ODBC-UID IDENTIFIED BY :ODBC-PWD
                   USING :ODBC-DSN
          END-EXEC.
               :
     *>表を参照する。
          MOVE '表のデータ参照' TO STMT-PROC.  … 2.
          EXEC SQL
               SELECT  … 3.
          END-EXEC.
               :
     *>データソースから切断する。
          MOVE 'データソースから切断' TO STMT-PROC.  … 2.
          EXEC SQL
               DISCONNECT
          END-EXEC.
          STOP RUN.
               :
      エラー処理.    … 4.
          PERFORM WITH TEST AFTER UNTIL 戻り値 NOT = ZERO
            CALL 'CBLSQLERROR' USING OP-1
            MOVE RETURN-CODE TO 戻り値
            EVALUATE 戻り値
              WHEN  0
                DISPLAY STMT-PROC … 5.
     *>              << エラー情報判定,リカバリ処理 >>
                                :
              WHEN  -1
                DISPLAY 'CBLSQLERRORが失敗しました。'
            END-EVALUATE
          END-PERFORM.
               :

上記の例では,3.の埋め込みSQL文実行でエラーが発生した場合に,1.の埋め込み例外宣言の指定によって,4.のエラー処理段落が実行されます。ここでCBLSQLERRORサービスルーチンを呼び出し,エラー情報を取得します。2.のように埋め込みSQL文実行ごとに,実行状態を退避しておくと,5.で,どの実行状態でエラーが発生したかがわかります。