Allgemeines
Anwendungsgebiet: | Abfragen und Zugriff zu Listen und Tabellen; siehe "Abfragen und Zugriff zu Listen und Tabellen" |
Makrotyp: | S-Typ, MF-Format 3: C-/D-/E-/L-/M-Form; siehe "S-Typ-Makroaufrufe" |
Makrobeschreibung
Der Makro GTIME informiert über
das aktuelle Datum und die aktuelle Uhrzeit, wahlweise in Form der universellen Weltzeit UTC (Universal Time Coordinate, entspricht der Greenwich-Zeit) oder der gesetzlichen, lokalen Landeszeit LT (Local Time). Dabei kann ein Monotonieverhalten für Aufrufer auf unterschiedlichen XCS-Knotenrechnern gefordert werden
den aktuellen Wochentag
die Zeitzone des Systems in Stunden und Minuten (entspricht der Zeitverschiebung gegenüber UTC)
die Größe der Zeitverschiebung bei Sommerzeit in Stunden und Minuten
die aktuelle Zeitverschiebung gegenüber der Normalzeit auf Grund der Sommerzeit
die Umstellzeitpunkte, an denen von Sommer- auf Winterzeit oder umgekehrt geschaltet wird
ob die Systemzeit mit einer externen Referenz synchronisiert ist, und wenn ja, mit welcher Referenz-Zeitquelle (z.B. Funkuhr)
ob in der nächsten Stunde eine Zeitumstellung ansteht
die aktuelle Epoche für das TODR (siehe Handbuch „Systembetreuung“ [10])
GTIME stellt diese Informationen im Datenbereich wahlweise in abdruckbarer, binärer oder TODR/TODX-Form (nur für die Ausgabe der lokalen Zeit (LT) oder der universellen Weltzeit (UTC)) zur Verfügung.
Hinweise
Da die Funktionen des Makros GTIME nicht über einen SVC, sondern über eine Unterprogrammschnittstelle ausgelöst werden, muss ein Programm, das GTIME aufruft, einen 18 Worte langen Sicherstellungsbereich zur Verfügung stellen. Vor dem Makroaufruf ist die Adresse dieses Sicherstellungsbereiches in Register R13 zu laden.
Abgesehen von einer Überprüfung des Standardheaders findet keine Validierung des Datenbereichs statt.
Makroaufrufformat und Operandenbeschreibung
GTIME |
MODE=LT / UTC ,FORMAT=ISO4 / BIN / TODR / TODX ,RESOLVE=SEC / MICROSEC ,LINKADR=*NONE / linkadr ,DATE=NO / YES ,DAY=NO / YES ,TOD=NO / YES ,ZONE=NO / YES ,EXTREF=NO / YES ,CHDATE=NONE / NEXT / PREV ,CHD_ANNOUNCMNT=*NO / *YES ,XCS_MODE=*NO / *YES ,MF=D / E / L / C / M [,PARAM=adr / (r)] ,PREFIX=N / p ,MACID=TIG / macid |
In der nachfolgenden Operandenbeschreibung sind die Operanden alphabetisch geordnet.
CHD_ANNOUNCMNT=
kündigt einen Umstellungszeitpunkt durch einen Indikator an.
*NO
Der Indikator soll nicht gesetzt werden.
*YES
Der Indikator wird gesetzt, falls innerhalb der nächsten Stunde eine Zeitumstellung ansteht.
Der Datenbereich zur Aufnahme des Indikators hat folgenden Aufbau (Makroauflösung mit MF=D und Standardwert für PREFIX):
NTIGGINF DS AL1 general_info NTIGICNH EQU X'80' chdate is expected in next * hour NTIGRESERVED_7BITS EQU X'7F' not yet used NTIGFRES DS XL2 reserved
CHDATE=
gibt die Richtung an, in welcher die Umstellungszeitpunkte (CHDATEs) gesucht werden sollen.
Für weitere Informationen zu Umstellungszeitpunkten siehe Hinweise auf "GTIME - Datum und Uhrzeit anfordern".
NONE
Es soll kein (weiterer) Umstellungszeitpunkt gesucht werden.
NEXT
Es soll der nächste Umstellungszeitpunkt gesucht werden.
Basis für den Suchbeginn ist der Inhalt des Feldes <prefix><macid>CHD
.
PREV
Es soll der vorhergehende Umstellungszeitpunkt gesucht werden.
Basis für den Suchbeginn ist der Inhalt des Feldes <prefix><macid>CHD
.
DATE=
entscheidet, ob das aktuelle Datum ausgegeben wird.
NO
Es werden keine Informationen über das aktuelle Datum übergeben.
YES
Das aktuelle Datum (Kalendertag und julianisches Datum) wird in einen Datenbereich übertragen. In welchem Bereich und in welchem Format die Information übergeben wird, hängt vom Wert des Operanden FORMAT ab:
FORMAT=ISO4
Das aktuelle Datum wird in der Form yyyy-mm-ddjjj
übergeben. Die beiden Bindestriche sind Bestandteil der Ausgabe. Dabei bedeuten:
| Jahr (vierstellig) Monat (zweistellig, ggf. mit führender Null) Tag (zweistellig, ggf. mit führender Null)
|
Der Datenbereich zur Aufnahme des Datums hat folgenden Aufbau (Makroauflösung mit MF=D und Standardwert für PREFIX):
* DATE IN ISO4 FORMAT (EXAMPLE :2012-01-20020) NTIGDTI DS 0XL16 date_iso4 NTIGDATE_UN DS 0XL10 date union NTIGDATE_1 DS 0XL10 date struct NTIGDTIY DS CL4 year NTIGDTI1 DS CL1 hyphen1 NTIGDTIM DS CL2 month NTIGDTI2 DS CL1 hyphen2
NTIGDTID DS CL2 day ORG NTIGDATE_UN NTIGDTIC DS CL10 date_char ORG NTIGDATE_UN+10 NTIGDTIJ DS CL3 julian date NTIGDTIB DS CL1 blank NTIGDYID DS CL2 weekday in ISO4
FORMAT=BIN
Jahr, Monat, Tag und julianisches Datum werden jeweils als ganze Zahl (in Binärform) übergeben. Der Datenbereich zur Aufnahme des Datums hat folgenden Aufbau (Makroauflösung mit MF=D und Standardwert für PREFIX):
* DATE IN BINARY FORMAT NTIGDTB DS 0XL16 date_bin * NTIGDATE_2 DS 0XL6 date NTIGDTBY DS H year NTIGDTBM DS H month NTIGDTBD DS H day NTIGDTBJ DS H Julian date NTIGFILL_6 DS XL6 fill for weekday NTIGDYBD DS H weekday bin.: MO=0, DI=1, ... * SO=6
DAY=
entscheidet, ob der aktuelle Wochentag ausgegeben wird.
NO
Es werden keine Informationen über den aktuellen Wochentag übergeben.
YES
Der aktuelle Wochentag wird in ein Feld des Datenbereichs übertragen. In welchem Feld und in welchem Format die Information übergeben wird, hängt vom Wert des Operanden FORMAT ab:
FORMAT=ISO4
Die ersten beiden Buchstaben des aktuellen Wochentages (MO, DI, MI, DO, FR, SA, SO) werden in das folgende Feld des Datenbereichs übertragen (Makroauflösung mit MF=D und Standardwert für PREFIX):
* DAY OF WEEK IN ISO4 FORMAT (EXAMPLE : MO)
NTIGDYI DS 0XL2
FORMAT=BIN
Der aktuelle Wochentag wird als ganze Zahl (in Binärform) (0 für Montag, 1 für Dienstag,..., 6 für Sonntag) in folgendem Halbwort des Datenbereichs übergeben (Makroauflösung mit MF=D und Standardwert für PREFIX):
* DAY OF WEEK IN BINARY FORMAT
NTIGDYB DS 0XL2
EXTREF=
bestimmt, ob die Information über die externe Referenz der Systemzeit geliefert werden soll, sofern sie vorhanden ist.
NO
Es soll keine Information geliefert werden.
YES
Die Information über eine evtl. vorhandene externe Referenz der Systemzeit soll geliefert werden.
Der Datenbereich zur Ausgabe der Information hat folgenden Aufbau (für Detailinformationen siehe die DSECT von GTIME; Standardwerte für PREFIX und MACID):
* FLAGS OF GTIME: TIME REFERENCE NTIGFLG DS 0XL4 flags of GTIME NTIGTREF DS FL1 time_reference * _time_reference_s NTIGNONE EQU 0 no external time reference NTIGSVPF EQU 1 SVP radio clock reference NTIGSVCE EQU 1 Server connected ext.reference NTIGCHNF EQU 2 Channel rad. cl. reference NTIGBSCE EQU 2 BS2 connected ext. reference NTIGDCET EQU 3 DCE reference NTIGXCST EQU 4 XCS reference NTIGSKPX EQU 5 SKP-X reference NTIGX2K EQU 5 X2000 reference
FORMAT=
legt fest, in welcher Form GTIME die angeforderten Informationen zur Verfügung stellt.
ISO4
Die Informationen werden in abdruckbarer Form übergeben. Der Aufbau des Datenbereichs wird zusammen mit der Beschreibung des Operanden TOD und ZONE beschrieben.
BIN
Die Informationen werden in Binärform übergeben. Der Aufbau des Datenbereichs wird zusammen mit der Beschreibung des Operanden TOD und ZONE beschrieben.
TODR / TODX
Die Informationen werden im TODR- oder TODX-Format im Feld NTIGTODR übergeben, die Einstellung der Epoche wird berücksichtigt. Die Unterschiede zwischen TODR und TODX sind beschrieben im Abschnitt „Systemzeit-Verwaltung“ des Handbuchs „Systembetreuung“ [10] und auch beim CTIME-Makro auf "CTIME - Mit Zeitstempeln rechnen".
Die Operandenwerte für DATE, DAY, TOD und ZONE müssen „NO“ sein. Der Operand MODE wird ausgewertet, d.h. für die Ausgabe der lokalen Zeit im TODR- oder TODX-Format muss MODE=LT eingestellt werden, sonst erhält man die UTC.
LINKADR=
gibt an, auf welche Weise dem Anwenderprogramm die Adresse des Einsprungpunktes I@GTIME für die GTIME-Routine im Subsystem GET-TIME zur Verfügung gestellt wird. Bei MF=E muss LINKADR angegeben werden, in allen anderen Fällen ist die Angabe von LINKADR wirkungslos.
*NONE
Bei der Übersetzung generiert der Assembler einen Externverweis für den Einsprungpunkt I@GTIME, der beim Binden über die Autolink-Funktion des BLS aufgelöst wird.
Dieser Wert kann verwendet werden, wenn das Modul, das den GTIME-Aufruf enthält,
immer mit dem Dynamischen Bindelader DBL gebunden und geladen wird (in diesem Fall lässt man den GTIME in der E-Form eine V-Konstante absetzen, welche beim Ladevorgang durch das BLS versorgt wird)
odermit dem BINDER (siehe Handbuch „BINDER“ [5]) unter der BINDER-Anweisung SET-EXTERN-RESOLUTION RESOLUTION=STD gebunden wird.
linkadr
symbolische Adresse (Name) eines Wortes, in dem der Anwender vor dem GTIME-Aufruf die Adresse des Einsprungpunktes I@GTIME bereitgestellt hat.
Das folgende Beispiel zeigt, wie dem Programm die Adresse des Einsprungpunktes I@GTIME zunächst durch einen geeigneten BIND-Aufruf zur Verfügung gestellt und anschließend für den GTIME-Aufruf in das mit linkadr bezeichnete Wort übertragen werden kann:
BIND MF=E,PARAM=BINDPL : GTIME MF=E,PARAM=OPLIST,LINKADR=AENTRY : AENTRY DS F OPLIST GTIME MF=L,... BINDPL BIND MF=L,SYMBOL=I@GTIME,SYMBLAD=AENTRY
Auf diese Weise muss dem Anwenderprogramm die Einsprungadresse der GTIME-Routine immer dann mitgeteilt werden, wenn keiner der unter LINKADR=*NONE erwähnten Fälle vorliegt, z.B. also insbesondere dann, wenn das Modul mit dem GTIME-Aufruf z.B. mit dem BINDER unter der BINDER-Anweisung SET-EXTERN-RESOLUTION RESOLUTION=MANDATORY gebunden wird.
MF=
Zur allgemeinen Beschreibung des Operanden MF, der dazugehörenden Operandenwerte und der evtl. nachfolgenden Operanden (z.B. PREFIX, MACID und PARAM) siehe Abschnitt „S-Typ-Makroaufrufe“. Die gültigen MF-Werte sind zu Beginn der Makrobeschreibung bei „Makrotyp“ angegeben und aus dem Aufrufformat ersichtlich.
Bei der C-Form, D-Form oder M-Form des Makroaufrufs kann ein Präfix PREFIX und bei der C-Form oder M-Form zusätzlich eine Macid MACID angegeben werden (siehe Abschnitt „S-Typ-Makroaufrufe“).
Bei der E-Form des Makroaufrufs wird das Label des Datenbereichs im Operanden PARAM angegeben. Voreinstellung: NTIG$PL
Beim Aufruf des Makros mit MF=L muss der Anwender dieses Label explizit angeben, sonst wird eine MNOTE
ausgegeben.
MODE=
legt fest, in welchem Zeitsystem Datum und Uhrzeit ausgegeben werden sollen.
LT
Datum und Uhrzeit werden im lokalen Zeitsystem (gesetzliche Landeszeit) ausgegeben.
UTC
Datum und Uhrzeit werden in Form der universellen Weltzeit UTC (Universal Time Coordinate entspricht Greenwich-Zeit) ausgegeben.
RESOLVE=
gibt die gewünschte Auflösung der GTIME-Zeitangabe für die Formate ISO4 und BIN an. Zum Aufbau der Ausgabebereiche siehe die beim Operanden TOD=YES angegebenen Bereiche.
SEC
Die Zeit wird auf Sekunden genau angegeben.
MICROSEC
Die Zeit wird auf Mikrosekunden genau angegeben.
TOD=
entscheidet, ob die aktuelle Uhrzeit ausgegeben wird.
NO
Es werden keine Informationen über die aktuelle Uhrzeit übergeben.
YES
Die aktuelle Uhrzeit wird in einen Datenbereich übertragen. In welchem Bereich und in welchem Format die Information übergeben wird, hängt vom Wert des Operanden FORMAT ab:
FORMAT=ISO4
Die aktuelle Uhrzeit wird in der Form hh:mm:ss
übergeben (die beiden Doppelpunkte sind Bestandteil der Ausgabe). Dabei bedeuten:
| Stunde (zweistellig, ggf. mit führender Null) |
| Minute (zweistellig, ggf. mit führender Null) |
| Sekunde (zweistellig, ggf. mit führender Null) |
Der Datenbereich zur Aufnahme der Uhrzeit hat folgenden Aufbau (Makroauflösung mit MF=D und Standardwert für PREFIX):
* TIME OF DAY IN ISO4 FORMAT (EXAMPLE : 08:31:09) NTIGTDI DS 0XL8 _tod_iso4_mdl NTIGTDIH DS CL2 hour NTIGTDI1 DS CL1 colon1 NTIGTDIM DS CL2 minute NTIGTDI2 DS CL1 colon2 NTIGTDIS DS CL2 second * SECOND FRACTION OF TIME OF DAY IN ISO4 FORMAT * (EXAMPLE : .123456) NTIGTFI DS 0XL6 _ftod_iso4_mdl NTIGTFIM DS CL3 millisecond NTIGTFIN DS CL3 microsecond
FORMAT=BIN
Stunde, Minute und Sekunde werden jeweils als ganze Zahl (in Binärform) übergeben. Der Datenbereich zur Aufnahme der Uhrzeit hat folgenden Aufbau (Makroauflösung mit MF=D und Standardwert für PREFIX):
* TOD IN BINARY FORMAT NTIGTDB DS 0XL6 _tod_bin_mdl NTIGTDBH DS H hour NTIGTDBM DS H minute NTIGTDBS DS H second * SECOND FRACTION OF TOD IN BINARY FORMAT NTIGTFB DS 0XL4 _ftod_bin_mdl NTIGTFBM DS H millisecond NTIGTFBN DS H microsecond
XCS_MODE=
liefert einen Zeitwert, der innerhalb des XCS-Verbundes bzgl. eines DLM-Locks für eine gemeinsame Ressource streng monoton ist.
*NO
Die oben beschriebene Monotonie wird nicht gefordert.
*YES
gibt einen Zeitwert aus, der unter der folgenden Bedingung innerhalb eines XCS-Verbundes monoton steigt:
Der Aufrufer muss zum Aufrufzeitpunkt einen DLM-Lock (siehe Abschnitt „Distributed-Lock-Manager (DLM)“) halten. Die Monotoniebeziehung gilt nur für die Zeitstempel, die unter dem gleichen Lock geholt wurden.
Der Zeitwert kann für Logging-Einträge genutzt werden.
Der Einsatz ist auf das Ausgabeformat FORMAT=*TODR und MODE=*UTC beschränkt. Nur im TODR-Format wird die benötigte Auflösung erreicht. Mit der Einschränkung auf MODE=*UTC ist sichergestellt, dass die Monotonie auch im Moment einer Zeitumstellung für alle Knotenrechner erhalten bleibt.
ZONE=
entscheidet, ob Kenngrößen der lokalen Zeitzone ausgegeben werden.
NO
Es werden keine Informationen über die lokale Zeitzone übergeben.
YES
Kenngrößen der lokalen Zeitzone werden in einen Datenbereich übertragen. In welchem Bereich und in welchem Format die Informationen übergeben werden, hängt vom Wert des Operanden FORMAT ab:
FORMAT=ISO4
Die Kenngrößen der lokalen Zeitzone werden in der Form shh1:mm1-hh2:mm2-z
übergeben (die Doppelpunkte und Bindestriche sind Bestandteil der Ausgabe). Dabei bedeuten:
| „+“ oder „-“: Vorzeichen des Zeitunterschiedes der lokalen Zeitzone |
| Zeitunterschied der lokalen Zeitzone zur UTC in Stunden (hh) und |
| Zeitverschiebung in der lokalen Zeitzone zwischen Sommer- und |
| „W“ oder „S“: Aktuelle Zeitzählung in der lokalen Zeitzone (W für |
Der Datenbereich zur Aufnahme dieser Informationen hat folgenden Aufbau (Makroauflösung mit MF=D und Standardwert für PREFIX):
* ZONE IN ISO4 FORMAT (EXAMPLE :+08:00-01:00-S) NTIGZOI DS 0XL14 _zone_iso4_mdl * NTIGZOIC DS 0XL6 time_zone NTIGZOIS DS CL1 sign NTIGZOIH DS CL2 hour NTIGZOI1 DS CL1 colon1 NTIGZOIM DS CL2 minute * NTIGZOI2 DS CL1 hyphen1 NTIGZSIC DS 0XL5 seasonal_difference NTIGZSIH DS CL2 hours NTIGZSI1 DS CL1 colon1 NTIGZSIM DS CL2 minutes * NTIGZSI2 DS CL1 hyphen2 NTIGZSIA DS FL1 actual season * _season_iso4_s NTIGZSIW EQU 230 'W': Wintertime NTIGZSIS EQU 226 'S': Daylight Savings Time
FORMAT=BIN
Die Kenngrößen der lokalen Zeitzone werden jeweils als ganze Zahlen (in Binärform) übergeben. Der Datenbereich zur Aufnahme dieser Informationen hat folgenden Aufbau (Makroauflösung mit MF=D und Standardwert für PREFIX):
* ZONE IN BINARY FORMAT NTIGZOB DS 0XL10 _zone_bin_mdl * NTIGTIMEZONE DS 0XL4 time_zone NTIGZOBH DS H hour NTIGZOBM DS H minute * * NTIGSEASONAL_DIFFERENCE DS 0XL4 seasonal_difference NTIGZSBH DS H hours NTIGZSBM DS H minutes * NTIGZSBA DS FL1 actual season * _season_bin_s NTIGZSBW EQU 0 Wintertime NTIGZSBS EQU 1 Daylight Savings Time * NTIGZONE_BIN_FILL DS XL1 to fill the gap
Hinweise zu Umstellungszeitpunkten
Um die CTIME-Funktionalität mit nicht-systemeigenen Umstellungszeitpunkten zu nutzen, muss man die Umstellungszeitpunkte vom System, auf dem die Zeitdaten entstehen, erfragen können. BS2000 kann max. 400 Umstellungszeitpunkte verwalten. Dabei kann pro GTIME-Aufruf ein Umstellungszeitpunkt erfragt werden.
Die Informationen über die Umstellungszeitpunkte werden in einem Feld mit der Länge 8 Byte (<prefix><macid>CHD
) zur Verfügung gestellt. Mit den beim Operanden CHDATE angegebenen Werten wird die Richtung der Abfrage der Umstellungszeitpunkte vorgegeben. Bezugspunkt ist dabei die Information, die zur Aufrufzeit von GTIME in diesem Feld steht:
Sind alle acht Byte des Feldes mit X'00' belegt, beginnt die Suche nach dem nächsten oder vorhergehenden Umstellungszeitpunkt bei der aktuellen Systemzeit. Ist das Feld dagegen mit einem Datum vorbelegt, wird dieses als bereits von GTIME gelieferte CHDATE-Information interpretiert und die Suche beginnt ab diesem Datum.
Die CHDATE-Informationen liegen als STCK-Werte auf UTC-Basis vor, die um 8 Bits logisch nach rechts verschoben wurden (SRDL-Befehl). Das niederwertigste Bit zeigt dabei die Art der Umstellung an: Ist das Bit 0, wird von Winter- auf Sommerzeit umgestellt, bzw. umgekehrt, wenn das Bit 1 ist.
Diese Daten müssen für die CTIME-Funktion in einer Tabelle angeordnet werden. Der Aufbau der Tabelle ist aus der Beschreibung des CTIME-Makros, Operand CHDLxIN bzw. CHDLOUT, zu entnehmen. Die Arbeitsweise mit Umstellungszeitpunkten ist ebenfalls beim Makro CTIME anhand eines Beispiels beschrieben (siehe "CTIME - Mit Zeitstempeln rechnen").
Auf die Rückgabedaten im Datenbereich kann mit folgenden Namen zugegriffen werden (Standardwerte für PREFIX und MACID):
NTIGCHD DS 0XL8 change date * NTIGTODC DS 0XL8 s_todr NTIGCHDATE_UN DS 0XL8 chdate_un NTIGCHDATE_VALUE DS XL8 chdate_bit64 ORG NTIGCHDATE_UN * NTIGCHDATE_MDL DS 0XL8 chdate_mdl NTIGCHD1 DS F most significant word NTIGCHD2 DS F least significant word
Registerverwendung
Beim Aufruf des Makros GTIME werden folgende Register benötigt:
R1: wird vom Makro mit der Adresse des Datenbereichs geladen.
R13: ist vor dem Makroaufruf mit der Adresse eines 18 Worte langen Sicherstellungsbereiches zu laden, den das aufrufende Programm zur Verfügung stellen muss.
R14: wird vom Makro mit der Rückkehradresse des Anwenderprogramms geladen.
R15: wird von der (über GTIME) gerufenen Routine überschrieben.
Rückinformation und Fehleranzeigen
Standardheader:
+---------------+ | | | | | |c|c|b|b|a|a|a|a| +---------------+
Über die Ausführung des Makros GTIME wird im Standardheader folgender Returncode übergeben (cc=Subcode2, bb=Subcode1, aaaa=Maincode):
cc | bb | aaaa | Erläuterung |
00 | 00 | 0000 | Funktion erfolgreich ausgeführt. |
02 | 0010 | Die Funktion wurde ausgeführt, aber dem System ist kein früheres CHDATE | |
02 | 0011 | Die Funktion wurde ausgeführt, aber dem System ist kein späteres CHDATE | |
02 | 0012 | Die Funktion wurde ausgeführt, aber dem System ist kein CHDATE bekannt. | |
20 | 0008 | Der Returncode kann nur bei Angabe von XCS_MODE=*YES auftreten. |
Weitere Returncodes, deren Bedeutung durch Konvention makroübergreifend festgelegt ist, können der Tabelle „Standard-Returncodes“ (Standardheader) entnommen werden.
Das aufrufende Programm wird beendet, wenn folgende Fehler auftreten:
Der Datenbereich ist dem Aufrufer nicht zugewiesen.
Der Datenbereich ist nicht auf Wortgrenze ausgerichtet.
Der Datenbereich ist gegen Schreibzugriff geschützt.
Im Datenfeld <prefix><macid>EPD (ein Byte) wird bei jedem GTIME-Aufruf die aktuelle Epoche des TODR geliefert, siehe Abschnitt „Systemzeit-Verwaltung“ im Handbuch „Systembetreuung“ [10].
Beispiele siehe Abschnitt „S-Typ-Makroaufrufe“ und beim Makro CTIME unter "CTIME - Mit Zeitstempeln rechnen".