SQLGetTypeInfo 函式
一致性
引進版本：ODBC 1.0 標準合規性：ISO 92
摘要
SQLGetTypeInfo 會傳回數據源所支援之數據類型的相關信息。 驅動程式會以 SQL 結果集的形式傳回資訊。 數據類型適用於資料定義語言 （DDL） 語句。
重要
應用程式必須使用 ALTER TABLE 和 CREATE TABLE 語句中 SQLGetTypeInfo 結果集TYPE_NAME數據行中傳回的類型名稱。 SQLGetTypeInfo 可能會傳回多個數據列，其值在DATA_TYPE數據行中相同。
語法
SQLRETURN SQLGetTypeInfo(
SQLHSTMT StatementHandle,
SQLSMALLINT DataType);
引數
StatementHandle
[輸入]結果集的語句句柄。
DataType
[輸入]SQL 數據類型。 這必須是附錄 D：數據類型或驅動程式特定 SQL 數據類型的 SQL 資料類型一節中的其中一個值。 SQL_ALL_TYPES指定應該傳回所有數據類型的相關信息。
傳回
SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_STILL_EXECUTING、SQL_ERROR或SQL_INVALID_HANDLE。
診斷
當 SQLGetTypeInfo 傳回SQL_ERROR或SQL_SUCCESS_WITH_INFO時，可以使用 SQL_HANDLE_STMT 的 HandleType 和 StatementHandle 句柄呼叫 SQLGetDiagRec 來取得相關聯的 SQLSTATE 值。 下表列出 SQLGetTypeInfo 通常傳回的 SQLSTATE 值，並說明此函式內容中的每個值;表示法 “（DM）” 在驅動程式管理員傳回的 SQLSTATE 描述之前。 除非另有說明，否則與每個 SQLSTATE 值相關聯的傳回碼會SQL_ERROR。
| SQLSTATE | 錯誤 | 描述 |
|---|---|---|
| 01000 | 一般警告 | 驅動程式特定的資訊訊息。 （函式會傳回SQL_SUCCESS_WITH_INFO。） |
| 01S02 | 選項值已變更 | 由於實作工作條件，指定的語句屬性無效，因此會暫時取代類似的值。 （通話 SQLGetStmtAttr 以判斷暫時替代的值。替代值對 StatementHandle 有效，直到數據指標關閉為止。 可以變更的語句屬性包括：SQL_ATTR_CONCURRENCY、SQL_ATTR_CURSOR_TYPE、SQL_ATTR_KEYSET_SIZE、SQL_ATTR_MAX_LENGTH、SQL_ATTR_MAX_ROWS、SQL_ATTR_QUERY_TIMEOUT和SQL_ATTR_SIMULATE_CURSOR。 （函式會傳回SQL_SUCCESS_WITH_INFO。） |
| 08S01 | 通訊連結失敗 | 驅動程式與驅動程式連線的數據源之間的通訊連結在函式完成處理之前失敗。 |
| 24000 | 無效的數據指標狀態 | 已開啟 StatementHandle 上的 數據指標， 並 已呼叫 SQLFetch 或 SQLFetchScroll 。 如果 SQLFetch 或 SQLFetchScroll 尚未傳回SQL_NO_DATA，而且如果 SQLFetch 或 SQLFetchScroll 傳回SQL_NO_DATA，驅動程式就會傳回此錯誤。 語句Handle 上已開啟結果集，但未呼叫 SQLFetch 或 SQLFetchScroll。 |
| 40001 | 串行化失敗 | 交易因為與另一個交易發生資源死結而回復。 |
| 40003 | 語句完成未知 | 此函式執行期間相關聯的連接失敗，且無法判斷交易的狀態。 |
| HY000 | 一般錯誤 | 發生錯誤，其中沒有特定的 SQLSTATE，也沒有定義任何實作特定的 SQLSTATE。 *MessageText 緩衝區中 SQLGetDiagRec 傳回的錯誤訊息描述錯誤及其原因。 |
| HY001 | 記憶體配置錯誤 | 驅動程式無法配置支援執行或完成函式所需的記憶體。 |
| HY004 | 無效的 SQL 資料類型 | 為自變數 DataType 指定的值既不是有效的 ODBC SQL 資料類型識別碼，也不是驅動程式所支援的驅動程式特定數據類型識別碼。 |
| HY008 | 作業已取消 | 已針對 StatementHandle 啟用異步處理，然後呼叫函式，並在完成執行之前，在 StatementHandle 上呼叫 SQLCancel 或 SQLCancelHandle。 然後在 StatementHandle 上再次呼叫函式。 在函式完成執行之前，會從多線程應用程式中的不同線程呼叫StatementHandle，並呼叫 SQLCancel 或 SQLCancelHandle。 |
| HY010 | 函式順序錯誤 | （DM） 已針對與 StatementHandle 相關聯的連接句柄呼叫異步執行函式。 呼叫 SQLGetTypeInfo 函式時，這個異步函式仍在執行中。 （DM） 已針對 StatementHandle 呼叫 SQLExecute、SQLExecDirect 或 SQLMoreResults，並傳回SQL_PARAM_DATA_AVAILABLE。 在擷取所有數據流參數的數據之前，會呼叫此函式。 （DM） 呼叫 StatementHandle 的異步執行函式（而非此函式），並在呼叫此函式時仍在執行中。 （DM） 已針對 StatementHandle 呼叫 SQLExecute、SQLExecDirect、SQLBulkOperations 或 SQLSetPos，並傳回SQL_NEED_DATA。 在針對所有數據執行中參數或數據行傳送數據之前，會呼叫此函式。 |
| HY013 | 記憶體管理錯誤 | 無法處理函式呼叫，因為基礎記憶體物件無法存取，可能是因為記憶體不足的情況。 |
| HY117 | 聯機因為未知的交易狀態而暫停。 只允許中斷連線和唯讀函式。 | （DM） 如需暫停狀態的詳細資訊，請參閱 SQLEndTran 函式。 |
| HYC00 | 未實作選擇性功能 | 驅動程式或數據源不支援SQL_ATTR_CONCURRENCY和SQL_ATTR_CURSOR_TYPE語句屬性的目前設定組合。 SQL_ATTR_USE_BOOKMARKS語句屬性已設定為 SQL_UB_VARIABLE，且SQL_ATTR_CURSOR_TYPE語句屬性已設定為驅動程式不支援書籤的數據指標類型。 |
| HYT00 | 逾時已超過 | 數據源傳回結果集之前，查詢逾時期限已過期。 逾時期間是透過 SQLSetStmtAttr 來設定，SQL_ATTR_QUERY_TIMEOUT。 |
| HYT01 | 已超過連線逾時 | 在數據源回應要求之前，連線逾時期限已過期。 線上逾時期間是透過 SQLSetConnectAttr 來設定，SQL_ATTR_CONNECTION_TIMEOUT。 |
| IM001 | 驅動程式不支援此函式 | （DM） 對應至 StatementHandle 的驅動程式不支援 函式。 |
| IM017 | 在異步通知模式中停用輪詢 | 每當使用通知模型時，輪詢就會停用。 |
| IM018 | 尚未呼叫 SQLCompleteAsync ，以完成此句柄上的先前異步操作。 | 如果句柄上的上一個函式呼叫傳回SQL_STILL_EXECUTING且啟用通知模式， 則必須在句柄上呼叫 SQLCompleteAsync ，才能執行後續處理並完成作業。 |
註解
SQLGetTypeInfo 會以標準結果集的形式傳回結果，依DATA_TYPE排序，然後依據數據類型對應至對應 ODBC SQL 數據類型的方式。 數據來源所定義的數據類型優先於使用者定義的數據類型。 因此，排序順序不一定一致，但可以先將排序順序一般化為DATA_TYPE，後面接著遞增TYPE_NAME。 例如，假設數據源定義了 INTEGER 和 COUNTER 數據類型，其中 COUNTER 是自動遞增，而且使用者定義資料類型 WHOLENUM 也已經定義。 這些會以 INTEGER、WHOLENUM 和 COUNTER 的順序傳回，因為 WHOLENUM 會密切對應至 ODBC SQL 數據類型SQL_INTEGER，而自動遞增數據類型，即使數據源支援，也不會對應至 ODBC SQL 數據類型。 如需如何使用這項信息的資訊，請參閱 DDL 語句。
如果 DataType 自變數指定適用於驅動程式所支援 ODBC 版本的數據類型，但驅動程式不支援，則會傳回空的結果集。
注意
如需 ODBC 類別目錄函式的一般使用、自變數和傳回數據的詳細資訊，請參閱 目錄函式。
下列數據行已針對 ODBC 3 重新命名。x. 數據行名稱變更不會影響回溯相容性，因為應用程式會依數據行編號系結。
| ODBC 2.0 數據行 | ODBC 3.x 欄 |
|---|---|
| PRECISION | COLUMN_SIZE |
| MONEY | FIXED_PREC_SCALE |
| AUTO_INCREMENT | AUTO_UNIQUE_VALUE |
下列數據行已新增至 SQLGetTypeInfo for ODBC 3 所傳回的結果集。x：
SQL_DATA_TYPE
INTERVAL_PRECISION
SQL_DATETIME_SUB
NUM_PREC_RADIX
下表列出結果集中的數據行。 驅動程式可以定義數據行 19 以外的其他數據行（INTERVAL_PRECISION）。 應用程式應該從結果集結尾倒數，而不是指定明確的序數位置，以存取驅動程式特定的數據行。 如需詳細資訊，請參閱 目錄函式傳回的數據。
注意
SQLGetTypeInfo 可能不會傳回所有數據類型。 例如，驅動程式可能不會傳回使用者定義的數據類型。 不論 SQLGetTypeInfo 是否傳回任何有效的數據類型，應用程式都可以使用任何有效的數據類型。 SQLGetTypeInfo 所傳回的數據類型是數據源所支援的數據類型。 它們適用於資料定義語言 （DDL） 語句。 驅動程式可以使用 SQLGetTypeInfo 所傳回之型別以外的數據類型傳回結果集數據。 在建立目錄函式的結果集時，驅動程式可能會使用數據源不支援的數據類型。
| 資料行名稱 | 資料行 數值 |
資料類型 | 註解 |
|---|---|---|---|
| TYPE_NAME （ODBC 2.0） | 1 | Varchar not NULL | 數據源相依的數據類型名稱;例如，“CHAR（）”、“VARCHAR（）”、“MONEY”、“LONG VARBINARY” 或 “CHAR （ ） FOR BIT DATA”。 應用程式必須在 CREATE TABLE 和 ALTER TABLE 語句中使用這個名稱。 |
| DATA_TYPE （ODBC 2.0） | 2 | Smallint not NULL | SQL 數據類型。 這可以是 ODBC SQL 資料類型或驅動程式特定的 SQL 資料類型。 對於 datetime 或 interval 數據類型，此數據行會傳回精簡的數據類型（例如SQL_TYPE_TIME或SQL_INTERVAL_YEAR_TO_MONTH）。 如需有效的 ODBC SQL 資料類型清單，請參閱 附錄 D：資料類型中的 SQL 資料類型。 如需驅動程式特定SQL數據類型的相關信息，請參閱驅動程序的檔。 |
| COLUMN_SIZE （ODBC 2.0） | 3 | 整數 | 伺服器支援此資料類型的數據行大小上限。 對於數值數據，這是最大有效位數。 對於字串數據，這是以字元為單位的長度。 對於 datetime 資料類型，這是字串表示的字元長度（假設小數秒數位件允許的最大有效位數）。 如果數據行大小不適用，則會傳回NULL。 對於間隔數據類型，這是間隔常值字元表示中的字元數（如間隔前置精確度所定義;請參閱 附錄 D： 數據類型中的間隔數據類型長度 ）。 如需數據行大小的詳細資訊，請參閱 附錄 D：數據類型中的數據行大小、十進位數、傳輸八位長度和顯示大小 。 |
| LITERAL_PREFIX （ODBC 2.0） | 4 | Varchar | 用來在常值前面加上的字元或字元;例如，字元數據類型的單引號 （'） 或二進位數據類型的0x;NULL 會針對不適用常值前置詞的數據類型傳回。 |
| LITERAL_SUFFIX （ODBC 2.0） | 5 | Varchar | 用來終止常值的字元或字元;例如，字元數據類型的單引號 （'） ;NULL 會針對不適用常值後綴的數據類型傳回。 |
| CREATE_PARAMS （ODBC 2.0） | 6 | Varchar | 關鍵詞清單，以逗號分隔，對應至應用程式在使用 [TYPE_NAME] 欄位中傳回的名稱時，應用程式可以在括號中指定的每個參數。 清單中的關鍵詞可以是下列任一項：長度、有效位數或小數字數。 它們會以語法要求使用的順序出現。 例如，DECIMAL 的CREATE_PARAMS會是「precision，scale」;VARCHAR 的CREATE_PARAMS等於“length”。如果沒有數據類型定義的參數，則會傳回 NULL;例如 INTEGER。 驅動程式會以使用所在國家/地區的語言提供CREATE_PARAMS文字。 |
| NULLABLE （ODBC 2.0） | 7 | Smallint not NULL | 資料類型是否接受 NULL 值： 如果數據類型不接受NULL值，SQL_NO_NULLS。 如果數據類型接受NULL值，SQL_NULLABLE。 如果不知道數據行是否接受 NULL 值，SQL_NULLABLE_UNKNOWN。 |
| CASE_SENSITIVE （ODBC 2.0） | 8 | Smallint not NULL | 字元資料類型在定序和比較中是否區分大小寫： 如果數據類型是字元數據類型且區分大小寫，SQL_TRUE。 如果數據類型不是字元數據類型或不區分大小寫，SQL_FALSE。 |
| 可搜尋 （ODBC 2.0） | 9 | Smallint not NULL | 在 WHERE 子句中使用資料類型的方式： 如果數據行不能用於 WHERE 子句，SQL_PRED_NONE。 （這與 ODBC 2 中的SQL_UNSEARCHABLE值相同。x.） SQL_PRED_CHAR如果數據行可以在 WHERE 子句中使用，但只能搭配 LIKE 述詞使用。 （這與 ODBC 2 中的SQL_LIKE_ONLY值相同。x.） SQL_PRED_BASIC如果數據行可用於 WHERE 子句中，除了 LIKE 以外的所有比較運算符（比較、量化比較、BETWEEN、DISTINCT、IN、MATCH 和 UNIQUE）。 （這與 ODBC 2 中的SQL_ALL_EXCEPT_LIKE值相同。x.） SQL_SEARCHABLE如果數據行可用於具有任何比較運算子的 WHERE 子句中。 |
| UNSIGNED_ATTRIBUTE （ODBC 2.0） | 10 | Smallint | 資料類型是否不帶正負號： 如果數據類型不帶正負號，SQL_TRUE。 如果數據類型已簽署，SQL_FALSE。 如果屬性不適用於數據類型或數據類型不是數值，則會傳回NULL。 |
| FIXED_PREC_SCALE （ODBC 2.0） | 11 | Smallint not NULL | 數據類型是否具有預先定義的固定有效位數和小數字數（也就是數據源特定的），例如 money 數據類型： 如果已預先定義固定有效位數和小數字數，SQL_TRUE。 如果它沒有預先定義的固定有效位數和小數位數，SQL_FALSE。 |
| AUTO_UNIQUE_VALUE （ODBC 2.0） | 12 | Smallint | 資料型態是否為自動遞增： 如果數據類型為自動遞增，SQL_TRUE。 如果數據類型不是自動遞增，SQL_FALSE。 如果屬性不適用於數據類型或數據類型不是數值，則會傳回NULL。 應用程式可以將值插入具有此屬性的數據行中，但通常無法更新數據行中的值。 在自動遞增數據列中插入時，會在插入時將唯一值插入數據行中。 未定義增量，但為數據源特定。 應用程式不應該假設自動遞增數據行會從任何特定點開始，或以任何特定值遞增。 |
| LOCAL_TYPE_NAME （ODBC 2.0） | 13 | Varchar | 數據類型數據源相依名稱的當地語系化版本。 如果數據源不支援當地語系化名稱，則會傳回 NULL。 此名稱僅供顯示，例如在對話框中。 |
| MINIMUM_SCALE （ODBC 2.0） | 14 | Smallint | 數據源上數據類型的最小小數字數。 如果數據類型具有固定小數位數，則MINIMUM_SCALE和MAXIMUM_SCALE數據行都包含這個值。 例如，SQL_TYPE_TIMESTAMP數據行可能有小數秒的固定小數字數。 NULL 會在不適用小數位數的地方傳回。 如需詳細資訊，請參閱 附錄 D：數據類型中的數據行大小、十進位數、傳輸八位長度和顯示大小 。 |
| MAXIMUM_SCALE （ODBC 2.0） | 15 | Smallint | 數據源上數據類型的最大小數字數。 NULL 會在不適用小數位數的地方傳回。 如果未在數據源上個別定義最大小數字數，而是定義為與最大精確度相同，則此數據行包含與COLUMN_SIZE數據行相同的值。 如需詳細資訊，請參閱 附錄 D：數據類型中的數據行大小、十進位數、傳輸八位長度和顯示大小 。 |
| SQL_DATA_TYPE （ODBC 3.0） | 16 | Smallint NOT NULL | SQL 數據類型的值，因為它出現在描述元的SQL_DESC_TYPE欄位中。 此數據行與DATA_TYPE數據行相同，但間隔和日期時間數據類型除外。 對於 interval 和 datetime 數據類型，結果集中SQL_DATA_TYPE欄位會傳回SQL_INTERVAL或SQL_DATETIME，而SQL_DATETIME_SUB欄位會傳回特定間隔或 datetime 數據類型的子碼。 （請參閱 附錄 D：資料類型。） |
| SQL_DATETIME_SUB （ODBC 3.0） | 17 | Smallint | 當SQL_DATA_TYPE的值是SQL_DATETIME或SQL_INTERVAL時，這個數據行會包含 datetime/interval 子程式代碼。 對於 datetime 和 interval 以外的數據類型，此字段為 NULL。 對於 interval 或 datetime 數據類型，結果集中SQL_DATA_TYPE欄位會傳回SQL_INTERVAL或SQL_DATETIME，而SQL_DATETIME_SUB欄位會傳回特定間隔或 datetime 數據類型的子碼。 （請參閱 附錄 D：資料類型。） |
| NUM_PREC_RADIX （ODBC 3.0） | 18 | 整數 | 如果數據類型是近似數值類型，這個數據行會包含值 2，指出COLUMN_SIZE指定一些位。 對於確切的數值類型，此數據行包含值 10，表示COLUMN_SIZE指定十進位數。 否則，這個資料行就是 NULL。 |
| INTERVAL_PRECISION （ODBC 3.0） | 19 | Smallint | 如果數據類型是間隔數據類型，則此數據行會包含間隔前置精確度的值。 （請參閱 附錄 D：資料類型中的間隔資料類型有效位數 。）否則，此數據行為 NULL。 |
屬性資訊可以套用至數據類型或結果集中的特定數據行。 SQLGetTypeInfo 會傳回與數據類型相關聯的屬性相關信息; SQLColAttribute 會傳回與結果集中數據行相關聯之屬性的相關信息。
相關函數
| 如需下列資訊 | 請參閱 |
|---|---|
| 將緩衝區系結至結果集中的數據行 | SQLBindCol 函式 |
| 取消語句處理 | SQLCancel 函式 |
| 傳回結果集中數據行的相關信息 | SQLColAttribute 函式 |
| 擷取數據區塊或捲動結果集 | SQLFetchScroll 函式 |
| 以正向方向擷取單一數據列或數據區塊 | SQLFetch 函式 |
| 傳回驅動程式或數據源的相關信息 | SQLGetInfo 函式 |