SQLGetDescRec 函式

  • 發行項

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

摘要
SQLGetDescRec 會傳回描述元記錄之多個欄位的目前設定或值。 傳回的欄位描述資料行或參數資料的名稱、資料類型和儲存。

語法

  
SQLRETURN SQLGetDescRec(  
      SQLHDESC        DescriptorHandle,  
      SQLSMALLINT     RecNumber,  
      SQLCHAR *       Name,  
      SQLSMALLINT     BufferLength,  
      SQLSMALLINT *   StringLengthPtr,  
      SQLSMALLINT *   TypePtr,  
      SQLSMALLINT *   SubTypePtr,  
      SQLLEN *        LengthPtr,  
      SQLSMALLINT *   PrecisionPtr,  
      SQLSMALLINT *   ScalePtr,  
      SQLSMALLINT *   NullablePtr);

引數

DescriptorHandle
[輸入]描述項控制碼。

RecNumber
[輸入]指出應用程式從中搜尋資訊的描述元記錄。 描述項記錄會從 1 編號，記錄號碼 0 是書簽記錄。 RecNumber 引數必須小於或等於 SQL_DESC_COUNT 的值。 如果 RecNumber 小於或等於SQL_DESC_COUNT但資料列不包含資料行或參數的資料，則對 SQLGetDescRec 的呼叫 會傳回欄位的預設值。 （如需詳細資訊，請參閱 中的。 SQLSetDescField .）

名稱
[輸出]緩衝區的指標，用來傳回描述元記錄的SQL_DESC_NAME欄位。

如果 Name 為 Null， StringLengthPtr 仍會傳回字元總數（不包括字元資料的 Null 終止字元），以在 Name 所指向的緩衝區中傳回。

BufferLength
[輸入]* Name 緩衝區的長度，以字元為單位。

StringLengthPtr
[輸出]緩衝區的指標，用來傳回在 * Name 緩衝區中傳回的資料字元數，但不包括 Null 終止字元。 如果字元數大於或等於 BufferLength，則 * Name 中的資料會截斷為 BufferLength 減去 Null 終止字元的長度，且由驅動程式以 Null 結尾。

TypePtr
[輸出]緩衝區的指標，用來傳回描述項記錄之SQL_DESC_TYPE欄位的值。

SubTypePtr
[輸出]對於類型為SQL_DATETIME或SQL_INTERVAL的記錄，這是緩衝區的指標，用來傳回SQL_DESC_DATETIME_INTERVAL_CODE欄位的值。

LengthPtr
[輸出]緩衝區的指標，用來傳回描述項記錄之SQL_DESC_OCTET_LENGTH欄位的值。

PrecisionPtr
[輸出]緩衝區的指標，用來傳回描述項記錄之SQL_DESC_PRECISION欄位的值。

ScalePtr
[輸出]緩衝區的指標，用來傳回描述元記錄之SQL_DESC_SCALE欄位的值。

NullablePtr
[輸出]緩衝區的指標，用來傳回描述項記錄之SQL_DESC_NullABLE欄位的值。

傳回

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_ERROR、SQL_NO_DATA或SQL_INVALID_HANDLE。

如果 RecNumber 大於目前的描述元記錄數目，則會傳回SQL_NO_DATA。

如果 DescriptorHandle 是 IRD 控制碼，而且語句處於已備妥或執行的狀態，但沒有與它相關聯的開啟資料指標，則會傳回SQL_NO_DATA。

診斷

當 SQLGetDescRec 傳回SQL_ERROR或SQL_SUCCESS_WITH_INFO時，藉由呼叫 具有 SQL_HANDLE_DESC HandleType 和 DescriptorHandle 的 HandleType 呼叫 SQLGetDiagRec ，即可取得相關聯的 SQLSTATE 值。 下表列出 SQLGetDescRec 通常傳 回的 SQLSTATE 值，並說明此函式內容中的每個值;標記法 「（DM）」 在驅動程式管理員傳回的 SQLSTATE 描述之前。 除非另有說明，否則與每個 SQLSTATE 值相關聯的傳回碼會SQL_ERROR。

SQLSTATE 錯誤 描述
01000 一般警告 驅動程式特定的資訊訊息。 （函式會傳回SQL_SUCCESS_WITH_INFO。）
01004 字串資料，右截斷 緩衝區 * Name 不夠大，無法傳回整個描述元欄位。 因此，欄位已截斷。 未解構描述元欄位的長度會在 * StringLengthPtr 中 傳回。 （函式會傳回SQL_SUCCESS_WITH_INFO。）
07009 不正確描述元索引 FieldIdentifier 引數是記錄欄位、 RecNumber 引數設定為 0，而 DescriptorHandle 引數是 IPD 控制碼。

（DM） RecNumber 引數設定為 0，而 SQL_ATTR_USE_BOOKMARKS 語句屬性設定為 SQL_UB_OFF， 而 DescriptorHandle 引數是 IRD 控制碼。

RecNumber 引數小於 0。
08S01 通訊連結失敗 驅動程式與驅動程式連線的資料來源之間的通訊連結在函式完成處理之前失敗。
HY000 一般錯誤 發生錯誤，其中沒有特定的 SQLSTATE，也沒有定義任何實作特定的 SQLSTATE。 *MessageText 緩衝區中 SQLGetDiagRec 傳 回的錯誤訊息描述錯誤及其原因。
HY001 記憶體配置錯誤 驅動程式無法配置支援執行或完成函式所需的記憶體。
HY007 未備妥相關聯的語句 描述項Handle 與 IRD 相關聯，且相關聯的語句控制碼未處於已備妥或已執行的狀態。
HY010 函式順序錯誤 （DM） 描述項Handle 與 StatementHandle 相關聯，其會呼叫非同步執行函式（而非此函式），而且在呼叫此函式時仍在執行中。

（DM） 描述項Handle 與 SQLExecute、SQLExecute 、 SQLBulkOperations 或 SQLSetPos 呼叫並傳回SQL_NEED_DATA的 StatementHandle 相關聯。 在針對所有資料執行中參數或資料行傳送資料之前，會呼叫此函式。

（DM） 針對與 DescriptorHandle 相關聯的連接控制碼呼叫非同步執行函式。 呼叫 SQLGetDescRec 時 ，這個非同步函式仍在執行中。
HY013 記憶體管理錯誤 無法處理函式呼叫，因為基礎記憶體物件無法存取，可能是因為記憶體不足的情況。
HY117 連線因為未知的交易狀態而暫停。 只允許中斷連線和唯讀函式。 （DM） 如需暫停狀態的詳細資訊，請參閱 SQLEndTran 函式 。
HYT01 已超過連線逾時 在資料來源回應要求之前，連線逾時期限已過期。 連線逾時期間是透過 SQLSetConnectAttr 來設定，SQL_ATTR_CONNECTION_TIMEOUT。
IM001 驅動程式不支援此函式 （DM） 與 DescriptorHandle 相關聯的 驅動程式不支援 函式。

註解

應用程式可以呼叫 SQLGetDescRec 來擷取單一資料行或參數下列描述項欄位的值：

  • SQL_DESC_NAME

  • SQL_DESC_TYPE

  • SQL_DESC_DATETIME_INTERVAL_CODE （針對類型為SQL_DATETIME或SQL_INTERVAL的記錄）

  • SQL_DESC_OCTET_LENGTH

  • SQL_DESC_PRECISION

  • SQL_DESC_SCALE

  • SQL_DESC_NULLABLE

SQLGetDescRec 不會擷取標頭欄位的值。

應用程式可以將對應至欄位的引數設定為 Null 指標，以防止傳回欄位的設定。

當應用程式呼叫 SQLGetDescRec 來擷取針對特定描述元類型未定義的域值時，函式會傳回SQL_SUCCESS但未定義欄位所傳回的值。 例如，針對 APD 或 ARD 的 SQL_DESC_NAME 或 SQL_DESC_NullABLE 欄位呼叫 SQLGetDescRec ，將會傳回SQL_SUCCESS但欄位未定義的值。

當應用程式呼叫 SQLGetDescRec 來擷取針對特定描述元類型所定義的域值，但尚未設定預設值，函式會傳回SQL_SUCCESS但未定義欄位傳回的值。 如需詳細資訊，請參閱 SQLSetDescField 中的 。

您也可以透過呼叫 SQLGetDescField 個別擷取欄位的值。 如需描述元標頭或記錄中欄位的描述，請參閱 SQLSetDescField 。 如需描述項的詳細資訊，請參閱描述項。

如需下列資訊 請參閱
系結資料行 SQLBindCol 函式
系結參數 SQLBindParameter 函式
取得描述元欄位 SQLGetDescField 函式
設定多個描述元欄位 SQLSetDescRec 函式

另請參閱

ODBC API 參考
ODBC 標頭檔