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を返す場合は、関連付けられている SQLSTATE 値を取得するには、SQL_HANDLE_STMTの HandleTypeStatementHandleハンドルを使用して SQLGetDiagRec を呼び出します。 次の表に、 SQLSetCursorName によって一般的に返される SQLSTATE 値の一覧を示し、この関数のコンテキストでそれぞれについて説明します。ドライバー マネージャーによって返される SQLSTATEs の説明の前に表記 "(DM)" が付きます。 特に記載がない限り、各 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 に関連付けられている接続ハンドルに対して非同期に実行される関数が呼び出されました。 この非同期関数は、 SQLSetCursorName 関数が呼び出されたときにまだ実行されていました。

(DM) 非同期実行関数が StatementHandle に対して呼び出され、この関数が呼び出されたときにまだ実行されていました。

(DM) SQLExecuteSQLExecDirectSQLBulkOperations、または SQLSetPosStatementHandle に対して呼び出され、SQL_NEED_DATA返されました。 この関数は、実行中のすべてのデータ パラメーターまたは列に対してデータが送信される前に呼び出されました。
HY013 メモリ管理エラー 基になるメモリ オブジェクトにアクセスできなかったため、メモリの状態が低いため、関数呼び出しを処理できませんでした。
HY090 文字列またはバッファーの長さが無効です (DM) 引数 NameLength は 0 未満でしたが、SQL_NTSと等しくありません。
HY117 不明なトランザクション状態のため、接続が中断されます。 切断および読み取り専用の関数のみが許可されます。 (DM) 中断状態の詳細については、 SQLEndTran 関数を参照してください。
HYT01 接続のタイムアウト データ ソースが要求に応答する前に、接続タイムアウト期間の有効期限が切れています。 接続タイムアウト期間は、 SQL_ATTR_CONNECTION_TIMEOUT SQLSetConnectAttr を介して設定されます。
IM001 ドライバーは、この関数をサポートしていません (DM) StatementHandle に関連付けられているドライバーは、関数をサポートしていません。

コメント

カーソル名は、位置指定の更新および削除ステートメント (UPDATEtable-name ..など) でのみ使用されます。WHERE CURRENTOFcursor-name)。 詳細については、「 位置指定更新および削除ステートメント」を参照してください。 アプリケーションが 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 ヘッダー ファイル