SQLGetCursorName 関数

  • [アーティクル]

準拠
導入されたバージョン: ODBC 1.0 Standards Compliance: ISO 92

まとめ
SQLGetCursorName は、指定したステートメントに関連付けられているカーソル名を返します。

構文

  
SQLRETURN SQLGetCursorName(  
     SQLHSTMT        StatementHandle,  
     SQLCHAR *       CursorName,  
     SQLSMALLINT     BufferLength,  
     SQLSMALLINT *   NameLengthPtr);

引数

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

CursorName
[出力]カーソル名を返すバッファーへのポインター。

CursorName が NULL の場合でも、NameLengthPtr は CursorName が指すバッファーで返すことができる文字数の合計 (文字データの null 終端文字を除く) を返します。

BufferLength
[入力]*CursorName の長さ (文字数)。

NameLengthPtr
[出力]*CursorName で返すことができる合計文字数 (null 終端文字を除く) を返すメモリへのポインター。 返すことができる文字数が BufferLength 以上の場合、*CursorName のカーソル名は BufferLength から null 終端文字の長さを引いた値に切り捨てられます。

戻り値

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_ERROR、またはSQL_INVALID_HANDLE。

診断

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

SQLSTATE エラー 説明
01000 一般的な警告 ドライバー固有の情報メッセージ。 (関数はSQL_SUCCESS_WITH_INFOを返します。
01004 文字列データ、右切り捨て バッファー *CursorName は、カーソル名全体を返すには十分な大きさではなかったため、カーソル名が切り捨てられました。 *NameLengthPtr では、カーソル名の長さが返されます。 (関数はSQL_SUCCESS_WITH_INFOを返します。
HY000 一般的なエラー 特定の SQLSTATE がなく、実装固有の SQLSTATE が定義されていないエラーが発生しました。 *MessageText バッファー内の SQLGetDiagRec によって返されるエラー メッセージは、エラーとその原因を説明します。
HY001 メモリ割り当てエラー ドライバーは、関数の実行または完了をサポートするために必要なメモリを割り当てることができませんでした。
HY010 関数シーケンス エラー (DM) StatementHandle に関連付けられている接続ハンドルに対して非同期実行関数が呼び出されました。 この非同期関数は、 SQLGetCursorName 関数が呼び出されたときにまだ実行されていました。

(DM) StatementHandle に対して SQLExecute、SQLExecDirect、または SQLMoreResults が呼び出され、SQL_PARAM_DATA_AVAILABLE返されました。 この関数は、ストリーミングされたすべてのパラメーターのデータが取得される前に呼び出されました。

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

(DM) StatementHandle に対して SQLExecute、SQLExecDirect、SQLBulkOperations、または SQLSetPos が呼び出され、SQL_NEED_DATA返されました。 この関数は、すべての実行時データ パラメーターまたは列に対してデータが送信される前に呼び出されました。
HY013 メモリ管理エラー メモリ不足の可能性があるため、基になるメモリ オブジェクトにアクセスできなかったため、関数呼び出しを処理できませんでした。
HY015 使用できるカーソル名がありません (DM) ドライバーは ODBC 2*.x* ドライバーであり、ステートメントにオープン カーソルがなく、 SQLSetCursorName でカーソル名が設定されていませんでした。
HY090 文字列またはバッファーの長さが無効です (DM) 引数 BufferLength で指定された値が 0 未満でした。
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文字で始まります。

Note

ODBC 2*.x* では、開いているカーソルがなく、 SQLSetCursorName の呼び出しによって名前が設定されていない場合、 SQLGetCursorName の呼び出しによって SQLSTATE HY015 が返されました (カーソル名は使用できません)。 ODBC 3*.x* では、これは正しくなくなりました。 SQLGetCursorName が呼び出されたときに関係なく、ドライバーはカーソル名を返します。

SQLGetCursorName は、名前が明示的または暗黙的に作成されたかどうかにかかわらず、カーソルの名前を返します。 SQLSetCursorName が呼び出されない場合、カーソル名は暗黙的に生成されます。 SQLSetCursorName は、カーソルが割り当て済みまたは準備済みの状態である限り、ステートメントのカーソルの名前を変更するために呼び出すことができます。

明示的または暗黙的に設定されたカーソル名は、関連付けられている StatementHandle が削除されるまで、handleType が SQL_HANDLE_STMTの SQLFreeHandle を使用して設定されたままになります。

対象 解決方法については、
SQL ステートメントの実行 SQLExecDirect 関数
準備された SQL ステートメントの実行 SQLExecute 関数
実行のためのステートメントの準備 SQLPrepare 関数
カーソル名の設定 SQLSetCursorName 関数

参照

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