General
Application areas: | Requesting and accessing lists and tables; see "Requesting and accessing lists and tables" |
Macro type: | Type S, MF format 3: C/D/E/L/M form; see "S-type macros" |
Macro description
The GTIME macro gives the following information:
the current date and time of day, either the UTC ('Universal Time Coordinate', corresponding to Greenwich Mean Time) or LT (standard 'Local Time' of the country). Monotony behavior for callers on different XCS network node computers can be requested at the same time
the current weekday
the time zone of the system (corresponds to the shift in time with respect to UTC) in hours and minutes
the amount of the time shift for daylight saving time (summer time) in hours and minutes
the current time shift with respect to the standard time (winter time) based on daylight saving time (summer time)
the points at which daylight saving time (summer time) changes to standard time (winter time) and vice versa
whether the system time is synchronized with an external reference and, if so, with which reference time source (e.g. radio clock)
whether a time change is due in the next hour
the current epoch for the TODR (see the “Introduction to System Administration” manual [10 (Related publications)])
GTIME supplies this information in the data area in printable, binary or TODR/TODX form (for the output of local time (LT) or the Universal Time Coordinate (UTC) only).
Notes
Because the functions of the GTIME macro are initiated via a subprogram interface rather than a SVC, a program calling GTIME must provide a save area 18 words long. The address of this save area must be loaded into register R13 before the macro call.
Apart from checking the standard header, there is no validation of the operand list.
Macro format and description of operands
GTIME |
MODE=LT / UTC ,FORMAT=ISO4 / BIN / TODR / TODX ,RESOLVE=SEC / MICROSEC ,LINKADR=*NONE / linkaddr ,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=addr / (r)] ,PREFIX=N / p ,MACID=TIG / macid |
The operands are described in alphabetical order below.
CHD_ANNOUNCMNT=
Informs about a time change by means of a flag.
*NO
The flag should not be set.
*YES
The flag is set if a time change is due within the next hour.
The data area for the output of the flag has the following structure (macro expansion with MF=D and standard value for 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=
Specifies the direction in which conversion times (CHDATEs) are to be sought. For further information on conversion times see notes on "GTIME - Get date and time".
NONE
Default setting. No (other) conversion time should be sought.
NEXT
The next conversion time should be sought.
The search begins at the contents of the field <prefix><macid>CHD.
PREV
The previous conversion time should be sought.
The search begins at the contents of the field <prefix><macid>CHD.
DATE=
Determines whether the current date is output.
NO
No information is given about the current date.
YES
The current date (calendar day and Julian date) is transferred to a data area. The value of the FORMAT operand governs the area and format in which the information is transferred:
FORMAT=ISO4
The current date is transferred in the form yyyy-mm-ddjjj (both hyphens are included in the output). Where:
| Year (four digits) |
The area in the operand list for accepting the date has the following format (macro expansion with MF=D and default value for 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
Year, month, day and Julian date are transferred as integers in each case (in binary form). The area in the operand list for accepting the date has the following format (macro expansion with MF=D and default value for 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=
Determines whether the current weekday is output.
NO
No information is given about the current weekday.
YES
The current weekday is transferred to a field of the operand list. The value of the FORMAT operand governs the area and format in which the information is transferred:
FORMAT=ISO4
The first two letters of the current weekday (MO, DI, MI, DO, FR, SA, SO) are transferred to the following field of the operand list (macro expansion with MF=D and default value for PREFIX):
* DAY OF WEEK IN ISO4 FORMAT (EXAMPLE : MO)
NTIGDYI DS 0XL2
FORMAT=BIN
The current weekday is transferred as an integer (in binary form) (0 for Monday,
1 for Tuesday,..., 6 for Sunday) in the following halfword of the operand list (macro expansion with MF=D and default value for PREFIX):
* DAY OF WEEK IN BINARY FORMAT
NTIGDYB DS 0XL2
EXTREF=
Determines whether the information on the external reference of the system time should be supplied where it is available.
NO
No information will be supplied.
YES
The information on any available external reference of the system time should be supplied.
The data area for the output of the information has the following structure (for detailed information see the GTIME DSECT; default values for PREFIX and 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=
Defines the form in which GTIME supplies the requested information.
ISO4
The information is provided in printable form. The structure of the data area is described together with the description of the TOD and ZONE operands.
BIN
The information is provided in binary form. The structure of the data area is described together with the description of the TOD and ZONE operands.
TODR / TODX
The information is transferred in TODR or TODX format in the NTIGTODR field, the setting of the epoch is taken into account. The differences between TODR and TODX are described in the section “System time administration” in the “Introduction to System Administration” manual [10 (Related publications)] and also in the information on the CTIME macro on "CTIME - Time stamp calculations".
The operand values for DATE, DAY, TOD and ZONE must be “NO”. The MODE operand is evaluated, i.e. MODE=LT must be set if the local time is to be output in TODR or TODX format; otherwise the UTC is output in TODR format.
LINKADR=
Specifies the manner in which the address of the entry point I@GTIME for the GTIME routine in the GET-TIME subsystem is supplied to the user program. If MF=E, LINKADR must be specified; in all other cases, specification of LINKADR has no effect.
*NONE
Default value: during assembly the assembler generates an external reference for the I@GTIME entry point and this is resolved during linking via the autolink function of the BLS.
This value can be used when the module containing the GTIME call:
is always linked and loaded with the dynamic binder loader DBL (in this case, GTIME in the E form is allowed to issue a V constant, which is supplied by the BLS during the load procedure)
oris linked with the BINDER (see the “BINDER” manual [5 (Related publications)]) under the BINDER statement SET-EXTERN-RESOLUTION RESOLUTION=STD.
linkaddr
Symbolic address (name) of a word in which the user has provided the address of the I@GTIME entry before the GTIME call.
The following example shows how the address of the of the I@GTIME entry is first supplied to the program by an appropriate BIND call and can then be transferred for the GTIME call into the word designated by “linkaddr”:
LINK 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
The entry address of the GTIME routine must always be supplied to the user program in this way if none of the cases mentioned in LINKADR=*NONE apply, e.g. especially if the module with the GTIME call is linked by BINDER under the BINDER statement SET-EXTERN-RESOLUTION RESOLUTION=MANDATORY.
MF=
For a general description of the MF operand, its operand values and any subsequent operands (e.g. PREFIX, MACID and PARAM), see "S-type macros". The valid MF values are given at the start of the macro description under “Macro type” and are included in the macro format.
A PREFIX can be specified in the C form, D form or M form of the macro and additionally a MACID in the C form or M form (see "S-type macros").
In the E form of the macro, the label of the data area is specified in the PARAM operand. Default setting: NTIG$PL
When calling the macro with MF=L, the user must specify this label explicitly, otherwise an MNOTE is output.
MODE=
Defines in which time system the date and time are to be output.
LT
Date and time are output in local time system (legal zone time).
UTC
Date and time are given as the UTC (Universal Time Coordinate, corresponds to Greenwich Mean Time).
RESOLVE=
specifies the desired level of expansion for the GTIME time specification for the formats ISO4 and BIN. For the format of output areas, see the areas specified for the TOD=YES operand.
SEC
Time is specified down to seconds.
MICROSEC
Time is specified down to microseconds.
TOD=
Determines whether the current time is output.
NO
No information is transferred about the current time.
YES
The current time is transferred to an area of the operand list. The value of the FORMAT operand governs the area and format in which the information is transferred:
FORMAT=ISO4
The current time is transferred in the form hh:mm:ss (both colons are included in the output). Where:
| Hours (two digits with leading zero as necessary) |
The area in the operand list for accepting the time has the following format (macro expansion with MF=D and default value for PREFIX):
* TIME OF DAY WITH FORMAT=ISO4 (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
Hour, minute and second are transferred as an integer in each case (in binary form).The area in the operand list for accepting the time has the following structure (macro expansion with MF=D and default value for 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=
supplies a time value which is strictly monotone within the XCS cluster with regard to a DLM lock for a shared resource.
*NO
The monotony described above is not required.
*YES
outputs a time value which ascends monotonically within an XCS cluster under the following conditions:
The caller must hold a DLM lock (see section “Distributed Lock Manager (DLM)”) at the time of the call. The monotony relationship applies only for the time stamp which has been fetched under the same lock.
The time value can be used for logging entries.
Its use is limited to the output format FORMAT=*TODR and MODE=*UTC. The necessary expansion is achieved in TODR format only. Restriction to MODE=*UTC ensures that monotony is maintained for all node computers even at the moment when a time change takes place.
ZONE=
Determines whether characteristic values of the local time zone are output.
NO
No information on the local time zone is transferred.
YES
Characteristic values of the local time zone are transferred to an area in the operand list. The value of the FORMAT operand governs the area and format in which the information is transferred:
FORMAT=ISO4
The characteristic values of the local time zone are transferred in the form shh1:mm1-hh2:mm2-z (colons and hyphens are included in the output). Where:
| “+” or “-”: Sign of time difference between the local time zone and UTC |
| Time difference between the local time zone and UTC in hours (hh) and |
| Time shift in the local time zone between daylight saving time (summer |
| “W” or “S”: Current timing in the local time zone (W for standard time |
The area in the operand list for accepting this information has the following format (macro resolution with MF=D and default value for 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
The characteristic values of the local time zone are transferred as integers in each case (in binary form).
The area in the operand list for accepting this information has the following format (macro resolution with MF=D and default value for 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
Notes on conversion times
In order to use CTIME functionality with non-system conversion times, it must be possible to find out the conversion times of the system on which time data is created. BS2000 can administer up to 400 conversion times. One conversion time inquiry can be made with each GTIME macro call.
Information about conversion times is provided in a field of 8 bytes
(<prefix><macid>CHD). The values specified for the CHDATE operand determine the direction of the conversion time inquiry. The reference point is the information present in this field when GTIME is called:
If all 8 bytes of the field contain X'00', the search begins after the next or preceding conversion time for the current system time. If the field already contains a date, however, this is interpreted as CHDATE information already supplied by GTIME and the search begins after that date.
The CHDATE information appears as STCK values based on UTC shifted 8 Bits logically to the right (SRDL instruction). The lowest-value bit indicates the type of conversion: 0 indicates conversion from standard time (winter time) to daylight saving time (summer time), and 1 daylight saving time (summer time) to standard time (winter time).
The CTIME function requires this data to be arranged as a table. The format of the table is given in the CTIME macro description, operands CHDLxIN and CHDLOUT. An example of working with conversion times is also given for the CTIME macro (see "CTIME - Time stamp calculations").
Data returned to the data area can be accessed with the following names (default values for PREFIX and 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
Register contents
The following registers are required for a GTIME macro call:
R1 R13 | is loaded by the macro with the address of the operand list. before the macro call, is to be loaded with the address of an 18-word save area |
R14 R15 | is loaded by the macro with the return address of the user program. is overwritten by the routine called (through GTIME). |
Return information and error flags
Standard header:
+---------------+ | | | | | |c|c|b|b|a|a|a|a| +---------------+
The following return code relating to the GTIME macro is transferred in the standard header(cc=Subcode2, bb=Subcode1, aaaa=Maincode):
cc | bb | aaaa | Meaning |
00 | 00 | 0000 | Function executed successfully. |
02 | 0010 | The function was executed but the system knows of no CHDATE earlier than | |
02 | 0011 | The function was executed but the system knows of no CHDATE later than | |
02 | 0012 | The function was executed but the system knows of no CHDATE. There is | |
20 | 0008 | The return code is possible only if XCS_MODE=*YES is specified. The |
Other return codes which, in accordance with conventions, apply to all macros are given in the table “Standard return codes” (Standard header).
The calling program is terminated when the following errors occur:
The data area is not assigned to the caller.
The data area is not aligned on a word boundary.
The data area is protected against write access.
The TODR’s current epoch is supplied with every GTIME call in the <prefix><macid>EPD data field (one byte), see the section “System time administration” in the “Introduction to System Administration” manual [10 (Related publications)].
For examples see section “S-type macros” (Macro Command Language Processor macros) and the CTIME macro ("CTIME - Time stamp calculations").