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 函式 |