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 CTIME bietet folgende Funktionen:
die Änderung der Darstellung von Zeitstempeln (FUNCT=*CONV)
die Addition und Subtraktion einer Zeitspanne von einem Zeitstempel (FUNCT=*ADD)
die Ermittlung der Zeitspanne zwischen zwei Zeitstempeln (FUNCT=*DIFF)
CTIME stellt die Ergebnisse im Datenbereich wahlweise in abdruckbarer, binärer oder TODR/TODX-Form zur Verfügung.
Hinweise
Der Makro CTIME benutzt keinen SVC.
Da die Funktionen des Makros CTIME nicht über einen SVC, sondern über eine Unterprogrammschnittstelle ausgelöst werden, muss ein Programm, das CTIME aufruft, einen 18 Worte langen Sicherstellungsbereich zur Verfügung stellen. Vor dem Makroaufruf ist die Adresse dieses Sicherstellungsbereiches in Register R13 zu laden.
Der Datenbereich enthält Speicherbereiche für:
1. Eingabezeitstempel |
| Länge: 48 Byte |
2. Eingabezeitstempel |
| Länge: 48 Byte |
Eingabezeitspanne |
| Länge: 32 Byte |
Ausgabezeitstempel |
| Länge: 48 Byte |
Ausgabezeitspanne |
| Länge: 32 Byte |
wobei die Feldnamen für PREFIX=N und MACID=TIC gelten.
Über Zeitstempel und Zeitspannen lassen sich die DSECTs NTICS (für Zeitstempel) und NTICD (für Zeitspannen) legen, um die Datenfelder mit den Zeitangaben anzusprechen.
Ein Zeitstempel besteht aus Datum (Jahr, Monat, Tag, Wochentag) und Uhrzeit (Stunde, Minute, Sekunde, Millisekunde, Mikrosekunde). Er bezieht sich immer auf eine bestimmte Zeitbasis und kann in verschiedenen Formaten angegeben werden. Zeitspannen bestehen aus Angaben von Tagen und Uhrzeit und können ebenfalls in verschiedenen Formaten angegeben werden.
Mögliche Zeitbasen sind:
UTC: Universal Time Coordinate entspricht Greenwich Time (Weltzeit)
LTI: Local Time (lokale Zeit im aufrufenden System)
FZ: Foreign Zone („fremde“, beliebige Zeitbasis)
Bei Angabe der beliebigen Zeitbasis ist der Zeitstempel nur dann eindeutig, wenn Zonen-Informationen mitgegeben werden. Diese Informationen geben Auskunft darüber, welche Weltzeit-Zonen-Differenz und/oder welche Sommer-Winterzeit-Umstellungsdifferenz beachtet werden muss und ob der Zeitstempel in Sommer- oder Winterzeit angegeben wurde.
Die Darstellung eines Zeitstempels ist in folgenden Formaten möglich:
| ISO4 | |||||||||||||||||||||||||||||||||||||||||||||||||
abdruckbares Format in Dezimalzahlen mit dem Aufbau
Es bedeutet in folgender Reihenfolge:
| |||||||||||||||||||||||||||||||||||||||||||||||||
Der Datenbereich zur Aufnahme des Zeitstempels hat folgenden Aufbau (Makroauflösung mit MF=D und PREFIX=N): NTICSISO4 DS 0XL48 timestamp in iso4
NTICSDATE_U DS 0XL10 date union
*
NTICSMD DS 0XL10 date
NTICSIDY DS CL4 year
NTICSID1 DS CL1 hyphen1
NTICSIDM DS CL2 month
NTICSID2 DS CL1 hyphen2
NTICSIDD DS CL2 day
*
ORG NTICSDATE_U
NTICSDATE_CHAR DS CL10 date_char
ORG NTICSDATE_U+10
NTICSIDJ DS CL3 julian
NTICSIDB DS CL1 blank
*
NTICSMW DS 0CL2 begin of weekday
NTICSIWD DS CL2 weekday
*
NTICSMT DS 0CL8 time: "hh:mm:ss"
NTICSITH DS CL2 hour
NTICSIT1 DS CL1 colon1
NTICSITM DS CL2 minute
NTICSIT2 DS CL1 colon2
NTICSITS DS CL2 second
*
NTICSMZ DS 0CL14 zone: "shh:mm-hh:mm-a"
NTICSIZS DS CL1 zonesign
NTICSIZH DS CL2 zonehour
NTICSIZ1 DS CL1 colon3
NTICSIZM DS CL2 zoneminute
NTICSIZ2 DS CL1 hyphen3
NTICSISH DS CL2 seasonhour
NTICSIS1 DS CL1 colon4
NTICSISM DS CL2 seasonminute
NTICSIS2 DS CL1 hyphen4
NTICSISA DS FL1 actualseason
*
NTICSMF DS 0XL6 begin of fraction of second
NTICSIF DS 0CL6 fraction of second : "mmmuuu"
NTICSIFM DS CL3 millisecond
NTICSIFN DS CL3 microsecond
NTICSILE EQU *-NTICSISO4 LENGTH OF ISO4 TIMESTAMP
* (without address of CHDATE List)
NTICSCDL DS A chdates_addr
| |||||||||||||||||||||||||||||||||||||||||||||||||
BINAR | Die numerischen Werte werden binär in Halbworten angegeben. Der Datenbereich zur Aufnahme des Zeitstempels hat folgenden Aufbau NTICSBINAR DS 0XL42 timestamp in binar NTICSBDY DS H year NTICSBDM DS H month NTICSBDD DS H day NTICSBDJ DS H julian NTICSFILL1 DS CL6 fill1 NTICSBWD DS H weekday * NTICSBTH DS H hour NTICSBTM DS H minute NTICSBTS DS H second NTICSBL1 EQU *-NTICSBINAR LENGTH OF BINARY TIMESTAMP * PART1 (date & time) NTICSFILL2 DS CL2 fill2 NTICSBZH DS H zonehour NTICSBZM DS H zoneminute NTICSBSH DS H seasonhour NTICSBSM DS H seasonminute NTICSBSA DS FL1 actualseason NTICSFILL3 DS CL5 fill3 * fraction of second NTICSBFM DS H millisecond NTICSBFN DS H microsecond NTICSBL2 EQU *-NTICSBFM LENGTH OF BINARY TIMESTAMP * PART2 (fraction of second) NTICSBLE EQU *-NTICSBINAR LENGTH OF BINARY TIMESTAMP | ||||||||||||||||||||||||||||||||||||||||||||||||
| TODR | |||||||||||||||||||||||||||||||||||||||||||||||||
Time-Of-Day-Register-Format: Das TOD-Register hat die Länge eines Doppelwortes Es wird durch die Hardware laufend hochgezählt. Mit dem STCK-Befehl kann Der Datenbereich zur Aufnahme des Zeitstempels hat folgenden Aufbau NTICST DS 0XL8 timestamp in TODR NTICSTMS DS F most significant word: * approx sec NTICSTLS DS F least significant word: * micro_sec * 2**12 | |||||||||||||||||||||||||||||||||||||||||||||||||
| TODX | |||||||||||||||||||||||||||||||||||||||||||||||||
Erweitertes Time-Of-Day-Register-Format: es hat die Länge eines Doppelwortes und enthält die Anzahl der Mikrosekunden seit dem Der Datenbereich zur Aufnahme des Zeitstempels hat folgenden Aufbau (Makroauflösung mit MF=D und PREFIX=N): NTICSX DS 0XL8 timestamp in TODX NTICSTHW DS F high word NTICSTLW DS F low word |
Die Darstellung von Zeitspannen ist in folgenden Formaten möglich:
| ISO4 / ISO4MIC | |
abdruckbares Format in Dezimalzahlen NTICDI DS 0XL32 tdiff in iso4
NTICDIS DS CL1 sign
NTICDIDD DS CL10 day
NTICDID1 DS CL1 hyphen
NTICDITH DS CL2 hour
NTICDIT1 DS CL1 colon1
NTICDITM DS CL2 minute
NTICDIT2 DS CL1 colon2
NTICDITS DS CL2 second
NTICDIFP DS CL1 point
NTICDIFM DS CL3 millisecond
NTICDIFN DS CL3 microsecond
NTICDILE EQU *-NTICDI LENGTH OF ISO4 TIMEDIFFERENCE
* (without unused field)
DS CL5 unused
| |
| BINAR / BINARMIC | |
binäre Angabe. NTICDB DS 0XL16 tdiff in binar
NTICDBDD DS F day
NTICDBTH DS H hour
NTICDBTM DS H minute
NTICDBTS DS H second
NTICDBFM DS H millisecond
NTICDBFN DS H microsecond
NTICDBLE EQU *-NTICDB LENGTH OF BINARY TIMESTAMP
* (without the fill field)
DS H to fill the gap
| |
TODR | |
Time-Of-Day-Register-Format. NTICDT DS 0XL8 tdiff in TODR (for C) NTICDTMS DS F most significant word: * approx. sec NTICDTLS DS F least significant word: * micro_sec * 2**12 | |
TODX | |
Erweitertes Time-Of-Day-Register-Format. NTICDX DS 0XL8 tdiff in TODX (for C) NTICDTHW DS F high word NTICDTLW DS F low word |
Wertebereiche
Es gelten die folgenden Wertebereiche für die Arbeit mit dem CTIME-Makro. Zu beachten ist die Unterscheidung in der Format-Darstellung bei den Ein- und Ausgabe-Zeitstempeln und Zeitspannen.
BINAR- oder ISO4-Format:
01.01.1900 00:00:00,000000 < Zeitstempel < 31.12.9999 23:59:59,999999
erlaubte Zeitdifferenz: ± 2147483647 Tage
TODR-Format:
t0 < Zeitstempel < t1
erlaubte Zeitdifferenz: ± 26062 Tage
t0 und t1 sind dabei abhängig von der festgelegten Epoche für das TOD-Register. Für die Standardepoche (GTIME-Parameter EPOCH=00) beträgt der Wertebereich for das TODR-Format:
01.01.1900 00:00:00,000000 < Zeitstempel < 17.09.2042 23:53:47,370495
TODX-Format:
01.01.1900 00:00:00,000000 <= Zeitstempel <= 18.03.4317 02:44:48,587775
erlaubte Zeitdifferenz: ± 882867 Tage
Makroaufrufformat und Operandenbeschreibung
CTIME |
FUNCT=*CONV / *ADD / *ADDLL / *DIFF / adr / (r) ,BASE1IN=*UTC / *LTI / *FZ / adr / (r) ,FRM1IN=*ISO4 / *ISO4MIC / *BINAR / *BINARMIC / *TODR / *TODX / adr / (r) ,INF1IN=*CALEND / *JULIAN / adr / (r) ,FRM1ZIN=*NONE / *ISO4 / *ISO4LST / *BINAR / *BINARLST / adr / (r) ,CHDL1IN=*NONE / adr / (r) ,BASE2IN=*UTC / *LTI / *FZ / adr / (r) ,FRM2IN=*ISO4 / *ISO4MIC / *BINAR / *BINARMIC / *TODR / *TODX / adr / (r) ,INF2IN=*CALEND / *JULIAN / adr / (r) ,FRM2ZIN=*NONE / *ISO4 / *ISO4LST / *BINAR / *BINARLST / adr / (r) ,CHDL2IN=*NONE / adr / (r) ,BASEOUT=*LTI / *UTC / *FZ / adr / (r) ,FRMOUT=*ISO4 / *ISO4MIC / *BINAR / *BINARMIC / *TODR / *TODX / adr / (r) ,FRMZOUT=*NONE / *ISO4 / *ISO4LST / *BINAR / *BINARLST / adr / (r) ,CHDLOUT=*NONE / adr / (r) ,FRMDIN=*ISO4 / *ISO4MIC / *BINAR / *BINARMIC / *TODR / *TODX / adr / (r) ,FRMDOUT=*ISO4 / *ISO4MIC / *BINAR / *BINARMIC / *TODR / *TODX / adr / (r) ,LINKADR=*NONE / linkadr ,MF=D / C / L / M / E [,PARAM=adr / (r)] ,PREFIX=N / p ,MACID=TIC / macid |
In der nachfolgenden Operandenbeschreibung sind die Operanden alphabetisch geordnet.
BASE1IN=
BASE2IN=
BASEOUT=
gibt die Zeitbasis an, die für den 1. oder 2. Eingabe-Zeitstempel (bei BASE1IN bzw. BASE2IN) oder für den Ausgabe-Zeitstempel (bei BASEOUT) gültig ist.
*UTC
Der Zeitstempel wird in der Zeitbasis der Weltzeit UTC (Universal Time Coordinate, entspricht der Greenwich-Zeit) angegeben.
Dieser Wert ist Voreinstellung bei BASE2IN.
*LTI
Der Zeitstempel wird in der im Aufrufer-System gültigen lokalen Zeitbasis LTI (Local TIme) angegeben.
Dieser Wert ist Voreinstellung bei BASEOUT.
*FZ
Der Zeitstempel wird in einer fremden bzw. beliebigen Zeitbasis (Foreign Zone) angegeben. Die diese Zeitbasis charakterisierenden Informationen müssen in der Zonen-Information des betreffenden Zeitstempels mitgegeben und mit den jeweiligen Operanden spezifiziert werden (Angabe des Operanden FRMxZIN bzw. FRMZOUT erforderlich).
adr
symbolische Adresse (Name) eines Feldes, das zuvor mit dem entsprechenden Equate geladen werden muss. Länge = 1 Byte.
(r)
r= Register mit dem Wert des entsprechenden Equates.
CHDL1IN=
CHDL2IN=
CHDLOUT=
gibt für FZ-Zeitstempel eine Tabelle (Liste) von Umstellungszeitpunkten mit, mit deren Hilfe die Einordnung der Zeitstempel in Sommer- oder Winterzeit erfolgt.
Eine Angabe ungleich *NONE ist nur bei MF=M und bei „FZ“-Zeitstempeln erlaubt.
*NONE
Es wird keine Tabelle mitgegeben.
adr
symbolische Adresse (Name) eines Feldes, das die Tabelle von Umstellungszeitpunkten enthält. Dieser Operandenwert ist nur mit bei MF=M erlaubt und darf nur in Verbindung mit BASExxx=*FZ angegeben werden. Die gewünschte Verarbeitung dieser Tabelle muss mit den Werten FRMxZIN=*ISO4LST/*BINARLST bzw. FRMZOUT=*ISO4LST/*BINARLST eingestellt werden. Zur eindeutigen Darstellung eines Zeitstempels gehört auch, dass die Felder Zonendifferenz und Umstellungsdifferenz der Zoneninformation belegt sind.
Die Tabelle muss auf Wortgrenze ausgerichtet und in folgender Form aufgebaut sein: Es werden aufeinander folgend Doppelworte erwartet, die die Informationen über die Umstellungszeitpunkte enthalten. Die CHDATE-Informationen liegen als STCK-Werte auf UTC-Basis vor, die um 8 Bits logisch nach rechts verschoben wurden (SRL-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.
Die Erstellung der Tabelle sollte mit GTIME CHDATE=... erfolgen. Die Werte in diesen Doppelworten müssen aufsteigend sein.
Die Tabelle muss mit einem Doppelwort D'0' beendet werden.
Zur Arbeitsweise siehe Beispiel auf "CTIME - Mit Zeitstempeln rechnen".
(r)
r = Register mit dem Adresswert von adr.
FRMDIN=
FRMDOUT
gibt an, welches Format der Eingabe-Zeitspanne vorliegt (bei FRMDIN als Eingabe-Zeitspanne) oder gewünscht wird (bei FRMDOUT als Ausgabe-Zeitspanne).
*ISO4
Die Zeitspanne wird im abdruckbaren Format dargestellt.
Bei FRMDOUT werden auch die Felder für Milli- und Mikrosekunden versorgt.
*ISO4MIC
Die Zeitspanne wird im abdruckbaren Format dargestellt. Bei FRMDIN wird die erhöhte Auflösung mit Milli- und Mikrosekunden erwartet.
*BINAR
Die Zeitspanne wird binär mit Festpunktzahlen dargestellt. Dabei werden die Tage mit 4 Byte, die Stunden, Minuten und Sekunden mit je 2 Byte dargestellt. Bei FRMDOUT werden auch die Felder für Milli- und Mikrosekunden versorgt.
*BINARMIC
Die Zeitspanne wird binär mit Festpunktzahlen dargestellt. Bei FRMDIN wird die erhöhte Auflösung mit Milli- und Mikrosekunden erwartet.
*TODR
Die Zeitspanne wird im Time-Of-Day-Register-Format dargestellt.
*TODX
Die Zeitspanne wird im erweiterten Time-Of-Day-Register-Format dargestellt.
adr
symbolische Adresse (Name) eines Feldes, das zuvor mit dem entsprechenden Equate geladen werden muss. Länge = 1 Byte.
(r)
r= Register mit dem Wert des entsprechenden Equates.
FRM1IN=
FRM2IN=
FRMOUT=
gibt an, welches Zeitstempel-Format vorliegt (bei FRM1IN, FRM2IN als Eingabe-Zeitstempel) oder gewünscht wird (bei FRMOUT als Ausgabe-Zeitstempel).
*ISO4
Der Zeitstempel wird im abdruckbaren Format dargestellt. Dieser Wert ist Voreinstellung bei FRM2IN und FRMOUT. Bei FRMOUT werden auch die Felder für Milli- und Mikrosekunden versorgt.
*ISO4MIC
Der Zeitstempel wird im abdruckbaren Format dargestellt. Bei den Eingabe-Zeitstempeln wird die erhöhte Auflösung mit Milli- und Mikrosekunden erwartet.
*BINAR
Der Zeitstempel wird binär mit Halbwort-Festpunktzahlen dargestellt. Bei FRMOUT werden auch die Felder für Milli- und Mikrosekunden versorgt.
*BINARMIC
Der Zeitstempel wird binär mit Halbwort-Festpunktzahlen dargestellt. Bei den Eingabe-Zeitstempeln wird die erhöhte Auflösung mit Milli- und Mikrosekunden erwartet.
*TODR
Der Zeitstempel wird im Time-Of-Day-Register-Format dargestellt.
*TODX
Die Zeitspanne wird im erweiterten Time-Of-Day-Register-Format dargestellt.
adr
symbolische Adresse (Name) eines Feldes, das zuvor mit dem entsprechenden Equate geladen werden muss. Länge = 1 Byte.
(r)
r= Register mit dem Wert des entsprechenden Equates.
FRM1ZIN=
FRM2ZIN=
FRMZOUT=
gibt das Format der mitgegebenen (bei FRMxZIN) bzw. der gewünschten (bei FRMZOUT) zusätzlichen Zonen-Information an, die die Zeitbasis des spezifizierten Zeitstempels charakterisiert.
Die Angabe des Operanden ist zwingend, wenn für den betreffenden Zeitstempel die Zeitbasis „FZ“ angegeben wurde.
Für einen LTI-Eingabe-Zeitstempel kann vorgegeben werden, ob die für den Zeitstempel mitgegebene Information Sommer- oder Winterzeit ausgewertet werden soll. „*NONE“ bedeutet dabei keine Auswertung, andere Werte verlangen, dass das entsprechende Feld der Zonen-Information mit einem gültigen Wert gefüllt ist.
Im Falle des Ausgabe-Zeitstempels gibt der Operand FRMZOUT an, in welchem Format die Ausgabe der Zonen-Information erfolgt. Bei „*NONE“ wird das Format des Zeitstempels selbst übernommen (liegt das Format „*TODR“ vor, wird die Zonen-Information binär ausgegeben).
*NONE
Es wird keine Information mitgegeben.
*ISO4
Die Zonen-Information wird im abdruckbaren Format angegeben.
*ISO4LST
Die Zonen-Information wird im abdruckbaren Format angegeben. Die Adresse der CHDATE-Tabelle muss durch den Operanden CHDLxIN bzw. CHDLOUT bekanntgegeben werden.
Die Angabe in der Zonen-Information, ob es sich um einen Zeitstempel für Sommer- oder Winterzeit handelt, wird dabei nicht berücksichtigt. Der FZ-Zeitstempel wird mit dieser Tabelle verglichen und daraus die Sommer-/Winterzeit-Information gewonnen (siehe auch Beispiel auf "CTIME - Mit Zeitstempeln rechnen").
*BINAR
Die Zonen-Information wird binär als Halbwort-Festpunktzahl angegeben.
*BINARLST
Die Zonen-Information wird binär als Halbwort-Festpunktzahl angegeben. Die Adresse der CHDATE-Tabelle muss durch den Operanden CHDLxIN bzw. CHDLOUT bekanntgegeben werden.
Die Angabe in der Zonen-Information, ob es sich um einen Zeitstempel für Sommer- oder Winterzeit handelt, wird dabei nicht berücksichtigt. Der FZ-Zeitstempel wird mit dieser Tabelle verglichen und daraus die Sommer-/Winterzeit-Information gewonnen (siehe auch Beispiel auf "CTIME - Mit Zeitstempeln rechnen").
adr
symbolische Adresse (Name) eines Feldes, das zuvor mit dem entsprechenden Equate geladen werden muss. Länge = 1 Byte.
(r)
r= Register mit dem Wert des entsprechenden Equates.
FUNCT=
gibt an, welche Funktion des CTIME-Makros ausgeführt werden soll.
*CONV
Der 1. Eingabe-Zeitstempel wird in eine andere Darstellung konvertiert. Das Ergebnis wird in den Ausgabezeitstempel geschrieben.
*ADD
Die Eingabezeitspanne wird zum 1. Eingabe-Zeitstempel addiert. Das Ergebnis steht im Ausgabe-Zeitstempel. Die Eingabe-Zeitspanne kann auch negativ sein. Das Format der Eingabe-Zeitspanne wird mit dem Operanden FRMDIN angegeben.
*ADDLL
Wie bei *ADD wird die Eingabezeitspanne zum 1. Eingabe-Zeitstempel addiert.
Es wird jedoch berücksichtigt, dass zwischen dem Eingabe-Zeitstempel und dem Ausgabe-Zeitstempel ein Sommer-Winterzeit-Umstellungszeitpunkt ist. (Solche Umstellungstage sind nicht wie üblich 24 Stunden lang, sondern um die Umstellungsdifferenz verlängert oder verkürzt. Bei der Addition werden sie im Gegensatz zu *ADD trotzdem als 24-Stunden-Tage betrachtet.) Das Ergebnis steht im Ausgabe-Zeitstempel. Die Eingabe-Zeitspanne kann auch negativ sein.
Beispiel
Die Umstellung von Winter- auf Sommerzeit fand am 30.03.2008 um 02:00:00 statt.
Eingabe-Zeitstempel 2008-03-29,23:00:00 Eingabe-Zeitspanne +00001-00:00:00 (1 Tag) Ergebnis von *ADD 2008-03-31,00:00:00 Ergebnis von *ADDLL 2008-03-30,23:00:00
*DIFF
Es wird die Zeitdifferenz vom 2. Eingabe-Zeitstempel zum 1. Eingabe-Zeitstempel berechnet. Das Ergebnis steht in der Ausgabe-Zeitspanne.
adr
symbolische Adresse (Name) eines Feldes, das zuvor mit dem entsprechenden Equate geladen werden muss. Länge = 1 Byte.
(r)
r= Register mit dem Wert des entsprechenden Equates.
INF1IN=
INF2IN=
gibt an, wie bei dem jeweiligen Eingabe-Zeitstempel der Tag des Jahres angegeben ist.
*CALEND
Die Angabe erfolgt in der üblichen Darstellung von Monat und Tag des Monats.
*JULIAN
Die Angabe des Tages erfolgt in der julianischen Schreibweise: die Tage des Jahres werden, beginnend mit dem 1. Januar, fortlaufend durchgezählt.
adr
symbolische Adresse (Name) eines Feldes, das zuvor mit dem entsprechenden Equate geladen werden muss. Länge = 1 Byte.
(r)
r= Register mit dem Wert des entsprechenden Equates.
LINKADR=
gibt an, auf welche Weise dem Anwenderprogramm die Adresse des Einsprungpunktes IGTCTI für die CTIME-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 die Einsprungstelle IGTCTI, der beim Binden über die Autolink-Funktion des BLS aufgelöst wird.
Dieser Wert kann verwendet werden, wenn das Modul, das den CTIME-Aufruf enthält,
immer mit dem Dynamischen Bindelader DBL gebunden und geladen wird (in diesem Fall lässt man den CTIME in der E-Form eine V-Konstante absetzen, welche beim Ladevorgang durch das BLS versorgt wird) oder
mit 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 CTIME-Aufruf die Adresse der Einsprungstelle IGTCTI bereitgestellt hat.
Das folgende Beispiel zeigt, wie dem Programm die Adresse der Einsprungstelle IGTCTI zunächst durch einen geeigneten BIND-Aufruf zur Verfügung gestellt und anschließend für den CTIME-Aufruf in das mit linkadr bezeichnete Wort übertragen werden kann:
BIND MF=E,PARAM=BINDPL
:
CTIME MF=E,PARAM=OPLIST,LINKADR=AENTRY
:
AENTRY DS F
OPLIST CTIME MF=L,...
BINDPL BIND MF=L,SYMBOL=IGTCTI,SYMBLAD=AENTRY
Auf diese Weise muss dem Anwenderprogramm die Einsprungadresse der CTIME-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 CTIME-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 AAbschnitt „S-Typ-Makroaufrufe“).
Bei der E-Form und der M-Form des Makroaufrufs wird das Label des Datenbereichs im Operanden PARAM angegeben. Der Datenbereich muss auf Doppelwort ausgerichtet sein. Voreinstellung: NTICPA
Beim Aufruf des Makros mit MF=L muss der Anwender dieses Label explizit angeben, sonst wird eine MNOTE ausgegeben.
Registerverwendung
Beim Aufruf des Makros CTIME 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 |
R14 | wird vom Makro mit der Rückkehradresse des Anwenderprogramms geladen. |
R15 | wird von der (über CTIME) gerufenen Routine überschrieben. |
Rückinformation und Fehleranzeigen
Standardheader:
+---------------+ | | | | | |c|c|b|b|a|a|a|a| +---------------+
Über die Ausführung des Makros CTIME wird im Standardheader folgender Returncode übergeben (cc=Subcode2, bb=Subcode1, aaaa=Maincode):
cc | bb | aaaa | Erläuterung |
00 | 00 | 0000 | Funktion erfolgreich ausgeführt. |
01 | 0001 | Die Funktion wurde abgebrochen: Ein angegebener Zeitstempel im | |
01 | 0002 | Die Funktion wurde abgebrochen: Die Zoneninformation zu einem angegebenen | |
01 | 0003 | Die Funktion wurde abgebrochen: Die Angabe einer Zeitspanne ist fehlerhaft. Maßnahme: Zeitspannen-Angabe korrigieren. | |
01 | 0006 | Die Funktion wurde abgebrochen: Die Spezifikation der Ein- oder Ausgabedaten | |
01 | 000D | Die Funktion wurde abgebrochen: Die Adresse der CHDATEs-Tabelle wurde | |
01 | 000E | Die Funktion wurde abgebrochen: Der Aufbau der CHDATEs-Tabelle ist
Maßnahme: | |
00 | 04 | FFFF | Die Funktion wurde abgebrochen: Der Datenbereich ist nicht auf |
02 | 00 | 0007 | Warnung: Die Funktion wurde ausgeführt, der Ausgabe-Zeitstempel liegt |
02 | 0008 | Warnung: Die Funktion wurde ausgeführt, die Darstellung des angegebenen | |
02 | 0009 | Warnung: Eingabe-Zeitstempel nicht eindeutig. Maßnahme: | |
02 | 000A | Warnung: Ausgabe-Zeitstempel nicht eindeutig. | |
02 | 000B | Warnung: Die Funktion wurde ausgeführt, bei der Addition von einer | |
02 | 000C | Warnung: Die Funktion wurde ausgeführt, bei der Subtraktion von einer | |
02 | 000F | Warnung: Die Funktion wurde ausgeführt, der Ausgabe-Zeistempel liegt |
Weitere Returncodes, deren Bedeutung durch Konvention makroübergreifend festgelegt ist, können der Tabelle „Standard-Returncodes“ (Standardheader) entnommen werden.
Wenn Subcode1 ungleich Null ist, wird nur der Returncode im Standardheader gesetzt und keine weiteren Daten übertragen.
Das aufrufende Programm wird beendet, wenn folgende Fehler auftreten:
Der Datenbereich ist dem Aufrufer nicht zugewiesen.
Der Datenbereich ist nicht auf Doppelwortgrenze ausgerichtet.
Der Datenbereich ist gegen Schreibzugriff geschützt.
Beispiel für die Nutzung einer anwenderspezifischen Tabelle von CHDATEs
TITLE 'GTIME and CTIME'
*
PRINT NOGEN,BASE
GPARMOD 31
*
CGTIME @ENTR TYP=M
BIND MF=E,PARAM=BINDPLG
BIND MF=E,PARAM=BINDPLC
*
LA R1,GTPAR1
USING NTIGPL,R1
MVC NTIGCHD(NTIGCHDL),=A(0,128) ----------------------------- (1)
LA R3,CHDATES ---------------------------------------------- (2)
*
@CYCL ,
GTIME MF=E,PARAM=(R1),LINKADR=AENTRYG ------------------------- (3)
MVC 0(NTIGCHDL,R3),NTIGCHD ---------------------------------- (4)
LA R3,NTIGCHDL(R3) ----------------------------------------- (5)
*
@WHEN NE
CLC NTIGRET,=A(0)
@BREA , ------------------------------------------------------- (6)
*
@BEND ,
*
**********************************************************************
* Following this part of the program, the system's CHDATES are *
* already stored in the CHDATES memory area. *
**********************************************************************
*
DTH1 LA R1,CTPAR2
USING NTICPL,R1
CTIME MF=M,CHDLOUT=CHDATES
*
RDATA MF=(E,READDATE) ----------------------------------------- (7)
LA R1,CTPAR2
USING NTICPL,R1
MVC NTIC1MD(L'DATEDATE),DATEDATE ---------------------------- (8)
MVC NTIC1MT(L'DATETIME),DATETIME
MVC NTIC3MZ(14),=C'+01:00:-01:00-'
CTIME MF=E,PARAM=(R1),LINKADR=AENTRYC ------------------------- (9)
*
END @EXIT
*
**********************************************************************
* With the above section of the program, RDATA is used to read in a *
* date in the format "yyyy mm dd hh mm ss" from the terminal and to *
* convert it using the CTIME from UTC to FZ, taking into account the *
* CHDATEs table. The event is shown in ISO4 format in the parameter *
* list in the output time stamp. *
**********************************************************************
*
READDATE RDATA INDATE,0,MF=L ------------------------------------------- (10)
*
INDATE DS 0CL30
DATELEN DS CL2
DATERES DS CL2
DATEDATE DS CL10
DATESPAC DS CL1
DATETIME DS CL8
*
GTPAR1 GTIME MF=L,CHDATE=NEXT -----------------------------------------(3)
*
CTPAR2 CTIME MF=L,FUNCT=*CONV,BASE1IN=*UTC,FRM1IN=*ISO4, C
BASEOUT=*LTI,FRMOUT=*ISO4 ------------------------------- (9)
*
CHDATES DS 100D ---------------------------------------------------- (11)
*
BINDPLG BIND MF=L,SYMBOL=I@GTIME,SYMBLAD=AENTRYG
BINDPLC BIND MF=L,SYMBOL=IGTCTI,SYMBLAD=AENTRYC
*
AENTRYG DS A
AENTRYC DS A
*
@END ,
**********************************************************************
* DSECTs *
**********************************************************************
*
NTICPL CTIME MF=D
NTIGPL GTIME MF=D
END
(1) | Vorbelegung der GTIME-Parameterliste mit einem Wert, der sichert, dass die folgenden CHDATEs in chronologischer Reihenfolge geliefert werden. |
(2) | In Register R3 wird die Speicheradresse des CHDATEs geladen. |
(3) | Mit dem GTIME-Aufruf wird das erste bzw. nächstes CHDATE geholt. |
(4) | Es wird im Speicherbereich gesichert. |
(5) | Der Zeiger auf die CHDATEs-Tabelle wird um X'08' hochgezählt. |
(6) | Die Schleife soll verlassen werden, wenn es kein nächstes CHDATE mehr gibt (oder im Fehlerfall). |
(7) | Der RDATA fordert die Eingabe eines Datums über Datensichtstation an. Das Datum muss im Format |
(8) | Der CTIME-Datenbereich wird mit Datum und Zone versorgt. |
(9) | Der Eingabezeitstempel wird von UTC in LTI konvertiert. Der Ausgabezeitstempel soll - ebenso wie der Eingabezeitstempel - im ISO4-Format vorliegen. |
(10) | RDATA-Datenbereich mit Definition des Eingabefeldes |
(11) | Bereichsdefinition für maximal 100 CHDATEs. |
Ablaufprotokoll
/start-assembh % BLS0500 PROGRAM 'ASSEMBH', VERSION '<ver>' OF '<date>' LOADED % ASS6010 <ver> OF BS2000 ASSEMBH READY //compile source=*library-element(macexmp.lib,cgtime), - // compiler-action=module-generation(module-format=llm), - // macro-library=$tsos.syslib.assembh.012, - ------------------- (12) // module-library=macexmp.lib, - // listing=parameters(output=*library-element(macexmp.lib,cgtime)), - // test-support=*aid % ASS6011 ASSEMBLY TIME: 1605 MSEC % ASS6018 0 FLAGS, 0 PRIVILEGED FLAGS, 0 MNOTES % ASS6019 HIGHEST ERROR-WEIGHT: NO ERRORS % ASS6006 LISTING GENERATOR TIME: 101 MSEC //end % ASS6012 END OF ASSEMBH /add-file-link link-name=blslib00,file-name=$tsos.syslib.assembh.012 --- (13) /load-executable-program library=macexmp.lib,element-or-symbol=cgtime, - / dbl-parameters=*par(resolution=*par(alternate-libraries=*yes)) % BLS0523 ELEMENT 'CGTIME', VERSION '@' FROM LIBRARY ':2OSG:$QM212.MACEXMP.LIB' IN PROCESS % BLS0524 LLM 'CGTIME', VERSION ' ' OF '<date> <time>' LOADED /%in dth1 <%d %@(chdates) -> %xl96> ----------------------------------- (14) /%in end <%d indate,%1 -> %xl232> -------------------------------------- (15) /%r *** TID: 005000D8 *** TSN: 2QSE ******************************************** CURRENT PC: 0000006A CSECT: CGTIME ************************************* V'00000208' = CGTIME + #'00000208' ---------------------------------- (16) 00000208 (00000208) 008FF960 489C4000 0090D566 AC464001 ..9-.. ...N... . 00000218 (00000218) 0091BA3A 1E2A4000 00929F0D 900E4001 .j.... ..k.... . 00000228 (00000228) 009383E1 01F24000 009468B4 73D64001 .lc..2 ..m...O . 00000238 (00000238) 00954D87 E5BA4000 0096325B 579E4001 .n(gV. ..o.$.. . 00000248 (00000248) 0097172E C9824000 009804CF 49A04001 .p..Ib ..q.... . 00000258 (00000258) 00FFFFFF FFFFFF00 0099CE76 2D684001 .~~~~~~..r.... . *2012-01-20 14:36:35 --------------------------------------------------- (17) SRC_REF: 230 SOURCE: CGTIME PROC: CGTIME ******************************* INDATE = |....2012-01-20 14:36:35.......| CURRENT PC: 00000098 CSECT: CGTIME ************************************* V'00000120' = CGTIME + #'00000120' ----------------------------------- (18) 00000120 (00000120) 00050702 00000000 01010001 01010001 ................ 00000130 (00000130) 02010000 01010100 F2F0F1F2 60F0F160 ........2012-01- 00000140 (00000140) F2F0F0F0 F0404040 F1F47AF3 F67AF3F5 20000 14:36:35 00000150 (00000150) 00000000 00000000 00000000 00000000 ................ 00000160 (00000160) 00000000 00000000 F0F0F0F0 60F0F060 ........0000-00- 00000170 (00000170) F0F0F0F0 F0404040 F0F07AF0 F07AF0F0 00000 00:00:00 00000180 (00000180) 00000000 00000000 00000000 00000000 ................ 00000190 (00000190) 00000000 00000000 4EF0F0F0 F0F0F0F0 ........+0000000 000001A0 (000001A0) F0F0F060 F0F07AF0 F07AF0F0 00000000 000-00:00:00.... 000001B0 (000001B0) 00000000 00000000 F2F0F1F2 60F0F160 ........2012-01- 000001C0 (000001C0) F2F0F0F2 F040C6D9 F1F57AF3 F67AF3F5 20020 FR15:36:35 000001D0 (000001D0) 4EF0F17A F0F060F0 F17AF0F0 60E6F0F0 +01:00-01:00-W00 000001E0 (000001E0) F0F0F0F0 00000208 00000000 0000016C 0000...........% 000001F0 (000001F0) 00000000 00000000 00000000 00000000 ................ 00000200 (00000200) 00000000 00F8C180 .....8A.
(12) | Bei der Assemblierung wird die Bibliothek angegeben, die die für strukturierte Programme benötigten @-Makros enthält. |
(13) | Für den Ablauf von strukturierten Programmen wird ebenfalls die Bibliothek mit den @-Makros benötigt. Sie wird hier mit dem Linknamen BLSLIB00 und die Angabe ALTERNATE-LIBRARIES=*YES im Ladeaufruf zugewiesen. |
(14) | An der symbolischen Adresse DTH1 soll die Tabelle der CHKDATEs ausgegeben werden. |
(15) | An der symbolischen Adresse END sollen das Feld INDATE und die Operandenliste ausgegeben werden. Die Anfangsadresse der Operandenliste steht nach einem erfolgreichen CTIME-Aufruf im Register R1. Die Länge der Operandenliste beträgt 232 Byte (diese Information erhält man durch die Auflösung der DSECT mit CTIME MF=D). |
(16) | Die symbolische Adresse DTH1 wurde erreicht. Die Tabelle der CHDATEs wird ausgegeben. Im System sind z.Zt. 10 CHDATEs bekannt. Sie liegen im TODR-Format vor, um 1 Byte nach rechts verschoben. Das Ende der CHDATEs-Tabelle markiert das System mit X'00FFFFFF FFFFFF00'. |
(17) | Die Eingabe eines Zeitstempels wird angefordert (Prompt „*“). |
(18) | Die symbolische Adresse END wurde erreicht. Der Inhalt des Feldes INDATE wird ausgegeben: Der eingegebene Zeitstempel wurde von RDATA korrekt eingelesen. Ausgabe der Operandenliste:
|