Lange gegevens verzenden

DBMS's definiëren lange gegevens als elk teken of binaire gegevens over een bepaalde grootte, zoals 254 tekens. Het is mogelijk niet mogelijk om een heel item met lange gegevens in het geheugen op te slaan, bijvoorbeeld wanneer het item een lang tekstdocument of een bitmap vertegenwoordigt. Omdat dergelijke gegevens niet in één buffer kunnen worden opgeslagen, verzendt de gegevensbron deze naar het stuurprogramma in delen met SQLPutData wanneer de instructie wordt uitgevoerd. Parameters waarvoor gegevens tijdens de uitvoering worden verzonden, worden parameters voor gegevens bij uitvoering genoemd.

De toepassing voert de volgende acties uit om gegevens te verzenden tijdens de uitvoering:

1. Geeft een 32-bits waarde door die de parameter identificeert in het argument ParameterValuePtr in SQLBindParameter in plaats van het adres van een buffer door te geven. Deze waarde wordt niet geanalyseerd door het stuurprogramma. Deze wordt later teruggezet naar de toepassing, dus het moet iets betekenen voor de toepassing. Dit kan bijvoorbeeld het nummer zijn van de parameter of de ingang van een bestand met gegevens.

2. Geeft het adres van een lengte/indicatorbuffer door in het argument StrLen_or_IndPtr van SQLBindParameter.

3. Slaat SQL_DATA_AT_EXEC of het resultaat van de macro SQL_LEN_DATA_AT_EXEC(lengte) op in de lengte/indicatorbuffer. Beide waarden geven aan het stuurprogramma aan dat de gegevens voor de parameter worden verzonden met SQLPutData. SQL_LEN_DATA_AT_EXEC(lengte) wordt gebruikt bij het verzenden van lange gegevens naar een gegevensbron die moet weten hoeveel bytes lange gegevens worden verzonden, zodat ruimte vooraf kan worden toegewezen. Om te bepalen of een gegevensbron deze waarde vereist, roept de toepassing SQLGetInfo aan met de optie SQL_NEED_LONG_DATA_LEN. Alle stuurprogramma's moeten deze macro ondersteunen; als de gegevensbron de bytelengte niet vereist, kan het stuurprogramma deze negeren.

4. Roept SQLExecute of SQLExecDirect aan. Het stuurprogramma detecteert dat een lengte/indicatorbuffer de waarde bevat SQL_DATA_AT_EXEC of het resultaat van de macro SQL_LEN_DATA_AT_EXEC(lengte) en retourneert SQL_NEED_DATA als de retourwaarde van de functie.

5. Roept SQLParamData aan als reactie op de SQL_NEED_DATA retourwaarde. Als lange gegevens moeten worden verzonden, retourneert SQLParamData SQL_NEED_DATA. In de buffer waarnaar het argument ValuePtrPtr verwijst, retourneert de driver de waarde die de uitvoeringsparameter van gegevens identificeert. Als er meer dan één gegevens-voor-executieparameter is, moet de toepassing deze waarde gebruiken om te bepalen voor welke parameter gegevens moeten worden verzonden; het stuurprogramma hoeft niet gegevens op te vragen voor gegevens-voor-executieparameters in een bepaalde volgorde.

6. Roept SQLPutData aan om de parametergegevens naar het stuurprogramma te verzenden. Als de parametergegevens niet in één buffer passen, zoals vaak het geval is bij lange gegevens, roept de toepassing SQLPutData herhaaldelijk aan om de gegevens in delen te verzenden; het is aan het stuurprogramma en de gegevensbron om de gegevens opnieuw samen te stellen. Als de toepassing null-beëindigde tekenreeksgegevens doorgeeft, moet het stuurprogramma of de gegevensbron het null-beëindigingskarakter verwijderen tijdens het herassembleerproces.

7. Roept SQLParamData opnieuw aan om aan te geven dat alle gegevens voor de parameter zijn verzonden. Als er parameters voor gegevens-uitvoering zijn waarvoor geen gegevens zijn verzonden, retourneert het stuurprogramma SQL_NEED_DATA en de waarde die de volgende parameter identificeert. De toepassing keert daarna terug naar stap 6. Als er gegevens zijn verzonden voor alle uitvoeringsgegevensparameters, wordt de instructie uitgevoerd. SQLParamData retourneert SQL_SUCCESS of SQL_SUCCESS_WITH_INFO en kan elke retourwaarde of diagnose retourneren die SQLExecute of SQLExecDirect kan retourneren.

Nadat SQLExecute of SQLExecDirect SQL_NEED_DATA retourneert en voordat de gegevens volledig zijn verzonden voor de laatste data-at-execution-parameter, bevindt de instructie zich in een Gegevens nodig-status. Hoewel een instructie de status Need Data heeft, kan de toepassing alleen SQLPutData, SQLParamData, SQLCancel, SQLGetDiagField of SQLGetDiagRec aanroepen; alle andere functies retourneren SQLSTATE HY010 (functiereeksfout). Het aanroepen van SQLCancel annuleert de uitvoering van de instructie en retourneert deze naar de vorige status. Zie bijlage B: ODBC-statusovergangstabellen voor meer informatie.

Zie de beschrijving van de functie SQLPutData voor een voorbeeld van het verzenden van gegevens tijdens de uitvoering.