SQLGetSQLCA() - SQLCA データ構造を取得する

SQLGetSQLCA() は、SQL ステートメントの準備と実行、データのフェッチ、カーソルのクローズに関連した SQLCA (SQL 連絡域) を戻します。SQLCA は、 SQLGetDiagRec() によって取得されたデータを補足する情報を戻すことができます。

ステートメント・ハンドルの割り振りなど、アプリケーション側で関数を厳密に処理する 場合は、SQLCA は利用できません。この場合、すべての値をゼロに設定した状態で空の SQLCA が戻されます。

SQLGetSQLCA() の ODBC 仕様

表 1. SQLGetSQLCA の仕様
ODBC 仕様レベル X/Open CLI CAE 仕様 ISO CLI 仕様
なし なし なし

構文

SQLRETURN  SQLGetSQLCA       (SQLHENV           henv,
                              SQLHDBC           hdbc,
                              SQLHSTMT          hstmt,
                              struct sqlca FAR  *pSqlca);

関数の引数

次の表は、この関数のそれぞれの引数ごとに、 データ・タイプ、用途、および説明を示しています。

表 2. SQLGetSQLCA() の引数
データ・タイプ 引数 使用法 説明
SQLHENV henv 入力 環境ハンドルを指定します。
SQLHDBC hdbc 入力 接続ハンドルを指定します。
SQLHSTMT hstmt 入力 ステートメント・ハンドルを指定します。
SQLCA * pqlCA 出力 SQL 連絡域を受け取るバッファーを指しています。

使用法

ハンドルは、SQLGetDiagRec() 関数の場合と同じ方法で使用します。 異なるハンドル・タイプに関連した SQLCA を取得するには、以下の引数の値を使用します。
  • 環境ハンドルの場合: hdbc を設定して SQL_NULL_HDBC にして 、hstmt を設定して SQL_NULL_HSTMT にして、有効な環境ハンドルを指定します。
  • 接続ハンドルの場合: 有効なデータベース接続を指定し、hstmt を設定して SQL_NULL_HSTMT に します。 引数 henv は無視されます。
  • ステートメント・ハンドルの場合: 有効なステートメント・ハンドルを指定します。 引数 henv と引数 hdbc は無視されます。

ある Db2® ODBC 関数が生成した診断情報を、SQLGetDiagRec() 以外の関数 を呼び出す前に同じハンドルで取り出さない場合は、直前の関数呼び出しの診断情報は失われます。 この情報は、2 番目の Db2 ODBC 関数呼び出しが診断情報を生成するかどうかに関係なく失われます。

データベース管理システムとの対話を行わない Db2 ODBC 関数を呼び出すと、SQLCA にはすべてゼロが入ります。 以下の関数については、意味のある情報が SQLCA に戻されます。
  • SQLCancel()
  • SQLConnect()、SQLDisconnect()
  • SQLExecDirect()、SQLExecute()
  • SQLFetch()
  • SQLPrepare()
  • SQLEndTran()
  • SQLColumns()
  • SQLConnect()
  • SQLGetData (LOB 列を伴う場合)
  • SQLSetConnectAttr() (SQL_ATTR_AUTOCOMMIT の場合)
  • SQLStatistics()
  • SQLTables()
  • SQLColumnPrivileges()
  • SQLExtendedFetch()
  • SQLForeignKeys()
  • SQLMoreResults()
  • SQLPrimaryKeys()
  • SQLProcedureColumns()
  • SQLProcedures()
  • SQLTablePrivileges()

戻りコード

SQLGetSQLCA() は、呼び出された後、次のいずれかの値を戻します。
  • SQL_SUCCESS
  • SQL_ERROR
  • SQL_INVALID_HANDLE

例

以下の例 は、SQLGetSQLCA() を使用して、SQLCA から 診断情報を取り出すアプリケーションを示しています。
図 1. 診断情報を取り出すアプリケーション
 /******************************************************************/
 /*  Prepare a query and execute that query against a non-existent */
 /*  table. Then invoke SQLGetSQLCA to extract                     */
 /*  native SQLCA data structure. Note that this API is NOT        */
 /*  defined within ODBC; it is unique to IBM CLI.          */
 /******************************************************************/
#include <stdio.h>
#include <string.h>
#include <stdlib.h>
#include <sqlca.h>
#include "sqlcli1.h"
void print_sqlca (SQLHENV,            // prototype for print_sqlca
                  SQLHDBC,
                  SQLHSTMT);
int main( )
{
   SQLHENV         hEnv    = SQL_NULL_HENV;
   SQLHDBC         hDbc    = SQL_NULL_HDBC;
   SQLHSTMT        hStmt   = SQL_NULL_HSTMT;
   SQLRETURN       rc      = SQL_SUCCESS;
   SQLINTEGER      RETCODE = 0;
   char            *pDSN = "STLEC1";
   SWORD           cbCursor;
   SDWORD          cbValue1;
   SDWORD          cbValue2;
   char            employee [30];
   int             salary = 0;
   int             param_salary = 30000;
   char            *stmt = "SELECT NAME, SALARY FROM EMPLOYEES WHERE SALARY > ?";
   (void) printf ("**** Entering CLIP11.¥n¥n");
  /*****************************************************************/
  /* Allocate environment handle                                   */
  /*****************************************************************/
   RETCODE = SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &hEnv);
   if (RETCODE != SQL_SUCCESS)
     goto dberror;
  /*****************************************************************/
  /* Allocate connection handle to DSN                             */
  /*****************************************************************/
   RETCODE = SQLAllocHandle(SQL_HANDLE_DBC, hEnv, &hDbc);
   if( RETCODE != SQL_SUCCESS )      // Could not get a Connect Handle
     goto dberror;
  /*****************************************************************/
  /* CONNECT TO data source (STLEC1)                               */
  /*****************************************************************/
   RETCODE = SQLConnect(hDbc,        // Connect handle
                        (SQLCHAR *) pDSN, // DSN
                        SQL_NTS,     // DSN is nul-terminated
                        NULL,        // Null UID
                        0   ,
                        NULL,        // Null Auth string
                        0);
   if( RETCODE != SQL_SUCCESS )      // Connect failed
     goto dberror;
  /*****************************************************************/
  /* Allocate statement handles                                    */
  /*****************************************************************/
  rc = SQLAllocHandle(SQL_HANDLE_STMT, SQL_NULL_HANDLE, hDbc, &hStmt);
  if (rc != SQL_SUCCESS)
    goto exit;
  /*****************************************************************/
  /* Prepare the query for multiple execution within current       */
  /* transaction. Note that query is collapsed when transaction    */
  /* is committed or rolled back.                                  */
  /*****************************************************************/
  rc = SQLPrepare (hStmt,
                   (SQLCHAR *) stmt,
                   strlen(stmt));
  if (rc != SQL_SUCCESS)
  {
    (void) printf ("**** PREPARE OF QUERY FAILED.¥n");
    (void) print_sqlca (hStmt,
                        hDbc,
                        hEnv);
    goto dberror;
  }
  rc = SQLBindCol (hStmt,           // bind employee name
                   1,
                   SQL_C_CHAR,
                   employee,
                   sizeof(employee),
                   &cbValue1);
  if (rc != SQL_SUCCESS)
  {
    (void) printf ("**** BIND OF NAME FAILED.¥n");
    goto dberror;
  }
  rc = SQLBindCol (hStmt,           // bind employee salary
                   2,
                   SQL_C_LONG,
                   &salary,
                   0,
                   &cbValue2);
  if (rc != SQL_SUCCESS)
  {
    (void) printf ("**** BIND OF SALARY FAILED.¥n");
    goto dberror;
  }
  /*****************************************************************/
  /* Bind parameter to replace '?' in query. This has an initial   */
  /* value of 30000.                                               */
  /*****************************************************************/
  rc = SQLBindParameter (hStmt,
                         1,
                         SQL_PARAM_INPUT,
                         SQL_C_LONG,
                         SQL_INTEGER,
                         0,
                         0,
                         &param_salary,
                         0,
                         NULL);
  /*****************************************************************/
  /* Execute prepared statement to generate answer set.            */
  /*****************************************************************/
  rc = SQLExecute (hStmt);
  if (rc != SQL_SUCCESS)
  {
    (void) printf ("**** EXECUTE OF QUERY FAILED.¥n");
    (void) print_sqlca (hStmt,
                        hDbc,
                        hEnv);
    goto dberror;
  }
  /*****************************************************************/
  /* Answer set is available -- Fetch rows and print employees     */
  /* and salary.                                                   */
  /*****************************************************************/
  (void) printf ("**** Employees whose salary exceeds %d follow.¥n¥n",
                 param_salary);
  while ((rc = SQLFetch (hStmt)) == SQL_SUCCESS)
  {
    (void) printf ("**** Employee Name %s with salary %d.¥n",
                   employee,
                   salary);
  }
  /*****************************************************************/
  /* Deallocate statement handles -- statement is no longer in a   */
  /* Prepared state.                                               */
  /*****************************************************************/
  rc = SQLFreeHandle(SQL_HANDLE_STMT, hStmt);
  /*****************************************************************/
  /* DISCONNECT from data source                                   */
  /*****************************************************************/
   RETCODE = SQLDisconnect(hDbc);
   if (RETCODE != SQL_SUCCESS)
     goto dberror;
  /*****************************************************************/
  /* Deallocate connection handle                                  */
  /*****************************************************************/
   RETCODE = SQLFreeHandle(SQL_HANDLE_DBC, hDbc);
   if (RETCODE != SQL_SUCCESS)
     goto dberror;
  /*****************************************************************/
  /* Free environment handle                                       */
  /*****************************************************************/
   RETCODE = SQLFreeHandle(SQL_HANDLE_ENV, hEnv);
   if (RETCODE == SQL_SUCCESS)
     goto exit;
   dberror:
   RETCODE=12;
   exit:
   (void) printf ("**** Exiting  CLIP11.¥n¥n");
   return RETCODE;
}
/*****************************************************************/
/* print_sqlca invokes SQLGetSQLCA and prints the native SQLCA.  */
/*****************************************************************/
void print_sqlca (SQLHENV  hEnv ,
                  SQLHDBC  hDbc ,
                  SQLHSTMT hStmt)
{
  SQLRETURN       rc      = SQL_SUCCESS;
  struct sqlca    sqlca;
  struct sqlca    *pSQLCA = &sqlca;
  int  code ;
  char state [6];
  char errp  [9];
  char tok   [40];
  int  count, len, start, end, i;
  if ((rc = SQLGetSQLCA (hEnv ,
                         hDbc ,
                         hStmt,
                         pSQLCA)) != SQL_SUCCESS)
  {
    (void) printf ("**** SQLGetSQLCA failed Return Code = 
    goto exit;
  }
  code = (int) pSQLCA->sqlcode;
  memcpy (state, pSQLCA->sqlstate, 5);
  state [5] = '¥0';
  (void) printf ("**** sqlcode = 
  memcpy (errp, pSQLCA->sqlerrp, 8);
  errp [8] = '¥0';
  (void) printf ("**** sqlerrp = 
  if (pSQLCA->sqlerrml == 0)
    (void) printf ("**** No tokens.¥n");
  else
  {
    for (len = 0, count = 0; len < pSQLCA->sqlerrml; len = ++end)
    {
      start = end = len;
      while ((pSQLCA->sqlerrmc [end] != 0XFF) &&;
             (end < pSQLCA->sqlerrml))
        end++;
      if (start != end)
      {
        memcpy (tok, &pSQLCA->sqlerrmc[start],
                                                            (end-start));
        tok [end-start+1] = '¥0';
        (void) printf ("**** Token # 
      }
    }
  }
  for (i = 0; i <= 5; i++)
    (void) printf ("**** sqlerrd # 
  for (i = 0; i <= 10; i++)
    (void) printf ("**** sqlwarn # 
  exit:
  return;
}