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