共用方式為


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時,可以使用SQL_HANDLE_STMT的 HandleTypeStatementHandle 句柄呼叫 SQLGetDiagRec 來取得相關聯的 SQLSTATE 值。 下表列出 SQLGetCursorName 通常傳回的 SQLSTATE 值,並說明此函式內容中的每個值;表示法 “(DM)” 在驅動程式管理員傳回的 SQLSTATE 描述之前。 除非另有說明,否則與每個 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 呼叫 SQLExecuteSQLExecDirectSQLMoreResults,並傳回SQL_PARAM_DATA_AVAILABLE。 在擷取所有數據流參數的數據之前,會呼叫此函式。

(DM) 呼叫 StatementHandle 的異步執行函式,並在呼叫此函式時仍在執行。

(DM) 已針對 StatementHandle 呼叫 SQLExecuteSQLExecDirectSQLBulkOperationsSQLSetPos,並傳回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 OF cursor-name)。 如需詳細資訊,請參閱 定位更新和刪除語句。 如果應用程式未呼叫 SQLSetCursorName 來定義資料指標名稱,驅動程式會產生名稱。 此名稱開頭為字母SQL_CUR。

注意

在 ODBC 2*.x*中,當沒有開啟的數據指標,而且沒有 SQLSetCursorName 呼叫已設定名稱時,SQLGetCursorName 的呼叫會傳回 SQLSTATE HY015 (沒有可用的數據指標名稱)。 在 ODBC 3*.x*中,這已不再成立;不論呼叫 SQLGetCursorName,驅動程式都會傳回數據指標名稱。

不論是否明確或隱含建立名稱,SQLGetCursorName 都會傳回數據指標的名稱。 如果未 呼叫 SQLSetCursorName ,則會隱含產生數據指標名稱。 只要數據指標處於已配置或備妥的狀態,就可以呼叫 SQLSetCursorName 來重新命名語句上的數據指標。

明確或隱含設定的數據指標名稱會保留設定,直到卸除關聯之 StatementHandle 為止,使用 SQLFreeHandle 搭配 handleType SQL_HANDLE_STMT。

如需下列資訊 請參閱
執行 SQL 語句 SQLExecDirect 函式
執行備妥的 SQL 語句 SQLExecute 函式
準備語句以供執行 SQLPrepare 函式
設定數據指標名稱 SQLSetCursorName 函式

另請參閱

ODBC API 參考
ODBC 標頭檔