SQLProcedures 函式
一致性
引進的版本：ODBC 1.0 標準合規性：ODBC
摘要
SQLProcedures 會傳回儲存在特定資料來源中的程式名稱清單。 程式 是用來描述 可執行物件的 泛型詞彙，或是可使用輸入和輸出參數叫用的具名實體。 如需程式的詳細資訊，請參閱 程式 。
語法
SQLRETURN SQLProcedures(
SQLHSTMT StatementHandle,
SQLCHAR * CatalogName,
SQLSMALLINT NameLength1,
SQLCHAR * SchemaName,
SQLSMALLINT NameLength2,
SQLCHAR * ProcName,
SQLSMALLINT NameLength3);
引數
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 的 字元長度。
傳回
SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_STILL_EXECUTING、SQL_ERROR或SQL_INVALID_HANDLE。
診斷
當 SQLProcedures 傳回SQL_ERROR或SQL_SUCCESS_WITH_INFO時，藉由呼叫 SQLGetDiagRec 搭配 SQL_HANDLE_STMT 的 HandleType 和 StatementHandle 的 HandleHandle ，即可取得相關聯的 SQLSTATE 值。 下表列出 SQLProcedures 通常傳 回的 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 緩衝區中 SQLGetDiagRec 傳 回的錯誤訊息描述錯誤及其原因。 |
| 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 引數為 null 指標。 |
| HY010 | 函式順序錯誤 | （DM） 已針對與 StatementHandle 相關聯的連接控制碼呼叫非同步執行函式。 呼叫此函式時，這個非同步函式仍在執行中。 （DM） 已針對 StatementHandle 呼叫 SQLExecute 、 SQLExecDirect 或 SQLMoreResults ，並傳回SQL_PARAM_DATA_AVAILABLE。 在擷取所有資料流程參數的資料之前，會呼叫此函式。 （DM） 呼叫 StatementHandle 的非同步執行函式（而非此函式），並在呼叫此函式時仍在執行中。 （DM） 已針對 StatementHandle 呼叫 SQLExecute 、 SQLExecDirect 、 SQLBulkOperations 或 SQLSetPos ，並傳回SQL_NEED_DATA。 在針對所有資料執行中參數或資料行傳送資料之前，會呼叫此函式。 |
| HY013 | 記憶體管理錯誤 | 無法處理函式呼叫，因為基礎記憶體物件無法存取，可能是因為記憶體不足的情況。 |
| 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 ，才能執行後續處理並完成作業。 |
註解
SQLProcedures 會列出要求範圍中的所有程式。 使用者可能或可能沒有執行上述任何程式的許可權。 若要檢查協助工具，應用程式可以呼叫 SQLGetInfo 並檢查SQL_ACCESSIBLE_PROCEDURES資訊值。 否則，應用程式必須能夠處理使用者選取無法執行的程式的情況。 如需如何使用這項資訊的資訊，請參閱 程式 。
注意
如需 ODBC 類別目錄函式的一般使用、引數和傳回資料的詳細資訊，請參閱 目錄函式 。
SQLProcedures 會以標準結果集的形式傳回結果，依PROCEDURE_CAT、PROCEDURE_SCHEMA和PROCEDURE_NAME排序。
注意
SQLProcedures 可能不會傳回所有程式。 無論 SQLProcedures 是否傳 回任何有效的程式，應用程式都可以使用任何有效的程式。
下列資料行已針對 ODBC 3*.x* 重新命名。 資料行名稱變更不會影響回溯相容性，因為應用程式會依資料行編號系結。
| ODBC 2.0 資料行 | ODBC 3*.x* 資料行 |
|---|---|
| PROCEDURE_QUALIFIER | PROCEDURE_CAT |
| PROCEDURE _OWNER | 程式_SCHEM |
若要判斷PROCEDURE_CAT、PROCEDURE_SCHEM和PROCEDURE_NAME資料行的實際長度，應用程式可以使用SQL_MAX_CATALOG_NAME_LEN、SQL_MAX_SCHEMA_NAME_LEN和SQL_MAX_PROCEDURE_NAME_LEN選項呼叫 SQLGetInfo 。
下表列出結果集中的資料行。 驅動程式可以定義資料行 8 以外的其他資料行（PROCEDURE_TYPE）。 應用程式應該從結果集結尾倒數，而不是指定明確的序數位置，以存取驅動程式特定的資料行。 如需詳細資訊，請參閱 目錄函 式傳回的資料。
| 資料行名稱 | 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 | 程式識別碼。 |
| NUM_INPUT_PARAMS （ODBC 2.0） | 4 | N/A | 保留供未來使用。 應用程式不應該依賴這些結果資料行中傳回的資料。 |
| NUM_OUTPUT_PARAMS （ODBC 2.0） | 5 | N/A | 保留供未來使用。 應用程式不應該依賴這些結果資料行中傳回的資料。 |
| NUM_RESULT_SETS （ODBC 2.0） | 6 | N/A | 保留供未來使用。 應用程式不應該依賴這些結果資料行中傳回的資料。 |
| 備註 （ODBC 2.0） | 7 | Varchar | 程式的描述。 |
| PROCEDURE_TYPE （ODBC 2.0） | 8 | Smallint | 定義程式類型： SQL_PT_UNKNOWN：無法判斷程式是否傳回值。 SQL_PT_PROCEDURE：傳回的物件是程式;也就是說，它沒有傳回值。 SQL_PT_FUNCTION：傳回的物件是函式;也就是說，它有傳回值。 |
SchemaName 和 ProcName 引數接受搜尋模式。 如需有效搜尋模式的詳細資訊，請參閱 模式值引數 。
程式碼範例
請參閱 程序呼叫 。
相關函數
| 如需下列資訊 | 請參閱 |
|---|---|
| 將緩衝區系結至結果集中的資料行 | SQLBindCol 函式 |
| 取消語句處理 | SQLCancel 函式 |
| 以正向方向擷取單一資料列或資料區塊 | SQLFetch 函式 |
| 擷取資料區塊或捲動結果集 | SQLFetchScroll 函式 |
| 傳回驅動程式或資料來源的相關資訊 | SQLGetInfo 函式 |
| 傳回程序的參數和結果集資料行 | SQLProcedureColumns 函式 |
| 叫用預存程式的語法 | 執行陳述式 |