メッセージを生成するステートメントの処理

Transact-SQL SET ステートメントのオプション STATISTICS TIME と STATISTICS IO は、実行時間の長いクエリの診断に利用できる情報を取得する場合に使用します。以前のバージョンの SQL Server では、クエリ プランを分析するための SHOWPLAN オプションもサポートされています。ODBC アプリケーションでは、次のステートメントを実行してこれらのオプションを設定できます。

SQLExecDirect(hstmt, "SET SHOWPLAN ON", SQL_NTS);
SQLExecDirect(hstmt, "SET STATISTICS TIME ON", SQL_NTS90
);
SQLExecDirect(hstmt, "SET STATISTICS IO ON", SQL_NTS);

SET STATISTICS TIME または SET SHOWPLAN が ON の場合、SQLExecute と SQLExecDirect から SQL_SUCCESS_WITH_INFO が返されます。アプリケーションでは、その時点で SQL_NO_DATA が返されるまで SQLGetDiagRec を呼び出して SHOWPLAN 出力または STATISTICS TIME 出力を取得できます。SHOWPLAN データの各行は、次の形式で返されます。

szSqlState="01000", *pfNativeError=6223,
szErrorMsg="[Microsoft][SQL Server Native Client][SQL Server] 
              Table Scan"

SQL Server Version 7.0 では、SHOWPLAN オプションが SHOWPLAN_ALL オプションと SHOWPLAN_TEXT オプションに置き換えられました。これらの両方のオプションでは、一連のメッセージではなく、結果セットとして出力が返されます。

STATISTICS TIME の各行は、次の形式で返されます。

szSqlState="01000", *pfNativeError= 3613,
szErrorMsg="[Microsoft][SQL Server Native Client][SQL Server]
   SQL Server Parse and Compile Time: cpu time = 0 ms."

SET STATISTICS IO の出力は、結果セットの最後に到達するまで使用できません。アプリケーションでは STATISTICS IO 出力を取得するために、SQLFetch または SQLFetchScroll から SQL_NO_DATA が返された時点で SQLGetDiagRec を呼び出します。STATISTICS IO の出力は、次の形式で返されます。

szSqlState="01000", *pfNativeError= 3615,
szErrorMsg="[Microsoft][ SQL Server Native Client][SQL Server]
   Table: testshow  scan count 1,  logical reads: 1,
   physical reads: 0."

DBCC ステートメントの使用

DBCC ステートメントは、結果セットではなく、メッセージとしてデータを返します。SQLExecDirect または SQLExecute は SQL_SUCCESS_WITH_INFO を返すので、アプリケーションでは SQL_NO_DATA が返されるまで SQLGetDiagRec を呼び出して出力を取得します。

たとえば、次のステートメントは SQL_SUCCESS_WITH_INFO を返します。

SQLExecDirect(hstmt, "DBCC CHECKTABLE(Authors)", SQL_NTS);

SQLGetDiagRec を呼び出すと、次の結果が返されます。

szSqlState = "01000", *pfNativeError = 2536,
szErrorMsg="[Microsoft][ SQL Server Native Client][SQL Server]
   Checking authors"
szSqlState = "01000", *pfNativeError = 2579,
szErrorMsg="[Microsoft][ SQL Server Native Client][SQL Server]
   The total number of data pages in this table is 1."
szSqlState = "01000", *pfNativeError = 7929,
szErrorMsg="[Microsoft][ SQL Server Native Client][SQL Server]
   Table has 23 data rows."
szSqlState = "01000", *pfNativeError = 2528
szErrorMsg="[Microsoft][ SQL Server Native Client][SQL Server]
   DBCC execution completed. If DBCC printed error messages,
   see your System Administrator."

PRINT ステートメントと RAISERROR ステートメントの使用

Transact-SQL PRINT ステートメントや RAISERROR ステートメントからも、SQLGetDiagRec を呼び出すことでデータが返されます。PRINT ステートメントでは、SQL ステートメントの実行により SQL_SUCCESS_WITH_INFO が返され、その後に続けて SQLGetDiagRec を呼び出すと SQLState に 01000 が返されます。重大度が 10 以下の RAISERROR の動作は PRINT と同様です。重大度が 11 以上の RAISERROR では、ステートメントの実行により SQL_ERROR が返され、その後に続けて SQLGetDiagRec を呼び出すと SQLState に 42000 が返されます。たとえば、次のステートメントでは SQL_SUCCESS_WITH_INFO が返されます。

SQLExecDirect (hstmt, "PRINT  'Some message' ", SQL_NTS);

SQLGetDiagRec を呼び出すと、次の結果が返されます。

szSQLState = "01000", *pfNative Error = 0,
szErrorMsg= "[Microsoft] [SQL Server Native Client][SQL Server]
   Some message"

次のステートメントからは、SQL_SUCCESS_WITH_INFO が返されます。

SQLExecDirect (hstmt, "RAISERROR ('Sample error 1.', 10, -1)",
   SQL_NTS)

SQLGetDiagRec を呼び出すと、次の結果が返されます。

szSQLState = "01000", *pfNative Error = 50000,
szErrorMsg= "[Microsoft] [SQL Server Native Client][SQL Server]
   Sample error 1."

次のステートメントからは、SQL_ERROR が返されます。

SQLExecDirect (hstmt, "RAISERROR ('Sample error 2.', 11, -1)", SQL_NTS)

SQLGetDiagRec を呼び出すと、次の結果が返されます。

szSQLState = "42000", *pfNative Error = 50000,
szErrorMsg= "[Microsoft] [SQL Server Native Client][SQL Server]
   Sample error 2."

PRINT ステートメントまたは RAISERROR ステートメントからの出力が結果セットに含まれているときは、SQLGetDiagRec を呼び出すタイミングが重要になります。PRINT 出力や RAISERROR 出力を取得するには、SQL_ERROR または SQL_SUCCESS_WITH_INFO を取得するステートメントの直後に SQLGetDiagRec を呼び出す必要があります。この操作は、上記の例のように、1 つの SQL ステートメントのみを実行するときは容易に実行できます。このような場合、SQLExecDirect または SQLExecute を呼び出すと、SQL_ERROR または SQL_SUCCESS_WITH_INFO が返され、SQLGetDiagRec を呼び出すことができます。SQL ステートメントのバッチの出力を処理するループをコーディングするとき、または SQL Server ストアド プロシージャを実行するときは、1 つの SQL ステートメントのみを実行するときほど簡単ではありません。

この場合、バッチまたはストアド プロシージャで実行される SELECT ステートメントごとに、SQL Server から結果セットが返されます。バッチまたはプロシージャに PRINT ステートメントまたは RAISERROR ステートメントが含まれている場合、これらのステートメントの出力は SELECT ステートメントの結果セットと交互に返されます。バッチまたはプロシージャの最初のステートメントが PRINT または RAISERROR の場合、SQLExecute または SQLExecDirect から SQL_SUCCESS_WITH_INFO や SQL_ERROR が返されます。また、アプリケーションでは、SQL_NO_DATA が返されるまで SQLGetDiagRec を呼び出して PRINT または RAISERROR に関する情報を取得する必要があります。

PRINT ステートメントまたは RAISERROR ステートメントを SQL ステートメント (SELECT ステートメントなど) の後に指定すると、SQLMoreResultsがエラーを含む結果セットに位置付けられた時点で、PRINT または RAISERROR に関する情報が返されます。SQLMoreResults は、メッセージの重大度に応じて、SQL_SUCCESS_WITH_INFO または SQL_ERROR を返します。メッセージは、SQL_NO_DATA が返されるまで SQLGetDiagRec を呼び出して取得します。

関連項目

概念

エラーとメッセージの処理