SQLColumns-取得表格的直欄資訊

SQLColumns() 會傳回指定表格中的直欄清單。會在查詢結果集中傳回資訊，您可以使用用來提取 SELECT 陳述式所產生結果集的相同函數來擷取該資訊。

Unicode (UTF-16) 相等: 此函數也可以與 Unicode (UTF-16) 字集搭配使用。對應的 Unicode 函數為 SQLColumnsW()。如需 Db2 for i CLI 的 Unicode 支援相關資訊，請參閱 Db2 for i CLI 中的 Unicode 。

語法

SQLRETURN SQLColumns  (SQLHSTMT       hstmt,
                       SQLCHAR        *szCatalogName,
                       SQLSMALLINT    cbCatalogName,
                       SQLCHAR        *szSchemaName,
                       SQLSMALLINT    cbSchemaName,
                       SQLCHAR        *szTableName,
                       SQLSMALLINT    cbTableName,
                       SQLCHAR        *szColumnName,
                       SQLSMALLINT    cbColumnName);

函數引數

表 1. SQLColumns 引數
資料類型	引數	使用	說明
SQLHSTMT	hstmt	輸入	陳述式控點。
SQLCHAR *	szCatalog名稱	輸入	可能包含 pattern-value 以限定結果集的緩衝區。型錄是三段式表格名稱的第一部分。這必須是空值指標或零長度字串。
SQLSMALLINT	cbCatalog名稱	輸入	szCatalog名稱的長度。這必須設為 0。
SQLCHAR *	szSchema名稱	輸入	可能包含 pattern-value 的緩衝區，可依綱目名稱來限定結果集。
SQLSMALLINT	cbSchema名稱	輸入	szSchema名稱的長度
SQLCHAR *	szTable名稱	輸入	可能包含 pattern-value 的緩衝區，可依表格名稱來限定結果集。
SQLSMALLINT	cbTable名稱	輸入	szTable名稱的長度
SQLCHAR *	szColumn名稱	輸入	緩衝區可包含 pattern-value ，以依直欄名稱來限定結果集。
SQLSMALLINT	cbColumn名稱	輸入	szColumn名稱的長度

用法

此函數會擷取表格或表格清單之直欄的相關資訊。

SQLColumns() 會傳回標準結果集。表 2 列出結果集中的直欄。

szCatalog名稱、 szSchema名稱、 szTable名稱和 szColumn名稱 引數接受搜尋型樣。跳出字元可以與萬用字元一起指定，以容許在搜尋型樣中使用該實際字元。跳出字元指定在 SQL_ATTR_ESCAPE_CHAR 環境屬性上。

此函數不會傳回結果集中由 SQLDescribeCol() 或 SQLColAttribute()擷取之直欄的相關資訊。如果應用程式想要取得結果集的直欄資訊，它應該一律呼叫 SQLDescribeCol() 或 SQLColAttribute() 以提高效率。 SQLColumns() 會對映至針對系統型錄的複式查詢，且可能需要大量系統資源。

表 2. SQLColumns 傳回的直欄
直欄號碼/名稱	資料類型	說明
1 TABLE_CAT	VARCHAR (128)	現行伺服器。
2 TABLE_SCHEM	VARCHAR (128)	包含 TABLE_NAME 的綱目名稱。
3 TABLE_NAME	VARCHAR (128)	表格、視圖或別名的名稱。
4 直欄 _ 名稱	VARCHAR (128)	直欄 ID。為其建置別名的指定視圖、表格或表格直欄的直欄名稱。
5 資料 _ 類型	SMALLINT 不是 NULL	DATA_TYPE 識別直欄的 SQL 資料類型。
6 TYPE_NAME	VARCHAR (128) 非空值	TYPE_NAME 是一個字串，代表對應於 DATA_TYPE 的資料類型名稱。如果資料類型是 FOR BIT DATA ，則對應的字串 FOR BIT DATA 會附加至資料類型，例如 CHAR () FOR BIT DATA。
7 COLUMN_SIZE	INTEGER	如果 DATA_TYPE 是近似數值資料類型，則此直欄包含直欄的假數精準度位元數。對於確切數值資料類型，此直欄包含直欄中容許的十進位數總數。對於時間及時間戳記資料類型，此直欄包含小數秒元件的精準度位數; 否則，此直欄為 NULL。附註: 精準度的 ODBC 定義通常是用來儲存資料類型的位數。
8 BUFFER_LENGTH	INTEGER	如果在 `SQLBindCol()` 、 `SQLGetData()`及 `SQLBindParam()` 呼叫上指定 SQL_DEFAULT ，從這個直欄儲存資料的位元組數上限。
9 DECIMAL_DIGITS	SMALLINT	直欄的小數位數。如果資料類型的小數位數不適用，則會傳回空值。
10 NUM_PREC_RADIX	SMALLINT	該值為 10、2 或 NULL。如果 DATA_TYPE 是近似數值資料類型，則此直欄包含值 2; 則 LENGTH_PRECITION 直欄包含直欄中容許的位元數。如果 DATA_TYPE 是確切的數值資料類型，則此直欄包含值 10 ，且 LENGTH_PRECISION 及 NUM_SCALE 直欄包含直欄容許的小數位數。對於數值資料類型，「資料庫管理系統 (DBMS)」可以傳回 NUM_PREC_RADIX 10 或 2。對於基數不適用的資料類型，會傳回空值。
11 可為空值	SMALLINT 不是 NULL	SQL_NO_NULLS (如果直欄不接受空值)。如果直欄接受 NULL 值，則為 SQL_NULLABLE。
12 個意見	NVARCHAR (2000)	包含直欄的敘述性資訊。
13 直欄 _DEF	NVARCHAR (2000)	直欄的預設值。如果預設值是數值文字，則此直欄包含沒有含括單引號之數值文字的字元表示法。如果預設值是字串，則此直欄是用單引號括住的字串。如果預設值是 pseudo-literal(例如 DATE、TIME 及 TIMESTAMP 直欄) ，則此直欄包含虛擬文字 (例如 CURRENT DATE) 的關鍵字，且不含含括引號。如果指定 NULL 作為預設值，則此直欄會傳回單字 NULL ，而不是用引號括住。如果預設值無法在沒有截斷的情況下表示，則此直欄包含沒有含括單引號的 TRUNCATED。如果未指定預設值，則此直欄為 NULL。
14 SQL_DATA_TYPE	SMALLINT 不是 NULL	DATA_TYPE 識別直欄的 SQL 資料類型。
15 SQL_DATETIME_SUB	SMALLINT	日期和時間資料類型的子類型碼: SQL_DATE SQL 時間 SQL 時間戳記對於所有其他資料類型，此直欄會傳回空值。
16 CHAR_OCTET_LENGTH	INTEGER	這包含字元資料類型直欄的長度上限 (以八位元組為單位)。對於單位元組字集，這與 LENGTH_PRECITREN 相同。對於所有其他資料類型，它是空值。
17 ORDINAL_POSITION	INTEGER 非空值	表格中直欄的序數位置。表格中的第一個直欄是數字 1。
18 可為空值	VARCHAR (3)	如果已知直欄不可為空值，則包含字串 'NO'; 否則包含 'YES'。

回覆碼

SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_ERROR
SQL_INVALID_HANDLE

診斷

表 3. SQLColumns SQLSTATE
SQL狀態	說明	說明
HY001	記憶體配置失敗	驅動程式無法配置支援處理或完成函數所需的記憶體。
HY009	無效的字串或緩衝區長度	其中一個名稱長度引數的值小於 0 ，但不等於 SQL_NTS。
HY010	函數順序錯誤	此陳述式控點有開啟的游標，或此陳述式控點沒有連線。
HY021	無效的內部描述子	內部描述子無法定址或配置，或包含無效的值。