次の方法で共有

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 ヘッダー ファイル