CONVERT-DATE-TIME

The CONVERT-DATE-TIME function takes an item of class alphanumeric, numeric, or date-time and returns a date-time item.

The function type is date-time.

The length of the returned value depends on the length allowed for the format of the date, time, or timestamp item specified in argument-2 through argument-4.

Format

Read syntax diagramSkip visual syntax diagramFUNCTION CONVERT-DATE-TIME(argument-1argument-2 argument-3argument-4 )
argument-1
Can be:
  • A date, time, or timestamp item
  • An item of class alphanumeric
  • A non-numeric literal
  • An item of class numeric integer
argument-2
Specifies the category of the return value and must be one of the following keywords:
  • DATE
  • TIME
  • TIMESTAMP
If argument-1 is a date, time, or timestamp item, CONVERT-DATE-TIME can only convert:
  • A date to a date, or a timestamp
  • A time to a time, or a timestamp
  • A timestamp to a date, a time, or a timestamp

If argument-2 is TIMESTAMP, argument-3 can only be specified with FORMAT OF special register, and argument-4 cannot be specified.

If argument-1 is a date-time item, a date-time move is done.

If argument-1 is a numeric integer, the returned date-time item will be right-justified and truncated, if it is longer than what is allowed by the date-time format specified in argument-3.

If argument-1 is anything else, the returned date-time item will be left-justified and truncated, if it is longer than what is allowed by the date-time format specified in argument-3.

argument-3
Specifies the format of a date or time item. It must be:
  • A nonnumeric literal at least 2 characters long
  • The keyword LOCALE
  • The FORMAT OF special register
For a list of valid literals and the rules that this argument must follow, refer to the SPECIAL-NAMES FORMAT clause described in FORMAT clause.

argument-3 should represent a category that is referred to by argument-2.

If argument-3 is the keyword LOCALE, then the format of the date or time is based on a LOCALE. If argument-4 is not specified, the current locale is used, otherwise the locale associated with the mnemonic-name or the LOCALE OF special register is used.

If argument-3 is not specified, the format of the returned value is dependent on the SPECIAL-NAMES FORMAT clause. If no format has been defined in the SPECIAL-NAMES paragraph, *ISO format is used. For TIMESTAMP, if argument-3 is not specified, the default format of @Y-%m-%d-%H%M%S.@Sm is used.

argument-4
Must be a mnemonic-name associated with a LOCALE, or the LOCALE OF special register.
argument-4 must follow these rules:
  • If argument-4 is specified and argument-3 is a locale-based format literal, for example contains %p, then the locale-based format literal would use the locale specified in argument-4 to determine the actual value of the conversion specifiers.
  • If argument-3 is a locale-based format literal (for example, contains %p) and argument-4 is not specified, the locale-based format literal would use the current locale to determine the actual value of the conversion specifiers.
  • If argument-3 is a locale-based format literal (for example, contains %p), and the LOCALE OF special register is used to refer to a non-locale item, the locale-based format literal would use the default locale to determine the actual value of the conversion specifiers.

Examples

The following examples show how the CONVERT-DATE-TIME intrinsic function can be used:

MOVE FUNCTION CONVERT-DATE-TIME ('95/05/30' DATE)
     TO  date-1.
MOVE FUNCTION CONVERT-DATE-TIME
     ('95/05/30' DATE '%y/%m/%d')
     TO  date-1.
MOVE FUNCTION CONVERT-DATE-TIME
     ('95/05/30' DATE '%y/%m/%d' my-locale)
     TO  date-1.
MOVE FUNCTION CONVERT-DATE-TIME
     ('95/05/30' DATE LOCALE my-locale)
     TO  date-1.