SQLBindParameter functie

Conformiteit
Versie geïntroduceerd: ODBC 2.0 Standaardnaleving: ODBC

Samenvatting
SQLBindParameter bindt een buffer aan een parametermarker in een SQL-instructie. SQLBindParameter ondersteunt binding aan een Unicode C-datatype, zelfs als de onderliggende driver geen Unicode-gegevens ondersteunt.

Syntax

  
SQLRETURN SQLBindParameter(  
      SQLHSTMT        StatementHandle,  
      SQLUSMALLINT    ParameterNumber,  
      SQLSMALLINT     InputOutputType,  
      SQLSMALLINT     ValueType,  
      SQLSMALLINT     ParameterType,  
      SQLULEN         ColumnSize,  
      SQLSMALLINT     DecimalDigits,  
      SQLPOINTER      ParameterValuePtr,  
      SQLLEN          BufferLength,  
      SQLLEN *        StrLen_or_IndPtr);  

Arguments

StatementHandle
[Invoer] Instructiehandgreep.

ParameterNumber
[Invoer] Parameternummer, opeenvolgend geordend in toenemende parametervolgorde, beginnend bij 1.

InputOutputType
[Invoer] Het type parameter. Voor meer informatie, zie "InputOutputType Argument" in "Comments."

WaardeType
[Invoer] Het C-datatype van de parameter. Voor meer informatie, zie "ValueType Argument" in "Reacties."

ParameterType
[Invoer] Het SQL-datatype van de parameter. Voor meer informatie, zie "ParameterType Argument" in "Comments."

KolomgrootteGrootte
[Invoer] De grootte van de kolom of uitdrukking van de bijbehorende parametermarker. Voor meer informatie, zie "ColumnSize Argument" in "Reacties."

Als je applicatie op een 64-bit Windows-besturingssysteem draait, zie dan ODBC 64-Bits Informatie.

DecimalDigits
[Invoer] De decimale cijfers van de kolom of uitdrukking van de bijbehorende parametermarker. Voor meer informatie over kolomgrootte, zie Kolomgrootte, Decimale cijfers, Overdracht van de octelengte en Weergavegrootte.

ParameterValuePtr
[Uitgestelde invoer] Een pointer naar een buffer voor de parameters data. Voor meer informatie, zie "ParameterValuePtr Argument" in "Comments."

BufferLength
[Invoer/Uitvoer] Lengte van de ParameterValuePtr-buffer in bytes. Voor meer informatie, zie "BufferLength Argument" in "Reacties."

Zie ODBC 64-bit Informatie als je applicatie op een 64-bit besturingssysteem draait.

StrLen_or_IndPtr
[Uitgestelde invoer] Een pointer naar een buffer voor de lengte van de parameter. Voor meer informatie, zie "StrLen_or_IndPtr Argument" in "Commentaren."

Returns

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR of SQL_INVALID_HANDLE.

Diagnostics

Wanneer SQLBindParameter SQL_ERROR of SQL_SUCCESS_WITH_INFO teruggeeft, 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 geeft een overzicht van de SQLSTATE-waarden die typisch door SQLBindParameter worden geretourneerd en legt elk uit in de context van deze functie; de notatie "(DM)" gaat vooraf aan de beschrijvingen van SQLSTATES die door de Driver Manager worden teruggegeven. De retourcode die is gekoppeld aan elke SQLSTATE-waarde is SQL_ERROR, tenzij anders vermeld.

Comments

Een applicatie roept SQLBindParameter aan om elke parametermarker in een SQL-instructie te binden. Bindings blijven van kracht totdat de applicatie opnieuw SQLBindParameter aanroept, SQLFreeStmt aanroept met de SQL_RESET_PARAMS-optie, of SQLSetDescField aanroept om het SQL_DESC_COUNT headerveld van de APD op 0 te zetten.

Zie Instructieparameters voor meer informatie over parameters. Voor meer informatie over parameterdatatypes en parametermarkers, zie Parameter Data Types en Parameter Markers in Appendix C: SQL Grammar.

ParameterNumber-argument

Als ParameterNumber in de aanroep van SQLBindParameter groter is dan de waarde van SQL_DESC_COUNT, wordt SQLSetDescField aangeroepen om de waarde van SQL_DESC_COUNT te verhogen naar ParameterNumber.

InputOutputType Argument

Het InputOutputType-argument specificeert het type van de parameter. Dit argument bepaalt het SQL_DESC_PARAMETER_TYPE veld van de IPD. Alle parameters in SQL-statements die geen procedures aanroepen, zoals INSERT statements, zijn invoerparameters. Parameters in procedure-aanroepen kunnen invoer-, invoer-/uitvoer- of uitvoerparameters zijn. (Een applicatie roept SQLProcedureColumns aan om het type van een parameter in een procedure-aanroep te bepalen; parameters waarvan het type niet bepaald kan worden, worden verondersteld invoerparameters te zijn.)

Het InputOutputType-argument is een van de volgende waarden:

• SQL_PARAM_INPUT. De parameter markeert een parameter in een SQL-instructie die geen procedure aanroept, zoals een INSERT statement, of het markeert een invoerparameter in een procedure. Bijvoorbeeld, de parameters in INSERT INTO Employee VALUES (?, ?, ?) zijn invoerparameters, terwijl de parameters in {call AddEmp(?, ?, ?)} wel inputparameters kunnen zijn, maar niet per se.

  Wanneer de instructie wordt uitgevoerd, stuurt de driver gegevens voor de parameter naar de databron; de *ParameterValuePtr-buffer moet een geldige invoerwaarde bevatten, of de *StrLen_or_IndPtr-buffer moet SQL_NULL_DATA, SQL_DATA_AT_EXEC of het resultaat van de SQL_LEN_DATA_AT_EXEC macro bevatten.

  Als een applicatie het type parameter in een procedure-aanroep niet kan bepalen, zet het InputOutputType op SQL_PARAM_INPUT; Als de databron een waarde voor de parameter teruggeeft, verwerpt de driver deze ook.

• SQL_PARAM_INPUT_OUTPUT. De parameter markeert een invoer-/uitvoerparameter in een procedure. Bijvoorbeeld, de parameter in {call GetEmpDept(?)} is een input/output-parameter die de naam van een werknemer accepteert en de naam van de afdeling van die medewerker teruggeeft.

  Wanneer de instructie wordt uitgevoerd, stuurt de driver gegevens voor de parameter naar de databron; de *ParameterValuePtr-buffer moet een geldige invoerwaarde bevatten, of de *StrLen_or_IndPtr-buffer moet SQL_NULL_DATA, SQL_DATA_AT_EXEC of het resultaat van de SQL_LEN_DATA_AT_EXEC macro bevatten. Nadat de instructie is uitgevoerd, retourneert de driver gegevens voor de parameter aan de applicatie; Als de databron geen waarde voor een input/outputparameter teruggeeft, stelt de driver de *StrLen_or_IndPtr buffer in op SQL_NULL_DATA.

  Opmerking

  Wanneer een ODBC 1.0-applicatie SQLSetParam aanroept in een ODBC 2.0-driver, zet de Driver Manager dit om in een aanroep van SQLBindParameter waarbij het InputOutputType-argument wordt ingesteld op SQL_PARAM_INPUT_OUTPUT.

• SQL_PARAM_OUTPUT. De parameter markeert de retourwaarde van een procedure of een outputparameter in een procedure; in beide gevallen worden deze outputparameters genoemd. Bijvoorbeeld, de parameter in {?=call GetNextEmpID} is een uitvoerparameter die de volgende werknemer-ID teruggeeft.

  Nadat de instructie is uitgevoerd, geeft de driver gegevens voor de parameter terug aan de applicatie, tenzij de argumenten ParameterValuePtr en StrLen_or_IndPtr beide nullpointers zijn, in welk geval de driver de uitvoerwaarde weggooit. Als de gegevensbron geen waarde voor een outputparameter teruggeeft, stelt de driver de *StrLen_or_IndPtr buffer in op SQL_NULL_DATA.

• SQL_PARAM_INPUT_OUTPUT_STREAM. Geeft aan dat een input/output-parameter gestreamd moet worden. SQLGetData kan parameterwaarden in delen lezen. BufferLength wordt genegeerd omdat de bufferlengte wordt bepaald bij de aanroep van SQLGetData. De waarde van de StrLen_or_IndPtr buffer moet SQL_NULL_DATA, SQL_DEFAULT_PARAM, SQL_DATA_AT_EXEC of het resultaat van de SQL_LEN_DATA_AT_EXEC macro bevatten. Een parameter moet bij invoer worden gebonden als een data-at-uitvoeringsparameter (DAE) als deze bij uitvoer gestreamd zal worden. ParameterValuePtr kan elke niet-nul pointerwaarde zijn die door SQLParamData wordt teruggegeven als het door de gebruiker gedefinieerde token waarvan de waarde werd doorgegeven met ParameterValuePtr voor zowel invoer als uitvoer. Zie Uitvoerparameters ophalen met BEHULP van SQLGetData voor meer informatie.

• SQL_PARAM_OUTPUT_STREAM. Hetzelfde als SQL_PARAM_INPUT_OUTPUT_STREAM, voor een outputparameter. * StrLen_or_IndPtr wordt genegeerd bij invoer.

De volgende tabel geeft verschillende combinaties van InputOutputType en *StrLen_or_IndPtr:

ValueType Argument

Het ValueType-argument specificeert het C-datatype van de parameter. Dit argument bepaalt de SQL_DESC_TYPE, SQL_DESC_CONCISE_TYPE en SQL_DESC_DATETIME_INTERVAL_CODE velden van de APD. Dit moet een van de waarden zijn in de sectie C Gegevenstypes van Bijlage D: Gegevenstypen.

Als het ValueType-argument een van de intervaldatatypes is, wordt het SQL_DESC_TYPE veld van het ParameterNumber-record van de APD ingesteld op SQL_INTERVAL, het SQL_DESC_CONCISE_TYPE-veld van de APD op het beknopte intervaldatatype, en het SQL_DESC_DATETIME_INTERVAL_CODE-veld van het ParameterNumber-record op een subcode voor het specifieke intervaldatatype. ( Zie Bijlage D: Gegevenstypes.) De standaardinterval-vooraanstaande precisie (2) en de standaardinterval-secondenprecisie (6), zoals ingesteld in respectievelijk de SQL_DESC_DATETIME_INTERVAL_PRECISION- en SQL_DESC_PRECISION-velden van de APD, worden voor de gegevens gebruikt. Als een van beide standaardprecisie niet geschikt is, moet de applicatie het descriptorveld expliciet instellen door een aanroep naar SQLSetDescField of SQLSetDescRec.

Als het ValueType-argument een van de datetime-datatypes is, wordt het SQL_DESC_TYPE-veld van het ParameterNumber-record van de APD ingesteld op SQL_DATETIME, het SQL_DESC_CONCISE_TYPE-veld van het ParameterNumber-record van de APD op het beknopte date-time datatype C, en het SQL_DESC_DATETIME_INTERVAL_CODE-veld van het ParameterNumber-record is ingesteld op een subcode voor het specifieke datetime-datatype. ( Zie Bijlage D: Gegevenstypes.)

Als het ValueType-argument een SQL_C_NUMERIC datatype is, worden de standaardprecisie (die door de driver is gedefinieerd) en de standaardschaal (0), zoals ingesteld in de SQL_DESC_PRECISION- en SQL_DESC_SCALE velden van de APD, gebruikt voor de data. Als de standaardprecisie of schaal niet passend is, moet de applicatie het descriptorveld expliciet instellen door een aanroep naar SQLSetDescField of SQLSetDescRec.

SQL_C_DEFAULT specificeert dat de parameterwaarde moet worden overgedragen van het standaard C-datatype voor het SQL-datatype dat met ParameterType is gespecificeerd.

Je kunt ook een uitgebreid C-datatype specificeren. Zie C-gegevenstypen in ODBC voor meer informatie.

Voor meer informatie, zie Standaard C Data Types, Gegevens omzetten van C naar SQL Data Types, en Gegevens omzetten van SQL naar C Data Types in Appendix D: Data Types.

ParameterType Argument

Dit moet een van de waarden zijn die staan vermeld in de sectie SQL Data Types van Appendix D: Data Types, of het moet een driver-specifieke waarde zijn. Dit argument bepaalt de SQL_DESC_TYPE, SQL_DESC_CONCISE_TYPE en SQL_DESC_DATETIME_INTERVAL_CODE velden van de IPD.

Als het ParameterType-argument een van de datetime-identificaties is, wordt het SQL_DESC_TYPE-veld van de IPD ingesteld op SQL_DATETIME, het SQL_DESC_CONCISE_TYPE-veld van de IPD op het beknopte datetime-SQL-datatype, en het SQL_DESC_DATETIME_INTERVAL_CODE-veld op de juiste datetime-subcodewaarde.

Als ParameterType een van de intervalidentificaties is, wordt het SQL_DESC_TYPE veld van de IPD ingesteld op SQL_INTERVAL, het SQL_DESC_CONCISE_TYPE veld van de IPD op het beknopte SQL-intervaldatatype, en het SQL_DESC_DATETIME_INTERVAL_CODE veld van de IPD op de juiste intervalsubcode. Het SQL_DESC_DATETIME_INTERVAL_PRECISION veld van de IPD is ingesteld op de intervalleidende precisie, en het SQL_DESC_PRECISION veld is ingesteld op de intervalsecondenprecisie, indien van toepassing. Als de standaardwaarde van SQL_DESC_DATETIME_INTERVAL_PRECISION of SQL_DESC_PRECISION niet geschikt is, moet de applicatie deze expliciet instellen door SQLSetDescField aan te roepen. Voor meer informatie over een van deze velden, zie SQLSetDescField.

Als het ValueType-argument een SQL_NUMERIC datatype is, worden de standaardprecisie (die door de driver is gedefinieerd) en de standaardschaal (0), zoals ingesteld in de SQL_DESC_PRECISION- en SQL_DESC_SCALE velden van de IPD, gebruikt voor de data. Als de standaardprecisie of schaal niet passend is, moet de applicatie het descriptorveld expliciet instellen door een aanroep naar SQLSetDescField of SQLSetDescRec.

Voor informatie over hoe data wordt omgezet, zie Gegevens omzetten van C naar SQL Data Types en Data Converteren van SQL naar C Data Types in Appendix D: Data Types.

ColumnSize-argument

Het ColumnSize-argument specificeert de grootte van de kolom of expressie die overeenkomt met de parametermarker, de lengte van die data, of beide. Dit argument stelt verschillende velden van de IPD in, afhankelijk van het SQL-datatype (het ParameterType-argument ). De volgende regels zijn van toepassing van toepassing:

• Als ParameterType SQL_CHAR, SQL_VARCHAR, SQL_LONGVARCHAR, SQL_BINARY, SQL_VARBINARY, SQL_LONGVARBINARY of een van de beknopte SQL-datum- of intervaldatatypes is, wordt het SQL_DESC_LENGTH veld van de IPD ingesteld op de waarde ColumnSize. (Voor meer informatie, zie de sectie Kolomgrootte, Decimale cijfers, Overdracht van Octetlengte en Beeldgrootte in Bijlage D: Data Types.)

• Als ParameterType SQL_DECIMAL, SQL_NUMERIC, SQL_FLOAT, SQL_REAL of SQL_DOUBLE is, wordt het SQL_DESC_PRECISION veld van de IPD ingesteld op de waarde ColumnSize.

• Voor andere datatypen wordt het ColumnSize-argument genegeerd.

Voor meer informatie, zie "Passing Parameter Values" en SQL_DATA_AT_EXEC in "StrLen_or_IndPtr Argument."

DecimalDigits-argument

Als ParameterType SQL_TYPE_TIME, SQL_TYPE_TIMESTAMP, SQL_INTERVAL_SECOND, SQL_INTERVAL_DAY_TO_SECOND, SQL_INTERVAL_HOUR_TO_SECOND of SQL_INTERVAL_MINUTE_TO_SECOND is, wordt het SQL_DESC_PRECISION veld van de IPD ingesteld op DecimalDigits. Als ParameterType SQL_NUMERIC of SQL_DECIMAL is, wordt het SQL_DESC_SCALE veld van de IPD ingesteld op Decimalcijfers. Voor alle andere datatypen wordt het DecimalDigits-argument genegeerd.

ParameterValuePtr-argument

Het ParameterValuePtr-argument wijst naar een buffer die, wanneer SQLExecute of SQLExecDirect wordt aangeroepen, de daadwerkelijke gegevens voor de parameter bevat. De gegevens moeten in de vorm zijn die door het ValueType-argument is gespecificeerd. Dit argument bepaalt het SQL_DESC_DATA_PTR veld van de APD. Een applicatie kan het ParameterValuePtr-argument instellen op een nullpointer, zolang *StrLen_or_IndPtr SQL_NULL_DATA of SQL_DATA_AT_EXEC is. (Dit geldt alleen voor invoer- of invoer-/uitvoerparameters.)

Als *StrLen_or_IndPtr het resultaat is van de macro of SQL_DATA_AT_EXEC SQL_LEN_DATA_AT_EXEC(length), dan is ParameterValuePtr een door de applicatie gedefinieerde pointerwaarde die aan de parameter is gekoppeld. Het wordt via SQLParamData teruggestuurd naar de applicatie. ParameterValuePtr kan bijvoorbeeld een niet-nul token zijn, zoals een parameternummer, een pointer naar data, of een pointer naar een structuur die de applicatie gebruikte om invoerparameters te binden. Let echter op dat als de parameter een input/ outputparameter is, ParameterValuePtr een pointer moet zijn naar een buffer waar de outputwaarde wordt opgeslagen. Als de waarde in het SQL_ATTR_PARAMSET_SIZE-statementattribuut groter is dan 1, kan de applicatie de waarde gebruiken waarnaar wordt verwezen door het SQL_ATTR_PARAMS_PROCESSED_PTR-statementattribuut samen met het ParameterValuePtr-argument . Bijvoorbeeld, ParameterValuePtr kan wijzen op een array van waarden en de applicatie kan de waarde gebruiken die door SQL_ATTR_PARAMS_PROCESSED_PTR wordt aangeduid om de juiste waarde uit de array te halen. Voor meer informatie, zie "Parameters doorgeven" later in deze sectie.

Als het InputOutputType-argument SQL_PARAM_INPUT_OUTPUT of SQL_PARAM_OUTPUT is, wijst ParameterValuePtr naar een buffer waarin de driver de uitvoerwaarde teruggeeft. Als de procedure één of meer resultaatsets teruggeeft, is de *ParameterValuePtr-buffer niet gegarandeerd ingesteld totdat alle resultaatsets/rijtellingen zijn verwerkt. Als de buffer pas is ingesteld nadat de verwerking is voltooid, zijn de outputparameters en retourwaarden niet beschikbaar totdat SQLMoreResults SQL_NO_DATA teruggeeft. Het aanroepen van SQLCloseCursor of SQLFreeStmt met een optie van SQL_CLOSE zorgt ervoor dat deze waarden worden verwijderd.

Als de waarde in het SQL_ATTR_PARAMSET_SIZE-statementattribuut groter is dan 1, wijst ParameterValuePtr naar een array. Een enkele SQL-instructie verwerkt de volledige array van invoerwaarden voor een invoer of input/outputparameter en geeft een array van outputwaarden terug voor een input/output of outputparameter.

BufferLength-argument

Voor karakter- en binaire C-gegevens specificeert het BufferLength-argument de lengte van de *ParameterValuePtr-buffer (als het een enkel element is) of de lengte van een element in de *ParameterValuePtr-array (als de waarde in het SQL_ATTR_PARAMSET_SIZE-statementattribuut groter is dan 1). Dit argument bepaalt het SQL_DESC_OCTET_LENGTH recordveld van de APD. Als de applicatie meerdere waarden specificeert, wordt BufferLength gebruikt om de locatie van waarden in de *ParameterValuePtr-array te bepalen, zowel bij invoer als bij uitvoer. Voor input/output- en outputparameters wordt het gebruikt om te bepalen of karakter- en binaire C-gegevens op output moeten worden afgekort:

• Voor karakter C-gegevens, als het aantal bytes dat teruggegeven kan worden groter is dan of gelijk is aan BufferLength, wordt de data in *ParameterValuePtr afgekapt tot BufferLength minus de lengte van een null-beëindigingsteken en wordt door de driver null-termined.

• Voor binaire C-gegevens, als het aantal bytes dat teruggegeven kan worden groter is dan BufferLength, wordt de data in *ParameterValuePtr afgekapt tot BufferLength-bytes .

Voor alle andere typen C-data wordt het BufferLength-argument genegeerd. De lengte van de *ParameterValuePtr-buffer (als het een enkel element is) of de lengte van een element in de *ParameterValuePtr-array (als de applicatie SQLSetStmtAttr aanroept met een Attribuut-argument van SQL_ATTR_PARAMSET_SIZE om meerdere waarden voor elke parameter te specificeren) wordt verondersteld de lengte van het C-datatype te zijn.

Voor gestreamde uitvoer of gestreamde input/outputparameters wordt het BufferLength-argument genegeerd omdat de bufferlengte is gespecificeerd in SQLGetData.

StrLen_or_IndPtr Argument

Het StrLen_or_IndPtr-argument wijst naar een buffer die, wanneer SQLExecute of SQLExecDirect wordt aangeroepen, een van de volgende bevat. (Dit argument stelt de velden SQL_DESC_OCTET_LENGTH_PTR en SQL_DESC_INDICATOR_PTR records in van de applicatieparameterpointers.)

• De lengte van de parameterwaarde opgeslagen in *ParameterValuePtr. Dit wordt genegeerd, behalve bij karakter- of binaire C-gegevens.

• SQL_NTS. De parameterwaarde is een null-terminated string.

• SQL_NULL_DATA. De parameterwaarde is NULL.

• SQL_DEFAULT_PARAM. Een procedure is het gebruik van de standaardwaarde van een parameter, in plaats van een waarde die uit de applicatie is opgehaald. Deze waarde is alleen geldig in een procedure die in ODBC-canonieke syntaxis wordt genoemd, en dan alleen als het InputOutputType-argument SQL_PARAM_INPUT, SQL_PARAM_INPUT_OUTPUT of SQL_PARAM_INPUT_OUTPUT_STREAM is. Wanneer *StrLen_or_IndPtr SQL_DEFAULT_PARAM is, worden de argumenten ValueType, ParameterType, ColumnSize, DecimalDigits, BufferLength en ParameterValuePtr genegeerd voor inputparameters en worden ze alleen gebruikt om de outputparameterwaarde voor input/outputparameters te definiëren.

• Het resultaat van de macro SQL_LEN_DATA_AT_EXEC(lengte). De gegevens voor de parameter worden verzonden met SQLPutData. Als het ParameterType-argument SQL_LONGVARBINARY, SQL_LONGVARCHAR of een lang, databron-specifiek datatype is, en de driver geeft "Y" terug voor het SQL_NEED_LONG_DATA_LEN informatietype in SQLGetInfo, dan is lengte het aantal bytes aan data dat voor de parameter moet worden verzonden; anders moet lengte een niet-negatieve waarde zijn en wordt deze genegeerd. Voor meer informatie, zie "Parameters doorgeven," later in deze sectie.

  Om bijvoorbeeld te specificeren dat 10.000 bytes aan data met SQLPutData in één of meer aanroepen worden verzonden, zet een applicatie voor een SQL_LONGVARCHAR parameter *StrLen_or_IndPtr op SQL_LEN_DATA_AT_EXEC(10000).

• SQL_DATA_AT_EXEC. De gegevens voor de parameter worden verzonden met SQLPutData. Deze waarde wordt gebruikt door ODBC 1.0-applicaties wanneer zij ODBC 3 aanroepen. X-bestuurders . Voor meer informatie, zie "Parameters doorgeven," later in deze sectie.

Als StrLen_or_IndPtr een nullpointer is, gaat de driver ervan uit dat alle inputparameterwaarden niet-NULL zijn en dat teken- en binaire data null-termined zijn. Als InputOutputType SQL_PARAM_OUTPUT of SQL_PARAM_OUTPUT_STREAM is en ParameterValuePtr en StrLen_or_IndPtr beide nullpointers zijn, verwijdert de driver de uitvoerwaarde.

Als het InputOutputType-argument SQL_PARAM_INPUT_OUTPUT, SQL_PARAM_OUTPUT, SQL_PARAM_INPUT_OUTPUT_STREAM of SQL_PARAM_OUTPUT_STREAM is, wijst StrLen_or_IndPtr op een buffer waarin de driver terugkeert SQL_NULL_DATA, het aantal bytes dat beschikbaar is om terug te geven in *ParameterValuePtr (exclusief de null-terminatiebyte van tekengegevens), of SQL_NO_TOTAL (als het aantal bytes dat kan worden teruggegeven niet kan worden bepaald). Als de procedure één of meer resultaatsets teruggeeft, is de *StrLen_or_IndPtr buffer niet gegarandeerd ingesteld totdat alle resultaten zijn opgehaald.

Als de waarde in het attribuut SQL_ATTR_PARAMSET_SIZE groter is dan 1, wijst StrLen_or_IndPtr naar een array van SQLLEN-waarden. Deze kunnen elk van de eerder in deze sectie genoemde waarden zijn en worden verwerkt met één SQL-instructie.

Parameterwaarden doorgeven

Een applicatie kan de waarde voor een parameter doorgeven in de *ParameterValuePtr-buffer of met één of meer aanroepen naar SQLPutData. Parameters waarvan de gegevens met SQLPutData worden doorgegeven, staan bekend als data-at-uitvoeringsparameters . Deze worden doorgaans gebruikt om gegevens te verzenden voor SQL_LONGVARBINARY en SQL_LONGVARCHAR parameters, en kunnen worden gecombineerd met andere parameters.

Om parameterwaarden door te geven, voert een applicatie de volgende reeks stappen uit:

1. Roept SQLBindParameter aan voor elke parameter om buffers te binden voor de parameter (ParameterValuePtr-argument ) en lengte/indicator (StrLen_or_IndPtr argument). Voor data-at-uitvoeringsparameters is ParameterValuePtr een door applicatie gedefinieerde pointerwaarde zoals een parameternummer of een pointer naar data. De waarde wordt later teruggegeven en kan worden gebruikt om de parameter te identificeren.

2. Plaatst waarden voor input- en input/outputparameters in de *ParameterValuePtr- en *StrLen_or_IndPtr buffers:

   • Voor normale parameters plaatst de applicatie de parameterwaarde in de *ParameterValuePtr-buffer en de lengte van die waarde in de *StrLen_or_IndPtr buffer. Voor meer informatie, zie Parameterwaarden instellen.

   • Voor data-at-execution-parameters plaatst de applicatie het resultaat van de macro SQL_LEN_DATA_AT_EXEC(length) (bij het aanroepen van een ODBC 2.0-driver) in de *StrLen_or_IndPtr-buffer .

3. Roept SQLExecute of SQLExecDirect aan om de SQL-instructie uit te voeren.

   • Als er geen parameters voor data bij uitvoering zijn, is het proces voltooid.

   • Als er data-at-executieparameters zijn, geeft de functie SQL_NEED_DATA terug.

4. Roept SQLParamData aan om de applicatie-gedefinieerde waarde op te halen die is gespecificeerd in het ParameterValuePtr-argument van SQLBindParameter voor de eerste data-at-uitvoeringsparameter die wordt verwerkt. SQLParamData geeft SQL_NEED_DATA terug.

   Opmerking

   Hoewel data-at-execution-parameters lijken op data-at-execution-kolommen, is de waarde die door SQLParamData wordt geretourneerd voor elke kolom verschillend. Data-at-execution-parameters zijn parameters in een SQL-instructie waarvoor gegevens samen met SQLPutData worden verzonden wanneer de instructie wordt uitgevoerd met SQLExecDirect of SQLExecute. Ze zijn gebonden met SQLBindParameter. De waarde die door SQLParamData wordt teruggegeven, is een pointerwaarde die wordt doorgegeven aan SQLBindParameter in het ParameterValuePtr-argument . Data-at-execution-kolommen zijn kolommen in een rijset waarvoor gegevens samen met SQLPutData worden verzonden wanneer een rij wordt bijgewerkt of toegevoegd met SQLBulkOperations of bijgewerkt met SQLSetPos. Ze zijn gebonden aan SQLBindCol. De waarde die door SQLParamData wordt teruggegeven, is het adres van de rij in de *TargetValuePtr-buffer (ingesteld door een aanroep naar SQLBindCol) die wordt verwerkt.

5. Roept SQLPutData één of meer keren aan om data voor de parameter te verzenden. Meer dan één aanroep is nodig als de datawaarde groter is dan de *ParameterValuePtr-buffer gespecificeerd in SQLPutData; meerdere aanroepen van SQLPutData voor dezelfde parameter zijn alleen toegestaan wanneer karakter C data wordt verzonden naar een kolom met een karakter-, binaire of databron-specifieke datatype, of wanneer binaire C-data wordt verzonden naar een kolom met een karakter-, binair- of databron-specifiek datatype.

6. Roept SQLParamData opnieuw aan om aan te geven dat alle data voor de parameter is verzonden.

   • Als er meer data-at-executieparameters zijn, geeft SQLParamData SQL_NEED_DATA en de applicatie-gedefinieerde waarde terug voor de volgende data-at-executieparameter die verwerkt moet worden. De applicatie herhaalt stappen 4 en 5.

   • Als er geen data-at-executieparameters meer zijn, is het proces voltooid. Als de instructie succesvol is uitgevoerd, geeft SQLParamData SQL_SUCCESS of SQL_SUCCESS_WITH_INFO terug; als de uitvoering mislukte, keert hij terug SQL_ERROR. Op dit punt kan SQLParamData elke SQLSTATE teruggeven die kan worden teruggegeven door de functie die wordt gebruikt om de instructie uit te voeren (SQLExecDirect of SQLExecute).

     Uitvoerwaarden voor alle input/output- of outputparameters zijn beschikbaar in de *ParameterValuePtr en *StrLen_or_IndPtr buffers nadat de applicatie alle resultaatsets heeft opgehaald die door de instructie zijn gegenereerd.

Het aanroepen van SQLExecute of SQLExecDirect plaatst de instructie in een SQL_NEED_DATA toestand. Op dit punt kan de applicatie alleen SQLCancel, SQLGetDiagField, SQLGetDiagRec, SQLGetFunctions, SQLParamData of SQLPutData aanroepen met de instructie of de verbindingshandle die bij de instructie hoort. Als het een andere functie aanroept met de instructie of de verbinding die aan de instructie is gekoppeld, geeft de functie SQLSTATE HY010 (Function sequence error) terug. De instructie verlaat de SQL_NEED_DATA toestand wanneer SQLParamData of SQLPutData een foutmelding teruggeeft, SQLParamData SQL_SUCCESS of SQL_SUCCESS_WITH_INFO teruggeeft, of de instructie wordt geannuleerd.

Als de applicatie SQLCancel aanroept terwijl de driver nog data nodig heeft voor data-at-execution-parameters, annuleert de driver de instructie-uitvoering; de applicatie kan vervolgens opnieuw SQLExecute of SQLExecDirect aanroepen.

Het ophalen van gestreamde uitgangsparameters

Wanneer een applicatie InputOutputType op SQL_PARAM_INPUT_OUTPUT_STREAM of SQL_PARAM_OUTPUT_STREAM zet, moet de outputparameterwaarde worden opgehaald door één of meer aanroepen naar SQLGetData. Wanneer de driver een gestreamde outputparameterwaarde heeft om terug te geven aan de applicatie, zal hij SQL_PARAM_DATA_AVAILABLE teruggeven als reactie op een aanroep van de volgende functies: SQLMoreResults, SQLExecute en SQLExecDirect. Een applicatie roept SQLParamData aan om te bepalen welke parameterwaarde beschikbaar is.

Voor meer informatie over SQL_PARAM_DATA_AVAILABLE en gestreamde uitvoerparameters, zie Retrieving Output Parameters Using SQLGetData.

Matrices van parameters gebruiken

Wanneer een applicatie een instructie voorbereidt met parametermarkers en een array parameters doorgeeft, zijn er twee verschillende manieren waarop dit kan worden uitgevoerd. Een manier is dat de driver vertrouwt op de arrayverwerkingscapaciteiten van de backend, waarbij de hele instructie met de array parameters als één atomaire eenheid wordt behandeld. Oracle is een voorbeeld van een databron die arrayverwerkingsmogelijkheden ondersteunt. Een andere manier om deze functie te implementeren is dat de driver een batch SQL-statements genereert, één SQL-instructie voor elke set parameters in de parameterarray, en de batch uitvoert. Arrays van parameters kunnen niet worden gebruikt met een UPDATE WHERE CURRENT OF-uitspraak .

Wanneer een array parameters wordt verwerkt, kunnen individuele resultaatsets/rijtellingen (één voor elke parameterset) beschikbaar zijn of kunnen resultaatsets/rijtellingen worden samengevoegd tot één. De SQL_PARAM_ARRAY_ROW_COUNTS-optie in SQLGetInfo geeft aan of er rijtellingen beschikbaar zijn voor elke set parameters (SQL_PARC_BATCH) of slechts één rijtelling beschikbaar is (SQL_PARC_NO_BATCH).

De SQL_PARAM_ARRAY_SELECTS optie in SQLGetInfo geeft aan of er voor elke set parameters (SQL_PAS_BATCH) een resultaatset beschikbaar is of slechts één resultaatset beschikbaar is (SQL_PAS_NO_BATCH). Als de driver niet toestaat dat een result set-genererende instructie met een array parameters wordt uitgevoerd, geeft SQL_PARAM_ARRAY_SELECTS SQL_PAS_NO_SELECT terug.

Voor meer informatie, zie SQLGetInfo Function.

Om arrays van parameters te ondersteunen, wordt het attribuut SQL_ATTR_PARAMSET_SIZE gesteld om het aantal waarden voor elke parameter te specificeren. Als het veld groter is dan 1, moeten de SQL_DESC_DATA_PTR, SQL_DESC_INDICATOR_PTR en SQL_DESC_OCTET_LENGTH_PTR velden van de APD naar arrays wijzen. De kardinaliteit van elke array is gelijk aan de waarde van SQL_ATTR_PARAMSET_SIZE.

Het SQL_DESC_ROWS_PROCESSED_PTR veld van de APD wijst naar een buffer die het aantal verzamelingen parameters bevat dat is verwerkt, inclusief foutensets. Naarmate elke set parameters wordt verwerkt, slaat de driver een nieuwe waarde op in de buffer. Er wordt geen getal teruggegeven als dit een nullpointer is. Wanneer arrays van parameters worden gebruikt, wordt de waarde waarnaar het SQL_DESC_ROWS_PROCESSED_PTR veld van de APD wijst, ingevuld als SQL_ERROR wordt teruggegeven door de instellingsfunctie. Als SQL_NEED_DATA wordt teruggegeven, wordt de waarde waarnaar het SQL_DESC_ROWS_PROCESSED_PTR veld van de APD wijst, gezet op de verzameling parameters die wordt verwerkt.

Wat er gebeurt wanneer een array parameters wordt gebonden en een UPDATE WHERE CURRENT OF-instructie wordt uitgevoerd, wordt door de driver gedefinieerd.

Column-Wise Parameterbinding

Bij kolomgebonden binding bindt de applicatie aparte parameter- en lengte-/indicatorarrays aan elke parameter.

Om kolomwijze binding te gebruiken, stelt de applicatie eerst het SQL_ATTR_PARAM_BIND_TYPE-statement-attribuut in op SQL_PARAM_BIND_BY_COLUMN. (Dit is de standaard.) Voor elke kolom die gebonden moet worden, voert de applicatie de volgende stappen uit:

1. Een parameterbufferarray wordt toegewezen.

2. Een array van lengte-/indicatorbuffers wordt toegewezen.

   Opmerking

   Als de applicatie direct naar descriptors schrijft wanneer kolomgewijze binding wordt gebruikt, kunnen aparte arrays worden gebruikt voor lengte- en indicatorgegevens.

3. Roept SQLBindParameter aan met de volgende argumenten:

   • ValueType is het C-type van een enkel element in de parameterbufferarray.

   • ParameterType is het SQL-type van de parameter.

   • ParameterValuePtr is het adres van de parameterbufferarray.

   • BufferLength is de grootte van een enkel element in de parameterbufferarray. Het BufferLength-argument wordt genegeerd wanneer de data data van vaste lengte is.

   • StrLen_or_IndPtr is het adres van de lengte/indicator-array.

Voor meer informatie over hoe deze informatie wordt gebruikt, zie "ParameterValuePtr-argument" in "Comments," later in deze sectie. Voor meer informatie over kolomgewijze binding van parameters, zie Binding Arrays of Parameters.

Row-Wise Parameterbinding

Bij rijgewijze binding definieert de applicatie een structuur die parameter- en lengte-/indicatorbuffers bevat voor elke parameter die gebonden moet worden.

Om rijgewijze binding te gebruiken, voert de applicatie de volgende stappen uit:

1. Definieert een structuur om een enkele set parameters te bevatten (inclusief zowel parameter- als lengte-/indicatorbuffers) en wijst een array van deze structuren toe.

   Opmerking

   Als de applicatie direct naar descriptors schrijft wanneer rijwijze binding wordt gebruikt, kunnen aparte velden worden gebruikt voor lengte- en indicatorgegevens.

2. Stelt het SQL_ATTR_PARAM_BIND_TYPE-statementattribuut in op de grootte van de structuur die een enkele set parameters bevat, of op de grootte van een instantie van een buffer waarin de parameters worden gebonden. De lengte moet ruimte bevatten voor alle gebonden parameters, en eventuele opvulling van de structuur of buffer, om ervoor te zorgen dat, wanneer het adres van een gebonden parameter wordt verhoogd met de gespecificeerde lengte, het resultaat naar het begin van dezelfde parameter in de volgende rij zal wijzen. Wanneer je de sizeof-operator in ANSI C gebruikt, is dit gedrag gegarandeerd.

3. Roept SQLBindParameter aan met de volgende argumenten voor elke parameter die gebonden moet worden:

   • ValueType is het type parameterbufferlid dat aan de kolom gebonden moet worden.

   • ParameterType is het SQL-type van de parameter.

   • ParameterValuePtr is het adres van het parameterbufferlid in het eerste arrayelement.

   • BufferLength is de grootte van het parameter bufferlid.

   • StrLen_or_IndPtr is het adres van het lengte/indicatorlid dat gebonden moet worden.

Voor meer informatie over hoe deze informatie wordt gebruikt, zie "ParameterValuePtr-argument ," later in deze sectie. Voor meer informatie over rijgewijze binding van parameters, zie de Binding Arrays of Parameters.

Foutinformatie

Als een driver geen parameterarrays als batches implementeert (de SQL_PARAM_ARRAY_ROW_COUNTS optie is gelijk aan SQL_PARC_NO_BATCH), worden foutsituaties behandeld alsof één instructie wordt uitgevoerd. Als de driver parameterarrays als batches implementeert, kan een applicatie het SQL_DESC_ARRAY_STATUS_PTR headerveld van de IPD gebruiken om te bepalen welke parameter van een SQL-instructie of welke parameter in een array van parameters SQLExecDirect of SQLExecute een foutmelding heeft veroorzaakt. Dit veld bevat statusinformatie voor elke rij parameterwaarden. Als het veld aangeeft dat er een fout is opgetreden, zullen velden in de diagnostische datastructuur het rij- en parameternummer van de parameter die faalde aangeven. Het aantal elementen in de array wordt gedefinieerd door het SQL_DESC_ARRAY_SIZE-headerveld in de APD, dat kan worden ingesteld met het SQL_ATTR_PARAMSET_SIZE-statementattribuut.

Wanneer SQLExecute of SQLExecDirect SQL_ERROR teruggeeft, zullen de elementen in de array waar het SQL_DESC_ARRAY_STATUS_PTR-veld in de IPD naar wijst, SQL_PARAM_ERROR, SQL_PARAM_SUCCESS, SQL_PARAM_SUCCESS_WITH_INFO, SQL_PARAM_UNUSED of SQL_PARAM_DIAG_UNAVAILABLE bevatten.

Voor elk element in deze array bevat de diagnostische datastructuur één of meer statusrecords. Het SQL_DIAG_ROW_NUMBER-veld van de structuur geeft het rijnummer aan van de parameterwaarden die de fout hebben veroorzaakt. Als het mogelijk is om de specifieke parameter in een rij parameters te bepalen die de fout heeft veroorzaakt, wordt het parameternummer in het SQL_DIAG_COLUMN_NUMBER veld ingevoerd.

SQL_PARAM_UNUSED wordt ingevoerd wanneer een parameter niet is gebruikt omdat er een fout is opgetreden in een eerdere parameter die SQLExecute of SQLExecDirect dwong om te stoppen. Als er bijvoorbeeld 50 parameters zijn en er is een fout opgetreden tijdens het uitvoeren van de veertigste set parameters waardoor SQLExecute of SQLExecDirect werd afgebroken, dan wordt SQL_PARAM_UNUSED ingevoerd in de statusarray voor parameters 41 tot en met 50.

SQL_PARAM_DIAG_UNAVAILABLE wordt ingevoerd wanneer de driver arrays van parameters als een monolithische eenheid behandelt, zodat deze specifieke parameterniveau van foutinformatie niet wordt gegenereerd.

Sommige fouten in de verwerking van een enkele set parameters zorgen ervoor dat de verwerking van de volgende sets parameters in de array stopt. Andere fouten beïnvloeden de verwerking van latere parameters niet. Welke fouten de verwerking stoppen, wordt door de driver gedefinieerd. Als de verwerking niet wordt gestopt, worden alle parameters in de array verwerkt, wordt SQL_SUCCESS_WITH_INFO teruggegeven als gevolg van de fout, en wordt de buffer gedefinieerd door SQL_ATTR_PARAMS_PROCESSED_PTR ingesteld op het totale aantal verzamelingen verwerkt parameters (zoals gedefinieerd door het SQL_ATTR_PARAMSET_SIZE-statementattribuut), waaronder foutensets.

Wanneer SQLExecute of SQLExecDirect terugkeert voordat alle parametersets in een parameterarray zijn verwerkt, bijvoorbeeld wanneer SQL_ERROR of SQL_NEED_DATA wordt teruggegeven, bevat de statusarray statussen voor die parameters die al zijn verwerkt. De locatie waar het SQL_DESC_ROWS_PROCESSED_PTR veld in de IPD naar wijst, bevat het rijnummer in de parameterarray dat de SQL_ERROR of SQL_NEED_DATA foutcode heeft veroorzaakt. Wanneer een array parameters naar een SELECT-instructie wordt gestuurd, wordt de beschikbaarheid van statusarraywaarden door de driver gedefinieerd; ze kunnen beschikbaar zijn nadat de instructie is uitgevoerd of wanneer resultaatsets zijn opgehaald.

Het negeren van een set parameters

Het SQL_DESC_ARRAY_STATUS_PTR-veld van de APD (zoals ingesteld door het attribuut SQL_ATTR_PARAM_STATUS_PTR-instructie) kan worden gebruikt om aan te geven dat een set gebonden parameters in een SQL-instructie genegeerd moet worden. Om de driver te laten negeren één of meer sets parameters tijdens de uitvoering, moet een applicatie deze stappen volgen:

1. Roep SQLSetDescField aan om het SQL_DESC_ARRAY_STATUS_PTR headerveld van de APD te zetten dat wijst naar een array van SQLUSMALLINT-waarden die statusinformatie bevatten. Dit veld kan ook worden ingesteld door SQLSetStmtAttr aan te roepen met een attribuut van SQL_ATTR_PARAM_OPERATION_PTR, waardoor een applicatie het veld kan instellen zonder een descriptorhandle te verkrijgen.

2. Stel elk element van de array die door het SQL_DESC_ARRAY_STATUS_PTR veld van de APD wordt gedefinieerd in op een van twee waarden:

   • SQL_PARAM_IGNORE, om aan te geven dat de rij is uitgesloten van de uitvoering van een statement.

   • SQL_PARAM_PROCEED, om aan te geven dat de rij is opgenomen in de uitvoering van een statement.

3. Roep SQLExecDirect of SQLExecute aan om de voorbereide instructie uit te voeren.

De volgende regels zijn van toepassing op de array die wordt gedefinieerd door het SQL_DESC_ARRAY_STATUS_PTR veld van de APD:

• De pointer staat standaard op null.

• Als de pointer null is, worden alle sets parameters gebruikt, alsof alle elementen op SQL_ROW_PROCEED zijn gezet.

• Het instellen van een element op SQL_PARAM_PROCEED garandeert niet dat de operatie die specifieke set parameters zal gebruiken.

• SQL_PARAM_PROCEED wordt gedefinieerd als 0 in het headerbestand.

Een applicatie kan het SQL_DESC_ARRAY_STATUS_PTR veld in de APD zo instellen dat het naar dezelfde array wijst als het veld van het SQL_DESC_ARRAY_STATUS_PTR veld in de IRD. Dit is handig bij het binden van parameters aan rijgegevens. Parameters kunnen vervolgens worden genegeerd op basis van de status van de rijgegevens. Naast SQL_PARAM_IGNORE zorgen de volgende codes ervoor dat een parameter in een SQL-instructie wordt genegeerd: SQL_ROW_DELETED, SQL_ROW_UPDATED en SQL_ROW_ERROR. Naast SQL_PARAM_PROCEED zorgen de volgende codes ervoor dat een SQL-instructie wordt uitgevoerd: SQL_ROW_SUCCESS, SQL_ROW_SUCCESS_WITH_INFO en SQL_ROW_ADDED.

Herbindingsparameters

Een applicatie kan een van twee bewerkingen uitvoeren om een binding te wijzigen:

• Roep SQLBindParameter aan om een nieuwe binding te specificeren voor een kolom die al gebonden is. De driver overschrijft de oude binding met de nieuwe.

• Specificeer een offset die aan het bufferadres wordt toegevoegd en die is gespecificeerd door de bindingsaanroep naar SQLBindParameter. Voor meer informatie, zie de volgende sectie, "Rebinding with Offsets."

Herbinding met offset

Herbinding van parameters is vooral nuttig wanneer een applicatie een buffergebied heeft dat veel parameters kan bevatten, maar een aanroep naar SQLExecDirect of SQLExecute slechts enkele van de parameters gebruikt. De resterende ruimte in het buffergebied kan worden gebruikt voor de volgende set parameters door de bestaande binding met een offset te wijzigen.

Het SQL_DESC_BIND_OFFSET_PTR headerveld in de APD wijst op de bindingsoffset. Als het veld niet-null is, dereferert de driver de pointer en, als geen van de waarden in de SQL_DESC_DATA_PTR, SQL_DESC_INDICATOR_PTR en SQL_DESC_OCTET_LENGTH_PTR velden een nullpointer is, voegt hij de gedereferencede waarde toe aan die velden in de descriptorrecords tijdens de uitvoering. De nieuwe pointerwaarden worden gebruikt wanneer de SQL-statements worden uitgevoerd. De offset blijft geldig na het herbinden. Omdat SQL_DESC_BIND_OFFSET_PTR een verwijzing naar de offset is in plaats van naar de offset zelf, kan een applicatie de offset direct wijzigen, zonder SQLSetDescField of SQLSetDescRec aan te roepen om het descriptorveld te wijzigen. De pointer staat standaard op null. Het SQL_DESC_BIND_OFFSET_PTR veld van de ARD kan worden ingesteld door een aanroep naar SQLSetDescField of door een aanroep naar SQLSetStmtAttr met een fAttribuut van SQL_ATTR_PARAM_BIND_OFFSET_PTR.

De bindingsoffset wordt altijd direct toegevoegd aan de waarden in de velden SQL_DESC_DATA_PTR, SQL_DESC_INDICATOR_PTR en SQL_DESC_OCTET_LENGTH_PTR. Als de offset wordt gewijzigd naar een andere waarde, wordt de nieuwe waarde nog steeds direct toegevoegd aan de waarde in elk descriptorveld. De nieuwe offset wordt niet opgeteld bij de som van de veldwaarde en eventuele eerdere offsets.

Beschrijvingen

Hoe een parameter wordt begrensd, wordt bepaald door velden van de APD's en IPD's. De argumenten in SQLBindParameter worden gebruikt om die descriptorvelden in te stellen. De velden kunnen ook worden ingesteld door de SQLSetDescField-functies , hoewel SQLBindParameter efficiënter is in gebruik omdat de applicatie geen descriptorhandle hoeft te verkrijgen om SQLBindParameter aan te roepen.

Conceptueel voert SQLBindParameter de volgende stappen in volgorde uit:

1. Roept SQLGetStmtAttr aan om het APD-handle te verkrijgen.

2. Roept SQLGetDescField aan om het SQL_DESC_COUNT veld van de APD te krijgen, en als de waarde van het ColumnNumber-argument de waarde van SQL_DESC_COUNT overschrijdt, roept SQLSetDescField aan om de waarde van SQL_DESC_COUNT te verhogen naar ColumnNumber.

3. Roept SQLSetDescField meerdere keren aan om waarden toe te wijzen aan de volgende velden van de APD:

   • Zet SQL_DESC_TYPE en SQL_DESC_CONCISE_TYPE op de waarde van ValueType, behalve dat als ValueType een van de beknopte identificaties is van een datetime- of intervalsubtype, het SQL_DESC_TYPE respectievelijk op SQL_DATETIME of SQL_INTERVAL zet, SQL_DESC_CONCISE_TYPE op de concise identifier zet, en SQL_DESC_DATETIME_INTERVAL_CODE op de bijbehorende datetime- of intervalsubcode.

   • Stelt het SQL_DESC_OCTET_LENGTH veld in op de waarde BufferLength.

   • Stelt het veld SQL_DESC_DATA_PTR in op de waarde van ParameterValue.

   • Zet het SQL_DESC_OCTET_LENGTH_PTR veld op de waarde van StrLen_or_Ind.

   • Zet het SQL_DESC_INDICATOR_PTR veld ook op de waarde van StrLen_or_Ind.

   De StrLen_or_Ind-parameter specificeert zowel de indicatorinformatie als de lengte van de parameterwaarde.

4. Roept SQLGetStmtAttr aan om het IPD-handle te verkrijgen.

5. Roept SQLGetDescField aan om het SQL_DESC_COUNT veld van de IPD te krijgen, en als de waarde van het ColumnNumber-argument hoger is dan de waarde van SQL_DESC_COUNT, roept SQLSetDescField aan om de waarde van SQL_DESC_COUNT te verhogen naar ColumnNumber.

6. Roept SQLSetDescField meerdere keren aan om waarden toe te wijzen aan de volgende velden van de IPD:

   • Zet SQL_DESC_TYPE en SQL_DESC_CONCISE_TYPE op de waarde van ParameterType, behalve dat als ParameterType een van de beknopte identificaties is van een datetime- of intervalsubtype, het SQL_DESC_TYPE respectievelijk op SQL_DATETIME of SQL_INTERVAL zet, SQL_DESC_CONCISE_TYPE op de concise identifier en SQL_DESC_DATETIME_INTERVAL_CODE op de bijbehorende datetime- of intervalsubcode.

   • Stelt één of meer van SQL_DESC_LENGTH, SQL_DESC_PRECISION en SQL_DESC_DATETIME_INTERVAL_PRECISION in, afhankelijk van ParameterType.

   • Stelt SQL_DESC_SCALE in op de waarde van Decimalcijfers.

Als de aanroep van SQLBindParameter faalt, zijn de inhoud van de descriptorvelden die in de APD zouden zijn ingesteld ongedefinieerd, en blijft het SQL_DESC_COUNT veld van de APD ongewijzigd. Daarnaast zijn de velden SQL_DESC_LENGTH, SQL_DESC_PRECISION, SQL_DESC_SCALE en SQL_DESC_TYPE van het betreffende record in de IPD niet gedefinieerd en het SQL_DESC_COUNT veld van de IPD ongewijzigd.

Conversie van aanroepen naar en van SQLSetParam

Wanneer een ODBC 1.0-applicatie SQLSetParam aanroept in een ODBC 3. x driver, de ODBC 3. x Driver Manager brengt de oproep in kaart zoals weergegeven in de volgende tabel.

Examples

Eén. Gebruik de SQLBindParameter-functie

In het volgende voorbeeld bereidt een applicatie een SQL-instructie voor om gegevens in de ORDERS-tabel in te voegen. Voor elke parameter in de instructie roept de applicatie SQLBindParameter aan om het ODBC C-datatype en het SQL-datatype van de parameter te specificeren, en om een buffer aan elke parameter te binden. Voor elke gegevensrij wijst de applicatie datawaarden toe aan elke parameter en roept SQLExecute aan om de instructie uit te voeren.

Het volgende voorbeeld gaat ervan uit dat je een ODBC-databron op je computer hebt genaamd Northwind, die is gekoppeld aan de Northwind-database.

Voor meer codevoorbeelden, zie SQLBulkOperations Function, SQLProcedures Function, SQLPutData Function en SQLSetPos Function.

// SQLBindParameter_Function.cpp  
// compile with: ODBC32.lib  
#include <windows.h>  
#include <sqltypes.h>  
#include <sqlext.h>  
  
#define EMPLOYEE_ID_LEN 10  
  
SQLHENV henv = NULL;  
SQLHDBC hdbc = NULL;  
SQLRETURN retcode;  
SQLHSTMT hstmt = NULL;  
SQLSMALLINT sCustID;  
  
SQLCHAR szEmployeeID[EMPLOYEE_ID_LEN];  
SQL_DATE_STRUCT dsOrderDate;  
SQLINTEGER cbCustID = 0, cbOrderDate = 0, cbEmployeeID = SQL_NTS;  
  
int main() {  
   retcode = SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &henv);  
   retcode = SQLSetEnvAttr(henv, SQL_ATTR_ODBC_VERSION, (SQLPOINTER*)SQL_OV_ODBC3, 0);   
  
   retcode = SQLAllocHandle(SQL_HANDLE_DBC, henv, &hdbc);   
   retcode = SQLSetConnectAttr(hdbc, SQL_LOGIN_TIMEOUT, (SQLPOINTER)5, 0);  
  
   retcode = SQLConnect(hdbc, (SQLCHAR*) "Northwind", SQL_NTS, (SQLCHAR*) NULL, 0, NULL, 0);  
   retcode = SQLAllocHandle(SQL_HANDLE_STMT, hdbc, &hstmt);  
  
   retcode = SQLBindParameter(hstmt, 1, SQL_PARAM_INPUT, SQL_C_CHAR, SQL_CHAR, EMPLOYEE_ID_LEN, 0, szEmployeeID, 0, &cbEmployeeID);  
   retcode = SQLBindParameter(hstmt, 2, SQL_PARAM_INPUT, SQL_C_SSHORT, SQL_INTEGER, 0, 0, &sCustID, 0, &cbCustID);  
   retcode = SQLBindParameter(hstmt, 3, SQL_PARAM_INPUT, SQL_C_TYPE_DATE, SQL_TIMESTAMP, sizeof(dsOrderDate), 0, &dsOrderDate, 0, &cbOrderDate);  
  
   retcode = SQLPrepare(hstmt, (SQLCHAR*)"INSERT INTO Orders(CustomerID, EmployeeID, OrderDate) VALUES (?, ?, ?)", SQL_NTS);  
  
   strcpy_s((char*)szEmployeeID, _countof(szEmployeeID), "BERGS");  
   sCustID = 5;  
   dsOrderDate.year = 2006;  
   dsOrderDate.month = 3;  
   dsOrderDate.day = 17;  
  
   retcode = SQLExecute(hstmt);  
}  

B. Voer een opgeslagen procedure uit met een benoemde parameter

In het volgende voorbeeld voert een applicatie een SQL Server stored procedure uit met behulp van een benoemde parameter.

// SQLBindParameter_Function_2.cpp  
// compile with: ODBC32.lib  
// sample assumes the following stored procedure:  
// use northwind  
// DROP PROCEDURE SQLBindParameter  
// GO  
//   
// CREATE PROCEDURE SQLBindParameter @quote int  
// AS  
// delete from orders where OrderID >= @quote  
// GO  
#include <windows.h>  
#include <sqltypes.h>  
#include <sqlext.h>  
  
SQLHDESC hIpd = NULL;  
SQLHENV henv = NULL;  
SQLHDBC hdbc = NULL;  
SQLRETURN retcode;  
SQLHSTMT hstmt = NULL;  
SQLCHAR szQuote[50] = "100084";  
SQLINTEGER cbValue = SQL_NTS;  
  
int main() {  
   retcode = SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &henv);  
   retcode = SQLSetEnvAttr(henv, SQL_ATTR_ODBC_VERSION, (SQLPOINTER*)SQL_OV_ODBC3, 0);   
  
   retcode = SQLAllocHandle(SQL_HANDLE_DBC, henv, &hdbc);   
   retcode = SQLSetConnectAttr(hdbc, SQL_LOGIN_TIMEOUT, (SQLPOINTER)5, 0);  
  
   retcode = SQLConnect(hdbc, (SQLCHAR*) "Northwind", SQL_NTS, (SQLCHAR*) NULL, 0, NULL, 0);  
   retcode = SQLAllocHandle(SQL_HANDLE_STMT, hdbc, &hstmt);  
  
   retcode = SQLPrepare(hstmt, (SQLCHAR*)"{call SQLBindParameter(?)}", SQL_NTS);  
   retcode = SQLBindParameter(hstmt, 1, SQL_PARAM_INPUT, SQL_C_CHAR, SQL_CHAR, 50, 0, szQuote, 0, &cbValue);  
   retcode = SQLGetStmtAttr(hstmt, SQL_ATTR_IMP_PARAM_DESC, &hIpd, 0, 0);  
   retcode = SQLSetDescField(hIpd, 1, SQL_DESC_NAME, "@quote", SQL_NTS);  
  
   retcode = SQLExecute(hstmt);  
}  

Gerelateerde functies

Zie ook

ODBC-API-verwijzing
ODBC-headerbestanden
Uitvoerparameters ophalen met SQLGetData