SQLProcedureColumns 函式
一致性
引進的版本：ODBC 1.0 標準合規性：ODBC
摘要
SQLProcedureColumns 會傳回輸入和輸出參數的清單，以及組成指定程式結果集的資料行。 驅動程式會將資訊當做指定語句的結果集傳回。
語法
SQLRETURN SQLProcedureColumns(
SQLHSTMT StatementHandle,
SQLCHAR * CatalogName,
SQLSMALLINT NameLength1,
SQLCHAR * SchemaName,
SQLSMALLINT NameLength2,
SQLCHAR * ProcName,
SQLSMALLINT NameLength3,
SQLCHAR * ColumnName,
SQLSMALLINT NameLength4);
引數
StatementHandle
[輸入]語句控制碼。
CatalogName
[輸入]程式目錄名稱。 如果驅動程式支援某些程式的目錄，但不支援其他程式，例如當驅動程式從不同的 DBMS 擷取資料時，空字串 （「」） 表示沒有目錄的程式。 CatalogName 不能包含字串搜尋模式。
如果 SQL_ATTR_METADATA_ID 語句屬性設定為 SQL_TRUE， 則 CatalogName 會被視為識別碼，而且其大小寫並不重要。 如果它是SQL_FALSE， CatalogName 是一般引數;它會以常值方式處理，而且其大小寫很重要。 如需詳細資訊，請參閱目錄函式中的引數。
NameLength1
[輸入]*CatalogName 的 字元長度。
SchemaName
[輸入]程式架構名稱的字串搜尋模式。 如果驅動程式支援某些程式的架構，但不支援其他程式，例如當驅動程式從不同的 DBMS 擷取資料時，空字串 （「」） 表示沒有架構的程式。
如果 SQL_ATTR_METADATA_ID 語句屬性設定為 SQL_TRUE，則 SchemaName 會被視為識別碼， 而且其大小寫並不重要。 如果它是SQL_FALSE， SchemaName 是模式值引數;它會以常值方式處理，而且其大小寫很重要。
NameLength2
[輸入]*SchemaName 的 字元長度。
ProcName
[輸入]程式名稱的字串搜尋模式。
如果 SQL_ATTR_METADATA_ID 語句屬性設定為 SQL_TRUE， ProcName 會被視為識別碼，而且其大小寫並不重要。 如果它是SQL_FALSE， ProcName 是模式值引數;它會以字面方式處理，而且其大小寫很重要。
NameLength3
[輸入]*ProcName 的 字元長度。
ColumnName
[輸入]資料行名稱的字串搜尋模式。
如果SQL_ATTR_METADATA_ID語句屬性設定為 SQL_TRUE，ColumnName 會被視為識別碼， 而且其大小寫並不重要。 如果它是SQL_FALSE， ColumnName 是模式值引數;它會以常值方式處理，而且其大小寫很重要。
NameLength4
[輸入]*ColumnName 的 字元長度。
傳回
SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_STILL_EXECUTING、SQL_ERROR或SQL_INVALID_HANDLE。
診斷
當 SQLProcedureColumns 傳回SQL_ERROR或SQL_SUCCESS_WITH_INFO時，藉由呼叫 具有 handleType 為 SQL_HANDLE_STMT 的 SQLGetDiagRec 和 StatementHandle 控制碼 ，即可取得相關聯的 SQLSTATE 值。 下表列出 SQLProcedureColumns 通常傳 回的 SQLSTATE 值，並說明此函式內容中的每個值;標記法 「（DM）」 在驅動程式管理員傳回的 SQLSTATE 描述之前。 除非另有說明，否則與每個 SQLSTATE 值相關聯的傳回碼會SQL_ERROR。
| SQLSTATE | 錯誤 | 描述 |
|---|---|---|
| 01000 | 一般警告 | 驅動程式特定的資訊訊息。 （函式會傳回SQL_SUCCESS_WITH_INFO。） |
| 08S01 | 通訊連結失敗 | 驅動程式與驅動程式連線的資料來源之間的通訊連結在函式完成處理之前失敗。 |
| 24000 | 不正確資料指標狀態 | 已開啟 StatementHandle 上的 資料指標，並 已呼叫 SQLFetch 或 SQLFetchScroll 。 如果 SQLFetch 或 SQLFetchScroll 尚未傳回SQL_NO_DATA，而且如果 SQLFetch 或 SQLFetchScroll 傳回SQL_NO_DATA，驅動程式就會傳回此錯誤。 語句上已開啟 資料指標，但 未呼叫 SQLFetch 或 SQLFetchScroll 。 |
| 40001 | 序列化失敗 | 交易因為與另一個交易發生資源死結而回復。 |
| 40003 | 語句完成未知 | 此函式執行期間相關聯的連接失敗，且無法判斷交易的狀態。 |
| HY000 | 一般錯誤 | 發生錯誤，其中沒有特定的 SQLSTATE，也沒有定義任何實作特定的 SQLSTATE。 *MessageText 緩衝區中 SQLError 傳 回的錯誤訊息描述錯誤及其原因。 |
| HY001 | 記憶體配置錯誤 | 驅動程式無法配置支援執行或完成函式所需的記憶體。 |
| HY008 | 作業已取消 | 已針對 StatementHandle 啟用非同步處理。 已呼叫函式，並在完成執行之前， 在 StatementHandle 上 呼叫 SQLCancel 或 SQLCancelHandle 。 然後在 StatementHandle 上 再次呼叫函式。 呼叫函式，並在完成執行之前， 從多執行緒應用程式中的不同執行緒呼叫 語句Handle 或 SQLCancelHandle 。 |
| HY009 | 不正確 Null 指標使用 | SQL_ATTR_METADATA_ID語句屬性已設定為 SQL_TRUE、 CatalogName 引數為 null 指標，而且 infoType SQL_CATALOG_NAME 會傳回支援目錄名稱。 （DM） SQL_ATTR_METADATA_ID語句屬性設定為 SQL_TRUE， 而 SchemaName 、 ProcName 或 ColumnName 引數為 null 指標。 |
| HY010 | 函式順序錯誤 | （DM） 已針對與 StatementHandle 相關聯的連接控制碼呼叫非同步執行函式。 呼叫 SQLProcedureColumns 函式時，這個 aynschronous 函式仍在執行中。 （DM） 已針對 StatementHandle 呼叫 SQLExecute 、 SQLExecDirect 或 SQLMoreResults ，並傳回SQL_PARAM_DATA_AVAILABLE。 在擷取所有資料流程參數的資料之前，會呼叫此函式。 （DM） 呼叫 StatementHandle 的非同步執行函式（而非此函式），並在呼叫此函式時仍在執行中。 （DM） 已針對 StatementHandle 呼叫 SQLExecute 、 SQLExecDirect 、 SQLBulkOperations 或 SQLSetPos ，並傳回SQL_NEED_DATA。 在針對所有資料執行中參數或資料行傳送資料之前，會呼叫此函式。 |
| HY090 | 不正確字串或緩衝區長度 | （DM） 其中一個名稱長度引數的值小於 0，但不等於SQL_NTS。 其中一個名稱長度引數的值超過對應目錄、架構、程式或資料行名稱的最大長度值。 |
| 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 ，才能執行後續處理並完成作業。 |
註解
在語句執行之前，通常會使用此函式來擷取程式參數的相關資訊，以及組成程式所傳回結果集或集合的資料行，如果有的話。 如需詳細資訊，請參閱程序。
注意
SQLProcedureColumns 可能不會傳回程序所使用的所有資料行。 例如，驅動程式可能只傳回程序所使用之參數的相關資訊，而不是它所產生的結果集中的資料行。
SchemaName 、 ProcName 和 ColumnName 引數接受搜尋模式。 如需有效搜尋模式的詳細資訊，請參閱 模式值引數 。
注意
如需 ODBC 類別目錄函式的一般使用、引數和傳回資料的詳細資訊，請參閱 目錄函式 。
SQLProcedureColumns 會以標準結果集的形式傳回結果，依PROCEDURE_CAT、PROCEDURE_SCHEM、PROCEDURE_NAME和COLUMN_TYPE排序。 每個程式的資料行名稱會依下列順序傳回：傳回值的名稱、程式調用中每個參數的名稱（依呼叫順序），然後在程式傳回的結果集中每個資料行的名稱（依資料行順序）。
應用程式應該會繫結相對於結果集結尾的驅動程式專用資料行。 如需詳細資訊，請參閱 目錄函 式傳回的資料。
若要判斷PROCEDURE_CAT、PROCEDURE_SCHEM、PROCEDURE_NAME和COLUMN_NAME資料行的實際長度，應用程式可以使用SQL_MAX_CATALOG_NAME_LEN、SQL_MAX_SCHEMA_NAME_LEN、SQL_MAX_PROCEDURE_NAME_LEN和SQL_MAX_COLUMN_NAME_LEN選項呼叫 SQLGetInfo 。
下列資料行已針對 ODBC 3 重新命名。 x . 資料行名稱變更不會影響回溯相容性，因為應用程式會依資料行編號系結。
| ODBC 2.0 資料行 | ODBC 3. x 欄 |
|---|---|
| PROCEDURE_QUALIFIER | PROCEDURE_CAT |
| PROCEDURE _OWNER | PROCEDURE_SCHEM |
| PRECISION | COLUMN_SIZE |
| LENGTH | BUFFER_LENGTH |
| SCALE | DECIMAL_DIGITS |
| RADIX | NUM_PREC_RADIX |
下列資料行已新增至 SQLProcedureColumns for ODBC 3 所 傳回的結果集。 x ：
COLUMN_DEF
DATETIME_CODE
CHAR_OCTET_LENGTH
ORDINAL_POSITION
IS_NULLABLE
下表列出結果集中的資料行。 驅動程式可以定義資料行 19 以外的其他資料行（IS_NullABLE）。 應用程式應該從結果集結尾倒數，而不是指定明確的序數位置，以存取驅動程式特定的資料行。 如需詳細資訊，請參閱 目錄函 式傳回的資料。
| 資料行名稱 | Column number | 資料類型 | 註解 |
|---|---|---|---|
| PROCEDURE_CAT （ODBC 2.0） | 1 | Varchar | 程式目錄名稱;如果不適用於資料來源，則為 Null。 如果驅動程式支援某些程式的目錄，但不支援其他程式，例如當驅動程式從不同的 DBMS 擷取資料時，它會針對沒有目錄的程式傳回空字串 （「」）。 |
| PROCEDURE_SCHEM （ODBC 2.0） | 2 | Varchar | 程式架構名稱;如果不適用於資料來源，則為 Null。 如果驅動程式支援某些程式的架構，但不支援其他程式，例如當驅動程式從不同的 DBMS 擷取資料時，它會針對沒有架構的程式傳回空字串 （「」）。 |
| PROCEDURE_NAME （ODBC 2.0） | 3 | Varchar not Null | 程式名稱。 針對沒有名稱的程式，會傳回空字串。 |
| COLUMN_NAME （ODBC 2.0） | 4 | Varchar not Null | 程式資料行名稱。 驅動程式會針對沒有名稱的程式資料行傳回空字串。 |
| COLUMN_TYPE （ODBC 2.0） | 5 | Smallint not Null | 將程式資料行定義為參數或結果集資料行： SQL_PARAM_TYPE_UNKNOWN：程式資料行是類型未知的參數。 （ODBC 1.0） SQL_PARAM_INPUT：程式資料行是輸入參數。 （ODBC 1.0） SQL_PARAM_INPUT_OUTPUT：程式資料行是輸入/輸出參數。 （ODBC 1.0） SQL_PARAM_OUTPUT：程式資料行是輸出參數。 （ODBC 2.0） SQL_RETURN_VALUE：程式資料行是程式的傳回值。 （ODBC 2.0） SQL_RESULT_COL：程式資料行是結果集資料行。 （ODBC 1.0） |
| DATA_TYPE （ODBC 2.0） | 6 | Smallint not Null | SQL 資料類型。 這可以是 ODBC SQL 資料類型或驅動程式特定的 SQL 資料類型。 對於 datetime 和 interval 資料類型，此資料行會傳回精簡的資料類型（例如，SQL_TYPE_TIME或SQL_INTERVAL_YEAR_TO_MONTH）。 如需有效的 ODBC SQL 資料類型清單，請參閱 附錄 D：資料類型中的 SQL 資料類型。 如需驅動程式特定 SQL 資料類型的相關資訊，請參閱驅動程式的檔。 |
| TYPE_NAME （ODBC 2.0） | 7 | Varchar not Null | 資料來源相依資料類型名稱;例如，「CHAR」、「VARCHAR」、「MONEY」、「LONG VARBINARY」 或 「CHAR （ ） FOR BIT DATA」。 |
| COLUMN_SIZE （ODBC 2.0） | 8 | 整數 | 資料來源上程式資料行的資料行大小。 如果資料行大小不適用，則會傳回 Null。 如需精確度的詳細資訊，請參閱 附錄 D：資料類型中的資料行大小、十進位數、傳輸八位長度和顯示大小 。 |
| BUFFER_LENGTH （ODBC 2.0） | 9 | 整數 | 如果指定SQL_C_DEFAULT，則為在 SQLGetData 或 SQLFetch 作業上 傳輸的資料位元組長度。 對於數值資料，此大小可能與儲存在資料來源上的資料大小不同。 如需詳細資訊，請參閱 附錄 D：資料類型中的資料行大小、十進位數、傳輸八位長度和顯示大小 。 |
| DECIMAL_DIGITS （ODBC 2.0） | 10 | Smallint | 資料來源上程式資料行的十進位數。 Null 會針對不適用小數位數的資料類型傳回 Null。 如需十進位數的詳細資訊，請參閱 附錄 D：資料類型中的資料行大小、十進位數、傳輸八位長度和顯示大小 。 |
| NUM_PREC_RADIX （ODBC 2.0） | 11 | Smallint | 如果是數值資料類型，則為 10 或 2。 如果為 10，COLUMN_SIZE 和 DECIMAL_DIGITS中的值會提供資料行允許的小數位數。 例如，DECIMAL（12，5） 資料行會傳回 10 的NUM_PREC_RADIX、12 的COLUMN_SIZE，以及 5 的DECIMAL_DIGITS;FLOAT 資料行可以傳回 10 的NUM_PREC_RADIX、15 的COLUMN_SIZE，以及 Null 的DECIMAL_DIGITS。 如果為 2，COLUMN_SIZE 和 DECIMAL_DIGITS中的值會提供資料行中允許的位數。 例如，FLOAT 資料行可以傳回 2 的NUM_PREC_RADIX、53 的COLUMN_SIZE，以及 Null 的DECIMAL_DIGITS。 null 會針對不適用NUM_PREC_RADIX的資料類型傳回。 |
| NullABLE （ODBC 2.0） | 12 | Smallint not Null | 程式資料行是否接受 Null 值： SQL_NO_NullS：程式資料行不接受 Null 值。 SQL_NullABLE：程式資料行接受 Null 值。 SQL_NullABLE_UNKNOWN：目前還不清楚程式資料行是否接受 Null 值。 |
| 備註 （ODBC 2.0） | 13 | Varchar | 程式資料行的描述。 |
| COLUMN_DEF （ODBC 3.0） | 14 | Varchar | 資料行的預設值。 如果 Null 指定為預設值，則此資料行是 Null 一字，不會以引號括住。 如果無法表示沒有截斷的預設值，則此資料行會包含 TRUNCATED，且沒有括住單引號。 如果未指定任何預設值，則此資料行為 Null。 COLUMN_DEF的值可用於產生新的資料行定義，但包含 TRUNCATED 值時除外。 |
| SQL_DATA_TYPE （ODBC 3.0） | 15 | Smallint not Null | SQL 資料類型的值，因為它出現在描述元的SQL_DESC_TYPE欄位中。 此資料行與DATA_TYPE資料行相同，但 datetime 和 interval 資料類型除外。 對於 datetime 和 interval 資料類型，結果集中SQL_DATA_TYPE欄位會傳回SQL_INTERVAL或SQL_DATETIME，而SQL_DATETIME_SUB欄位會傳回特定間隔或 datetime 資料類型的子碼。 （請參閱 附錄 D：資料類型 。） |
| SQL_DATETIME_SUB （ODBC 3.0） | 16 | Smallint | datetime 和 interval 資料類型的子類型程式碼。 對於其他資料類型，這個資料行會傳回 Null。 |
| CHAR_OCTET_LENGTH （ODBC 3.0） | 17 | 整數 | 字元或二進位資料類型資料行的位元組長度上限。 對於所有其他資料類型，這個資料行會傳回 Null。 |
| ORDINAL_POSITION （ODBC 3.0） | 18 | 整數不是 Null | 針對輸入和輸出參數，參數在程式定義中的序數位置（以遞增參數順序，從 1 開始）。 針對傳回值（如果有的話），會傳回 0。 針對結果集資料行，資料行在結果集中的序數位置，結果集中的第一個資料行為數位 1。 如果有多個結果集，則會以驅動程式特定方式傳回資料行序數位置。 |
| IS_NullABLE （ODBC 3.0） | 19 | Varchar | 如果資料行不包含 Null，則為 「NO」。 如果資料行可以包含 Null，則為 「YES」。 如果 Null 屬性未知，此資料行會傳回長度為零的字串。 遵循 ISO 規則來判斷可為 Null 性。 符合 ISO SQL 標準的 DBMS 無法傳回空字串。 針對此資料行傳回的值與 NullABLE 資料行所傳回的值不同。 （請參閱 NullABLE 資料行的描述。 |
程式碼範例
請參閱 程序呼叫 。
相關函數
| 如需下列資訊 | 請參閱 |
|---|---|
| 將緩衝區系結至結果集中的資料行 | SQLBindCol 函式 |
| 取消語句處理 | SQLCancel 函式 |
| 以正向方向擷取單一資料列或資料區塊 | SQLFetch 函式 |
| 擷取資料區塊或捲動結果集 | SQLFetchScroll 函式 |
| 傳回資料來源中的程式清單 | SQLProcedures 函式 |