SQLSetCursorName 関数

準拠
導入されたバージョン: ODBC 1.0 標準コンプライアンス: ISO 92

まとめ
SQLSetCursorName は、カーソル名をアクティブなステートメントに関連付けます。 アプリケーションが SQLSetCursorName を呼び出さない場合、ドライバーは SQL ステートメントの処理に必要に応じてカーソル名を生成します。

構文

  
SQLRETURN SQLSetCursorName(  
     SQLHSTMT      StatementHandle,  
     SQLCHAR *     CursorName,  
     SQLSMALLINT   NameLength);  

引数

StatementHandle
[入力]ステートメント ハンドル。

CursorName
[入力]カーソル名。 効率的な処理を行う場合は、カーソル名に先頭または末尾のスペースを含めないようにしてください。また、カーソル名に区切り記号が含まれている場合は、区切り記号をカーソル名の最初の文字として配置する必要があります。

NameLength
[入力]*CursorName の文字数。

返品

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_ERROR、またはSQL_INVALID_HANDLE。

診断

SQLSetCursorNameがSQL_ERRORまたはSQL_SUCCESS_WITH_INFOを返す場合は、SQL_HANDLE_STMTのHandleTypeとStatementHandleのHandleを使用してSQLGetDiagRecを呼び出すことによって、関連付けられている SQLSTATE 値を取得できます。 次の表に、 SQLSetCursorName によって一般的に返される SQLSTATE 値の一覧を示しこの関数のコンテキストでそれぞれについて説明します。表記 "(DM)" は、ドライバー マネージャーによって返される SQLSTATEs の説明の前にあります。 特に明記されていない限り、各 SQLSTATE 値に関連付けられている戻りコードはSQL_ERROR。

Comments

カーソル名は、位置指定された更新および削除ステートメント (たとえば、 UPDATE table-name ... でのみ使用されます。WHERE CURRENT OF cursor-name)。 詳細については、「 Positioned Update ステートメントと Delete ステートメントを参照してください。 アプリケーションが SQLSetCursorName を呼び出してカーソル名を定義しない場合、クエリ ステートメントの実行時に、ドライバーは文字SQL_CURで始まり、長さが 18 文字を超えない名前を生成します。

接続内のすべてのカーソル名は一意である必要があります。 カーソル名の最大長は、ドライバーによって定義されます。 相互運用性を最大限に高めるために、アプリケーションではカーソル名を 18 文字以下に制限することをお勧めします。 ODBC 3*.x* では、カーソル名が引用符で囲まれた識別子の場合、大文字と小文字が区別され、SQL の構文で許可されない文字や、空白や予約済みキーワードなど、特別に扱われる文字を含めることができます。 カーソル名を大文字と小文字を区別して扱う必要がある場合は、引用符で囲まれた識別子として渡す必要があります。

明示的または暗黙的に設定されたカーソル名は、関連付けられているステートメントが削除されるまで、 SQLFreeHandle を使用して設定されたままになります。 SQLSetCursorName を呼び出して、カーソルが割り当て済みまたは準備済みの状態である限り、ステートメントのカーソルの名前を変更できます。

コード例

次の例では、アプリケーションは SQLSetCursorName を使用してステートメントのカーソル名を設定します。 その後、そのステートメントを使用して CUSTOMERS テーブルから結果を取得します。 最後に、John Smith の電話番号を変更するために、配置された更新を実行します。 アプリケーションは、 SELECT および UPDATE ステートメントに対して異なるステートメント ハンドルを使用します。

別のコード例については、 SQLSetPos を参照してください。

#define NAME_LEN 50  
#define PHONE_LEN 10  
  
SQLHSTMT     hstmtSelect,  
SQLHSTMT     hstmtUpdate;  
SQLRETURN    retcode;  
SQLHDBC      hdbc;  
SQLCHAR      szName[NAME_LEN], szPhone[PHONE_LEN];  
SQLINTEGER   cbName, cbPhone;  
  
/* Allocate the statements and set the cursor name. */  
  
SQLAllocHandle(SQL_HANDLE_STMT, hdbc, &hstmtSelect);  
SQLAllocHandle(SQL_HANDLE_STMT, hdbc, &hstmtUpdate);  
SQLSetCursorName(hstmtSelect, "C1", SQL_NTS);  
  
/* SELECT the result set and bind its columns to local buffers. */  
  
SQLExecDirect(hstmtSelect,  
      "SELECT NAME, PHONE FROM CUSTOMERS",  
      SQL_NTS);  
SQLBindCol(hstmtSelect, 1, SQL_C_CHAR, szName, NAME_LEN, &cbName);  
SQLBindCol(hstmtSelect, 2, SQL_C_CHAR, szPhone, PHONE_LEN, &cbPhone);  
  
/* Read through the result set until the cursor is */  
/* positioned on the row for John Smith. */  
  
do  
 retcode = SQLFetch(hstmtSelect);  
while ((retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) &&  
   (strcmp(szName, "Smith, John") != 0));  
  
/* Perform a positioned update of John Smith's name. */  
  
if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {  
   SQLExecDirect(hstmtUpdate,  
   "UPDATE EMPLOYEE SET PHONE=\"2064890154\" WHERE CURRENT OF C1",  
   SQL_NTS);  
}  

関連する関数

参照

ODBC API リファレンス
ODBC ヘッダー ファイル