SQLProcedureColumns, functie
conformance
Versie geïntroduceerd: NALEVING van ODBC 1.0-standaarden: ODBC
Samenvattings-
SQLProcedureColumns retourneert de lijst met invoer- en uitvoerparameters, evenals de kolommen waaruit de resultatenset voor de opgegeven procedures bestaat. Het stuurprogramma retourneert de informatie als resultaatset op de opgegeven instructie.
Syntaxis
SQLRETURN SQLProcedureColumns(
SQLHSTMT StatementHandle,
SQLCHAR * CatalogName,
SQLSMALLINT NameLength1,
SQLCHAR * SchemaName,
SQLSMALLINT NameLength2,
SQLCHAR * ProcName,
SQLSMALLINT NameLength3,
SQLCHAR * ColumnName,
SQLSMALLINT NameLength4);
Argumenten
StatementHandle-
[Invoer] Instructiehandgreep.
CatalogName-
[Invoer] Naam van procedurecatalogus. Als een stuurprogramma catalogi ondersteunt voor sommige procedures, maar niet voor andere, zoals wanneer het stuurprogramma gegevens ophaalt uit verschillende DBMS's, geeft een lege tekenreeks ("") de procedures aan die geen catalogi hebben.
CatalogName kan geen tekenreekszoekpatroon bevatten.
Als het kenmerk SQL_ATTR_METADATA_ID instructie is ingesteld op SQL_TRUE, wordt CatalogName- behandeld als een id en is het niet significant. Als het SQL_FALSE is, is CatalogName een gewoon argument; het wordt letterlijk behandeld en het geval is belangrijk. Zie Argumenten in Catalogusfunctiesvoor meer informatie.
NameLength1-
[Invoer] Lengte in tekens van *CatalogName.
SchemaName-
[Invoer] Tekenreekszoekpatroon voor procedureschemanamen. Als een stuurprogramma schema's ondersteunt voor sommige procedures, maar niet voor andere, zoals wanneer het stuurprogramma gegevens ophaalt uit verschillende DBMS's, geeft een lege tekenreeks ("") de procedures aan die geen schema's hebben.
Als het kenmerk SQL_ATTR_METADATA_ID instructie is ingesteld op SQL_TRUE, wordt SchemaName- beschouwd als een id en is het niet significant. Als het SQL_FALSE is, is SchemaName een argument voor een patroonwaarde; het wordt letterlijk behandeld en het geval is belangrijk.
NameLength2-
[Invoer] Lengte in tekens van *SchemaName.
ProcName-
[Invoer] Tekenreekszoekpatroon voor procedurenamen.
Als het kenmerk SQL_ATTR_METADATA_ID instructie is ingesteld op SQL_TRUE, wordt ProcName- beschouwd als een id en is de case niet significant. Als dit SQL_FALSE is, is ProcName een argument voor patroonwaarden; het wordt letterlijk behandeld en het geval is belangrijk.
NameLength3-
[Invoer] Lengte in tekens van *ProcName.
ColumnName-
[Invoer] Tekenreekszoekpatroon voor kolomnamen.
Als het kenmerk SQL_ATTR_METADATA_ID instructie is ingesteld op SQL_TRUE, wordt ColumnName- beschouwd als een id en is het niet significant. Als dit SQL_FALSE is, is ColumnName een argument voor een patroonwaarde; het wordt letterlijk behandeld en het geval is belangrijk.
NameLength4-
[Invoer] Lengte in tekens van *ColumnName.
Retourneert
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR of SQL_INVALID_HANDLE.
Diagnostiek
Wanneer SQLProcedureColumns SQL_ERROR of SQL_SUCCESS_WITH_INFO retourneert, kan een bijbehorende SQLSTATE-waarde worden verkregen door SQLGetDiagRec- aan te roepen met een HandleType- van SQL_HANDLE_STMT en een Handle van StatementHandle-. De volgende tabel bevat de SQLSTATE-waarden die vaak worden geretourneerd door SQLProcedureColumns en legt elke waarden uit in de context van deze functie; de notatie (DM)' voorafgaat aan de beschrijvingen van SQLSTATEs die worden geretourneerd door Driver Manager. De retourcode die is gekoppeld aan elke SQLSTATE-waarde is SQL_ERROR, tenzij anders vermeld.
| SQLSTATE | Fout | Beschrijving |
|---|---|---|
| 01000 | Algemene waarschuwing | Stuurprogrammaspecifiek informatiebericht. (Functie retourneert SQL_SUCCESS_WITH_INFO.) |
| 08S01 | Communicatiekoppelingsfout | De communicatiekoppeling tussen het stuurprogramma en de gegevensbron waarmee het stuurprogramma is verbonden, is mislukt voordat de verwerking van de functie is voltooid. |
| 24000 | Ongeldige cursorstatus | Er is een cursor geopend op de StatementHandle-en SQLFetch- of SQLFetchScroll- is aangeroepen. Deze fout wordt geretourneerd door Driver Manager als SQLFetch of SQLFetchScroll- niet SQL_NO_DATA heeft geretourneerd en wordt geretourneerd door het stuurprogramma als SQLFetch of SQLFetchScroll SQL_NO_DATA heeft geretourneerd. Er is een cursor geopend op de StatementHandle-, maar SQLFetch of SQLFetchScroll niet is aangeroepen. |
| 40001 | Serialisatiefout | De transactie is teruggedraaid vanwege een resource-impasse met een andere transactie. |
| 40003 | Voltooiing van instructie onbekend | De gekoppelde verbinding is mislukt tijdens de uitvoering van deze functie en de status van de transactie kan niet worden bepaald. |
| HY000 | Algemene fout | Er is een fout opgetreden waarvoor er geen specifieke SQLSTATE is en waarvoor geen implementatiespecifieke SQLSTATE is gedefinieerd. Het foutbericht dat wordt geretourneerd door SQLError- in de *MessageText buffer beschrijft de fout en de oorzaak ervan. |
| HY001 | Fout bij geheugentoewijzing | Het stuurprogramma kan geen geheugen toewijzen dat nodig is om de uitvoering of voltooiing van de functie te ondersteunen. |
| HY008 | Bewerking geannuleerd | Asynchrone verwerking is ingeschakeld voor de StatementHandle-. De functie is aangeroepen en voordat de uitvoering werd voltooid, SQLCancel of SQLCancelHandle werd aangeroepen op de StatementHandle-. Vervolgens werd de functie opnieuw aangeroepen op de StatementHandle-. De functie is aangeroepen en voordat de uitvoering is voltooid, werd SQLCancel of SQLCancelHandle- aangeroepen op de StatementHandle- uit een andere thread in een multithread-toepassing. |
| HY009 | Ongeldig gebruik van null-aanwijzer | Het kenmerk SQL_ATTR_METADATA_ID instructie is ingesteld op SQL_TRUE, het argument CatalogName is een null-aanwijzer en de SQL_CATALOG_NAME InfoType- retourneert dat catalogusnamen worden ondersteund. (DM) Het kenmerk SQL_ATTR_METADATA_ID instructie is ingesteld op SQL_TRUE en het argument SchemaName, ProcNameof ColumnName argument was een null-aanwijzer. |
| HY010 | Fout in functiereeks | (DM) Er is een asynchroon uitgevoerde functie aangeroepen voor de verbindingsgreep die is gekoppeld aan de StatementHandle-. Deze asynchrone functie werd nog steeds uitgevoerd toen de functie SQLProcedureColumns werd aangeroepen. (DM) SQLExecute, SQLExecDirectof SQLMoreResults is aangeroepen voor de StatementHandle- en SQL_PARAM_DATA_AVAILABLE geretourneerd. Deze functie is aangeroepen voordat gegevens zijn opgehaald voor alle gestreamde parameters. (DM) Een asynchroon uitgevoerde functie (niet deze) is aangeroepen voor de StatementHandle- en werd nog steeds uitgevoerd toen deze functie werd aangeroepen. (DM) SQLExecute, SQLExecDirect, SQLBulkOperationsof SQLSetPos is aangeroepen voor de StatementHandle- en SQL_NEED_DATA geretourneerd. Deze functie is aangeroepen voordat gegevens werden verzonden voor alle parameters of kolommen voor uitvoering van gegevens. |
| HY090 | Ongeldige tekenreeks- of bufferlengte | (DM) De waarde van een van de argumenten voor de naamlengte was kleiner dan 0, maar niet gelijk aan SQL_NTS. De waarde van een van de argumenten voor de lengte van de naam heeft de maximumlengtewaarde overschreden voor de bijbehorende catalogus, het schema, de procedure of de kolomnaam. |
| HY117 | De verbinding is onderbroken vanwege een onbekende transactiestatus. Alleen de verbinding verbreken en alleen-lezenfuncties zijn toegestaan. | (DM) Zie SQLEndTran Functionvoor meer informatie over de onderbroken status. |
| HYC00 | Optionele functie niet geïmplementeerd | Er is een procedurecatalogus opgegeven en het stuurprogramma of de gegevensbron biedt geen ondersteuning voor catalogi. Er is een procedureschema opgegeven en het stuurprogramma of de gegevensbron biedt geen ondersteuning voor schema's. Er is een tekenreekszoekpatroon opgegeven voor het procedureschema, de procedurenaam of de kolomnaam en de gegevensbron biedt geen ondersteuning voor zoekpatronen voor een of meer van deze argumenten. De combinatie van de huidige instellingen van de SQL_ATTR_CONCURRENCY- en SQL_ATTR_CURSOR_TYPE instructiekenmerken wordt niet ondersteund door het stuurprogramma of de gegevensbron. Het kenmerk SQL_ATTR_USE_BOOKMARKS instructie is ingesteld op SQL_UB_VARIABLE en het kenmerk SQL_ATTR_CURSOR_TYPE instructie is ingesteld op een cursortype waarvoor het stuurprogramma geen bladwijzers ondersteunt. |
| HYT00 | Time-out verlopen | De time-outperiode is verlopen voordat de gegevensbron de resultatenset heeft geretourneerd. De time-outperiode wordt ingesteld via SQLSetStmtAttr-, SQL_ATTR_QUERY_TIMEOUT. |
| HYT01 | Time-out voor verbinding verlopen | De time-outperiode voor de verbinding is verlopen voordat de gegevensbron op de aanvraag heeft gereageerd. De time-outperiode voor de verbinding wordt ingesteld via SQLSetConnectAttr-, SQL_ATTR_CONNECTION_TIMEOUT. |
| IM001 | Stuurprogramma biedt geen ondersteuning voor deze functie | (DM) Het stuurprogramma dat is gekoppeld aan de StatementHandle- biedt geen ondersteuning voor de functie. |
| IM017 | Polling is uitgeschakeld in de asynchrone meldingsmodus | Wanneer het meldingsmodel wordt gebruikt, wordt polling uitgeschakeld. |
| IM018 | SQLCompleteAsync- is niet aangeroepen om de vorige asynchrone bewerking op deze ingang te voltooien. | Als de vorige functieaanroep op de ingang SQL_STILL_EXECUTING retourneert en als de meldingsmodus is ingeschakeld, moet SQLCompleteAsync- worden aangeroepen op de ingang om de bewerking na verwerking uit te voeren en de bewerking te voltooien. |
Opmerkingen
Deze functie wordt doorgaans gebruikt voordat de instructie wordt uitgevoerd om informatie op te halen over procedureparameters en de kolommen waaruit de resultatenset bestaat of sets die door de procedure worden geretourneerd, indien van toepassing. Zie Proceduresvoor meer informatie.
Notitie
SQLProcedureColumns retourneert mogelijk niet alle kolommen die door een procedure worden gebruikt. Een stuurprogramma kan bijvoorbeeld alleen informatie retourneren over de parameters die door een procedure worden gebruikt en niet de kolommen in een resultatenset die wordt gegenereerd.
De SchemaName, ProcNameen ColumnName-argumenten accepteren zoekpatronen. Zie Patroonwaardeargumentenvoor meer informatie over geldige zoekpatronen.
Notitie
Zie Catalogusfunctiesvoor meer informatie over het algemene gebruik, argumenten en geretourneerde gegevens van ODBC-catalogusfuncties.
SQLProcedureColumns retourneert de resultaten als een standaardresultatenset, gesorteerd op PROCEDURE_CAT, PROCEDURE_SCHEM, PROCEDURE_NAME en COLUMN_TYPE. Kolomnamen worden geretourneerd voor elke procedure in de volgende volgorde: de naam van de retourwaarde, de namen van elke parameter in de aanroepprocedure (in aanroepvolgorde) en vervolgens de namen van elke kolom in de resultatenset die wordt geretourneerd door de procedure (in kolomvolgorde).
Toepassingen moeten stuurprogrammaspecifieke kolommen binden ten opzichte van het einde van de resultatenset. Zie gegevens die worden geretourneerd door Catalogusfunctiesvoor meer informatie.
Als u de werkelijke lengte van de PROCEDURE_CAT, PROCEDURE_SCHEM, PROCEDURE_NAME en COLUMN_NAME kolommen wilt bepalen, kan een toepassing SQLGetInfo- aanroepen met de opties SQL_MAX_CATALOG_NAME_LEN, SQL_MAX_SCHEMA_NAME_LEN, SQL_MAX_PROCEDURE_NAME_LEN en SQL_MAX_COLUMN_NAME_LEN.
De naam van de volgende kolommen is gewijzigd voor ODBC 3.x. De naam van de kolom heeft geen invloed op compatibiliteit met eerdere versies omdat toepassingen binden op kolomnummer.
| ODBC 2.0-kolom | ODBC 3.x kolom |
|---|---|
| PROCEDURE_QUALIFIER | PROCEDURE_CAT |
| PROCEDURE _OWNER | PROCEDURE_SCHEM |
| PRECISIE | COLUMN_SIZE |
| LENGTE | BUFFER_LENGTH |
| SCHUB | DECIMAL_DIGITS |
| RADIX | NUM_PREC_RADIX |
De volgende kolommen zijn toegevoegd aan de resultatenset die wordt geretourneerd door SQLProcedureColumns voor ODBC 3.x:
COLUMN_DEF
DATETIME_CODE
CHAR_OCTET_LENGTH
ORDINAL_POSITION
IS_NULLABLE
De volgende tabel bevat de kolommen in de resultatenset. Extra kolommen buiten kolom 19 (IS_NULLABLE) kunnen worden gedefinieerd door het stuurprogramma. Een toepassing moet toegang krijgen tot stuurprogrammaspecifieke kolommen door af te tellen vanaf het einde van de resultatenset in plaats van een expliciete rangschikkingspositie op te geven. Zie gegevens die worden geretourneerd door Catalogusfunctiesvoor meer informatie.
| Kolomnaam | Kolomnummer | Gegevenstype | Opmerkingen |
|---|---|---|---|
| PROCEDURE_CAT (ODBC 2.0) | 1 | Varchar | Naam van procedurecatalogus; NULL indien niet van toepassing op de gegevensbron. Als een stuurprogramma catalogi ondersteunt voor sommige procedures, maar niet voor andere, zoals wanneer het stuurprogramma gegevens ophaalt uit verschillende DBMS's, retourneert het een lege tekenreeks ("") voor de procedures die geen catalogi hebben. |
| PROCEDURE_SCHEM (ODBC 2.0) | 2 | Varchar | Schemanaam van procedure; NULL indien niet van toepassing op de gegevensbron. Als een stuurprogramma schema's ondersteunt voor sommige procedures, maar niet voor andere, zoals wanneer het stuurprogramma gegevens ophaalt uit verschillende DBMS's, retourneert het een lege tekenreeks ("") voor die procedures die geen schema's hebben. |
| PROCEDURE_NAME (ODBC 2.0) | 3 | Varchar niet NULL | Procedurenaam. Er wordt een lege tekenreeks geretourneerd voor een procedure die geen naam heeft. |
| COLUMN_NAME (ODBC 2.0) | 4 | Varchar niet NULL | Naam van de procedurekolom. Het stuurprogramma retourneert een lege tekenreeks voor een procedurekolom die geen naam heeft. |
| COLUMN_TYPE (ODBC 2.0) | 5 | Smallint niet NULL | Definieert de procedurekolom als een parameter of een kolom met resultatensets: SQL_PARAM_TYPE_UNKNOWN: De procedurekolom is een parameter waarvan het type onbekend is. (ODBC 1.0) SQL_PARAM_INPUT: De procedurekolom is een invoerparameter. (ODBC 1.0) SQL_PARAM_INPUT_OUTPUT: De procedurekolom is een invoer-/uitvoerparameter. (ODBC 1.0) SQL_PARAM_OUTPUT: De procedurekolom is een uitvoerparameter. (ODBC 2.0) SQL_RETURN_VALUE: De procedurekolom is de retourwaarde van de procedure. (ODBC 2.0) SQL_RESULT_COL: De procedurekolom is een kolom met resultatensets. (ODBC 1.0) |
| DATA_TYPE (ODBC 2.0) | 6 | Smallint niet NULL | SQL-gegevenstype. Dit kan een ODBC SQL-gegevenstype of een stuurprogrammaspecifiek SQL-gegevenstype zijn. Voor gegevenstypen voor datum/tijd en interval retourneert deze kolom de beknopte gegevenstypen (bijvoorbeeld SQL_TYPE_TIME of SQL_INTERVAL_YEAR_TO_MONTH). Zie voor een lijst met geldige ODBC SQL-gegevenstypen SQL-gegevenstypen in bijlage D: gegevenstypen. Zie de documentatie van het stuurprogramma voor informatie over stuurprogrammaspecifieke SQL-gegevenstypen. |
| TYPE_NAME (ODBC 2.0) | 7 | Varchar niet NULL | Naam van gegevensbronafhankelijk gegevenstype; Bijvoorbeeld "CHAR", "VARCHAR", "MONEY", "LONG VARBINARY" of "CHAR ( ) FOR BIT DATA". |
| COLUMN_SIZE (ODBC 2.0) | 8 | Geheel getal | De kolomgrootte van de procedurekolom op de gegevensbron. NULL wordt geretourneerd voor gegevenstypen waarbij de kolomgrootte niet van toepassing is. Zie voor meer informatie over precisie kolomgrootte, decimale cijfers, octetlengte en weergavegrootte in bijlage D: gegevenstypen. |
| BUFFER_LENGTH (ODBC 2.0) | 9 | Geheel getal | De lengte in bytes aan gegevens die worden overgedragen op een SQLGetData- of SQLFetch- bewerking als SQL_C_DEFAULT is opgegeven. Voor numerieke gegevens kan deze grootte afwijken van de grootte van de gegevens die zijn opgeslagen op de gegevensbron. Zie voor meer informatie kolomgrootte, decimale cijfers, octetlengte en weergavegrootte, in bijlage D: gegevenstypen. |
| DECIMAL_DIGITS (ODBC 2.0) | 10 | Smallint | De decimale cijfers van de procedurekolom op de gegevensbron. NULL wordt geretourneerd voor gegevenstypen waarbij decimale cijfers niet van toepassing zijn. Zie Kolomgrootte, Decimale cijfers, Octetlengte overdragen en Weergavegroottein bijlage D voor meer informatie over decimale cijfers. |
| NUM_PREC_RADIX (ODBC 2.0) | 11 | Smallint | Voor numerieke gegevenstypen, 10 of 2. Als 10, geven de waarden in COLUMN_SIZE en DECIMAL_DIGITS het aantal decimale cijfers dat is toegestaan voor de kolom. Een kolom DECIMAL(12;5) retourneert bijvoorbeeld een NUM_PREC_RADIX van 10, een COLUMN_SIZE van 12 en een DECIMAL_DIGITS van 5; een FLOAT-kolom kan een NUM_PREC_RADIX van 10, een COLUMN_SIZE van 15 en een DECIMAL_DIGITS van NULL retourneren. Als 2, geven de waarden in COLUMN_SIZE en DECIMAL_DIGITS het aantal bits dat is toegestaan in de kolom. Een FLOAT-kolom kan bijvoorbeeld een NUM_PREC_RADIX van 2, een COLUMN_SIZE van 53 en een DECIMAL_DIGITS null retourneren. NULL wordt geretourneerd voor gegevenstypen waarbij NUM_PREC_RADIX niet van toepassing is. |
| NULLABLE (ODBC 2.0) | 12 | Smallint niet NULL | Of de procedurekolom een NULL-waarde accepteert: SQL_NO_NULLS: De procedurekolom accepteert geen NULL-waarden. SQL_NULLABLE: De procedurekolom accepteert NULL-waarden. SQL_NULLABLE_UNKNOWN: Het is niet bekend of de procedurekolom NULL-waarden accepteert. |
| OPMERKINGEN (ODBC 2.0) | 13 | Varchar | Een beschrijving van de procedurekolom. |
| COLUMN_DEF (ODBC 3.0) | 14 | Varchar | De standaardwaarde van de kolom. Als NULL is opgegeven als de standaardwaarde, is deze kolom het woord NULL, niet tussen aanhalingstekens geplaatst. Als de standaardwaarde niet kan worden weergegeven zonder afkapping, bevat deze kolom AFGEKAPT, zonder enkele aanhalingstekens. Als er geen standaardwaarde is opgegeven, is deze kolom NULL. De waarde van COLUMN_DEF kan worden gebruikt bij het genereren van een nieuwe kolomdefinitie, behalve wanneer deze de waarde AFGEKAPT bevat. |
| SQL_DATA_TYPE (ODBC 3.0) | 15 | Smallint niet NULL | De waarde van het SQL-gegevenstype zoals deze wordt weergegeven in het SQL_DESC_TYPE veld van de descriptor. Deze kolom is hetzelfde als de DATA_TYPE kolom, met uitzondering van gegevenstypen voor datum/tijd en interval. Voor gegevenstypen voor datum/tijd en interval retourneert het SQL_DATA_TYPE veld in de resultatenset SQL_INTERVAL of SQL_DATETIME en retourneert het SQL_DATETIME_SUB veld de subcode voor het specifieke interval of het gegevenstype datum/tijd. (Zie bijlage D: gegevenstypen.) |
| SQL_DATETIME_SUB (ODBC 3.0) | 16 | Smallint | De subtypecode voor gegevenstypen datum/tijd en interval. Voor andere gegevenstypen retourneert deze kolom een NULL. |
| CHAR_OCTET_LENGTH (ODBC 3.0) | 17 | Geheel getal | De maximale lengte in bytes van een kolom van een teken of binair gegevenstype. Voor alle andere gegevenstypen retourneert deze kolom een NULL. |
| ORDINAL_POSITION (ODBC 3.0) | 18 | Geheel getal niet NULL | Voor invoer- en uitvoerparameters, de rangorde van de parameter in de proceduredefinitie (in toenemende parametervolgorde, beginnend bij 1). Voor een retourwaarde (indien aanwezig) wordt 0 geretourneerd. Voor kolommen met resultatensets is de rangtelpositie van de kolom in de resultatenset, waarbij de eerste kolom in de resultatenset nummer 1 is. Als er meerdere resultatensets zijn, worden kolom ordinale posities geretourneerd op een stuurprogrammaspecifieke manier. |
| IS_NULLABLE (ODBC 3.0) | 19 | Varchar | "NEE" als de kolom geen NULL's bevat. Ja als de kolom NULL's kan bevatten. Deze kolom retourneert een tekenreeks met lengte nul als null-waarde onbekend is. ISO-regels worden gevolgd om de null-waarde te bepalen. Een MET ISO SQL compatibele DBMS kan geen lege tekenreeks retourneren. De waarde die voor deze kolom wordt geretourneerd, verschilt van de waarde die wordt geretourneerd voor de kolom NULLABLE. (Zie de beschrijving van de kolom NULLABLE.) |
Codevoorbeeld
Zie procedureoproepen.
Verwante functies
| Voor informatie over | Zien |
|---|---|
| Een buffer koppelen aan een kolom in een resultatenset | SQLBindCol-functie |
| Verwerking van instructie annuleren | SQLCancel Function- |
| Eén rij of een blok gegevens ophalen in een richting met alleen-doorsturen | SQLFetch-functie |
| Een gegevensblok ophalen of door een resultatenset schuiven | SQLFetchScroll-functie |
| Een lijst met procedures in een gegevensbron retourneren | SQLProcedures-functie |