分享方式:


SQLGetStmtAttr 函式

一致性
引進版本:ODBC 3.0 標準合規性:ISO 92

摘要
SQLGetStmtAttr 會傳回語句屬性的目前設定。

注意

如需 Driver Manager 在 ODBC 3 時將此函式對應至之內容的詳細資訊。 x 應用程式正在使用 ODBC 2。 x 驅動程式,請參閱 對應替代函式以取得應用程式的 回溯相容性。

語法

  
SQLRETURN SQLGetStmtAttr(  
     SQLHSTMT        StatementHandle,  
     SQLINTEGER      Attribute,  
     SQLPOINTER      ValuePtr,  
     SQLINTEGER      BufferLength,  
     SQLINTEGER *    StringLengthPtr);  

引數

StatementHandle
[輸入]語句控制碼。

屬性
[輸入]要擷取的屬性。

ValuePtr
[輸出]要在其中傳回 Attribute 中所 指定屬性值之緩衝區的指標。

如果 ValuePtr 為 Null, StringLengthPtr 仍會傳回可供 ValuePtr 指向 的緩衝區中傳回的位元組總數(不包括字元資料的 Null 終止字元)。

BufferLength
[輸入]如果 Attribute 是 ODBC 定義的屬性,而 ValuePtr 指向字元字串或二進位緩衝區,則這個引數應該是 * ValuePtr 的長度。 如果 Attribute 是 ODBC 定義的屬性,而 * ValuePtr 是整數, 則會忽略 BufferLength 。 如果 *ValuePtr 傳回的值是 Unicode 字串(呼叫 SQLGetStmtAttrW 時), BufferLength 引數必須是偶數。

如果 Attribute 是驅動程式定義的屬性,應用程式會藉由設定 BufferLength 引數,將屬性的性質指示給驅動程式管理員。 BufferLength 可以具有下列值:

  • 如果 *ValuePtr 是字元字串的指標, 則 BufferLength 是字串的長度或SQL_NTS。

  • 如果 *ValuePtr 是二進位緩衝區的指標,則應用程式會將SQL_LEN_BINARY_ATTR( length ) 宏的結果放在 BufferLength 。 這會在 BufferLength 放置負值。

  • 如果 *ValuePtr 是字元字串或二進位字串以外的值指標,則 BufferLength 的值SQL_IS_POINTER。

  • 如果 *ValuePtr 包含固定長度的資料類型,則 BufferLength 會視需要SQL_IS_INTEGER或SQL_IS_UINTEGER。

StringLengthPtr
[輸出]緩衝區的指標,用來傳回 *ValuePtr 傳回的位元組總數(不包括 Null 終止字元)。 如果屬性值是字元字串,而且可用的位元組數目大於或等於 BufferLength,則 *ValuePtr 中的資料 會截斷為 BufferLength 減去 Null 終止字元的長度,而且由驅動程式以 Null 終止。

傳回

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_ERROR或SQL_INVALID_HANDLE。

診斷

SQLGetStmtAttr 傳回SQL_ERROR或SQL_SUCCESS_WITH_INFO時,透過呼叫 SQLGetDiagRec handletype 為 SQL_HANDLE_STMT 和 StatementHandle 的 HandleHandle ,即可取得相關聯的 SQLSTATE 值。 下表列出 SQLGetStmtAttr 通常傳 回的 SQLSTATE 值,並說明此函式內容中的每個值;標記法 「(DM)」 在驅動程式管理員所傳回的 SQLSTATE 描述之前。 除非另有說明,否則與每個 SQLSTATE 值相關聯的傳回碼會SQL_ERROR。

SQLSTATE 錯誤 描述
01000 一般警告 驅動程式特定的資訊訊息。 (函式會傳回SQL_SUCCESS_WITH_INFO。)
01004 字串資料,右截斷 在 *ValuePtr 傳回的資料被截斷為 BufferLength 減去 Null 終止字元的長度。 未建構字串值的長度會在 * StringLengthPtr 中 傳回。 (函式會傳回SQL_SUCCESS_WITH_INFO。)
24000 不正確資料指標狀態 引數 Attribute 已SQL_ATTR_ROW_NUMBER且資料指標未開啟,或游標位於結果集開頭之前或結果集結尾之後。
HY000 一般錯誤 發生錯誤,其中沒有特定的 SQLSTATE,也沒有定義任何實作特定的 SQLSTATE。 引數 MessageText 中 SQLGetDiagRec 回的錯誤訊息會描述錯誤及其原因。
HY001 記憶體配置錯誤 驅動程式無法配置支援執行或完成函式所需的記憶體。
HY010 函式順序錯誤 (DM) 已針對與 StatementHandle 相關聯的連接控制碼呼叫非同步執行函式。 呼叫 SQLGetStmtAttr 函式時 ,這個非同步函式仍在執行中。

(DM) 呼叫 StatementHandle 的非同步執行函式,並在呼叫此函式時仍在執行。

(DM) 已針對 StatementHandle 呼叫 SQLExecute SQLExecDirect SQLBulkOperations SQLSetPos ,並傳回SQL_NEED_DATA。 在針對所有資料執行中參數或資料行傳送資料之前,會呼叫此函式。
HY013 記憶體管理錯誤 無法處理函式呼叫,因為基礎記憶體物件無法存取,可能是因為記憶體不足的情況。
HY090 不正確字串或緩衝區長度 (DM) *ValuePtr 是字元字串,而 BufferLength 小於零,但不等於SQL_NTS。
HY092 不正確屬性/選項識別碼 針對引數 Attribute 指定的值對驅動程式支援的 ODBC 版本無效。
HY109 不正確資料指標位置 Attribute 引數SQL_ATTR_ROW_NUMBER且資料列已刪除或無法擷取。
HY117 連線因為未知的交易狀態而暫停。 只允許中斷連線和唯讀函式。 (DM) 如需暫停狀態的詳細資訊,請參閱 SQLEndTran 函式
HYC00 未實作選擇性功能 為引數 Attribute 指定的值是驅動程式所支援之 ODBC 版本的有效 ODBC 語句屬性,但驅動程式不支援。
HYT01 已超過連線逾時 在資料來源回應要求之前,連線逾時期限已過期。 連線逾時期間是透過 SQLSetConnectAttr 來設定,SQL_ATTR_CONNECTION_TIMEOUT。
IM001 驅動程式不支援此函式 (DM) 對應至 StatementHandle 驅動程式不支援 函式。

註解

如需語句屬性的一般資訊,請參閱 語句屬性

對 SQLGetStmtAttr 的 呼叫會在 *ValuePtr 傳回 Attribute 中指定的 語句屬性值。 該值可以是 SQLULEN 值或以 Null 結尾的字元字串。 如果值為 SQLULEN 值,某些驅動程式可能只會寫入較低的 32 位或 16 位緩衝區,並將較高順序的位保持不變。 因此,應用程式應該使用 SQLULEN 的緩衝區,並將值初始化為 0,再呼叫此函式。 此外, 不會使用 BufferLength StringLengthPtr 引數。 如果值是 Null 終止的字串,應用程式會在 BufferLength 引數中 指定該字串的最大長度,而驅動程式會在 *StringLengthPtr 緩衝區中 傳回該字串的長度。

允許呼叫 SQLGetStmtAttr 的應用程式使用 ODBC 2。 x 驅動程式,SQLGetStmtAttr 的呼叫 會在驅動程式管理員中對應至 SQLGetStmtOption

下列語句屬性是唯讀的,因此可由 SQLGetStmtAttr 擷取 ,但不能由 SQLSetStmtAttr 設定:

  • SQL_ATTR_IMP_PARAM_DESC

  • SQL_ATTR_IMP_ROW_DESC

  • SQL_ATTR_ROW_NUMBER

如需可設定和擷取的屬性清單,請參閱 SQLSetStmtAttr

如需下列資訊 請參閱
傳回連接屬性的設定 SQLGetConnectAttr 函式
設定連接屬性 SQLSetConnectAttr 函式
設定語句屬性 SQLSetStmtAttr 函式

另請參閱

ODBC API 參考
ODBC 標頭檔