Validates a time and converts it from internal format to the specified display format.
Arguments
htime
This value represents the number of elapsed seconds since midnight. It is the second component of a $HOROLOG value, which can be extracted by using $PIECE($HOROLOG,",",2). htime can be an integer, or a fractional number with the number of fractional digits of precision specified by precision.
For tformat values –1 through 4, htime valid values must have their integer portion in the range 0 through 86399. (-0 is treated as 0.) Values outside of this range generate an <ILLEGAL VALUE> error. For tformat values 9 and 10, htime valid values can also include negative numbers and numbers greater than 86399.
precision
The function displays fractional seconds carried out to the number of decimal places specified in the precision argument. For example, if you enter a value of 3 as precision, $ZTIME displays fractional seconds to three decimal places. If you enter a value of 9, $ZTIME displays fractional seconds to nine decimal places. Supported values are as follows:
Value |
Description |
-1 |
Gets the precision value from the TimePrecision property of the current locale, which defaults to a value of 0. This is the default behavior if you do not specify precision. |
n |
A value that is greater than or equal to 0 results in the expression of time to n decimal places. |
0 |
If set to 0, or defaults to a value of 0, fractional seconds are truncated. |
To determine the default time precision for your locale, invoke the GetFormatItem()Opens in a new tab NLS class method:
WRITE ##class(%SYS.NLS.Format).GetFormatItem("TimePrecision")
erropt
This argument suppresses error messages associated with invalid htime values. Instead of generating <ILLEGAL VALUE> error messages, the function returns the value indicated by erropt.
localeopt
This argument selects either the user’s current locale definition (0) or the ODBC locale definition (1) as the source for time options. The ODBC locale cannot be changed; it is used to format date and time strings that are portable between InterSystems IRIS processes that have made different National Language Support (NLS) choices.
The ODBC locale time definitions are as follows:
Examples
To return the current local time using the special variable $HOROLOG, you must use the $PIECE function to specify the second piece of $HOROLOG. The following returns the time in the 24–hour clock format “13:55:11”:
WRITE $ZTIME($PIECE($HOROLOG,",",2),1)
In the examples that follow, htime is set to $PIECE($HOROLOG,",",2) for the current time. These examples show how to use the various forms of $ZTIME to return different time formats.
The following example in many cases returns time in the format "13:28:55"; however, this format is dependent on locale:
SET htime=$PIECE($HOROLOG,",",2)
WRITE $ZTIME(htime)
The following example returns time in the format "13:28:55":
SET htime=$PIECE($HOROLOG,",",2)
WRITE $ZTIME(htime,1)
The following example returns time in the format "13:28:55.999":
SET htime=$PIECE($HOROLOG,",",2)
WRITE $ZTIME(htime,1,3)
The following example returns time in the format "13:28:55.999999999":
SET htime=$PIECE($HOROLOG,",",2)
WRITE $ZTIME(htime,1,9)
The following example returns time in the format "13:28":
SET htime=$PIECE($HOROLOG,",",2)
WRITE $ZTIME(htime,2)
The following example returns time in the format "01:28:24PM":
SET htime=$PIECE($HOROLOG,",",2)
WRITE $ZTIME(htime,3)
The following example returns time in the format "01:28PM":
SET htime=$PIECE($HOROLOG,",",2)
WRITE $ZTIME(htime,4)
The following example returns time in the format “13:45:56.021”, the current UTC time with three decimal places of precision:
SET t=$ZTIME($PIECE($ZTIMESTAMP,",",2),1,3)
WRITE "Current UTC time is ",t
Time Suffixes
By default, InterSystems IRIS uses properties in the current locale to determine the names of its time suffixes. For $ZTIME, these properties (and their corresponding default values) are:
This documentation will always use these default values for these properties.
To determine the default time suffixes for your locale, invoke the following NLS class methods:
WRITE ##class(%SYS.NLS.Format).GetFormatItem("AM"),!
WRITE ##class(%SYS.NLS.Format).GetFormatItem("PM")