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。

SQLSTATE	エラー	説明
01000	一般的な警告	ドライバー固有の情報メッセージ。 (関数はSQL_SUCCESS_WITH_INFOを返します。
01004	文字列データ、右切り捨て	カーソル名が上限を超えたため、使用できる最大文字数のみが使用されました。
24000	カーソル状態が無効	StatementHandle に対応するステートメントは、既に実行状態またはカーソル位置指定状態でした。
34000	カーソル名が無効	*CursorName で指定されたカーソル名は、ドライバーで定義されている最大長を超えたか、"SQLCUR" または "SQL_CUR" で開始されたため、無効でした。
3C000	重複するカーソル名	*CursorName で指定されたカーソル名は既に存在します。
HY000	一般的なエラー	特定の SQLSTATE がなく、実装固有の SQLSTATE が定義されていないエラーが発生しました。 *MessageText バッファー内の SQLGetDiagRec によって返されるエラー メッセージには、エラーとその原因が記述されています。
HY001	メモリ割り当てエラー	ドライバーは、関数の実行または完了をサポートするために必要なメモリを割り当てませんでした。
HY009	null ポインターの使用が無効です	(DM) 引数 CursorName が null ポインターでした。
HY010	関数シーケンス エラー	(DM) StatementHandle に関連付けられている接続ハンドルに対して非同期実行関数が呼び出されました。 この aynchronous 関数は、 SQLSetCursorName 関数が呼び出されたときに、まだ実行されていました。 (DM) 非同期実行関数が StatementHandle に対して呼び出され、この関数が呼び出されたときにはまだ実行されていました。 (DM) SQLExecute、 SQLExecDirect、 SQLBulkOperations、または SQLSetPos が StatementHandle に対して呼び出され、SQL_NEED_DATAが返されました。 この関数は、すべての実行時データ パラメーターまたは列に対してデータが送信される前に呼び出されました。
HY013	メモリ管理エラー	メモリが不足している可能性があるため、基になるメモリ オブジェクトにアクセスできなかったため、関数呼び出しを処理できませんでした。
HY090	文字列またはバッファーの長さが無効です	(DM) 引数 NameLength は 0 未満でしたが、SQL_NTSと等しくありません。
HY117	不明なトランザクション状態のため、接続が中断されます。 切断関数と読み取り専用関数のみが許可されます。	(DM) 中断状態の詳細については、「 SQLEndTran 関数を参照してください。
HYT01	接続のタイムアウト	データ ソースが要求に応答する前に、接続タイムアウト期間の有効期限が切れています。 接続タイムアウト期間は、SQL_ATTR_CONNECTION_TIMEOUT SQLSetConnectAttr によって設定されます。
IM001	ドライバーは、この関数をサポートしていません	(DM) StatementHandle に関連付けられているドライバーは、関数をサポートしていません。

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);  
}  

関連する関数

情報	参照トピック
SQL ステートメントの実行	SQLExecDirect 関数
準備された SQL ステートメントの実行	SQLExecute 関数
カーソル名を返す	SQLGetCursorName 関数
カーソルのスクロール オプションの設定	SQLSetScrollOptions 関数

参照

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