Matrices van parameters gebruiken

Als u matrices van parameters wilt gebruiken, roept de toepassing SQLSetStmtAttr aan met een kenmerkargument van SQL_ATTR_PARAMSET_SIZE om het aantal sets parameters op te geven. SqlSetStmtAttr wordt aanroepen met een kenmerkargument van SQL_ATTR_PARAMS_PROCESSED_PTR om het adres op te geven van een variabele waarin het stuurprogramma het aantal sets parameters kan retourneren dat is verwerkt, inclusief foutsets. SqlSetStmtAttr wordt aanroepen met een kenmerkargument van SQL_ATTR_PARAM_STATUS_PTR om te verwijzen naar een matrix waarin statusinformatie moet worden geretourneerd voor elke rij met parameterwaarden. Het stuurprogramma slaat deze adressen op in de structuur die wordt onderhouden voor de opdracht.

Voordat de instructie wordt uitgevoerd, stelt de toepassing de waarde in van elk element van elke afhankelijke matrix. Wanneer de instructie wordt uitgevoerd, gebruikt het stuurprogramma de informatie die het heeft opgeslagen om de parameterwaarden op te halen en naar de gegevensbron te verzenden; Indien mogelijk moet het stuurprogramma deze waarden verzenden als matrices. Hoewel het gebruik van matrices van parameters het beste wordt geïmplementeerd door de SQL-instructie uit te voeren met alle parameters in de matrix met één aanroep naar de gegevensbron, is deze mogelijkheid momenteel niet algemeen beschikbaar in DBMSs. Stuurprogramma's kunnen dit echter simuleren door meerdere keren een SQL-instructie uit te voeren, elk met één set parameters.

Voordat een toepassing matrices van parameters gebruikt, moet deze worden ondersteund door de stuurprogramma's die door de toepassing worden gebruikt. U kunt dit op twee manieren doen:

• Gebruik alleen stuurprogramma's die bekend zijn om matrices van parameters te ondersteunen. De toepassing kan de namen van deze stuurprogramma's coderen of de gebruiker kan worden geïnstrueerd om alleen deze stuurprogramma's te gebruiken. Aangepaste toepassingen en verticale toepassingen maken vaak gebruik van een beperkte set stuurprogramma's.

• Controleer op ondersteuning van matrices met parameters tijdens runtime. Een stuurprogramma ondersteunt matrices met parameters als het mogelijk is om het kenmerk SQL_ATTR_PARAMSET_SIZE instructie in te stellen op een waarde die groter is dan 1. Algemene toepassingen en verticale toepassingen controleren vaak op ondersteuning van matrices van parameters tijdens runtime.

De beschikbaarheid van het aantal rijen en resultatensets in geparameteriseerde uitvoering kan worden bepaald door SQLGetInfo aan te roepen met de opties SQL_PARAM_ARRAY_ROW_COUNTS en SQL_PARAM_ARRAY_SELECTS. Voor INSERT-, UPDATE- en DELETE-instructies geeft de SQL_PARAM_ARRAY_ROW_COUNTS optie aan of afzonderlijke rijen (één voor elke parameterset) beschikbaar zijn (SQL_PARC_BATCH) of dat het aantal rijen wordt samengevouwen (SQL_PARC_NO_BATCH). Voor SELECT-instructies geeft de SQL_PARAM_ARRAY_SELECTS optie aan of een resultatenset beschikbaar is voor elke set parameters (SQL_PAS_BATCH) of of er slechts één resultatenset beschikbaar is (SQL_PAS_NO_BATCH). Als het stuurprogramma niet toestaat dat instructies voor het genereren van resultatensets worden uitgevoerd met een matrix met parameters, retourneert SQL_PARAM_ARRAY_SELECTS SQL_PAS_NO_SELECT. Het is gegevensbronspecifiek of matrices van parameters kunnen worden gebruikt met andere typen instructies, met name omdat het gebruik van parameters in deze instructies gegevensbronspecifiek is en geen ODBC SQL-grammatica volgt.

Het door het SQL_ATTR_PARAM_OPERATION_PTR-kenmerk verwezen array kan worden gebruikt om rijen met parameters te negeren. Als een element van de matrix is ingesteld op SQL_PARAM_IGNORE, wordt de set parameters die overeenkomen met dat element uitgesloten van de SQLExecute - of SQLExecDirect-aanroep . De array waarnaar wordt verwezen door het kenmerk SQL_ATTR_PARAM_OPERATION_PTR wordt toegewezen en ingevuld door de toepassing en gelezen door het stuurprogramma. Als opgehaalde rijen worden gebruikt als invoerparameters, kunnen de waarden van de rijstatusmatrix worden gebruikt in de parameterbewerkingmatrix.

Foutverwerking

Als er een fout optreedt tijdens het uitvoeren van de instructie, retourneert de uitvoeringsfunctie een fout en wordt de variabele rijnummer ingesteld op het nummer van de rij met de fout. Het is gegevensbronspecifiek of alle rijen behalve de foutenset worden uitgevoerd of of alle rijen vóór (maar niet na) de foutenset worden uitgevoerd. Omdat het sets van parameters verwerkt, stelt het stuurprogramma de buffer in zoals opgegeven door het kenmerk SQL_ATTR_PARAMS_PROCESSED_PTR, op het nummer van de rij die momenteel wordt verwerkt. Als alle sets behalve de foutenset worden uitgevoerd, stelt het stuurprogramma deze buffer in op SQL_ATTR_PARAMSET_SIZE nadat alle rijen zijn verwerkt.

Als het kenmerk SQL_ATTR_PARAM_STATUS_PTR is ingesteld, retourneren SQLExecute of SQLExecDirect de parameterstatusarray, die de status van elke set parameters geeft. De parameterstatusmatrix wordt toegewezen door de toepassing en ingevuld door het stuurprogramma. De elementen geven aan of de SQL-instructie is uitgevoerd voor de rij parameters of dat er een fout is opgetreden tijdens het verwerken van de set parameters. Als er een fout is opgetreden, stelt het stuurprogramma de bijbehorende waarde in de parameterstatusmatrix in op SQL_PARAM_ERROR en retourneert SQL_SUCCESS_WITH_INFO. De toepassing kan de statusmatrix controleren om te bepalen welke rijen zijn verwerkt. Met behulp van het rijnummer kan de toepassing vaak de fout corrigeren en de verwerking hervatten.

Hoe de parameterstatusmatrix wordt gebruikt, wordt bepaald door de SQL_PARAM_ARRAY_ROW_COUNTS en SQL_PARAM_ARRAY_SELECTS opties die worden geretourneerd door een aanroep naar SQLGetInfo. Voor INSERT-, UPDATE- en DELETE-instructies wordt de parameterstatusmatrix ingevuld met statusinformatie als SQL_PARC_BATCH wordt geretourneerd voor SQL_PARAM_ARRAY_ROW_COUNTS, maar niet als SQL_PARC_NO_BATCH wordt geretourneerd. Voor SELECT-instructies wordt de parameterstatusmatrix ingevuld als SQL_PAS_BATCH wordt geretourneerd voor SQL_PARAM_ARRAY_SELECT, maar niet als SQL_PAS_NO_BATCH of SQL_PAS_NO_SELECT wordt geretourneerd.

Parameters voor gegevens tijdens uitvoering

Als een van de waarden in de lengte-/indicatormatrix SQL_DATA_AT_EXEC is of het resultaat is van de macro SQL_LEN_DATA_AT_EXEC(lengte), worden de gegevens voor deze waarden op gebruikelijke wijze verzonden met SQLPutData. De volgende aspecten van dit proces hebben speciale opmerkingen omdat ze niet gemakkelijk duidelijk zijn:

• Wanneer het stuurprogramma SQL_NEED_DATA retourneert, moet het adres van de rijnummervariabele worden ingesteld op de rij waarvoor gegevens nodig zijn. Net als in het geval met één waarde kan de toepassing geen veronderstellingen maken over de volgorde waarin het stuurprogramma parameterwaarden binnen één set parameters aanvraagt. Als er een fout optreedt bij het uitvoeren van een parameter voor gegevens bij uitvoering, wordt de buffer die is opgegeven door het kenmerk SQL_ATTR_PARAMS_PROCESSED_PTR instructie ingesteld op het nummer van de rij waarop de fout is opgetreden, de status voor de rij in de rijstatusmatrix die is opgegeven door het kenmerk SQL_ATTR_PARAM_STATUS_PTR instructie is ingesteld op SQL_PARAM_ERROR, en de aanroep van SQLExecute, SQLExecDirect, SQLParamData of SQLPutData retourneert SQL_ERROR. De inhoud van deze buffer is niet gedefinieerd als SQLExecute, SQLExecDirect of SQLParamData SQL_STILL_EXECUTING retourneert.

• Omdat het stuurprogramma de waarde in het argument ParameterValuePtr van SQLBindParameter niet interpreteert voor parameters voor gegevens-bij-uitvoering, als de toepassing een aanwijzer naar een matrix levert, haalt SQLParamData geen element van deze matrix op en retourneert deze naar de toepassing. In plaats daarvan wordt de scalaire waarde geretourneerd die de toepassing had opgegeven. Dit betekent dat de waarde die wordt geretourneerd door SQLParamData niet voldoende is om de parameter op te geven waarvoor de toepassing gegevens moet verzenden; de toepassing moet ook rekening houden met het huidige rijnummer.

  Wanneer slechts enkele elementen van een array met parameters uitvoeringsgegevens-parameters zijn, moet de toepassing het adres van een array in ParameterValuePtr doorgeven die elementen voor alle parameters bevat. Deze matrix wordt normaal gesproken geïnterpreteerd voor de parameters die geen gegevens-bij-uitvoering parameters zijn. Voor de gegevens-bij-uitvoering-parameters is de waarde die SQLParamData aan de applicatie biedt, en die normaal gesproken kan worden gebruikt om de gegevens te identificeren die het stuurprogramma bij deze gelegenheid aanvraagt, altijd het adres van de array.