共用方式為

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

另請參閱

ODBC API 參考
ODBC 標頭檔