WklTimerList

WklTimerList führt geplante Aufgaben für ein Access-Formular aus: eine Suche, die 400 ms nach dem letzten Tastendruck beginnt, einen Zähler, der alle 30 Sekunden aktualisiert wird, eine Warteschlange von Webanfragen, die das Limit eines Datendienstes einhält. Ein Steuerelement nimmt beliebig viele Aufgaben auf, jede mit eigenem Schlüssel, eigener Verzögerung, eigenem Intervall und eigenen Regeln für Überschneidungen, Wiederholungsversuche und Zeitlimits. In der Entwurfsansicht ist es sichtbar, in der Formularansicht unsichtbar.

Seit Release 1.60.0. Die Arten wttEvent und wttHttp sind verfügbar; wttSteps, wttFile, wttChecksum, wttZip und wttProgram gehören zum Vertrag, werden in dieser Version aber mit wkeNotAvailable abgelehnt.

Erste Schritte

Liste durchsuchen, während der Benutzer tippt: eine verzögerte Suche und ein Zähler, der alle 30 Sekunden aktualisiert wird.

Häufige Aufgaben

Eine Suche 400 ms nach dem letzten Tastendruck starten: eine Aufgabe mit Delay = 400, Restart im Ereignis Change des Textfelds.
Einen Zähler alle 30 Sekunden aktualisieren: eine Aufgabe mit Interval = 30000, AutoStart = True.
1.700 Anfragen an einen Dienst senden, der 300 pro Minute zulässt: eine Aufgabe der Art wttHttp mit RateLimit = 300, RateWindow = 60000, ein Requests.Add je Zeile mit dem Schlüssel der Zeile als Tag (Viele Anforderungen im Takt eines Webdiensts senden).

Schaubild

graph TD
    A[Formular öffnet sich] --> B{AutoStart}
    B -->|True| C[Aufgaben warten]
    B -->|False| D[Aufgaben angehalten bis Start]
    D --> C
    C -->|fällig, wttEvent| E[TaskDue an das Formular übergeben]
    E -->|Prozedur beendet| C
    C -->|fällig, wttHttp| F[Warteschlange sendet ihre Anfragen]
    F -->|jede Antwort| R[RequestCompleted oder RequestFailed]
    R --> F
    F -->|Warteschlange leer| G[TaskCompleted]
    G -->|Interval größer als 0| C
    X[Formular schließt sich] --> J[Alle Aufgaben enden, danach kein Ereignis mehr]

Wichtige Funktionen

Mehrere Aufgaben je Formular, jede durch einen Schlüssel gekennzeichnet; einzeln oder alle zusammen gestartet, angehalten, pausiert und fortgesetzt.
Erster Fälligkeitszeitpunkt nach einer Verzögerung ab dem Start oder zu einer Uhrzeit.
Wiederholung in einem festen Intervall, das ab dem Fälligkeitszeitpunkt zählt, nicht ab dem Ende des Laufs: Ein Lauf von 2 Sekunden verschiebt eine 30-Sekunden-Reihe nicht.
Überschneidungsregel für Fälligkeitszeitpunkte, die verstreichen, während ein Lauf noch andauert: verwerfen (wtoSkip) oder genau einen behalten (wtoOnce). Die Warteschlange wächst nie.
Wiederholungsversuche und Zeitlimits je Aufgabe.
Arten von Arbeit: ein VBA-Ereignis (wttEvent), VBA in Schritten (wttSteps) und Aufträge, die das Steuerelement selbst im Hintergrund ausführt: Webanfrage (wttHttp), Dateien kopieren oder verschieben (wttFile), Prüfsumme (wttChecksum), ZIP (wttZip), externes Programm (wttProgram).
Getaktete Webanfragen: ein Mindestabstand, ein Limit je Zeitfenster, eine Pause, wenn der Dienst mit 429 antwortet, ein Anhalten der ganzen Warteschlange bei 401, bis sich die Anwendung neu anmeldet.

Grundkonzepte

Ein Zeitgeber macht VBA nicht parallel. VBA, Formulare, DAO und das Objektmodell von Access laufen im Hauptthread von Access. Eine Aufgabe der Art wttEvent oder wttSteps läuft in diesem Thread, wenn sie fällig ist; nur die Hintergrundarten laufen anderswo, und ihre Ergebnisse kommen als Ereignisse in den Hauptthread zurück.

Ereignisse werden eingereiht, nie aus einem anderen Ereignis heraus ausgelöst. VBA stellt ein Ereignis eines Objekts nicht zu, während eine Ereignisprozedur desselben Objekts läuft. Das Steuerelement reiht deshalb jedes fällige Ereignis in sein eigenes Nachrichtenfenster ein und stellt es zu, nachdem die laufende Prozedur beendet ist. Eine MsgBox in einer Ereignisprozedur verzögert das nächste Ereignis; verloren geht es nicht.

Ein eigenes Nachrichtenfenster. Ein ActiveX-Steuerelement, das in Access unsichtbar oder deaktiviert ist, hat kein Fenster und empfängt keine Nachrichten. Die Zeitgeberliste verwendet ein ausgeblendetes reines Nachrichtenfenster, das vom Öffnen bis zum Schließen des Formulars besteht, gleichgültig, was Visible und Enabled angeben.

Das Leben einer Aufgabe endet mit dem Formular. Wenn sich das Formular schließt, hält jede Aufgabe an, laufende Hintergrundaufträge werden abgebrochen, und danach trifft kein Ereignis mehr ein.

Die Uhr. Verzögerungen und Intervalle zählen auf einem monotonen Zähler; ein Benutzer, der die Uhr von Windows vor- oder zurückstellt, lässt eine Aufgabe deshalb weder zu früh noch zu spät auslösen. StartAt ist eine lokale Uhrzeit.

Regeln

Diese Regeln entscheiden, wann eine Aufgabe fällig ist. Sie gelten für jede Art von Aufgabe gleich.

Situation	Verhalten
`Start` mit `Delay = 0` und ohne `StartAt`	Sofort fällig.
`StartAt` in der Zukunft	Zu dieser Uhrzeit fällig.
`StartAt` in der Vergangenheit, `Interval = 0`	Sofort fällig.
`StartAt` in der Vergangenheit, `Interval > 0`	Fällig zum nächsten Zeitpunkt der Reihe `StartAt + n × Interval` nach dem aktuellen Zeitpunkt.
Lauf abgeschlossen, `Interval > 0`	Nächster Fälligkeitszeitpunkt = vorheriger Fälligkeitszeitpunkt + `Interval`.
Lauf abgeschlossen, `Interval = 0`	Zustand `wtsDone`.
Während des Laufs verstrichene Fälligkeitszeitpunkte, `wtoSkip`	Sie werden verworfen; nächster Fälligkeitszeitpunkt ist der nächste der Reihe nach dem aktuellen Zeitpunkt.
Während des Laufs verstrichene Fälligkeitszeitpunkte, `wtoOnce`	Ein Lauf folgt sofort; die übrigen werden verworfen.
`Trigger` während eines Laufs, `wtoOnce`	Ein weiterer Lauf wird vorgemerkt; weitere Auslöser fügen keine weiteren hinzu.
`Trigger` während eines Laufs, `wtoSkip`	Wird ignoriert.
Lauf fehlgeschlagen, `Retries` übrig	Derselbe Lauf (dieselbe `RunId`) wird nach `RetryDelay` wiederholt; `TaskFailed` mit `WillRetry = True`.
Lauf fehlgeschlagen, keine Wiederholungsversuche übrig	`TaskFailed` mit `WillRetry = False`; `LastError` behält den Text; die Reihe läuft weiter, wenn `Interval > 0`.
Lauf abgebrochen	Wird nie wiederholt.
Lauf dauert länger als `Timeout`	Hintergrundaufträge: Der Versuch wird abgebrochen (bei einer Warteschlange von Webanfragen je Anfrage, siehe unten). Ein `wttEvent`-Lauf ist die VBA-Ereignisprozedur und lässt sich nicht unterbrechen; `Timeout` wirkt sich darauf nicht aus.
`Pause`	Die verbleibende Zeit wird festgehalten; `Resume` setzt damit fort.
`Stop` während eines Laufs	Der Lauf endet normal; danach wird nichts mehr geplant, und kein vorgemerkter Lauf folgt.
`Restart`	Die Verzögerung beginnt ab dem aktuellen Zeitpunkt neu: die verzögerte Suche nach jedem Tastendruck.
`Enabled = False`	Nie fällig, auch nicht bei `Trigger`.

Regeln für Webanfragen (wttHttp). Eine Aufgabe dieser Art ist eine Warteschlange: Sie nimmt beliebig viele Anfragen auf, sendet sie nacheinander und hält den folgenden Takt für alle zusammen ein.

Situation	Verhalten
`MinGap`	Die kürzeste Zeit zwischen zwei Anfragestarts der Warteschlange.
`RateLimit`, `RateWindow`	Höchstens `RateLimit` Starts in jedem Zeitraum von `RateWindow` Millisekunden. Beide lassen sich in beliebiger Reihenfolge setzen; `Start` einer Warteschlange mit `RateLimit`, aber ohne `RateWindow` wird mit `wkeInvalidValue` abgelehnt.
Antwort 429 mit `Retry-After`	Die ganze Warteschlange pausiert für diese Zeit (Sekunden oder ein HTTP-Datum, RFC 9110, Abschnitt 10.2.3); eine bereits gesetzte längere Pause bleibt bestehen. `QueuePaused` meldet Grund und Ende. Die Anfrage wird erneut gesendet.
Antwort 429 ohne `Retry-After`	Wie oben, für `RateWindow` Millisekunden; ohne `RateWindow` für 60 Sekunden.
Antwort 401	Die ganze Warteschlange hält an; nur `QueueHalted` meldet das, mit dem Status und den Antwortheadern. Die Anwendung meldet sich im Hauptthread neu an, setzt die gemeinsamen Header und ruft `Resume` auf; die angehaltene Anfrage wird als erste erneut gesendet.
Ein zweites 401 in Folge für dieselbe Anfrage	`RequestFailed` für diese Anfrage (damit eine fehlgeschlagene Anmeldung keine Endlosschleife erzeugt), und die Warteschlange hält mit `QueueHalted` erneut an.
Keine Antwort (Verbindung unterbrochen, Zeitlimit)	Erneut gesendet nach `RetryDelay`, solange `Retries` übrig sind, vor jeder anderen wartenden Anfrage.
`Timeout`, `Retries`, `RetryDelay`	Gelten je Anfrage und je Versuch, nicht für die ganze Warteschlange.
Jede andere Antwort, auch 5xx	Mit `RequestFailed` gemeldet, nie erneut gesendet: Eine Wiederholung könnte die Arbeit doppelt ausführen.
Eine Wiederholung	Sendet dieselben eigenen Header, denselben Body und denselben `Idempotency-Key`. Gemeinsame Header werden bei jedem Senden gelesen; ein neuer Sitzungsheader nach einem 401 gilt daher für sie und für jede noch wartende Anfrage.
`Stop`	Es wird nichts mehr gesendet. Die Anfrage, die unterwegs ist, wird nicht abgebrochen: Ihre Antwort kommt und wird gemeldet, weil eine geschlossene Verbindung beim Dienst eine Änderung hinterlassen kann, deren Ausgang niemand kennt. Die noch nicht gesendeten Anfragen bleiben im Zustand `wrsWaiting`, ohne Ereignis. `Start` sendet sie.
`Requests.Clear` oder `Request.Cancel`	Jede noch nicht erledigte Anfrage endet mit `RequestCancelled` und dem Zustand `wrsCancelled`; bei einer Anfrage, die unterwegs ist, wird die Verbindung geschlossen, und sie wird nie erneut gesendet. Ihr Ausgang beim Dienst ist unbekannt: Senden Sie sie selbst mit demselben `IdempotencyKey` erneut, wenn der Dienst das unterstützt.
Mehrere Warteschlangen für denselben Dienst	Teilen ihren Takt nicht: Jede hält ihr eigenes `MinGap` und `RateLimit` ein. Legen Sie alle Anfragen an einen Dienst in eine Warteschlange, zum Beispiel auf dem Formular des Anwendungsrahmens.
Die Warteschlange ist leer	`TaskCompleted` mit `Result` = `Array(completed, failed)`, den Anzahlen der in diesem Lauf abgeschlossenen und endgültig fehlgeschlagenen Anfragen. Später hinzugefügte Anfragen starten die Warteschlange erneut, solange die Aufgabe gestartet ist.

Codierung, Anmeldung und Geheimnisse:

Thema	Regel
Body der Anfrage	Als UTF-8 mit dem `ContentType` der Anfrage gesendet (Standardwert `application/json; charset=utf-8`).
Antworttext	`Result.Text` wird nach dem `charset` der Antwort decodiert; ohne Angabe als UTF-8.
Windows-Anmeldung	`UseWindowsLogin = True` meldet sich mit dem Windows-Konto des Access-Prozesses an (Negotiate, NTLM), wenn der Dienst danach fragt. Standardwert `False`.
Geheimnisse	Gemeinsame Header, eigene Header sowie Bodys von Anfragen und Antworten bleiben ausschließlich im Arbeitsspeicher. Das Ablaufprotokoll und die Fehlertexte nennen die Methode, die Adresse ohne ihren Abfrageteil und den Status; nie einen Headerwert oder einen Body.

Vertrag

WklTimerList (Steuerelement) mit der Auflistung Tasks aus WklTimerTask.

Member von `WklTimerTask`	Bedeutung
`Key`	Eindeutiger Text, verglichen ohne Beachtung der Groß- und Kleinschreibung.
`Enabled`	Die Aufgabe nimmt teil.
`Kind`	`wttEvent`, `wttSteps`, `wttHttp`, `wttFile`, `wttChecksum`, `wttZip`, `wttProgram`.
`Delay`, `StartAt`	Erster Fälligkeitszeitpunkt: Millisekunden nach `Start` oder eine Uhrzeit.
`Interval`	Wiederholung in Millisekunden; 0 = einmal.
`Overlap`	`wtoSkip` oder `wtoOnce`.
`Timeout`, `Retries`, `RetryDelay`	Zeitlimit eines Laufs (0 = keines), Wiederholungsversuche nach einem Fehlschlag, Wartezeit vor einem Wiederholungsversuch.
`Tag`	Beliebiger Wert; wird unverändert an jedes Ereignis übergeben.
`State`	`wtsStopped`, `wtsWaiting`, `wtsRunning`, `wtsPaused`, `wtsDone` (schreibgeschützt).
`RunCount`, `LastRun`, `NextRun`, `LastError`	Schreibgeschützt.
`Start`, `Stop`, `Pause`, `Resume`, `Trigger`, `Restart`	Siehe Regeln.

Member von `WklTimerList`	Bedeutung
`Tasks`	Die Aufgaben; `Add(Key)`, `Remove(Key)`, `Item(Key)`, `Count`.
`Start`, `Stop`, `Pause`, `Resume`	Für alle Aufgaben.
`AutoStart`	Alle Aufgaben starten, wenn sich das Formular öffnet.
`Running`	Die Anzahl der laufenden Läufe.
`MaxParallel`	Gleichzeitige Hintergrundaufträge; Standardwert 1. Reserviert für die Arten Datei, Prüfsumme, ZIP und Programm; jede Warteschlange von Webanfragen sendet immer eine Anfrage nach der anderen, und mehrere Warteschlangen laufen nebeneinander.

Ereignis	Wann
`TaskDue(Key, RunId, Tag, Cancel)`	Ein `wttEvent`-Lauf ist fällig; die Ereignisprozedur ist der Lauf. `Cancel = True` überspringt ihn; die Reihe läuft weiter. Eine Warteschlange von Webanfragen löst stattdessen `TaskStarted` aus, mit ihrer ersten Anfrage.
`TaskStep(Key, RunId, Step, Done, Progress)`	Nur `wttSteps`: einmal je Schritt; Access erhält zwischen den Schritten die Kontrolle zurück.
`TaskStarted(Key, RunId)`	Ein Hintergrundauftrag hat begonnen.
`TaskProgress(Key, RunId, Percent, Text)`	Ein Hintergrundauftrag meldet seinen Fortschritt.
`TaskCompleted(Key, RunId, Result)`	Ein Hintergrundlauf wurde erfolgreich beendet; bei einer Warteschlange von Webanfragen ist die Warteschlange leer geworden. Ein `wttEvent`-Lauf löst keines aus: Sein Lauf ist `TaskDue`.
`TaskFailed(Key, RunId, Number, Description, WillRetry)`	Ein Lauf ist fehlgeschlagen.
`TaskCancelled(Key, RunId, Reason)`	Ein Lauf wurde abgebrochen (durch `Stop` eines Hintergrundauftrags, durch das Zeitlimit, durch das Schließen des Formulars).

Result je Art: Dateien und ZIP Files, Bytes; Prüfsumme Hash; Programm ExitCode, Output, ErrorOutput.

Warteschlange von Webanfragen

Member einer WklTimerTask der Art wttHttp:

Member	Bedeutung
`Requests`	Die Anfragen der Warteschlange; `Add(Method, Url, [Body], [Tag], [ContentType]) As WklHttpRequest`, `Item(Id)`, `Count` (auch erledigte), `Waiting` (noch nicht gesendet), `Clear`, `Forget` (entfernt erledigte Anfragen und gibt zurück, wie viele).
`SharedHeader(Name)`	Liest und schreibt einen Header, der mit jeder Anfrage der Warteschlange gesendet wird, zum Beispiel `X-Api-Key`, `Authorization` oder den Sitzungsheader eines zweiten Faktors. Ein leerer Wert entfernt ihn.
`MinGap`, `RateLimit`, `RateWindow`	Der Takt, siehe Regeln.
`UseWindowsLogin`	Anmeldung mit dem Windows-Konto, siehe oben.
`Halted`, `PausedUntil`	Schreibgeschützt: Die Warteschlange wartet nach einem 401 auf `Resume`; das Ende einer Pause nach 429 oder `Null`.

Member von WklHttpRequest:

Member	Bedeutung
`Id`	Nummer der Anfrage, eindeutig in der Aufgabe; wird an jedes Anfrageereignis übergeben.
`Method`, `Url`, `Body`, `ContentType`	Wie an `Add` übergeben; änderbar, bis die Anfrage gesendet ist.
`Header(Name)`	Ein eigener Header dieser Anfrage.
`IdempotencyKey`	Wird als `Idempotency-Key` gesendet; standardmäßig eine neue GUID, für jede Wiederholung dieselbe. Ein leerer Wert sendet keinen.
`Tag`	Beliebiger Wert; wird unverändert an jedes Anfrageereignis übergeben, zum Beispiel der Schlüssel einer Zeile.
`State`	`wrsWaiting`, `wrsSending`, `wrsCompleted`, `wrsFailed`, `wrsCancelled`.
`Cancel`	Beendet die Anfrage: Ist sie noch nicht gesendet, wird sie aus der Warteschlange genommen; ist sie unterwegs, wird die Verbindung geschlossen.

Ereignisse der Warteschlange (zusätzlich zu den obigen Ereignissen der Aufgabe):

Ereignis	Wann
`RequestCompleted(Key, Id, Tag, Status, Result)`	Eine Antwort 2xx oder 3xx ist eingetroffen. `Result`: `Status`, `Text`, `Header(Name)`, `Headers`. Hier lassen sich weitere Anfragen hinzufügen.
`RequestFailed(Key, Id, Tag, Status, Description, WillRetry, Result)`	Eine andere Antwort oder keine Antwort; `Status` ist 0, wenn keine kam. `Result` enthält die Antwort (`Text`, `Header(Name)`), wenn eine kam, zum Beispiel eine problem+json-Meldung; andernfalls `Nothing`.
`RequestCancelled(Key, Id, Tag, Reason)`	Durch `Cancel`, `Requests.Clear`, das Zeitlimit oder das Schließen des Formulars.
`QueuePaused(Key, Reason, ResumeAt)`	Ein 429 hat die Warteschlange bis `ResumeAt` (Ortszeit) pausiert.
`QueueHalted(Key, Id, Status, Headers)`	Ein 401 hat die Warteschlange angehalten; `Headers` enthält die Antwortheader als Text.
`QueueResumed(Key)`	Die Pause ist beendet, oder `Resume` wurde aufgerufen.

Administration

Freigegebenes Paket installieren

Fehlerbehebung

Noch keine.

Für Entwickler

API-Referenz (Englisch): WklTimerList, WklTimerTasks, WklTimerTask
API-Referenz (Englisch): WklHttpRequests, WklHttpRequest, WklHttpResult