Modul ConvertTimeZone (CTZ): Unterschied zwischen den Versionen

Aus FHEMWiki
K (Infobox eingefügt; <source> Tags (deprecated) durch <syntaxhighlight> ersetzt)
Zeile 1: Zeile 1:
{{Infobox Modul
|ModPurpose=Zeitzonenumrechnung
|ModType=x
|ModCmdRef=CTZ
|ModFTopic=115379
|ModForumArea=Sonstiges
|ModTechName=CTZ.pm
|ModOwner=DS_Starter ({{Link2FU|16933|Forum}}/[[Benutzer Diskussion:DS_Starter|Wiki]])
}}
Das Modul CTZ.pm konvertiert Zeitstrings von einer Zeitzone in eine andere Zeitzone.
Das Modul CTZ.pm konvertiert Zeitstrings von einer Zeitzone in eine andere Zeitzone.
So können zum Beispiel lokale Zeitangaben in UTC bzw. von UTC in lokale Zeit konvertiert werden.
So können zum Beispiel lokale Zeitangaben in UTC bzw. von UTC in lokale Zeit konvertiert werden.
Das Modul ist sowohl zur Verwendung in FHEM-Modulen als auch in eigenen Routinen (99_myUtils) geeignet.
Das Modul ist sowohl zur Verwendung in FHEM-Modulen als auch in eigenen Routinen ([[99 myUtils anlegen|99_myUtils]]) geeignet.


Das Modul muß vor der Verwendung eingebunden werden mit
Das Modul muß vor der Verwendung eingebunden werden mit
Zeile 21: Zeile 30:
Die Funktion '''getTZNames''' liefert eine Array Referenz zu einer Liste aller Zeitzonen, die mit diesem Modul verwendet werden können.
Die Funktion '''getTZNames''' liefert eine Array Referenz zu einer Liste aller Zeitzonen, die mit diesem Modul verwendet werden können.


:<source lang="perl">
:<syntaxhighlight lang="perl">
my $list = getTZNames ();
my $list = getTZNames ();
</source>
</syntaxhighlight>


Mit einem get-Befehl kann zum Beipiel die komplette Liste abgerufen werden:
Mit einem get-Befehl kann zum Beipiel die komplette Liste abgerufen werden:


:<source lang="perl">
:<syntaxhighlight lang="perl">
sub XXX_Get {
sub XXX_Get {
   my ($hash, @a) = @_;
   my ($hash, @a) = @_;
Zeile 47: Zeile 56:
return;
return;
}
}
</source>
</syntaxhighlight>


Es erscheint die Liste der verwendbaren Zeitzonen:
Es erscheint die Liste der verwendbaren Zeitzonen:
Zeile 82: Zeile 91:
Aufruf:  
Aufruf:  


:<source lang="perl">
:<syntaxhighlight lang="perl">
my ($err, $dtconv) = convertTimeZone ($params);
my ($err, $dtconv) = convertTimeZone ($params);
</source>
</syntaxhighlight>


Der Parameter $params ist eine Referenz auf eine Hash-Struktur, welche die einzelnen Parameter enthält. Der Hash $params kann folgende Optionen beinhalten:  
Der Parameter $params ist eine Referenz auf eine Hash-Struktur, welche die einzelnen Parameter enthält. Der Hash $params kann folgende Optionen beinhalten:  
Zeile 117: Zeile 126:
Beispiel zur Umwandlung eines Zeitstrings der lokalen Zeitzone in die koordinierte Weltzeit UTC mit Ausgabe im Log:
Beispiel zur Umwandlung eines Zeitstrings der lokalen Zeitzone in die koordinierte Weltzeit UTC mit Ausgabe im Log:


:<source lang="perl">
:<syntaxhighlight lang="perl">
my $name = "xxx";
my $name = "xxx";
...
...
Zeile 129: Zeile 138:


my ($err, $dtconv) = convertTimeZone ($params);
my ($err, $dtconv) = convertTimeZone ($params);
</source>
</syntaxhighlight>


Im Log wird ausgegeben:
Im Log wird ausgegeben:
Zeile 141: Zeile 150:
Die Konvertierung eines UTC-Zeitstrings in eine beliebige Zeitzone (siehe Funktion 'getTZNames') geschieht identisch, wobei in diesem Fall der Parameter tzcurrent den Wert 'UTC' enthalten muß:
Die Konvertierung eines UTC-Zeitstrings in eine beliebige Zeitzone (siehe Funktion 'getTZNames') geschieht identisch, wobei in diesem Fall der Parameter tzcurrent den Wert 'UTC' enthalten muß:


:<source lang="perl">
:<syntaxhighlight lang="perl">
my $name = "xxx";
my $name = "xxx";
...
...
Zeile 153: Zeile 162:


my ($err, $dtconv) = convertTimeZone ($params);
my ($err, $dtconv) = convertTimeZone ($params);
</source>
</syntaxhighlight>

Version vom 12. März 2022, 19:09 Uhr

CTZ
Zweck / Funktion
Zeitzonenumrechnung
Allgemein
Typ Inoffiziell
Details
Dokumentation Thema
Support (Forum) Sonstiges
Modulname CTZ.pm
Ersteller DS_Starter (Forum /Wiki)
Wichtig: sofern vorhanden, gilt im Zweifel immer die (englische) Beschreibung in der commandref!

Das Modul CTZ.pm konvertiert Zeitstrings von einer Zeitzone in eine andere Zeitzone. So können zum Beispiel lokale Zeitangaben in UTC bzw. von UTC in lokale Zeit konvertiert werden. Das Modul ist sowohl zur Verwendung in FHEM-Modulen als auch in eigenen Routinen (99_myUtils) geeignet.

Das Modul muß vor der Verwendung eingebunden werden mit

use FHEM::Utility::CTZ qw(:all);

bzw. mit

use FHEM::Utility::CTZ qw(convertTimeZone getTZNames);

Das Modul stellt nachfolgend beschriebene Funktionen bereit.

getTZNames

Die Funktion getTZNames liefert eine Array Referenz zu einer Liste aller Zeitzonen, die mit diesem Modul verwendet werden können.

my $list = getTZNames ();

Mit einem get-Befehl kann zum Beipiel die komplette Liste abgerufen werden:

sub XXX_Get {
  my ($hash, @a) = @_;
  my $name       = $a[0];
  my $opt        = $a[1];

  my $getlist = "Unknown argument $opt, choose one of ".
                "tzg "                
                ;

  if ($opt eq 'tzg') {
      my $atz = getTZNames (); 
      return join "\n", @{$atz};
  }
  else {
      return "$getlist";
  } 
  
return;
}

Es erscheint die Liste der verwendbaren Zeitzonen:

...
Europe/Amsterdam
Europe/Andorra
Europe/Astrakhan
Europe/Athens
Europe/Belgrade
Europe/Berlin
Europe/Brussels
Europe/Bucharest
Europe/Budapest
Europe/Chisinau
Europe/Copenhagen
Europe/Dublin
Europe/Gibraltar
Europe/Helsinki
Europe/Istanbul
...

Die Notation der möglichen Zeitzonen wird in der Funktion convertTimeZone verwendet.


convertTimeZone

Mit der Funktion convertTimeZone wird ein übergebener Zeitstring in die Zeit der gewünschten Zeitzone konvertiert. Dieser Funktion wird eine Hashreferenz mit allen Funktionsparametern übergeben. Dieser Hash enthält sämtliche Parameter inkl. Werten. Zurück gegeben werden ein Error-Wert und der konvertierte Zeitstring.

Aufruf:

my ($err, $dtconv) = convertTimeZone ($params);

Der Parameter $params ist eine Referenz auf eine Hash-Struktur, welche die einzelnen Parameter enthält. Der Hash $params kann folgende Optionen beinhalten:


Parameter Optional Beispiel Beschreibung
name nein "LogDB" Der Name des aufrufenden Device.
dtstring nein '2022-03-09 22:17:45' Der Original-Zeitstring der umgewandelt werden soll. Der Zeitstring kann auch Millisekunden enthalten. Die Form ist diesem Fall YYYY-MM-DD hh:mm:ss.xxx
tzcurrent ja 'Europe/Berlin' Die Zeitzone des Original-Zeitstrings (dtstring). Es kann 'local' angegeben werden. In diesem Fall wird die Zeitzone des Systems versucht automatisch zu ermitteln. Das gilt ebenso wenn tzcurrent nicht angegeben ist.
tzconv ja 'Asia/Singapore' Die Zeitzone in welche der übergebene Zeitstring konvertiert werden soll. Ist tzconv nicht angegeben, wird 'UTC' verwendet.
writelog ja 1 1 - der originale und der konvertierte Zeitstring werden mit der (ermittelten) Zeitzone (Abkürzung) im Log ausgegeben
0 - es erfolgt keine Ausgabe im Log

Als Rückgabewert wird ein Array mit zwei Rückgabewerten zurückgegeben.

Rückgabewert Bedeutung
$err Falls bei der Konvertierung ein Fehler aufgetreten ist, enthält die Variable einen Text zum aufgetretenen Fehler. Ansonsten ist dieser Wert mit einem Leerstring gefüllt ($err = "").
$dtconv Wenn kein Konvertierungsfehler aufgetreten ist enthält die Variable den umgewandelten Zeitstring, ansonsten undef.

Beispiel zur Umwandlung eines Zeitstrings der lokalen Zeitzone in die koordinierte Weltzeit UTC mit Ausgabe im Log:

my $name = "xxx";
...
my $params = {
  name      => $name,
  dtstring  => '2022-03-09 22:17:45',
  tzcurrent => 'local',
  tzconv    => 'UTC',
  writelog  => 1
};

my ($err, $dtconv) = convertTimeZone ($params);

Im Log wird ausgegeben:

2022.03.11 21:12:52 1: FHEM::Utility::CTZ - original timestring: 2022-03-09 22:17:45 CET
2022.03.11 21:12:52 1: FHEM::Utility::CTZ - converted timestring: 2022-03-09 21:17:45 UTC


Die Konvertierung eines UTC-Zeitstrings in eine beliebige Zeitzone (siehe Funktion 'getTZNames') geschieht identisch, wobei in diesem Fall der Parameter tzcurrent den Wert 'UTC' enthalten muß:

my $name = "xxx";
...
my $params = {
  name      => $name,
  dtstring  => '2022-03-09 21:17:45',
  tzcurrent => 'UTC',
  tzconv    => 'Europe/Berlin',              # oder 'local'
  writelog  => 0
};

my ($err, $dtconv) = convertTimeZone ($params);