FORMATTED-TIME

The FORMATTED-TIME function uses a format to convert a value that represents seconds past midnight to a formatted time of day in the requested format.

The type of this function depends on the type of argument-1 as follows:
Table 1. FORMATTED-TIME function type depending on the argument-1 types
argument-1 type Function type
Alphanumeric Alphanumeric
National National
UTF-8 UTF-8

Format

Read syntax diagramSkip visual syntax diagramFUNCTION FORMATTED-TIME (argument-1 argument-2argument-3)
argument-1
Must be a national, a UTF-8, or an alphanumeric literal.
The content of argument-1 must be a time format. For details, see Date and time formats.
argument-2
Must be a numeric value in standard numeric time form. For details, see Standard numeric time form.
A value in standard numeric time form is a numeric value that represents seconds past midnight.
argument-3
Argument-3 is an integer representation of the offset from Coordinated Universal Time (UTC) expressed in minutes. If argument-3 is specified, the magnitude of the value must be less than or equal to 1439. For details, see UTC offset value.
Note: The offset value 1439 represents 23 hours and 59 minutes, which is one minute less than a day.
Argument-3 must not be specified if the time portion of the format in argument-1 is neither a UTC format nor an offset format.
If argument-3 is omitted and the time portion of the format in argument-1 is a UTC format or an offset format, the function will be evaluated as though 0 was specified for argument-3.

Returned values

  • The returned value is a representation of the standard numeric time contained in argument-2 according to the format in argument-1.
  • If the format in argument-1 indicates that the returned value is expressed in UTC, the time portion of the returned value reflects the adjustment of the value in argument-2 by the offset in argument-3.
  • If the format in argument-1 indicates that the time is returned as an offset from UTC, the value in argument-2 is reflected directly in the time portion of the returned value, and the offset in argument-3 is reflected directly in the offset portion of the returned value.

Example

If the first argument has the format "hhmmss.ss+hhmm", the second argument the value "18867.812479168304" which represents the local time, and the third argument the value "-300", which represents the five hours that Eastern Standard Time (EST) differs from UTC, the returned value would be "05142781-0500".