Skip to content

ABAP Keyword Documentation →  ABAP − Reference →  Processing Internal Data →  Date and Time Processing →  Time Stamps →  Time Stamp Field with Time Stamp Type →  Conversion Statements for Time Stamp Fields 

CONVERT UTCLONG

Quick Reference

Other versions: 7.31 | 7.40 | 7.54

Syntax


CONVERT UTCLONG time_stamp 
        INTO [DATE dat] 

             [TIME tim [FRACTIONAL SECONDS fs]] 

             [DAYLIGHT SAVING TIME dst] 

             TIME ZONE tz.

Effect

This statement converts the time stamp contained in a time stamp field time_stamp to the local date and local time of the time zone specified in tz and assigns the result to the variables dat, tim, and dst. At least one of the additions DATE, TIME, or DAYLIGHT SAVING TIME must be specified. The conversion is made in accordance with the rules for time zones.

time_stamp is a time-stamp-like expression position and tz is a functional operand position.

  • The operand time_stamp must be of the type utclong, which contains a valid time stamp. If time_stamp does not contain a valid time stamp, a handleable exception of the class CX_SY_CONVERSION_NO_DATE_TIME is raised.
  • The operand tz must be character-like and contain a time zone from the database table TTZZ.
  • If tz is initial, the UTC time stamp is not converted to a different time zone. The local date and the local time in the target fields match the UTC reference time.
  • If the specified time zone is not found in the database table TTZZ, a handleable exception of the class CX_SY_CONVERSION_NO_DATE_TIME is raised, unless the time stamp is initial.
  • If the rule set for the specified time zone is incomplete, a non-handleable exception is raised.
  • The local date is assigned to dat as a return value of the data type d. The following can be specified for dat:
  • An existing variable of type d.
  • An inline declaration DATA(var), where a variable of data type d is declared.
  • The local time without the fractions of seconds is assigned to tim as a return value of data type t. The following can be specified for tim:
  • An existing variable of type t.
  • An inline declaration DATA(var), where a variable of data type t is declared.
  • The fractions of seconds are assigned to fs as a return value of the data type decfloat34. The following can be specified for fs:
  • An existing variable of the type decfloat34.
  • An inline declaration DATA(var), where a variable of data type decfloat34 is declared.
  • If the time stamp in time_stamp for the time zone specified in tz is in summer time, dst is given the value "X". Otherwise it is given the value " ". The following can be specified for dst:
  • An existing variable of the type c with length 1
  • An inline declaration DATA(var), where a variable of data type c with length 1 is declared.

Irrespective of the time zone specified, an initial time stamp generates type-dependent initial values in all target fields. If the time stamp has the minimum value "0001-01-01T00:00:00.0000000" or is in the last possible second "9999-12-31T23:59:59.fffffff" no time shift is calculated. A time stamp whose value is greater than or equal to the last second or is between "9999-12-31 23:59:59.0000000" and "9999-12-31 23:59:59.9999999" is handled in the same way as the maximum value "9999-12-31 23:59:59.9999999".

If time_stamp contains a valid value, but results in an invalid date in combination with a valid time zone in tz, a handleable exception of the class CX_SY_CONVERSION_NO_DATE_TIME is raised.


Notes

  • A current UTC time stamp can be generated with the predefined function utclong_current.
  • The current user time zone can be found in the system field sy-zonlo.
  • It is now possible to use the return value for the summer time in dst to distinguish duplicate local time specifications that occur when UTC time stamps are converted into local time during the double hour in the changeover between summer and winter time.
  • Usually, an invalid date and the associated exception can be created from a valid time stamp only by combining the first valid day with time zones west of UTC or the last valid day with time zones east of UTC.
  • An initial time zone tz matches UTC only if the tables of the rules for time zones are filled correctly for the time zone UTC.
  • The statement CONVERT INTO UTCLONG does not set the return value sy-subrc.


Example

For the time zone "EST" in the database table TTZZ, a shift of -5 hours from the UTC reference time is entered in the database table TTZR. In the database table TTZDV, the end of summer time is defined as the first Sunday in November at 02:00 using the key "USA". In 2019, the first Sunday is November 03. With these settings in the rules, the two conversions below both result in the same local time of "01:30:00". The first conversion shows that the time is still in summer time.

CONVERT UTCLONG CONV utclong( '2019-11-03 05:30:00' ) 
        INTO DATE DATA(dat) 
             TIME DATA(tim) 
             DAYLIGHT SAVINGS TIME DATA(dst) 
             TIME ZONE 'EST'. 
cl_demo_output=>write( |{ dat DATE = ISO } { 
                          tim TIME = ISO } { dst }| ). 

CONVERT UTCLONG CONV utclong( '2019-11-03 6:30:00 AM' ) 
        INTO DATE dat 
             TIME tim 
             DAYLIGHT SAVING TIME dst 
             TIME ZONE 'EST'. 
cl_demo_output=>write( |{ dat DATE = ISO } { 
                          tim TIME = ISO } { dst }| ). 

cl_demo_output=>display( ).

Executable Example

Convert Time Stamp to Time Stamp Field.

Exceptions

Handleable Exceptions

CX_SY_CONVERSION_NO_DATE_TIME

  • Cause: Invalid time zone in tz.
    Runtime error: INVALID_TIME_ZONE
  • Cause: An invalid date would be generated.
    Runtime error: LOCAL_TIMESTAMP_OUT_OF_RANGE
  • Cause: The specified time stamp is invalid.
    Runtime error: INVALID_UTCLONG

Non-Handleable Exceptions

  • Cause: Incomplete set of rules for the specified time zone.
    Runtime error: CONVERT_TSTMP_INCONSISTENT_TAB
  • Cause: An operand with an incorrect type is being used.
    Runtime error: TCHK_TYPE_LOAD