FORMATTED-DATETIME

The FORMATTED-DATETIME function uses a combined date and time format to convert and combine a date in the integer date form and a numeric time expressed as seconds past midnight to a formatted date and time representation according to that combined date and time format.

The type of this function depends on the type of argument-1 as follows:
Table 1. FORMATTED-DATETIME 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-DATETIME (argument-1 argument-2argument-3argument-4)
argument-1
Must be a national, a UTF-8, or an alphanumeric literal.
The content of argument-1 must be a date format. For details, see Date and time formats.
argument-2
Must be in integer date form. For details, see Integer date form.
A value in integer date form is a positive integer that represents a number of days succeeding 31 December 1600, in the Gregorian calendar. It is based on a starting date of Monday, 1 January 1601 and integer date 1 represents Monday, 1 January 1601.
The INTDATE compiler option affects the starting date for the integer date functions. For details, see INTDATE in the Enterprise COBOL Programming Guide.
argument-3
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-4
Must be an integer specifying the offset from Coordinated Universal Time (UTC) expressed in minutes. If argument-4 is specified, the magnitude of the value must be less than or equal to 1439. For details, see UTC offset value.
Note:
  • An offset time format is a time format with the offset appended at the end, for example, hhmmss+hhmm, hh:mm:ss+hh:mm, hhmmss.ssss+hhmm, and hh:mm:ss.ssss+hh:mm.
  • A UTC time format is a time format in the UTC timezone, for example, hhmmssZ, hh:mm:ssZ, hhmmss.ssssZ, or hh:mm:ss.ssssZ.
If argument-4 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-4.
Note: The offset value "1439" represents 23 hours and 59 minutes, which is one minute less than a day.

Returned values

  • The returned value is a representation of the date contained in argument-2 combined with the time contained in argument-3 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-3 by the offset in argument-4.
  • If the format in argument-1 indicates that the time is to be returned as an offset from UTC, the value in argument-3 is reflected directly in the time portion of the returned value, and the offset in argument-4 is reflected directly in the offset portion of the returned value.

Example

If the first argument has the format "YYMMDDThhmmss.ss+hhmm", the second argument the value "143951", the third argument the value "18867.812479168304", and the fourth argument the value "+300", the returned value would be "19950215T05142781+0500".