Nachdem wir uns im letzten Artikel mit diversen CEE-APIs beschäftigt haben, mit deren Hilfe die Anzahl der Sekunden oder Anzahl der Tage seit Beginn der gregorianischen Zeitrechnung berechnet werden kann, werden in diesem Artikel CEE-APIs vorgestellt, die es ermöglichen aus einem lilianischen Datum ein alphanumerisches Datum in beliebigem Format zu erstellen.
CEEDATE – Konvertieren lilianisches Datum in alphanumerisches Datum
Durch das API CEEDATE ist es möglich ein lilianisches Datum (Anzahl Tage seit Beginn der gregorianischen Zeitrechnung) in ein alphanumerisches Datum in fast jeder beliebigen Aufbereitung zu konvertieren. Das lilianische Datum kann mit Hilfe des APIs CEEDAYS aus einem alphanumerischen Datum ermittelt werden. Alternativ kann das lilianische Datum natürlich auch direkt als Differenz aus dem Ausgangsdatum und dem 14. Oktober 1582 (15. Oktober 1582 = 1.Tag!) berechnet werden.
Das lilianische Datum muss als erster Parameter an das API CEEDATE übergeben werden. Insgesamt erfordert das API CEEDATE vier Parameter, wie die folgende Auflistung zeigt:
|
Required Parameter Group: |
|||
|
|
|||
|
1 |
input_Lilian_date |
Input |
INT4 |
|
2 |
picture_string |
Input |
VSTRING |
|
3 |
output_char_date |
Output |
VSTRING |
|
|
|||
|
Omissible Parameter: |
|||
|
|
|||
|
4 |
fc |
Output |
FEEDBACK |
Beispiel 1: Parameterbeschreibung für API CEEDATE
Im zweiten Parameter muss das Format des alphanumerischen Ausgabe-Datums angegeben werden. Die zulässigen Formate wurden bereits in API-Programmierung – CEE-API – Datumsaufbereitung – Teil I beschrieben. Das Format des Ausgabestrings muss kein vollständiges Datum beinhalten, vielmehr ist es auch möglich nur einzelne Teile z. B. den Namen des Wochentags oder das Jahr auszugeben.
Über den dritten Parameter wird das aufbereitete Datum als alphanumerischer String zurückgegeben.
Sowohl bei dem zweiten als auch dem dritten Parameter können alphanumerische Strings von beliebiger Länge an das API CEEDATE übergeben werden. Damit die tatsächliche Länge der übergebenen Parameter-Felder innerhalb des APIs ermittelt werden kann, müssen über operationale Deskriptoren zusätzliche Informationen bereitgestellt werden. Durch die Angabe des Schlüssel-Wortes OPDESC im Prototypen wird sichergestellt, dass die operationalen Deskriptoren bzw. die benötigten Informationen übergeben werden.
Bei dem letzten Parameter, der „omissible“ ist, handelt es sich um den Feedback-Code, über den eine Fehlerbehandlung möglich ist. Alternativ kann anstatt des vierten Parameters aber auch der Sonderwert *OMIT übergeben werden. Omissible Parameter werden im Prototypen durch das Schlüsselwort Options(*Omit) gekennzeichnet.
Damit kann der Prototyp für das API CEEDATE wie folgt aussehen:
D CEEDATE PR OpDesc
D ParLilDate 10I 0 Const
D ParString 256A Varying Const Options(*VarSize)
D POutCharDate 256A Varying Options(*VarSize)
D ParFeedBack 12A Options(*Omit)
Beispiel 2: Prototyp für API CEEDATE
Das folgende Beispiel zeigt die Funktion CvtDateToLongDate(), in der ein übergebenes Datum in ein alphanumerisches Datum im Format Wochentag, TT. Monat JJJJ konvertiert wird. Über das API CEEDAYS wird das Datum zunächst in ein lilianisches Datum umgewandelt. Das API CEEDATE konvertiert anschließend das lilianische Datum in den gewünschten String.
*************************************************************************
* Procedure name: CvtDateToLongDate
* Purpose: Konvertieren Datum in Wochentag, TT. Monat JJJJ
* Returns: Alphanumer. Aufbereitung in Wochentag, TT. Monat JJJJ
* Parameter: ParDate => Datum
**************************************************************************
P CvtDateToLongDate...
P B Export
D CvtDateToLongDate...
D PI 256A Varying
D ParDate D Const
D LocLilDate S 10I 0
D RtnLongDate S 256A Varying
*-------------------------------------------------------------------------
/Free
CEEDAYS(%Char(ParDate: *ISO): 'YYYY-MM-DD': LocLilDate: *Omit);
CEEDATE(LocLilDate: 'Wwwwwwwwwz, ZD. Mmmmmmmmmz YYYY':
RtnLongDate: *Omit);
Return RtnLongDate;
/End-Free
P CvtDateToLongDate...
P E
Beispiel 3: Funktion CvtDateToLongDate()
Über das API CEEDATE können nur reine Datums-Informationen, also Jahr, Monat, Tag verarbeitet und aufbereitet werden. Muss jedoch eine Zeitmarke oder z. B. auch nur eine Zeit aufbereitet werden, muss das API CEEDATM verwendet werden.
CEEDATM – Konvertieren lilianische Sekunden in alphanumerische Zeitmarke
In diesem API wird eine Zeitmarke, ein Datum oder eine Zeit aus der Anzahl Sekunden seit Beginn der gregorianischen Zeitrechnung aufbereitet. Die Anzahl Sekunden kann über das API CEEISEC (Convert Integers to Seconds) aus numerischen Datums- und Zeitangaben ermittelt werden. Alternativ können die lilianischen Sekunden mit dem API CEESECS (Convert Timestamp to Number of Seconds) aus numerischen Werten errechnet werden.
Die folgende Auflistung zeigt die für das API CEEDATM benötigten Parameter:
|
Required Parameter Group: |
|||
|
|
|||
|
1 |
input_seconds |
Input |
FLOAT8 |
|
2 |
picture_string |
Input |
VSTRING |
|
3 |
output_timestamp |
Output |
VSTRING |
|
|
|||
|
Omissible Parameter: |
|||
|
|
|||
|
4 |
Fc |
Output |
FEEDBACK |
Beispiel 4: Parameterbeschreibung für API CEEDATM
Wie auch beim API CEEDATE werden insgesamt vier Parameter benötigt. Im ersten Parameter muss das gewünschte Datum, Zeit oder Zeitmarke als lilianische Sekunden im Fließkommaformat (Double = 8F) übergeben werden.
Die übrigen Parameter entsprechen den Parametern zwei bis vier im API CEEDATE und können folglich ebenso definiert werden.
Der Prototyp für das API CEEDATM sieht demnach wie folgt aus:
D CEEDATM PR OpDesc
D ParLilSecs 8F Const
D ParString 256A Varying Const Options(*VarSize)
D POutCharDate 256A Varying Options(*VarSize)
D ParFeedBack 12A Options(*Omit)
Beispiel 5: Prototyp für API CEEDATM
Das folgende Beispiel zeigt die Funktion GetTimeHHMMFromTimeStamp in der der Zeitanteil aus einer Zeitmarke ermittelt und im Format HH:MM ausgegeben wird. Über das API CEESECS wird zunächst die übergebene Zeitmarke in lilianische Sekunden konvertiert. Das Ergebnis aus dem Aufruf dieses APIs wird dann im API CEEDATM eingesetzt und im Format HH:MM aufbereitet.
*************************************************************************
* Procedure name: GetTimeHHMMFromTimeStamp
* Purpose: Ermitteln Stunden und Minuten-Anteil aus Zeitmarke
* Returns: HH:MM
* Parameter: ParZeitmarke => ZeitMarke
*************************************************************************
P GetTimeHHMMFromTimestamp...
P B Export
D GetTimeHHMMFromTimestamp...
D PI 5A
D ParTimestamp Z Const
D RtnHHMM S 5A Varying
D LocLilSecs S 8F
*------------------------------------------------------------------------
/Free
CEESECS(%Subst(%Char(ParTimeStamp: *ISO0): 1: 14):
'YYYYMMDDHHMISS': LocLilSecs: *Omit);
CEEDATM(LocLilSecs: 'HH:MI': RtnHHMM: *Omit);
Return RtnHHMM;
/End-Free
P GetTimeHHMMFromTimestamp...
P E
Beispiel 6 : Funktion GetTimeHHMMFromTimestamp()
Bislang wurde bei der Aufbereitung der Datums-, Zeit- und Zeitmarken-Werte das Ausgabe-Format immer hart angegeben. Nun kann es vorkommen, dass das Datum, z. B. beim Schreiben einer Rechnung oder eines Lieferscheins, jeweils im Standard-Format des Empfänger-Landes angegeben werden muss. In diesem Fall leisten die folgenden APIs gute Dienste:
CEEFMDA Ermitteln Standard-Datums-Format für Land oder Region
CEEFMDT Ermitteln Standard-Datums- und Zeit-Format für Land oder Region
CEEFMTM Ermitteln Standard-Zeit-Format für Land oder Region
Jedes der zuvor genannten APIs erfordert insgesamt drei Parameter:
Bei dem ersten Parameter handelt es sich um einen „omissiblen“ 2 Byte langen alphanumerischen Parameter, in dem die Länder-Kennung des gewünschten Landes angegeben wird. Wird der Parameter mit *Blanks übergeben oder omittet (Sonder-Wert *OMIT), wird das in den System-Werten (QDATFMT, QDATSEP, QTIMSEP) hinterlegte Format verwendet.
Für folgende Länder oder Regionen können die Standard-Formate ermittelt werden.
| Land / Region | Länder-Kennung |
| Albanien | AL |
| Ägypten | EG |
| Algerien | DZ |
| Argentinien | AR |
| Australien | AU |
| Bahrain | BH |
| Belgien | BE |
| Bolivien | BO |
| Brasilien | BR |
| Bulgarien | BG |
| Chile | CL |
| China | CN |
| Costa Rica | CR |
| Dänemark | DK |
| Deutschland | DE |
| Dominikanische Republik | DO |
| El Salvador | SV |
| Equador | EC |
| Finnland | FI |
| Frankreich | FR |
| Griechenland | GR |
| Großbritannien | GB |
| Guatemala | GT |
| Honduras | HN |
| Indien | IN |
| Irak | IQ |
| Iran | IR |
| Irland | IE |
| Island | IS |
| Israel | IL |
| Italien | IT |
| Japan | JP |
| Jemen | YE |
| Jordanien | JO |
| Jugoslawien | YU |
| Kanada | CA |
| Kolumbien | CO |
| Kuwait | KW |
| Libanon | LB |
| Libyen | LY |
| Marokko | MA |
| Mexiko | MX |
| Neuseeland | NZ |
| Niederlande | NL |
| Nord-Korea | KP |
| Norwegen | NO |
| Oman | OM |
| Österreich | AT |
| Pakistan | PK |
| Panama | PA |
| Paraguay | PY |
| Peru | PE |
| Polen | PL |
| Portugal | PT |
| Quatar | QA |
| Rumänien | RO |
| Russland | RU |
| Saudi Arabia | SA |
| Schweden | SE |
| Schweiz | CH |
| Slowakei | SK |
| Slowenein | SI |
| Spanien | ES |
| Süd-Afrika | ZA |
| Sudan | SD |
| Süd-Korea | KR |
| Syrien | SY |
| Taiwan | TW |
| Thailand | TH |
| Tschechische Republik | CZ |
| Tunesien | TN |
| Türkei | TR |
| Ungarn | HU |
| Uruguay | UY |
| USA | US |
| Venezuela | VE |
| Vereinigte Arabische Emirate | AE |
Tabelle 1: Länder-Codes für CEE-APIs
Bei dem zweiten Parameter handelt es sich um einen Ausgabe-Parameter, in dem das aufbereitete alphanumerische Datums-, Zeit- oder Zeitmarken-Format ausgegeben wird. Bei dem APIs CEEFMDA muss dieser Parameter mit fixer Länge definiert werden (Datenart CHAR), während bei den APIs CEEFMDT und CEEFMTM ein Ausgabestring mit variabler Länge erforderlich ist (Datentyp VSTRING). Eine maximale Länge ist in der Parameter-Beschreibung nicht vorgegeben. Aus diesem Grund sind auch hier wieder operationale Deskriptoren erforderlich.
Bei dem dritten Parameter handelt es sich wiederum um den Feedback Code, der auch als Sonderwert *OMIT übergeben werden kann.
CEEFMDT – Ermitteln Standard-Datums- und Zeit-Format für Land oder Region
Anhand des APIs CEEFMDT wird nun zunächst die Parameter-Beschreibung, der Prototyp und anschließend der Aufruf dieses APIs in der Funktion CvtTimestampToCountryFormat(),in der eine Zeitmarke im jeweiligen länderspezifischen Format aufbereitet wird, gezeigt.
|
Omissible Parameter: |
|||
|
|
|||
|
1 |
country/region_code |
Input |
CHAR2 |
|
|
|||
|
Required Parameter: |
|||
|
|
|||
|
2 |
datetime_str |
Output |
VSTRING |
|
|
|||
|
Omissible Parameter: |
|||
|
|
|||
|
3 |
fc |
Output |
FEEDBACK |
Beispiel 7: Parameterbeschreibung API CEEFMDT
Basierend auf dieser Parameterbeschreibung wurde folgender Prototyp generiert.
D CEEFMDT PR OpDesc
D ParCountryC 2A Const Options(*Omit)
D ParFormat 256A Varying Const Options(*VarSize)
D ParFeedBack 12A Options(*Omit)
Beispiel 8: Prototyp API CEEFMDT – Ermitteln Datums-/Zeitformat pro Land/Region
Bei der Funktion CvtTimestampToCountryFormat() können zwei Parameter übergeben werden, eine Zeitmarke, die immer erforderlich ist, und ein Länder-Code.
Über das API CEEFMDT wird zunächst das Datums- und Zeitformat für den übergebenen Länder-Code ermittelt. Wurde der Länder-Code nicht oder nur mit *Blanks gefüllt übergeben, wird der Default-Länder-Code aus den System-Werten ermittelt.
Die übergebene Zeitmarke wird mit Hilfe des APIs CEESECS in lilianische Sekunden konvertiert.
Sowohl das ermittelte Datums- und Zeit-Format als auch die lilianischen Sekunden werden bei folgendem Aufruf des APIs CEEDATM, das die lilianischen Sekunden in das übergebene Datums- und Zeit-Format umwandelt, als Parameter-Werte übergeben.
*************************************************************************
* Procedure name: CvtTimeStampToCountryFormat
* Purpose: Konvertieren Datum in Default Format für Land
* Returns: Alphanumerische Aufbereitung in Länder-Format
* Parameter: ParTimeStamp => Zeitmarke
* Parameter: ParLandCode => Ländercode
*************************************************************************
P CvtTimeStampToCountryFormat...
P B Export
D CvtTimeStampToCountryFormat...
D PI 256A Varying OpDesc
D ParTimeStamp Z Const
D ParLandCode 2A Const Options(*NoPass)
D ParPosLandCode C const(2)
D RtnDateAlpha S 256A Varying
D LocLilSecs S 8F
D LocDateFormat S 256A
*-------------------------------------------------------------------------
/Free
If %Parms >= ParPosLandCode and ParLandCode <> *Blanks;
CEEFMDT(ParLandCode: LocDateFormat: *Omit);
Else;
CEEFMDT(*Omit: LocDateFormat: *Omit);
EndIf;
CEESECS(%Subst(%Char(ParTimeStamp: *ISO0): 1: 14):
'YYYYMMDDHHMISS': LocLilSecs: *Omit);
CEEDATM(LocLilSecs: %Trim(LocDateFormat): RtnDateAlpha: *Omit);
Return RtnDateAlpha;
/End-Free
P CvtTimeStampToCountryFormat...
P E
Beispiel 9: Funktion CvtTimestampToCountryFormat()
Bei der Funktion CvtTimeStampToCountryFormat() wird davon ausgegangen, dass entweder ein gültiges Länderkennzeichen oder kein Länderkennzeichen übergeben wird. Was passiert jedoch, wenn ein ungültiges Länderkennzeichen übergeben wird oder wenn in einem CEE-API ein sonstiger Fehler auftritt? Das wird im nächsten Artikel geklärt!
Bis dahin schon mal viel Spaß beim Hin- und Her-Konvertieren von Datums-, Zeit- und Zeitmarken-Formaten.
