Automatische query-providers

Beschikbaar sinds versie 2.384.99 via de XLSX-werkmapfacade op Windows; automatische providerselectie gebeurt uitsluitend tijdens een expliciete query-vernieuwing

Een bestaande query vernieuwen

Workbook.QueryProviders.BaseDirectory := 'C:\Data';
Workbook.QueryProviders.MaxInputBytes := 64 * 1024 * 1024;
Workbook.QueryProviders.MaxResultCells := 2000000;
Workbook.QueryProviders.TimeoutSeconds := 30;
Status := Sheet.RefreshQueryTable('ImportedData', 1000000);

TXLSXWorkbook.QueryProviders: TXLSQueryProviderDispatcher stelt een door de werkmap beheerde dispatcher uit lxQueryProviders beschikbaar; geef de dispatcher niet zelf vrij

TXLSXWorksheet.RefreshQueryTable(const AName: WideString; AMaxRows: Integer = 1000000; AOnProgress: TXLSQueryRefreshProgress = nil): Integer en de overload met een zero-based AIndex selecteren een bestaande query en gebruiken deze dispatcher

Bestaande overloads die een expliciete TXLSQueryTableProvider accepteren blijven die provider rechtstreeks gebruiken, inclusief hun huidige afwijzing van een ontbrekende provider; ze vallen niet terug op automatische dispatch

Vernieuwen geeft 1 bij succes terug, 0 bij annulering of -1 bij een fout, met diagnostische codes 1401 en 1400 onder xlsOperationRefresh; de bestaande transactionele resultaatverwerking, schemavalidatie, literalen en opmaakgedrag blijven onveranderd

Deze diagnoses heten xlsDiagnosticQueryRefreshCancelled en xlsDiagnosticQueryRefreshFailed; de schrijfbewaking van de werkmap wordt verkregen vóór de statusconversie, dus een bevroren leesweergave of een andere afwijzing door de schrijfbewaking geeft een exception

Openen en opslaan van een werkmap haalt nooit verbindingsgegevens op, evalueert nooit query's en doet niets met bewaarde RefreshOnLoad-metadata; vernieuw elke benodigde query expliciet voordat je het resultaat opslaat

Ondersteunde ingebouwde providers

• xlckText leest lokale tekst met scheidingstekens of vaste kolombreedtes met strikte decoding als UTF-8, UTF-16LE, UTF-16BE, Windows-1252 of Latin-1, geconfigureerde startrijen en ondersteunde veldtypen, waaronder zes datumvolgordes en overgeslagen velden; invoer met scheidingstekens ondersteunt ook geciteerde records over meerdere regels
• xlckAdo, xlckOleDb en xlckOdbc gebruiken geïnstalleerde Windows ADO- en database-drivers met alleen-lezen verbindingen en recordsets; CommandType = 2 kiest SQL-tekst en CommandType = 3 kiest een tabelopdracht
• xlckWeb gebruikt Windows WinHTTP voor een anonieme HTTP- of HTTPS-GET van één niet-lege rechthoekige HTML-tabel, geselecteerd op positieve index of naam; ondersteunde tekensets voor het antwoord zijn UTF-8, UTF-16, Windows-1252 en Latin-1

BaseDirectory levert uitsluitend de basis voor relatieve lokale tekstpaden; database-connectiestrings en web-URL's blijven expliciete verbindingsmetadata

Een niet-opgegeven tekstcodering accepteert uitsluitend ASCII-invoer, tenzij een ondersteund byte order mark de codering identificeert; niet-ASCII-invoer vereist een expliciete ondersteunde codering of een byte order mark

Zet voor een Text-verbinding met scheidingstekens TextPrompt = False, TextDelimited = True en precies één scheidingsteken, zonder opeenvolgende scheidingstekens samen te vouwen; nieuw aangemaakte verbindingen vragen standaard om invoer en gebruiken een tabscheidingsteken, dus maak TextTab leeg wanneer je een ander scheidingsteken kiest

Tekst met vaste kolombreedte

Zet TextPrompt = False en TextDelimited = False en voeg daarna TextFields toe in strikt stijgende zero-based Position-volgorde, beginnend bij nul; elk veld eindigt op de volgende positie of bij de fysieke recordscheiding, en xltiftSkip sluit zijn veld uit van het resultaat

Posities tellen gedecodeerde UTF-16-code-eenheden en niet invoerbytes; een grens die een surrogaatpaar splitst wordt geweigerd, en CRLF, LF en CR beëindigen records onafhankelijk van de instellingen voor scheidingsteken en kwalificatieteken

Veldopvulling wordt vóór de conversie getrimd, inclusief expliciet getypeerde tekst, conform het geverifieerde native importgedrag voor vaste kolombreedtes; aanhalingstekens, tabs en scheidingstekens binnen een veld blijven letterlijke invoer, en korte records leveren lege velden achteraan op zonder het gedeclareerde schema te wijzigen

Zonder TextFields is elk record één algemeen veld; TextFirstRow selecteert het eerste schemarecord, Query.Headers slaat de waarden van dat record over en expliciete lege records blijven rijen

De bestaande limieten voor rijen, invoerbytes, resultaatcellen en velden van 32767-code-eenheden gelden; ongeldige metadata, conversiefouten of overdreven invoer wissen de staging-gegevens vóór de transactionele werkbladupdate, en annulering behoudt de vorige resultaatcellen

Connection.TextPrompt := False;
Connection.TextDelimited := False;
Connection.TextFields.Add(xltiftGeneral, 0);
Connection.TextFields.Add(xltiftText, 8);
Status := Sheet.RefreshQueryTable('Imported');

Zet voor een Web-verbinding WebHtmlTables = True en WebHtmlFormat = 'none'; ondersteunde aanvragen weigeren ingesloten inloggegevens, fragmenten, authenticatie en redirects

De ingebouwde providers weigeren niet-ondersteunde metadata binnen hun eigen verbindingssoort; databasevernieuwing weigert OLAP- of serveropdrachten, omleiding via verbindingsbestanden, opgeslagen wachtwoorden en vragen om inloggegevens, Text-vernieuwing weigert bestandsvragen, en Web-vernieuwing vereist anonieme tabelmetadata

Getypeerde databaseparameters

SQL-tekstopdrachten ondersteunen positionele ?-markeringen die via een ADO Command worden gebonden, in de volgorde van Connection.Parameters; parameterwaarden vervangen nooit de SQL-tekst, en namen labelen bindingen zonder de positionele volgorde te veranderen

De preflight telt markeringen buiten strings met enkele aanhalingstekens, identifiers met dubbele aanhalingstekens of backticks, tussen haken geplaatste identifiers, regelcommentaar en genest blokcommentaar, inclusief verdubbelde aanhaal- of haakjes-escapes; ongebalanceerde aanhalingstekens of commentaar en een afwijkend aantal markeringen worden geweigerd vóór het openen van een verbinding

Gebruik ParameterType = 'value' met een expliciete ValueKind van xlcpvInteger, xlcpvDouble, xlcpvBoolean of xlcpvString en de bijbehorende waarde-eigenschap; nul, False en lege strings zijn gewoon waarden, en xlcpvNone leidt tijdens de uitvoering geen waarde af

Connection.CommandType := 2;
Connection.CommandText := 'SELECT Amount FROM Sales WHERE Amount > ?';
with Connection.Parameters.Add do
begin
  Name := 'MinimumAmount';
  ParameterType := 'value';
  ValueKind := xlcpvInteger;
  IntegerValue := 0;
  SqlType := 4;
end;
Status := Sheet.RefreshQueryTable('SalesQuery');

Gebruik ParameterType = 'cell', ValueKind = xlcpvCell en CellReference voor een volledig gekwalificeerde lokale werkbladverwijzing zoals Inputs!$A$1 of 'Sales Input'!B2; gequote bladnamen gebruiken verdubbelde apostrofs, en bereiken, externe werkmappen, namen en niet-gekwalificeerde celverwijzingen worden geweigerd

Werkbladvernieuwing maakt een snapshot van opgeslagen scalaire waarden en beschikbare formulecaches zonder herberekening of materialisatie van packed cells; ontbrekende formulecaches en foutcellen worden geweigerd, terwijl een ontbrekende of lege cel uitsluitend SQL null levert bij een expliciet ondersteund SQL-type

De cel-snapshot behoudt zijn Variant-type en staat signed Int64-, Currency-, getypeerde datum- en null-invoer toe zonder die terug te brengen tot de opgeslagen 32-bits integer- of Double-literaalvelden; direct opgeslagen datum-, null- en Int64-literalen vallen buiten het native metadata-model voor parameters, dus gebruik getypeerde celbindingen voor die waarden

SqlType gebruikt ODBC-SQL-typecodes die expliciet naar ADO-typen worden gemapt; het is geen ADO DataTypeEnum-waarde

Ondersteunde expliciete typen accepteren ook SQL null; arrays, referentie-Variants, fouten, niet-eindige getallen, niet-ondersteunde SQL-typen en conversies die integerprecisie zouden verliezen worden geweigerd, en NUMERIC of DECIMAL vereisen precisie- en schaal-metadata die deze binding-API niet aanbiedt

ADO ontvangt de getypeerde waarde en de gedeclareerde grootte, met minstens één toegewezen code-eenheid voor lege tekst; native drivers blijven verantwoordelijk voor SQL-dialect, ondersteunde parametertypes en resultaatconversies, dus een geïnstalleerde provider kan alsnog een geldige binding weigeren of nauwere numerieke of datumcapaciteiten hebben

Jet en ACE gebruiken getypeerde OLE DATE-bindingen voor gevalideerde DATE-, TIME- en TIMESTAMP-waarden om datum en tijd onafhankelijk van landspecifieke tijdstempeltekstprojecties te behouden; de validatieregels voor DATE en TIME blijven gelden, en null-projectatie blijft providerspecifiek

Parameters vereisen een SQL-tekstopdracht en zijn beperkt tot 1024 per fetch, 255 code-eenheden per naam en 32767 code-eenheden per tekstwaarde; opdrachttekst, parameterverwijzingen, namen en payloads verbruiken ook het invoerbytebudget

Vragen om invoer en onbekende parameterextensie-attributen worden geweigerd; RefreshOnChange blijft bewaarde metadata en start geen achtergrondvernieuwing, en openen of opslaan lost geen cellen op en voert geen opdrachten uit

Directe Fetch ondersteunt literalen; FetchWithCellResolver(Connection, Query, MaxRows, out Data, var Abort, AResolver) accepteert een TXLSQueryParameterCellResolver-callback voor celwaarden, waarvan het Boolean-resultaat aangeeft of een opgeslagen waarde beschikbaar is

De callback geldt alleen voor de aanroep zelf en wordt niet bewaard; automatische werkbladvernieuwing levert zijn eigen lokale resolver, en geregistreerde aangepaste providers behouden voorrang en bepalen hun eigen parameterssemantiek

Web-vernieuwing ondersteunt gewone text/html-tabellen zonder cellen die over kolommen lopen, geneste geselecteerde tabellen of scriptgestuurde inhoud; niet-ondersteunde layouts en entiteiten worden geweigerd in plaats van gedeeltelijke gegevens op te leveren

Een aangepaste provider registreren

Workbook.QueryProviders.RegisterProvider(xlckWeb, CustomProvider);
try
  Status := Sheet.RefreshQueryTable('RemoteData');
finally
  Workbook.QueryProviders.RegisterProvider(xlckWeb, nil);
end;

TXLSQueryProviderDispatcher.Create construeert een onafhankelijk beheerde dispatcher voor direct gebruik; de werkmap maakt en beheert zijn eigen instantie

RegisterProvider(AKind: TXLSConnectionKind; AProvider: TXLSQueryTableProvider) installeert een geleende handler voor een gedeclareerde verbindingssoort, en nil heft de registratie op; de handler moet beschikbaar blijven zolang de registratie bestaat

Een geregistreerde handler heeft voorrang op de ingebouwde provider en kan toepassingsspecifieke authenticatie of verbindingssoorten ondersteunen; registratiewijzigingen, configuratiewijzigingen en recursieve dispatch worden geweigerd tijdens het ophalen, en ongeldige enum-waarden worden geweigerd vóór arraytoegang

Fetch(Connection, Query, MaxRows, out Data, var Abort) ontvangt losgemaakte metadata tijdens werkbladvernieuwing en geeft een rechthoekige TXLSQueryResultData terug; annulering of exceptions wissen de staging-resultaten voordat ze worden doorgegeven

Resourcelimieten

MaxInputBytes staat standaard op 67108864 bytes en begrenst tekst- of web-invoer en ondersteunde database-resultaatpayloads; MaxResultCells staat standaard op 2000000 cellen en begrenst het rechthoekige resultaat

TimeoutSeconds staat standaard op 30 en configureert ondersteunde native database- of HTTP-fasen; het is geen gegarandeerde deadline voor de volledige bewerking of voor een aangepaste provider

Alle drie de instellingen en MaxRows moeten positief zijn, en de timeout moet in een native milliseconde-integer passen; de dispatcher weigert overtollige rijen, kolommen of cellen zonder af te kappen, terwijl byte- en invoerlimieten door de ingebouwde providers worden afgedwongen en bij aangepaste fetches de verantwoordelijkheid van de geregistreerde handler blijven

Werkbladvernieuwing valideert alle resultaatwaarden en herstelt cellen en query- of tabelmetadata na annulering of toepassingsfouten; aangepaste providers blijven verantwoordelijk voor het naleven van hun eigen limieten voor externe bewerkingen

Native XLSX-resultaatbindingen

Op tabellen gebaseerde databasequery's gebruiken de tabel-naar-querytabel-relatie, samenhangende veld-ID's, kolomidentiteiten en een verborgen lokale doelnaam; zelfstandige ondersteunde Text- en Web-bestemmingen behouden hun resultaatbereik

TXLSXTable.ColumnUniqueNames[Index]: WideString stelt zero-based native kolomidentiteiten beschikbaar en behoudt die bij toewijzing, kopiëren en heropenen, samen met ColumnQueryTableFieldIds

Een verouderde Text-verbinding die direct als externe tabel is gebonden is geen ondersteunde native exportvorm en opslaan weigert die vóór de uitvoer; expliciet vernieuwde tekstwaarden kunnen een gewone tabel vullen, of een geïnstalleerde ADO/ODBC-tekstdriver kan een native op tabellen gebaseerde databasequery bieden

Niet-gerelateerde of niet-ondersteunde geïmporteerde relaties en extensie-XML blijven behouden; deze functie zet ondoorzichtige externe grafen niet om in ondersteunde vernieuwbare query's

Zie verbindings- en transactionele query-API's voor doelvalidatie, progress-callbacks en het omringende metadata-model