Class Reference
IRIS for UNIX 2019.2
InterSystems: The power behind what matters   
Documentation  Search
  [ENSLIB] >  [Ens] >  [Util] >  [Time]
Private  Storage   

class Ens.Util.Time

This class provides utility methods related to Time.

Inventory

Parameters Properties Methods Queries Indices ForeignKeys Triggers
11


Summary

Methods
ConvertDateTime Duration FixCentury FormatDateTime
ParseDateTime SecondsUntil TimeoutToSeconds getCExpansion


Methods

• classmethod ConvertDateTime(pValue As %String, pSpecIn As %String, pSpecOut As %String, pFReplacementOut As %String, Output pSC As %Status, pAllowExtraValueChars As %Boolean) as %String
Convert a string in a particular date format(pSpecIn) to the format as described by pSpecOut.
If the token %f is used in pSpecOut, then %f is replaced by the string designated by pFReplacementOut, and the status (or errors) are returned in pSC.
If pAllowExtraValueChars is false (the default) then the parsed time string needs to exactly match the input spec.
If true, then it is okay if the input has extra text left over at the end that wasn't exactly matched by the spec.

This method essentially calls ParseDateTime on the initial String (pValue) to turn it into a time, then calls FormatDateTime to convert the time into the desired output format. Refer to the class documentation on these two methods for usage and limitations.
The important point is that there is currently a date range for parsing dates- it is from January 1, 1970 through January 18, 2038. The exact times of the cutoff dates are Operating System dependent. For more details see ParseDateTime.
• classmethod Duration(pDuration As %String, Output pSeconds As %Integer) as %Status
Given a time duration in the format, http://www.w3.org/TR/xmlschema-2/#duration, return the duration as a number of seconds (via pSeconds).
'duration' format example: P1Y2M3DT10H30M3S
Only positive duration values are supported.
• classmethod FixCentury(yy)
Override to use your own century fixing algorithm
• classmethod FormatDateTime(pSpec As %String = "", pFReplacement As %String = "", pTimeUTCODBC As %String) as %String
Format a time according to a format string pSpec. If given, the time pTimeUTCODBC must be in the UTC time zone (Universal Coordinated Time a.k.a. GMT / Greenwich Mean Time) given in ODBC format. The string pFReplacement will be substituted wherever pSpec contains the token %f or %F.
If pTimeUTCODBC (the input time to format) is not provided then the current time is used.
The pSpec argument consists of one or more format codes; the format codes are preceded by a percent sign (%). Characters that are not part of a format code are output unchanged.
The following format codes are supported:
Base timezone to convert to before formatting (supported only at the beginning of the format spec string).
code Description
%K(<tz>) Timezone offset, <tz> values (case insensitive):
Server (default) time on the server where the executing code resides.
UTC Universal Time Coordinated (a.k.a. GMT / Greenwich Mean Time)
[+]n number of hours after (east of) UTC time (may be fractional)
-n number of hours before (west of) UTC time (may be fractional)
[+]hhmm hours and minutes after (east of) UTC time (in the ISO 8601:2000 standard format)
-hhmm hours and minutes after (west of) UTC time

Date and Time Expansion:
code Description
%a locale's abbreviated weekday name
%A locale's full weekday name
%b locale's abbreviated month name
%B locale's full month name
%c date and time representation appropriate for locale ; equivalent to %c(-1,-1,-1)
%c(<df>,<tf>,<sp>) date/time formatted according to $ZDateTime() date 'dformat', time 'tformat', and sub-second 'precision'
%d day of the month as a 2-digit number (01-31)
%#d day of the month as a number (1-31) without leading zero
%D date; equivalent to %m / %d / %y
%#D date; equivalent to %#m / %#d / %y
%f input replacement text
%#f input replacement text, stripped of final dot piece, if any
%$f final dot piece of input replacement text and dot, if any
%$#f final dot piece of input replacement text, if any
%F input replacement text converted to uppercase
%#F input replacement text converted to uppercase, stripped of final dot piece, if any
%$F final dot piece of input replacement text and dot, if any, converted to uppercase
%$#F final dot piece of input replacement text, if any, converted to uppercase
%h equivalent to %b
%H hour in 24-hour format as a 2-digit number (00-23)
%#H hour in 24-hour format as a number (0-23) without leading zeros
%I hour in 12-hour format as a 2-digit number(01-12)
%#I hour in 12-hour format as a number (1-12) without leading zeros
%j day of the year as a 3-digit number (001-366)
%#j day of the year as a number (1-366) without leading zeros
%K(<tz>) timezone to use to convert time for display, see above. Produces no output; supported only at the beginning of the format spec string.
%m month as a 2-digit number (01-12)
%#m month as a number (1-12) without leading zeros
%M minute as a 2-digit number (00-59)
%#M minute as a number (0-59) without leading zeros
%N fractional second in milliseconds as a 3-digit number (000-999)
%p current locale's a.m./p.m. indicator for 12-hour clock (lowercase)
%#p current locale's am/pm indicator for 12-hour clock (lowercase, without dots)
%P current locale's A.M./P.M. indicator for 12-hour clock (uppercase)
%#P current locale's AM/PM indicator for 12-hour clock (uppercase, without dots)
%q equivalent to %q() or %q(0)
%q(0) HL7 format date/time; equivalent to %Y%m%d%H%M%S
%q(1) ODBC format date/time; equivalent to %Y-%m-%d %H:%M:%S.%N
%q(2) ISO 8601:2000 standard date format; equivalent to %Y-%m-%d
%q(3) $Horolog format
%q(4) $ZTimestamp format
%q(5) A 36-character GUID (Globally Unique IDentifier). This is guaranteed to be unique but is not technically a timestamp.
%Q ODBC format date/time; equivalent to %c(3,,3) or %q(1)
%Q(n) equivalent to %q(n)
%r time with seconds in 12-hour format using a.m./p.m. notation; equivalent to %I:%M:%S %p
%#r time with seconds in 12-hour format using am/pm notation without whitespace or dots; equivalent to %I:%M:%S%#p
%R time in 24-hour notation; equivalent to %H:%M
%S second as a 2-digit number (00-60) (60 for leap seconds)
%t replaced by a <tab>.
%T time with seconds in 24-hour notation; equivalent to %H:%M:%S
%u day of the week as a number (1-7), with 1 representing Monday.
%#u equivalent to %u
%U week of year as a number, with Sunday as first day of week (00-53); equivalent to %U(0). The first Sunday of January is the first day of week 1; days in the new year before this are in week 0.
%U(<dow>) week of the year as a number, starting on the given DayOfWeek (Sunday=0)
%#U week of the year as a number, with Sunday as first day of week (00-53), without leading zeros (0-53); equivalent to %#U(0)
%#U(<dow>) week of the year as a number, starting on the given DayOfWeek (Sunday=0), without leading zeros
%w day of the week as a number (0-6; Sunday is 0)
%#w equivalent to %w
%W week of the year as a number (00-53); equivalent to %U(1). The first Monday of January is the first day of week 1; days in the new year before this are in week 0.
%W(<dow>) equivalent to %U(<dow>)
%#W week of the year as a number (0-53) without leading zeros; equivalent to %#U(1).
%#W(<dow>) equivalent to %#U(<dow>)
%y year within a century as a number (00-99)
%Y year including the century, as a 4-digit number (0000-9999)
%z timezone offset from UTC in the ISO 8601:2000 standard format ( +hhmm or -hhmm ). For example, "-0430" means 4 hours 30 minutes behind UTC (west of Greenwich)
%#z timezone offset from UTC in hours with leading +/- and without leading or trailing zeros; trailing decimals may appear ( +h.nnn or -h.nnn ) For example, "-4.5" means 4 hours 30 minutes behind UTC (west of Greenwich)
%% Literal % percent sign
%( Literal ( left parenthesis
%_ Reserved token (currently treated as a literal- printed out as itself)
• classmethod ParseDateTime(pValue As %String, pSpecIn As %String, Output pSC As %Status, pAllowExtraValueChars As %Boolean = 0) as %String
Parse the given pValue according to a format string pSpecIn.
Returns a time string in the UTC time zone (Universal Coordinated Time a.k.a. GMT / Greenwich Mean Time) in ODBC format (YYYY-MM-DD), or empty string if pValue cannot be parsed.
Note: the $$$timeLocaltoUTC macro removes any fractional second precision beyond three digits. Also: tz (timezone) is set to "server" by default, so when timeLocalToUTC() is called, it only accepts dates between January 1, 1970 ($HOROLOG = 47117,00000) through January 18, 2038 ($HOROLOG = 71971,86399). This is because zutil(193) is used; any dates outside of this range causes an Illegal Value error. This is an operating system limitation.(this paragraph also appears in the documentation).
The pSpec argument may contain literal characters, and any of the following format codes to represent time fields to be parsed. It is composed of zero or more format codes. Each format code is composed of one of the following:
  • one or more white-space characters
  • an ordinary character (neither '%' nor a white-space character)
  • a format code.

Each format code is composed of a '%' character followed by a conversion character that specifies how to interpret the input value text at that position. Format codes of indeterminate length must be preceded by literal text or format codes of fixed size, and must be followed by literal text or end-of-text.
For example, when using a day of the month that could be either one or two characters(the 5th of july, or the 30th); the date can be represented as 7/5/2007. since there is a slash after the 5; that day can be separated and parsed out from the other numbers. however, for the date 1/2/1975; without slashes-121975; the date could be misconstrued as december 19, 1975 instead of january 2, 1975. Therefore, when fields do not have delimiters only fixed length fields can be used, 01021975 would be a valid way to get enter the date without delimiters such as slashes.
Even if zeros are used (as in the prior example), indeterminite length fields must have delimiters for this code to function properly.
The following format codes are supported:
Base timezone to convert to before formatting (supported only at the beginning of the format spec string)
code Description
%K(<tz>) Timezone offset, <tz> values (case insensitive):
Server (default) time on the server where the executing code resides.
UTC Universal Time Coordinated (a.k.a. GMT / Greenwich Mean Time)
[+]n number of hours after (east of) UTC time (may be fractional)
-n number of hours before (west of) UTC time (may be fractional)
[+]hhmm hours and minutes after (east of) UTC time (in the ISO 8601:2000 standard format)
-hhmm hours and minutes after (west of) UTC time

Date and Time Expansion:

code Description
%a day of the week using the locale's weekday names; either the abbreviated or full name will be matched.
%A equivalent to %a.
%b month using the locale's month names; either the abbreviated or full name will be matched.
%B equivalent to %b.
%c equivalent to c(1,1,3)
%c(<df>,<tf>,<sp>) date/time formatted according to $ZDateTime() date 'dformat', time 'tformat', and sub-second 'precision'
%C equivalent to %c
%d day of the month as a 2-digit number (01-31)
%#d day of the month as a number (1-31); leading zeros not required
%D date; equivalent to %m / %d / %y
%#D date; equivalent to %#m / %#d / %y
%h equivalent to %b
%H hour in 24-hour format as a 2-digit number (00-23)
%#H hour in 24-hour format as a number (0-23); leading zeros not required
%I hour in 12-hour format as a 2-digit number (01-12)
%#I hour in 12-hour format as a number (1-12); leading zeros not required
%j day of the year as a 3-digit number (001-366)
%#j day of the year as a number (1-366); leading zeros not required
%K(<tz>) timezone to use to convert time for display, see above. Produces no output; supported only at the beginning of the format spec string.
%m month as a 2-digit number (01-12)
%#m month as number (1-12); leading zeros not required
%M minute as a 2-digit number (00-59)
%#M minute as number (0-59); leading zeros not required
%N fractional second in milliseconds as number (000-999)
%N(<num>) same as above (fractional part of a second), but the input number indicates the number of digits that
the fraction uses, three is the default if there are no args.
%p locale's equivalent of a.m. or p.m.; either lowercase or uppercase will be matched.
%#p locale's equivalent of am or pm (without dots); either lowercase or uppercase will be matched.
%P equivalent to %p
%#P equivalent to %#p
%q equivalent to %q() or %q(0)
%q(0) HL7 format date/time; equivalent to %Y%m%d%H%M%#S with seconds optional
%q(1) ODBC format date/time; equivalent to %Y-%m-%d %H:%M:%S.%N
%q(2) ISO 8601:2000 standard date format; equivalent to %Y-%m-%d
%q(3) $Horolog format
%q(4) $ZTimestamp format
%q(5) HL7 format date/time; equivalent to %Y%m%d%H%M%S with seconds required
%Q ODBC format date/time; equivalent to %c(3,,3) or %q(1)
%Q(n) equivalent to %q(n)
%r time with seconds in 12-hour format using a.m./p.m. notation; equivalent to %I:%M:%S %p
%#r time with seconds in 12-hour format using am/pm notation without whitespace or dots; equivalent to %I:%M:%S%#p
%R time in 24-hour notation; equivalent to %H:%M
%S seconds as a 2-digit number (00-60) (60 for leap seconds)
%#S optionally appearing seconds as a 0, 1, or 2 digit number (0-60) (60 for leap seconds)
%t any white space.
%T time with seconds in 24-hour notation; equivalent to %H:%M:%S
%u day of the week as a number (1-7), with 1 representing Monday.
%#u equivalent to %u
%U week of year as a number, with Sunday as first day of week (00-53); equivalent to %U(0). The first Sunday of January is the first day of week 1; days in the new year before this are in week 0.
%U(<dow>) week of the year as a number, starting on the given DayOfWeek (Sunday=0)
%#U week of the year as a number, with Sunday as first day of week (00-53); leading zeros not required; equivalent to %#U(0)
%#U(<dow>) week of the year as a number, starting on the given DayOfWeek (Sunday=0); leading zeros not required
%w day of the week as a number (0-6; Sunday is 0)
%#w equivalent to %w
%W week of the year as a number (00-53); equivalent to %U(1). The first Monday of January is the first day of week 1; days in the new year before this are in week 0.
%W(<dow>) equivalent to %U(<dow>)
%#W week of the year as a number (0-53); leading zeros not required, equivalent to %#U(1).
%#W(<dow>) equivalent to %#U(<dow>)
%y year within a century as a number (00-99). When the century is not otherwise specified, the method FixCentury() is called to resolve it.
%Y year including the century, as a 4-digit number (0000-9999)
%z timezone offset from UTC in the ISO 8601:2000 standard format ( +hhmm or -hhmm ). For example, "-0430" means 4 hours 30 minutes behind UTC (west of Greenwich)
%#z timezone offset from UTC in hours with leading +/- and without leading or trailing zeros; trailing decimals may appear ( +h.nnn or -h.nnn ) For example, "-4.5" means 4 hours 30 minutes behind UTC (west of Greenwich)
%% Literal % percent sign
%( Literal ( left parenthesis
• classmethod SecondsUntil(pDateTime As %String, Output pSeconds As %Float) as %Status
Given a 'dateTime' value in the format, http://www.w3.org/TR/xmlschema-2/#dateTime return the number of seconds until that instant (via pSeconds. If the time instant has passed return 0.
'dateTime' format example:- 2003-06-06T09:30:00
• classmethod TimeoutToSeconds(pTimeout As %String, Output pSeconds As %Float) as %Status
This call accepts a time value in either of the formats: It returns the number of seconds until the specified time (via pSeconds).
If the time value is already a number of seconds, return it.
• classmethod getCExpansion(args As %String, ByRef nLength)


Copyright (c) 2019 by InterSystems Corporation. Cambridge, Massachusetts, U.S.A. All rights reserved. Confidential property of InterSystems Corporation.