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的 HandleType 和 StatementHandle 控制碼 呼叫 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 呼叫 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 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 標頭檔