Skip to main content

$ZTIMEH (ObjectScript)

Validates a time and converts it from display format to InterSystems IRIS internal format.

Synopsis

$ZTIMEH(time,tformat,erropt,localeopt)
$ZTH(time,tformat,erropt,localeopt)

Arguments

Argument Description
time The time value to be converted.
tformat Optional — A numeric value that specifies the time format from which you are converting.
erropt Optional — The expression returned if the time argument is considered invalid.
localeopt Optional — A boolean flag that specifies which locale to use. When 0, the current locale determines the time separator, and the other characters, strings, and options used to format times. When 1, the ODBC locale determines these characters, strings, and 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 default is 0.

Omitted arguments between specified argument values are indicated by placeholder commas. Trailing placeholder commas are not required, but are permitted. Blank spaces are permitted between the commas that indicate an omitted argument.

Description

The $ZTIMEH function converts a time value from a format produced by the $ZTIME function to the format of the special variables $HOROLOG and $ZTIMESTAMP. If the optional argument tformat is not specified, the input time must be in the format “hh:mm:ss.fff...”. Otherwise, the same integer format code used to produce the printable time from the $ZTIME function must be used for the time to be converted properly.

Fractional Seconds

Unlike the $ZTIME function, $ZTIMEH does not allow you to specify a precision. Any fractional seconds in the original time format returned by $ZTIME are retained in the value returned by $ZTIMEH.

Arguments

tformat

Supported values are as follows:

Code Description
-1 Get the effective format value from the TimeFormat property of the current locale, which defaults to a value of 1. This is the default behavior if you do not specify tformat and localeopt is unspecified or 0.
1 Input time is in the form "hh:mm:ss" (24-hour clock).
2 Input time is in the form “hh:mm” (24-hour clock).
3 Input time is in the form “hh:mm:ss[AM/PM]” (12-hour clock).
4 Input time is in the form “hh:mm[AM/PM]” (12-hour clock).

To determine the default time format for your locale, invoke the GetFormatItem()Opens in a new tab NLS class method:

  WRITE ##class(%SYS.NLS.Format).GetFormatItem("TimeFormat")

erropt

This argument suppresses error messages associated with invalid time 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:

  • Time format defaults to 1. Time separator is ":". Time precision is 0 (no fractional seconds).

  • AM and PM indicators are "AM" and "PM". The words "Noon" and "Midnight" are used.

Examples

When the input time is “14:43:38”, the following examples both return 53018:

   SET time="14:43:38"
   WRITE !,$ZTIMEH(time)
   WRITE !,$ZTIMEH(time,1)

When the input time is “14:43:38.974”, the following example returns 53018.974:

   SET time="14:43:38.974"
   WRITE $ZTIMEH(time,1)

Invalid Argument Values

You receive a <FUNCTION> error if you specify an invalid tformat code (an integer less than -1 or greater than 4, a zero, or a non-integer value).

If you do not supply an erropt value, you receive an <ILLEGAL VALUE> error under the following conditions:

  • Specify a time with an hour value outside the allowed range of 0 to 23 (inclusive).

  • Specify a time with a minute value outside the allowed range of 0 to 59 (inclusive).

  • Specify a time with a second value outside the allowed range of 0 to 59 (inclusive).

  • Specify a time value which uses a delimiter other than the value of the TimeSeparator property of the current locale.

Time Separator

By default, InterSystems IRIS uses the value of the TimeSeparator property of the current locale to determine the delimiter character for the time string. By default, the delimiter is “:”; all documentation examples use this delimiter.

To determine the default time separator for your locale, invoke the GetFormatItem()Opens in a new tab NLS class method:

  WRITE ##class(%SYS.NLS.Format).GetFormatItem("TimeSeparator")

Time Suffixes

By default, InterSystems IRIS uses properties in the current locale to determine the names of its time suffixes. For $ZTIMEH, these properties (and their corresponding default values) are:

  • AM (“AM”)

  • PM (“PM”)

  • Midnight (“MIDNIGHT”)

  • Noon (“NOON”)

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

To determine the default time suffixes for your locale, invoke the GetFormatItem()Opens in a new tab NLS class method, as follows:

  WRITE ##class(%SYS.NLS.Format).GetFormatItem("AM"),!
  WRITE ##class(%SYS.NLS.Format).GetFormatItem("PM"),!
  WRITE ##class(%SYS.NLS.Format).GetFormatItem("Midnight"),!
  WRITE ##class(%SYS.NLS.Format).GetFormatItem("Noon")

See Also

FeedbackOpens in a new tab