SQLSetCursorName 関数

  • [アーティクル]

準拠
導入されたバージョン: ODBC 1.0 Standards Compliance: 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の HandleType と StatementHandle の Handle を指定して SQLGetDiagRec を呼び出します。 次の表に、 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 に関連付けられている接続ハンドルに対して非同期実行関数が呼び出されました。 SQLSetCursorName 関数が呼び出されたときに、この非同期関数は引き続き実行されていました。

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

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

説明

カーソル名は、位置指定の update ステートメントと delete ステートメント ( UPDATEテーブル名 ... など) でのみ使用されます。WHERE CURRENT OFcursor-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 ヘッダー ファイル