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.