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 標頭檔