Skip to main content

This is documentation for Caché & Ensemble. See the InterSystems IRIS version of this content.

For information on migrating to InterSystems IRIS, see How to Migrate to InterSystems IRIS, available on the WRC Distributions page (login required).

MINUTE

A time function that returns the minute for a datetime expression.

Synopsis

{fn MINUTE(time-expression)}

Arguments

Argument Description
time-expression An expression that is the name of a column, the result of another scalar function, or a string or numeric literal. It must resolve either to a datetime string or a time integer, where the underlying data type can be represented as %Time or %TimeStamp.

Description

MINUTE returns an integer specifying the minutes for a given time or datetime value. Minutes are calculated for a $HOROLOG or $ZTIMESTAMP value, an ODBC format date string, or a timestamp.

A time-expression timestamp is data type %Library.TimeStamp (yyyy-mm-dd hh:mm:ss.fff).

To change the default time format, use the SET OPTION command.

Note that you can supply a time integer (number of elapsed seconds), but not a time string (hh:mm:ss). You must supply a datetime string (yyyy-mm-dd hh:mm:ss). You can omit the seconds (:ss) portion of a datetime string and still return the minutes portion. The time-expression can also be specified as data type %Library.FilemanDate, %Library.FilemanTimestamp, or %MV.Date.

The minutes (mm) portion should be an integer in the range from 0 through 59. There is, however, no range checking for user-supplied values. Numbers greater than 59, negative numbers and fractions are returned as specified. Leading zeros are optional on input; leading zeros are suppressed on output.

MINUTE returns zero minutes when the minutes portion is '0', '00', or a nonnumeric value. Zero minutes is also returned if no time expression is supplied, or the minutes portion of the time expression is omitted entirely ('hh', 'hh:', 'hh::', or 'hh::ss'), or if the time expression format is invalid.

The same time information can be returned using DATEPART or DATENAME.

This function can also be invoked from ObjectScript using the MINUTE() method call:

$SYSTEM.SQL.MINUTE(time-expression)

Examples

The following examples both return the number 45 because it is the forty-fifth minute of the time expression in the datetime string:

SELECT {fn MINUTE('2000-02-16 18:45:38')} AS Minutes_Given
SELECT {fn MINUTE(67538)} AS Minutes_Given

The following example also returns 45. As shown here, the seconds portion of the time value can be omitted:

SELECT {fn MINUTE('2000-02-16 18:45')} AS Minutes_Given

The following example returns 0 minutes because the time expression has been omitted from the datetime string:

SELECT {fn MINUTE('2000-02-16')} AS Minutes_Given

The following examples all return the minutes portion of the current time:

SELECT {fn MINUTE(CURRENT_TIME)} AS Min_CurrentT,
       {fn MINUTE({fn CURTIME()})} AS Min_CurT,
       {fn MINUTE({fn NOW()})} AS Min_Now,
       {fn MINUTE($HOROLOG)} AS Min_Horolog,
       {fn MINUTE($ZTIMESTAMP)} AS Min_ZTS

The following example shows that leading zeros are suppressed. The first MINUTE function returns a length 2, the others return a length of 1. An omitted time is considered to be 0 minutes, which has a length of 1:

SELECT LENGTH({fn MINUTE('2004-02-05 11:45:00')}),
       LENGTH({fn MINUTE('2004-02-15 03:05:00')}),
       LENGTH({fn MINUTE('2004-02-15 3:5:0')}),
       LENGTH({fn MINUTE('2004-02-15')})

The following Embedded SQL example shows that the MINUTE function recognizes the TimeSeparator character specified for the locale:

  DO ##class(%SYS.NLS.Format).SetFormatItem("TimeSeparator",".")
  &sql(SELECT {fn MINUTE('2000-02-16 18.45.38')}
  INTO :a)
  WRITE "minutes=",a

See Also

Feedback