SQLGetCursorName 関数
準拠
導入されたバージョン: ODBC 1.0 標準コンプライアンス: 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の HandleTypeを使用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) SQLExecute、 SQLExecDirect、または SQLMoreResults StatementHandle が呼び出され、SQL_PARAM_DATA_AVAILABLEが返されました。 この関数は、すべてのストリーミング パラメーターのデータが取得される前に呼び出されました。 (DM) 非同期実行関数が StatementHandle に対して呼び出され、この関数が呼び出されたときにはまだ実行されていました。 (DM) SQLExecute、 SQLExecDirect、 SQLBulkOperations、または SQLSetPos が StatementHandle に対して呼び出され、SQL_NEED_DATAが返されました。 この関数は、すべての実行時データ パラメーターまたは列に対してデータが送信される前に呼び出されました。 |
HY013 | メモリ管理エラー | メモリが不足している可能性があるため、基になるメモリ オブジェクトにアクセスできなかったため、関数呼び出しを処理できませんでした。 |
HY015 | 使用可能なカーソル名がありません | (DM) ドライバーは ODBC 2*.x* ドライバーで、ステートメントにオープン カーソルがなく、 SQLSetCursorName でカーソル名が設定されていませんでした。 |
HY090 | 文字列またはバッファーの長さが無効です | (DM) 引数 BufferLength で指定された値が 0 未満でした。 |
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で始まります。
Note
ODBC 2*.x* では、開いているカーソルがなく、 SQLSetCursorName の呼び出しによって名前が設定されていない場合、 SQLGetCursorName の呼び出しによって SQLSTATE HY015 が返されました (カーソル名は使用できません)。 ODBC 3*.x* では、これは true ではなくなりました。 SQLGetCursorName が呼び出されたときに関係なく、ドライバーはカーソル名を返します。
SQLGetCursorName は、名前が明示的または暗黙的に作成されたかどうかにかかわらず、カーソルの名前を返します。 SQLSetCursorNameが呼び出されない場合、カーソル名が暗黙的に生成されます。 SQLSetCursorName を呼び出して、カーソルが割り当て済みまたは準備済みの状態である限り、ステートメントのカーソルの名前を変更できます。
明示的または暗黙的に設定されたカーソル名は、関連付けられている StatementHandle が削除されるまで、SQL_HANDLE_STMTの HandleType でSQLFreeHandleを使用して設定されたままになります。
関連する関数
情報 | 参照トピック |
---|---|
SQL ステートメントの実行 | SQLExecDirect 関数 |
準備された SQL ステートメントの実行 | SQLExecute 関数 |
実行のためのステートメントの準備 | SQLPrepare 関数 |
カーソル名の設定 | SQLSetCursorName 関数 |