dateCalc (Datum berechnen)
Die Berechnungsfunktion $dateCalc dient zum Erzeugen von Datumswerten über absolute und relative Berechnungskomponenten.
Syntax
$dateCalc(expression[,dateValue])
Parameter
|
Name |
Beschreibung |
|
expression |
Ein Ausdruck mit einem oder mehreren Berechnungskomponenten, die in der Reihenfolge ihrer Nennung im Ausdruck auf einen durch den Parameter "dateValue" (s. unten) bestimmten Bezugszeitpunkt sequentiell angewendet werden. Jede einzelne Berechnungskomponente ist nach folgendem Schema aufgebaut: [+|-]NU Dabei steht N (engl.: number) für eine Ganzzahl und U (engl.: unit) für einen Buchstaben zur Identifikation der betreffenden Datumskomponente (z. B. M für Monat; vollständige Liste im folgenden Abschnitt):
Mehrere Berechnungskomponenten können über Leerzeichen getrennt verkettet werden. Sie werden sequentiell (von links nach rechts) abgearbeitet. Beispiel: "+1d +3h 0m" = Bezugsdatum + 1 Tag + 3 Stunden und Minuten auf 0 gesetzt. ►HINWEISE◄
|
|
dateValue |
Dieser optionale Parameter definiert den Bezugszeitpunkt für die Datumsermittlung. Ohne eine Angabe dient die aktuelle Clientzeit ( $now() ) als Bezugszeitpunkt. Als Datumswert können die folgenden Datentypen verwendet werden:
|
Rückgabewert
Gibt das Ergebnis der Berechnung als neuen Wert, kompatibel zum Eingabewert (dateValue Parameter), zurück. Ist dateValue beispielsweise ein Datumsbereich (DateRange), so wird auch wieder ein Datumsbereichsobjekt zurückgeliefert.
Kennbuchstaben für die Identifikation von Datumskomponenten
Zur Identifikation von Datumskomponenten im Parameter Ausdruck sind folgende Kennbuchstaben zulässig:
|
Kennbuchstabe |
Datumskomponente |
Zulässige Werte |
|
y |
Jahr |
>= 1 |
|
M |
Monat im Jahr |
1 (Januar) bis 12 (Dezember) |
|
d |
Tag im Monat |
1 bis Anzahl Tage im entsprechenden Monat |
|
D |
Tag im Jahr |
1 bis Anzahl Tage im entsprechenden Jahr |
|
w |
Woche im Jahr |
Clientseitig nicht unterstützt |
|
F oder E |
Tag in der Woche |
Clientseitig nicht unterstützt |
|
H |
Stunde des Tages |
0 bis 23 |
|
m |
Minute der Stunde |
0 bis 59 |
|
s |
Sekunde der Minute |
0 bis 59 |
|
S |
Millisekunden in der Sekunde |
0 bis 999 |
Beispiele
Absolutes Datum aus Komponenten aufbauen
Ein absoluter Datumswert (16. Februar 2015 um 13:21 Uhr) wird durch diesen Funktionsaufruf erzeugt:
$dateCalc(16d 2M 2015y 13H 21m 0s 0S)
►HINWEIS◄ Ohne die Berechnungskomponenten "0s 0S" würden die Sekunden und Millisekunden aus der aktuellen Systemzeit übernommen.
Relativer Zeitpunkt "Morgen um dieselbe Zeit"
Der folgende Funktionsausruf ermittelt einen Zeitpunkt relativ zur aktuellen Systemzeit, der den nachfolgenden Kalendertag mit der aktuellen Uhrzeit kombiniert:
$dateCalc(+1d)
Relativer Zeitpunkt "17 Uhr am letzten Tag des Monats aus einem bestimmten Datumswert"
Der folgende Funktionsaufruf ermittelt einen Zeitpunkt durch eine Kombination absoluter und relativer Berechnungskomponenten ausgehend von einem Bezugszeitpunkt aus einem bestimmten Feld mit der ID # 99:
$dateCalc(1d +1M -1d 17H 0m 0s 0S, $el(99))
Relativer Zeitpunkt abhängig von Eingaben/Auswahlen in anderen Feldern
Der folgende Funktionsaufruf ermittelt einen Zeitpunkt relativ zur aktuellen Systemzeit anhand von Eingaben/Auswahlen in anderen Feldern:
$dateCalc($concatWs(+,$el(12),d ,$el(14), 0s 0S))
Ein Eingabefeld mit der ID # 12 definiert eine gewisse Anzahl von Tagen als Offset in die Zukunft. Das Auswahlfeld mit der ID # 14 definiert eine absolute Angabe für die Uhrzeit mit zwei Optionen "10H 0m" und "17H 45m".
Im Formular wird der "berechnete Liefertermin" per $dateCalc über die schreibgeschützte Lieferzeit (Element # 12) und unter Berücksichtigung einer per Auswahloption auswählbaren Lieferuhrzeit ("Lieferung bis ...", Element # 14) relativ zur Systemzeit ermittelt.
Die Aktualisierung erfolgt über ein Verhalten Berechnen das bei Auswahl von "Lieferung bis ..." ausgelöst wird.
Tipp: $dateCalc im Ausdruck von Vergleichsfunktionen für Datumswerte
$dateCalc kann beim Auswerten von Datumswerten per Verhalten (Vergleiche mit (Vergleichstyp)) oder zur Validierung von Datumsfeldern (vergleiche mit (Validierer)) verwendet werden, um einen Vergleichswert per Ausdruck zu ermitteln.
Beispiel: Maximale Zeitspanne zwischen "von" und "bis" in einem Datumsbereich
In einem Datumsbereich soll ein Validierer sicherstellen, dass das Bis-Datum maximal 3 Monate nach dem Von-Datum liegt.
Konfiguration
In den Eigenschaften für das Bis-Datumselement des Datumsbereichselements wird in der Rubrik Validierung ein Validierer vom Typ vergleiche mit (Validierer) hinzugefügt.
Als Vergleichstyp wird eine "kleiner oder gleich" Bedingung ausgewählt, sodass der per $dateCalc ermittelte "Grenztermin" als maximal zulässiger Wert gilt.
Als Vergleichsquelle wird die Option Ausdruck ausgewählt, so dass ein Berechnungsausdruck angegeben werden kann.
Der Berechnungsausdruck ermittelt per $dateCalc den Grenztermin relativ zum "Von-Datum" (im Element mit ID # 7):
Der Ausdruck-Parameter +3M addiert drei Monate zum Wert im Datumswert-Parameter.
Der Datumswert-Parameter verweist auf den Wert in Feld # 7 (Von-Datum).
Beispiel in der Anwendung
Unzulässige Eingabe:
Zulässige Eingabe:
►HINWEISE◄
Die im Beispiel gewählten Datumswerte sollen verdeutlichen, dass die $dateCalc-Funktion ("30.11.2019" +3M) als Grenztermin den 01.03.2020 ermittelt und nicht etwa den "30.02.2020", der auch in einem Schaltjahr kein gültiges Datum ist.
Für beide Datumsfelder sollte in der Eigenschaften-Rubrik "Datum/Uhrzeit" die Option Zeit 00:00 bei Datumsänderung ausgewählt werden, da sonst bei Änderungen die Systemuhrzeit übernommen wird, was die Validierung beeinträchtigen kann, bei der die Uhrzeit-Komponenten auch berücksichtigt werden, wenn sie nicht angezeigt werden.
Eine nachträgliche Veränderung am "Von"-Termin löst keine Aktualisierung der Validierung für das "Bis"-Element aus. Als Abhilfe kann bei Änderung des "Von"-Elements ein Element validieren Verhalten für das "Bis"-Element ausgeführt werden.