SQLSetCursorName 函式
一致性
引進版本：ODBC 1.0 標準合規性：ISO 92
摘要
SQLSetCursorName 會將數據指標名稱與使用中語句產生關聯。 如果應用程式未呼叫 SQLSetCursorName，驅動程式會視需要產生數據指標名稱以進行 SQL 語句處理。
語法
SQLRETURN SQLSetCursorName(
SQLHSTMT StatementHandle,
SQLCHAR * CursorName,
SQLSMALLINT NameLength);
引數
StatementHandle
[輸入]語句句柄。
CursorName
[輸入]數據指標名稱。 為了有效率地處理，數據指標名稱不應在數據指標名稱中包含任何前置或尾端空格，如果數據指標名稱包含分隔標識符，則分隔符應定位為數據指標名稱中的第一個字元。
NameLength
[輸入]*CursorName 的字元長度。
傳回
SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_ERROR或SQL_INVALID_HANDLE。
診斷
當 SQLSetCursorName 傳回SQL_ERROR或SQL_SUCCESS_WITH_INFO時，藉由呼叫 SQLGetDiagRec 搭配 SQL_HANDLE_STMT 的 HandleType 和 StatementHandle 的 HandleHandle，即可取得相關聯的 SQLSTATE 值。 下表列出 SQLSetCursorName 通常傳回的 SQLSTATE 值，並說明此函式內容中的每個值;表示法 “（DM）” 在驅動程式管理員傳回的 SQLSTATE 描述之前。 除非另有說明，否則與每個 SQLSTATE 值相關聯的傳回碼會SQL_ERROR。
| SQLSTATE | 錯誤 | 描述 |
|---|---|---|
| 01000 | 一般警告 | 驅動程式特定的資訊訊息。 （函式會傳回SQL_SUCCESS_WITH_INFO。） |
| 01004 | 字串數據，右截斷 | 數據指標名稱超過上限，因此只使用允許的最大字元數。 |
| 24000 | 無效的數據指標狀態 | 對應至 StatementHandle 的語句已經處於已執行或游標定位的狀態。 |
| 34000 | 無效的數據指標名稱 | 在 *CursorName 中指定的數據指標名稱無效，因為它超過驅動程式所定義的長度上限，或是以 “SQLCUR” 或 “SQL_CUR” 開頭。 |
| 3C000 | 重複的數據指標名稱 | *CursorName 中指定的數據指標名稱已經存在。 |
| HY000 | 一般錯誤 | 發生錯誤，其中沒有特定的 SQLSTATE，也沒有定義任何實作特定的 SQLSTATE。 *MessageText 緩衝區中 SQLGetDiagRec 傳回的錯誤訊息描述錯誤及其原因。 |
| HY001 | 記憶體配置錯誤 | 驅動程式無法配置支援執行或完成函式所需的記憶體。 |
| HY009 | 無效的 Null 指標使用 | （DM） CursorName 自變數為 Null 指標。 |
| HY010 | 函式順序錯誤 | （DM） 已針對與 StatementHandle 相關聯的連接句柄呼叫異步執行函式。 呼叫 SQLSetCursorName 函式時，這個異步函式仍在執行中。 （DM） 呼叫 StatementHandle 的異步執行函式，並在呼叫此函式時仍在執行。 （DM） 已針對 StatementHandle 呼叫 SQLExecute、SQLExecDirect、SQLBulkOperations 或 SQLSetPos，並傳回SQL_NEED_DATA。 在針對所有數據執行中參數或數據行傳送數據之前，會呼叫此函式。 |
| HY013 | 記憶體管理錯誤 | 無法處理函式呼叫，因為基礎記憶體物件無法存取，可能是因為記憶體不足的情況。 |
| HY090 | 無效的字串或緩衝區長度 | （DM） 自變數 NameLength 小於 0，但不等於SQL_NTS。 |
| HY117 | 聯機因為未知的交易狀態而暫停。 只允許中斷連線和唯讀函式。 | （DM） 如需暫停狀態的詳細資訊，請參閱 SQLEndTran 函式。 |
| HYT01 | 已超過連線逾時 | 在數據源回應要求之前，連線逾時期限已過期。 線上逾時期間是透過 SQLSetConnectAttr 來設定，SQL_ATTR_CONNECTION_TIMEOUT。 |
| IM001 | 驅動程式不支援此函式 | （DM） 與 StatementHandle 相關聯的驅動程式不支援 函式。 |
註解
數據指標名稱只用於定位的 update 和 delete 語句中（例如 UPDATE數據表名稱 ...WHERE CURRENT OFcursor-name）。 如需詳細資訊，請參閱 定位更新和刪除語句。 如果應用程式未呼叫 SQLSetCursorName 來定義數據指標名稱，則驅動程式在執行查詢語句時，會產生開頭為字母SQL_CUR的名稱，且長度不超過 18 個字元。
連接內的所有數據指標名稱都必須是唯一的。 驅動程式會定義數據指標名稱的最大長度。 為了達到最大互操作性，建議應用程式將游標名稱限制為不超過 18 個字元。 在 ODBC 3*.x*中，如果數據指標名稱是引號標識元，則會以區分大小寫的方式處理，而且可以包含 SQL 語法不允許或會特別處理的字元，例如空白或保留關鍵詞。 如果數據指標名稱必須以區分大小寫的方式處理，則必須以引號標識碼的形式傳遞。
明確或隱含地設定的數據指標名稱會保留設定，直到卸除與它相關聯的語句為止，使用 SQLFreeHandle。 只要數據指標處於已配置或備妥的狀態，就可以呼叫 SQLSetCursorName 來重新命名語句上的數據指標。
程式碼範例
在下列範例中，應用程式會使用 SQLSetCursorName 來設定語句的數據指標名稱。 然後，它會使用該語句從 CUSTOMERS 數據表擷取結果。 最後，它會執行定位更新來變更 John Smith 的電話號碼。 請注意，應用程式會針對 SELECT 和 UPDATE 語句使用不同的語句句柄。
如需另一個程式代碼範例，請參閱 SQLSetPos。
#define NAME_LEN 50
#define PHONE_LEN 10
SQLHSTMT hstmtSelect,
SQLHSTMT hstmtUpdate;
SQLRETURN retcode;
SQLHDBC hdbc;
SQLCHAR szName[NAME_LEN], szPhone[PHONE_LEN];
SQLINTEGER cbName, cbPhone;
/* Allocate the statements and set the cursor name. */
SQLAllocHandle(SQL_HANDLE_STMT, hdbc, &hstmtSelect);
SQLAllocHandle(SQL_HANDLE_STMT, hdbc, &hstmtUpdate);
SQLSetCursorName(hstmtSelect, "C1", SQL_NTS);
/* SELECT the result set and bind its columns to local buffers. */
SQLExecDirect(hstmtSelect,
"SELECT NAME, PHONE FROM CUSTOMERS",
SQL_NTS);
SQLBindCol(hstmtSelect, 1, SQL_C_CHAR, szName, NAME_LEN, &cbName);
SQLBindCol(hstmtSelect, 2, SQL_C_CHAR, szPhone, PHONE_LEN, &cbPhone);
/* Read through the result set until the cursor is */
/* positioned on the row for John Smith. */
do
retcode = SQLFetch(hstmtSelect);
while ((retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) &&
(strcmp(szName, "Smith, John") != 0));
/* Perform a positioned update of John Smith's name. */
if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {
SQLExecDirect(hstmtUpdate,
"UPDATE EMPLOYEE SET PHONE=\"2064890154\" WHERE CURRENT OF C1",
SQL_NTS);
}
相關函數
| 如需下列資訊 | 請參閱 |
|---|---|
| 執行 SQL 語句 | SQLExecDirect 函式 |
| 執行備妥的 SQL 語句 | SQLExecute 函式 |
| 傳回數據指標名稱 | SQLGetCursorName 函式 |
| 設定游標卷動選項 | SQLSetScrollOptions 函式 |