Caché ObjectScript Reference
$ZTIMEH
|
|
Validates a time and converts it from display format to Caché internal format.
Synopsis
$ZTIMEH(time,tformat,erropt,localeopt)
$ZTH(time,tformat,erropt,localeopt)
Omitted parameters between specified parameter 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 parameter.
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 parameter
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.
Supported values are as follows:
To determine the default time format for your locale, invoke the
GetFormatItem() NLS class method:
WRITE ##class(%SYS.NLS.Format).GetFormatItem("TimeFormat")
This parameter suppresses error messages associated with invalid
time values. Instead of generating <ILLEGAL VALUE> error messages, the function returns the value indicated by
erropt.
This parameter 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 Caché 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.
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)
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.
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 noninteger 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.
By default, Caché 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() NLS class method:
WRITE ##class(%SYS.NLS.Format).GetFormatItem("TimeSeparator")
By default, Caché uses properties in the current locale to determine the names of its time suffixes. For
$ZTIMEH, 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
GetFormatItem() 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")