SQLProcedureColumns, funkcja

zgodności
Wersja wprowadzona: Zgodność ze standardami ODBC 1.0: ODBC

podsumowania
SQLProcedureColumns zwraca listę parametrów wejściowych i wyjściowych, a także kolumny tworzące zestaw wyników dla określonych procedur. Sterownik zwraca informacje w wyniku ustawione na określonej instrukcji.

Składnia

  
SQLRETURN SQLProcedureColumns(  
     SQLHSTMT      StatementHandle,  
     SQLCHAR *     CatalogName,  
     SQLSMALLINT   NameLength1,  
     SQLCHAR *     SchemaName,  
     SQLSMALLINT   NameLength2,  
     SQLCHAR *     ProcName,  
     SQLSMALLINT   NameLength3,  
     SQLCHAR *     ColumnName,  
     SQLSMALLINT   NameLength4);  

Argumenty

, instrukcjaHandle
[Dane wejściowe] Uchwyt instrukcji.

CatalogName
[Dane wejściowe] Nazwa wykazu procedur. Jeśli sterownik obsługuje wykazy dla niektórych procedur, ale nie dla innych, takich jak gdy sterownik pobiera dane z różnych zestawów DBMS, pusty ciąg ("") oznacza te procedury, które nie mają wykazów. CatalogName nie może zawierać wzorca wyszukiwania ciągów.

Jeśli atrybut instrukcji SQL_ATTR_METADATA_ID jest ustawiony na SQL_TRUE, CatalogName jest traktowany jako identyfikator, a jego przypadek nie jest znaczący. Jeśli jest SQL_FALSE, CatalogName jest zwykłym argumentem; jest traktowany dosłownie, a jego przypadek jest znaczący. Aby uzyskać więcej informacji, zobacz Argumenty w usłudze Catalog Functions.

NameLength1
[Dane wejściowe] Długość znaków *CatalogName.

nazwa_schematu
[Dane wejściowe] Wzorzec wyszukiwania ciągów dla nazw schematów procedur. Jeśli sterownik obsługuje schematy niektórych procedur, ale nie dla innych, takich jak gdy sterownik pobiera dane z różnych zestawów DBMS, pusty ciąg ("") oznacza te procedury, które nie mają schematów.

Jeśli atrybut instrukcji SQL_ATTR_METADATA_ID jest ustawiony na SQL_TRUE, SchemaName jest traktowany jako identyfikator, a jego wielkość nie jest znacząca. Jeśli jest SQL_FALSE, SchemaName jest argumentem wartości wzorca; jest traktowany dosłownie, a jego przypadek jest znaczący.

NameLength2
[Dane wejściowe] Długość znaków *Nazwa schematu.

ProcName
[Dane wejściowe] Wzorzec wyszukiwania ciągów dla nazw procedur.

Jeśli atrybut instrukcji SQL_ATTR_METADATA_ID jest ustawiony na SQL_TRUE, ProcName jest traktowany jako identyfikator, a jego wielkość nie jest znacząca. Jeśli jest SQL_FALSE, ProcName jest argumentem wartości wzorca; jest traktowany dosłownie, a jego przypadek jest znaczący.

NameLength3
[Dane wejściowe] Długość znaków *ProcName.

Nazwakolumny
[Dane wejściowe] Wzorzec wyszukiwania ciągów dla nazw kolumn.

Jeśli atrybut instrukcji SQL_ATTR_METADATA_ID jest ustawiony na SQL_TRUE, Nazwakolumny jest traktowana jako identyfikator, a jego wielkość nie jest znacząca. Jeśli jest SQL_FALSE, Nazwakolumny jest argumentem wartości wzorca; jest traktowany dosłownie, a jego przypadek jest znaczący.

NameLength4
[Dane wejściowe] Długość znaków *Nazwakolumny.

Zwraca

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR lub SQL_INVALID_HANDLE.

Diagnostyka

Gdy sqlProcedureColumns zwraca SQL_ERROR lub SQL_SUCCESS_WITH_INFO, skojarzona wartość SQLSTATE może zostać uzyskana przez wywołanie SQLGetDiagRec z HandleType SQL_HANDLE_STMT i handle instrukcji Handle. W poniższej tabeli wymieniono wartości SQLSTATE, które są często zwracane przez SQLProcedureColumns i objaśniono poszczególne wartości w kontekście tej funkcji; notacja "(DM)" poprzedza opisy obiektów SQLSTATEs zwróconych przez menedżera sterowników. Kod zwracany skojarzony z każdą wartością SQLSTATE jest SQL_ERROR, chyba że określono inaczej.

SQLSTATE	Błąd	Opis
01000	Ostrzeżenie ogólne	Komunikat informacyjny specyficzny dla sterownika. (Funkcja zwraca SQL_SUCCESS_WITH_INFO).
08S01	Błąd połączenia komunikacyjnego	Połączenie komunikacyjne między sterownikiem a źródłem danych, z którym sterownik został połączony, nie powiodło się przed zakończeniem przetwarzania funkcji.
24000	Nieprawidłowy stan kursora	Kursor został otwarty na StatementHandlei wywoływano SQLFetch lub SQLFetchScroll. Ten błąd jest zwracany przez Menedżera sterowników, jeśli SQLFetch lub SQLFetchScroll nie zwrócił SQL_NO_DATA i jest zwracany przez sterownik, jeśli sqlFetch lub SQLFetchScroll zwrócił SQL_NO_DATA. Kursor został otwarty w StatementHandle, ale sqlFetch lub SQLFetchScroll nie został wywołany.
40001	Niepowodzenie serializacji	Transakcja została wycofana z powodu zakleszczenia zasobu z inną transakcją.
40003	Ukończenie instrukcji nieznane	Skojarzone połączenie nie powiodło się podczas wykonywania tej funkcji, a nie można określić stanu transakcji.
HY000	Błąd ogólny	Wystąpił błąd, dla którego nie było określonego stanu SQLSTATE i dla którego nie zdefiniowano parametru SQLSTATE specyficznego dla implementacji. Komunikat o błędzie zwrócony przez SQLError w buforze *MessageText opisuje błąd i jego przyczynę.
HY001	Błąd alokacji pamięci	Sterownik nie może przydzielić pamięci wymaganej do obsługi wykonywania lub ukończenia funkcji.
HY008	Operacja anulowana	Przetwarzanie asynchroniczne zostało włączone dla instrukcji Handle. Wywołano funkcję , a przed zakończeniem wykonywania SQLCancel lub SQLCancelHandle została wywołana w StatementHandle. Następnie funkcja została ponownie wywołana w StatementHandle. Wywołano funkcję i przed jej ukończeniem SQLCancel lub SQLCancelHandle została wywołana w StatementHandle z innego wątku w aplikacji wielowątku.
HY009	Nieprawidłowe użycie wskaźnika o wartości null	Atrybut instrukcji SQL_ATTR_METADATA_ID został ustawiony na SQL_TRUE, argument CatalogName był wskaźnikiem o wartości null, a SQL_CATALOG_NAME InfoType zwraca, że nazwy wykazu są obsługiwane. (DM) Atrybut instrukcji SQL_ATTR_METADATA_ID został ustawiony na SQL_TRUE, a argument SchemaName, ProcNamelub ColumnName argument był wskaźnikiem o wartości null.
HY010	Błąd sekwencji funkcji	(DM) Asynchronicznie wykonywana funkcja została wywołana dla dojścia połączenia skojarzonego z StatementHandle. Ta funkcja asynchroniczna była nadal wykonywana, gdy wywołano funkcję SQLProcedureColumns. (DM) SQLExecute, SQLExecDirectlub SQLMoreResults został wezwany do StatementHandle i zwrócił SQL_PARAM_DATA_AVAILABLE. Ta funkcja została wywołana przed pobraniem danych dla wszystkich parametrów przesyłanych strumieniowo. (DM) Asynchronicznie wykonywana funkcja (a nie ta) została wywołana dla StatementHandle i nadal była wykonywana, gdy ta funkcja została wywołana. (DM) SQLExecute, SQLExecDirect, SQLBulkOperationslub SQLSetPos została wywołana dla StatementHandle i zwrócona SQL_NEED_DATA. Ta funkcja została wywołana przed wysłaniem danych dla wszystkich parametrów wykonywania danych lub kolumn.
HY090	Nieprawidłowa długość ciągu lub buforu	(DM) Wartość jednego z argumentów długości nazwy była mniejsza niż 0, ale nie równa SQL_NTS. Wartość jednego z argumentów długości nazwy przekroczyła maksymalną wartość długości odpowiedniego katalogu, schematu, procedury lub nazwy kolumny.
HY117	Połączenie jest zawieszone z powodu nieznanego stanu transakcji. Dozwolone są tylko funkcje rozłączania i tylko do odczytu.	(DM) Aby uzyskać więcej informacji na temat stanu wstrzymania, zobacz funkcja SQLEndTran.
HYC00	Opcjonalna funkcja nie zaimplementowana	Określono wykaz procedur, a sterownik lub źródło danych nie obsługuje wykazów. Określono schemat procedury, a sterownik lub źródło danych nie obsługuje schematów. Wzorzec wyszukiwania ciągów został określony dla schematu procedury, nazwy procedury lub nazwy kolumny, a źródło danych nie obsługuje wzorców wyszukiwania dla co najmniej jednego z tych argumentów. Kombinacja bieżących ustawień SQL_ATTR_CONCURRENCY i atrybutów instrukcji SQL_ATTR_CURSOR_TYPE nie była obsługiwana przez sterownik lub źródło danych. Atrybut instrukcji SQL_ATTR_USE_BOOKMARKS został ustawiony na SQL_UB_VARIABLE, a atrybut instrukcji SQL_ATTR_CURSOR_TYPE został ustawiony na typ kursora, dla którego sterownik nie obsługuje zakładek.
HYT00	Upłynął limit czasu	Okres przekroczenia limitu czasu wygasł przed zwróceniem zestawu wyników przez źródło danych. Limit czasu jest ustawiany za pomocą sqlSetStmtAttr, SQL_ATTR_QUERY_TIMEOUT.
HYT01	Upłynął limit czasu połączenia	Okres przekroczenia limitu czasu połączenia wygasł, zanim źródło danych odpowiedziało na żądanie. Limit czasu połączenia jest ustawiany za pomocą SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT.
IM001	Sterownik nie obsługuje tej funkcji	(DM) Sterownik skojarzony z instrukcją Handle nie obsługuje funkcji.
IM017	Sondowanie jest wyłączone w trybie powiadomień asynchronicznych	Za każdym razem, gdy jest używany model powiadomień, sondowanie jest wyłączone.
IM018	sqlCompleteAsync nie została wywołana w celu ukończenia poprzedniej operacji asynchronicznej na tym dojściu.	Jeśli poprzednie wywołanie funkcji na dojściu zwraca SQL_STILL_EXECUTING i jeśli tryb powiadomień jest włączony, SQLCompleteAsync należy wywołać do dojścia, aby wykonać przetwarzanie końcowe i zakończyć operację.

Komentarze

Ta funkcja jest zwykle używana przed wykonaniem instrukcji w celu pobrania informacji o parametrach procedury i kolumnach, które składają się na zestaw wyników lub zestawy zwracane przez procedurę, jeśli istnieją. Aby uzyskać więcej informacji, zobacz Procedures.

Nuta

SQLProcedureColumns może nie zwracać wszystkich kolumn używanych przez procedurę. Na przykład sterownik może zwracać tylko informacje o parametrach używanych przez procedurę, a nie kolumnach w zestawie wyników, które generuje.

Argumenty SchemaName, ProcNamei Nazwakolumny akceptują wzorce wyszukiwania. Aby uzyskać więcej informacji na temat prawidłowych wzorców wyszukiwania, zobacz argumenty wartości wzorca .

Nuta

Aby uzyskać więcej informacji na temat ogólnego użycia, argumentów i zwracanych danych funkcji wykazu ODBC, zobacz Catalog Functions.

SQLProcedureColumns zwraca wyniki w postaci standardowego zestawu wyników uporządkowanego według PROCEDURE_CAT, PROCEDURE_SCHEM, PROCEDURE_NAME i COLUMN_TYPE. Nazwy kolumn są zwracane dla każdej procedury w następującej kolejności: nazwa zwracanej wartości, nazwy każdego parametru w wywołaniu procedury (w kolejności wywołania), a następnie nazwy każdej kolumny w zestawie wyników zwracane przez procedurę (w kolejności kolumn).

Aplikacje powinny wiązać kolumny specyficzne dla sterownika względem końca zestawu wyników. Aby uzyskać więcej informacji, zobacz Dane zwrócone przez funkcje katalogu.

Aby określić rzeczywiste długości kolumn PROCEDURE_CAT, PROCEDURE_SCHEM, PROCEDURE_NAME i COLUMN_NAME, aplikacja może wywoływać SQLGetInfo z opcjami SQL_MAX_CATALOG_NAME_LEN, SQL_MAX_SCHEMA_NAME_LEN, SQL_MAX_PROCEDURE_NAME_LEN i SQL_MAX_COLUMN_NAME_LEN.

Nazwa następujących kolumn została zmieniona na ODBC 3.x. Zmiany nazwy kolumny nie mają wpływu na zgodność z poprzednimi wersjami, ponieważ aplikacje są powiązane według numeru kolumny.

Kolumna ODBC 2.0	ODBC 3.x kolumna
PROCEDURE_QUALIFIER	PROCEDURE_CAT
_OWNER PROCEDURY	PROCEDURE_SCHEM
PRECYZJA	COLUMN_SIZE
DŁUGOŚĆ	BUFFER_LENGTH
SKALA	DECIMAL_DIGITS
PODSTAWA	NUM_PREC_RADIX

Następujące kolumny zostały dodane do zestawu wyników zwróconego przez SQLProcedureColumns dla ODBC 3.x:

• COLUMN_DEF

• DATETIME_CODE

• CHAR_OCTET_LENGTH

• ORDINAL_POSITION

• IS_NULLABLE

W poniższej tabeli wymieniono kolumny w zestawie wyników. Dodatkowe kolumny poza kolumną 19 (IS_NULLABLE) można zdefiniować przez sterownik. Aplikacja powinna uzyskać dostęp do kolumn specyficznych dla sterownika przez odliczanie od końca zestawu wyników zamiast określania jawnej pozycji porządkowej. Aby uzyskać więcej informacji, zobacz Dane zwrócone przez funkcje katalogu.

Nazwa kolumny	Numer kolumny	Typ danych	Komentarze
PROCEDURE_CAT (ODBC 2.0)	1	Varchar	Nazwa wykazu procedur; Wartość NULL, jeśli nie ma zastosowania do źródła danych. Jeśli sterownik obsługuje wykazy dla niektórych procedur, ale nie dla innych, takich jak gdy sterownik pobiera dane z różnych zestawów DBMS, zwraca pusty ciąg ("") dla tych procedur, które nie mają wykazów.
PROCEDURE_SCHEM (ODBC 2.0)	2	Varchar	Nazwa schematu procedury; Wartość NULL, jeśli nie ma zastosowania do źródła danych. Jeśli sterownik obsługuje schematy dla niektórych procedur, ale nie dla innych, takich jak gdy sterownik pobiera dane z różnych zestawów DBMS, zwraca pusty ciąg ("") dla tych procedur, które nie mają schematów.
PROCEDURE_NAME (ODBC 2.0)	3	Varchar nie ma wartości NULL	Nazwa procedury. Pusty ciąg jest zwracany dla procedury, która nie ma nazwy.
COLUMN_NAME (ODBC 2.0)	4	Varchar nie ma wartości NULL	Nazwa kolumny procedury. Sterownik zwraca pusty ciąg dla kolumny procedury, która nie ma nazwy.
COLUMN_TYPE (ODBC 2.0)	5	Parametr Smallint nie ma wartości NULL	Definiuje kolumnę procedury jako parametr lub kolumnę zestawu wyników: SQL_PARAM_TYPE_UNKNOWN: kolumna procedury jest parametrem, którego typ jest nieznany. (ODBC 1.0) SQL_PARAM_INPUT: kolumna procedury jest parametrem wejściowym. (ODBC 1.0) SQL_PARAM_INPUT_OUTPUT: kolumna procedury jest parametrem wejściowym/wyjściowym. (ODBC 1.0) SQL_PARAM_OUTPUT: kolumna procedury jest parametrem wyjściowym. (ODBC 2.0) SQL_RETURN_VALUE: kolumna procedury jest zwracaną wartością procedury. (ODBC 2.0) SQL_RESULT_COL: kolumna procedury jest kolumną zestawu wyników. (ODBC 1.0)
DATA_TYPE (ODBC 2.0)	6	Parametr Smallint nie ma wartości NULL	Typ danych SQL. Może to być typ danych SQL ODBC lub typ danych SQL specyficzny dla sterownika. W przypadku typów danych data/godzina i interwał ta kolumna zwraca zwięzłe typy danych (na przykład SQL_TYPE_TIME lub SQL_INTERVAL_YEAR_TO_MONTH). Aby uzyskać listę prawidłowych typów danych SQL ODBC, zobacz typy danych SQL w dodatku D: Typy danych. Aby uzyskać informacje o typach danych SQL specyficznych dla sterownika, zobacz dokumentację sterownika.
TYPE_NAME (ODBC 2.0)	7	Varchar nie ma wartości NULL	Nazwa typu danych zależnego od źródła danych; na przykład "CHAR", "VARCHAR", "MONEY", "LONG VARBINARY" lub "CHAR ( ) FOR BIT DATA".
COLUMN_SIZE (ODBC 2.0)	8	Liczba całkowita	Rozmiar kolumny procedury w źródle danych. Wartość NULL jest zwracana dla typów danych, w których rozmiar kolumny nie ma zastosowania. Aby uzyskać więcej informacji na temat dokładności, zobacz Rozmiar kolumny, Cyfry dziesiętne, Długość oktetu transferu i Rozmiar wyświetlania w dodatku D: Typy danych.
BUFFER_LENGTH (ODBC 2.0)	9	Liczba całkowita	Długość bajtów danych przesyłanych w sqlGetData lub operacji SQLFetch, jeśli określono SQL_C_DEFAULT. W przypadku danych liczbowych rozmiar może być inny niż rozmiar danych przechowywanych w źródle danych. Aby uzyskać więcej informacji, zobacz Rozmiar kolumny, Cyfry dziesiętne, Długość oktetu transferu i Rozmiar wyświetlania, w dodatku D: Typy danych.
DECIMAL_DIGITS (ODBC 2.0)	10	Smallint	Cyfry dziesiętne kolumny procedury w źródle danych. Wartość NULL jest zwracana dla typów danych, w których cyfry dziesiętne nie mają zastosowania. Aby uzyskać więcej informacji na temat cyfr dziesiętnych, zobacz Rozmiar kolumny, Cyfry dziesiętne, Długość oktetu transferu i Rozmiar wyświetlania, w dodatku D: Typy danych.
NUM_PREC_RADIX (ODBC 2.0)	11	Smallint	W przypadku typów danych liczbowych 10 lub 2. Jeśli 10, wartości w COLUMN_SIZE i DECIMAL_DIGITS dają liczbę cyfr dziesiętnych dozwolonych dla kolumny. Na przykład kolumna DECIMAL(12,5) zwróci NUM_PREC_RADIX z 10, COLUMN_SIZE 12 i DECIMAL_DIGITS 5; kolumna FLOAT może zwrócić NUM_PREC_RADIX z 10, COLUMN_SIZE 15 i DECIMAL_DIGITS wartości NULL. Jeśli 2, wartości w COLUMN_SIZE i DECIMAL_DIGITS dają liczbę bitów dozwolonych w kolumnie. Na przykład kolumna FLOAT może zwrócić NUM_PREC_RADIX z 2, COLUMN_SIZE 53 i DECIMAL_DIGITS null. Wartość NULL jest zwracana dla typów danych, w których NUM_PREC_RADIX nie ma zastosowania.
DOPUSZCZANA WARTOŚĆ NULL (ODBC 2.0)	12	Parametr Smallint nie ma wartości NULL	Czy kolumna procedury akceptuje wartość NULL: SQL_NO_NULLS: kolumna procedury nie akceptuje wartości NULL. SQL_NULLABLE: kolumna procedury akceptuje wartości NULL. SQL_NULLABLE_UNKNOWN: Nie wiadomo, czy kolumna procedury akceptuje wartości NULL.
UWAGI (ODBC 2.0)	13	Varchar	Opis kolumny procedury.
COLUMN_DEF (ODBC 3.0)	14	Varchar	Wartość domyślna kolumny. Jeśli wartość NULL została określona jako wartość domyślna, ta kolumna jest słowem NULL, a nie jest ujęta w cudzysłów. Jeśli wartość domyślna nie może być reprezentowana bez obcinania, ta kolumna zawiera metodę TRUNCATED bez ujęć pojedynczych cudzysłowów. Jeśli nie określono wartości domyślnej, ta kolumna ma wartość NULL. Wartość COLUMN_DEF może służyć do generowania nowej definicji kolumny, z wyjątkiem sytuacji, gdy zawiera wartość TRUNCATED.
SQL_DATA_TYPE (ODBC 3.0)	15	Parametr Smallint nie ma wartości NULL	Wartość typu danych SQL wyświetlana w polu SQL_DESC_TYPE deskryptora. Ta kolumna jest taka sama jak kolumna DATA_TYPE, z wyjątkiem typów danych typu data/godzina i interwał. W przypadku typów danych daty/godziny i interwału pole SQL_DATA_TYPE w zestawie wyników zwróci SQL_INTERVAL lub SQL_DATETIME, a pole SQL_DATETIME_SUB zwróci kod podrzędny dla określonego typu danych interwału lub daty/godziny. (Zobacz dodatek D: Typy danych.)
SQL_DATETIME_SUB (ODBC 3.0)	16	Smallint	Kod podtypu dla typów danych typu data/godzina i interwał. W przypadku innych typów danych ta kolumna zwraca wartość NULL.
CHAR_OCTET_LENGTH (ODBC 3.0)	17	Liczba całkowita	Maksymalna długość w bajtach kolumny typu danych lub znaku binarnego. W przypadku wszystkich innych typów danych ta kolumna zwraca wartość NULL.
ORDINAL_POSITION (ODBC 3.0)	18	Liczba całkowita nie ma wartości NULL	W przypadku parametrów wejściowych i wyjściowych pozycja porządkowa parametru w definicji procedury (w kolejności zwiększania kolejności parametrów, począwszy od 1). W przypadku wartości zwracanej (jeśli istnieje) zwracana jest wartość 0. W przypadku kolumn zestawu wyników pozycja porządkowa kolumny w zestawie wyników z pierwszą kolumną w zestawie wyników jest liczbą 1. Jeśli istnieje wiele zestawów wyników, pozycje porządkowe kolumn są zwracane w sposób specyficzny dla sterownika.
IS_NULLABLE (ODBC 3.0)	19	Varchar	"NIE", jeśli kolumna nie zawiera NULLs. "TAK", jeśli kolumna może zawierać NULLs. Ta kolumna zwraca ciąg o zerowej długości, jeśli wartość null jest nieznana. Reguły ISO są przestrzegane w celu określenia wartości null. System DBMS zgodny ze specyfikacją SQL ISO nie może zwrócić pustego ciągu. Wartość zwracana dla tej kolumny różni się od wartości zwracanej dla kolumny NULLABLE. (Zobacz opis kolumny NULLABLE).

Przykład kodu

Zobacz Wywołania procedur.

Powiązane funkcje

Aby uzyskać informacje o	Widzieć
Wiązanie buforu z kolumną w zestawie wyników	funkcji SQLBindCol
Anulowanie przetwarzania instrukcji	funkcji SQLCancel
Pobieranie pojedynczego wiersza lub bloku danych w kierunku tylko do przodu	funkcji SQLFetch
Pobieranie bloku danych lub przewijanie zestawu wyników	funkcji SQLFetchScroll
Zwracanie listy procedur w źródle danych	funkcji SQLProcedures

Zobacz też

dokumentacja interfejsu API ODBC
plików nagłówków ODBC