$ZTIME; $ZTIME

Validates the time and converts it from the internal format to the specified display format.

The outline

$ZTIME(htime,tformat,precision,erropt,localeopt)
$ZT(htime,tformat,precision,erropt,localeopt)
Copy the code

parameter

• Htime can be specified as the internal system time of a number, variable name, or expression.
• Tformat Optional – An integer value specifying the format in which the time value is to be returned.
• Precision Optional – A number that specifies the number of decimal places to use to represent the time. If omitted, the fractional second is truncated.
• Erropt Optional – Returns an expression if the htime argument is considered invalid.
• Localeopt Optional – Specifies the Boolean flag for the locale to use. When 0, the current locale determines the time delimiter and other characters, strings, and options used to format the time. When it is 1, the ODBC locale determines these characters, strings, and options. ODBC locale cannot be changed; It is used to format date and time strings that can be ported between Cache processes that make different national Language support (NLS) choices. The default value is 0.

Ellipsis parameters between specified parameter values are represented by the placeholder comma. The trailing placeholder comma is not required, but is allowed. Spaces between commas are allowed to indicate omitted arguments.

describe

The $ZTIME function converts the internal system time (htime), specified in time format from the special variable $HOROLOG or $ZTIMESTAMP, to printable format. If no optional parameter is used, the time is returned in hh:mm:ss format. Hh is the hour, mm is the minute, and SS is the second in the 24-hour system. Otherwise, the time is returned in the format specified by the values of the TF format and precision parameters.

parameter

htime

This value represents the number of seconds that have passed since midnight. It is the second component of the $HOROLOG value and can be extracted using $PIECE($HOROLOG,”,”,2). Htime can be an integer or a decimal number with a precision specified by precision.

For tformat values — 1 through 4, the integer part of htime valid values must be in the range 0 through 86399. (-0 is 0.) Values outside this range produce an error. For tformat values 9 and 10, htime valid values can also include negative numbers and numbers greater than 86399.

tformat

The following values are supported:

To determine the locale’s default time format, call the GetFormatItem () NLS class method:.

DHC-APP>WRITE ##class(%SYS.NLS.Format).GetFormatItem("TimeFormat"1)Copy the code

In the 12-hour clock format, morning and evening are represented by time suffixes, which are displayed as AM and PM. To determine the default time suffix for the locale, call the following NLS class methods:

DHC-APP>WRITE ##class(%SYS.NLS.Format).GetFormatItem("AM")
AM
DHC-APP>WRITE# #class(%SYS.NLS.Format).GetFormatItem("PM")
PM
Copy the code

tformat 9 and 10

Time formats 9 and 10 are provided to support MultiValue. For all internal time values that ObjectScript allows: 0 to 86399, they are the same as Tformats 1 and 2. As with other time formats, -0 is treated as 0.

Time formats 9 and 10 accept negative values and return the corresponding negative time values. Tformat 9 returns a negative htime as “-hh: mm: ss” in 24-hour format. The negative htime returned by tformat 10 is -hh: mm in 24-hour format. For time format 10, -59.9 returns -00:00, and -00:01 returns -60.

Time formats 9 and 10 accept values greater than 86399 and return the corresponding time. For time format 10, “86400” returns “24:00” and “400000” returns “111:06”.

Time format 9 Returns whole seconds for all values, and optionally decimal seconds. The precision parameter specifies the number of decimal seconds.

precision

This function displays the number of decimal seconds after the decimal seconds specified in the accuracy parameter. For example, if you enter a precision value of 3, $ZTIME displays the fractional second as three decimal places. If you enter a value of 9, $ZTIME will display decimal seconds to nine decimal places. The following values are supported:

To determine the default time precision of the locale, call the GetFormatItem () NLS class method:

DHC-APP>WRITE ##class(%SYS.NLS.Format).GetFormatItem("TimePrecision")
0
Copy the code

erropt

This parameter disallows the display of error messages related to invalid htime values. This function returns the VALUE indicated by Erropt, rather than generating an error

message.

localeopt

This parameter selects the user’s current locale definition (0) or ODBC locale definition (1) as the source of the time option. You cannot change the ODBC locale. It is used to format date and time strings that are portable between Cache flows that have made different national language support (NLS) choices.

The ODBC locale time is defined as follows:

• The default time format is 1. The time delimiter is:. Time accuracy is 0 (no fractional seconds).
• The AM and PM indicators are AM and PM respectively. Use the words “Noon” and “Midnight”.

The sample

To return the current local time using the special variable $HOROLOG, you must specify the second part of $HOROLOG using the $PIECE function. The following content is returned in 24-hour format: 13:55:11:

DHC-APP>WRITE $ZTIME($PIECE($HOROLOG,",".2),109:00:57
Copy the code

In the following example, set htime to $PIECE($HOROLOG,”,”,2) of the current time. These examples show how to use various forms of $ZTIME to return different time formats.

The following example returns the time in many cases as “13:28:55”; However, this format depends on the locale:

DHC-APP>SET htime=$PIECE($HOROLOG,",".2)
 
DHC-APP>WRITE $ZTIME(htime)
09:02:44
Copy the code

The following example returns the time in “13:28:55.999” format:

DHC-APP>SET htime=$PIECE($HOROLOG,",".2)
 
DHC-APP>WRITE $ZTIME(htime,1.309:03:46.000
Copy the code

The following example returns the time in “13:28:55.999999999” format:

DHC-APP>SET htime=$PIECE($HOROLOG,",".2)
 
DHC-APP>WRITE $ZTIME(htime,1.909:03:46.000000000
Copy the code

The following example returns the time in “13:28” format:

DHC-APP>SET htime=$PIECE($HOROLOG,",".2)

DHC-APP>WRITE $ZTIME(htime,209:03
Copy the code

The following example returns the time in “01:28:24pm” format:

DHC-APP>SET htime=$PIECE($HOROLOG,",".2)
 
DHC-APP>WRITE $ZTIME(htime,309:03:46AM
Copy the code

The following example returns the time in 01:28pm format:

DHC-APP>SET htime=$PIECE($HOROLOG,",",2)

DHC-APP>WRITE $ZTIME(htime,4)
09:03AM
Copy the code

The following example returns the time as “13:45:56.021”, the current UTC time, to three decimal places:

DHC-APP>SET t=$ZTIME($PIECE($ZTIMESTAMP,",".2),1.3)
 
DHC-APP>WRITE "Current UTC time is ",t
Current UTC time is 01:05:47.548
Copy the code

Pay attention to

Invalid parameter value

• If an invalid tformat value is specified, it is received<FUNCTION>Error.
• If the value specified by htime is outside the allowed range from 0 to 86399 inclusive and is not provided<ILLEGAL VALUE>Error value, all tformats except 9 and 10 receive an error.

Decimal Delimiter

$ZTIME uses the value of the DecimalSeparator property of the current locale as a separator between the integer and fractional parts of the integer. The default value of DecimalSeparator is “. ; All document examples use this delimiter.

To determine the default decimal separator for the locale, call the GetFormatItem () NLS class method

DHC-APP> WRITE ##class(%SYS.NLS.Format).GetFormatItem("DecimalSeparator").Copy the code

Time Delimiter

By default, the Cache uses the value of the current locale’s TimeSeparator property to determine the delimiter of the time string. By default, the delimiter is:. All document examples use this delimiter.

To determine the default time separator for the locale, call the following NLS class methods:

DHC-APP>WRITE ##class(%SYS.NLS.Format).GetFormatItem("TimeSeparator")
:
Copy the code

Time suffix

By default, the Cache uses attributes in the current locale to determine the name of its time suffix. For $ZTIME, these attributes (and their corresponding defaults) are:

• AM (” AM “)
• PM (PM)

This document will always use these default values for these properties.

To determine the default time suffix for the locale, call the following NLS class methods:

DHC-APP>WRITE ##class(%SYS.NLS.Format).GetFormatItem("AM")
AM
DHC-APP>WRITE# #class(%SYS.NLS.Format).GetFormatItem("PM")
PM
Copy the code