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 INTO UTCLONG

Quick Reference

Other versions: ~~7.31~~ | ~~7.40~~ | 7.54

Syntax


CONVERT DATE dat 
        TIME tim [FRACTIONAL SECONDS fs] 

        [DAYLIGHT SAVING TIME dst] 

        TIME ZONE tz 
        INTO UTCLONG time_stamp.

Effect

This statement converts a date specified in dat, a time specified in tim, optionally with fractions of seconds specified in fs, and a summer time marker specified in dst for the time zone specified in tz into a time stamp and maps the result to a time stamp field time_stamp. The conversion is made in accordance with the rules for time zones.

dat, tim, fs, dst, and tz are functional operand positions.

An operand of the type d, which contains a valid date, must be specified for dat. If dat contains an invalid value, a handleable exception of the class CX_SY_CONVERSION_NO_DATE is raised. The days from October 5, 1582 through October 14, 1582 missing due to the switch from the Julian to the Gregorian calendar are considered invalid values here.
An operand of the type t, which contains a valid time must be specified for tim. In tim, only the values 00 to 23 are valid for the hours, and 00 to 59 for the minutes and seconds, as well as the value 240000. If tim contains an invalid value, a handleable exception of the class CX_SY_CONVERSION_NO_TIME is raised. The value 240000 causes the date in dat to be increased by a day and the time to be set to 000000.
An operand of the type decfloat34, containing fractions of seconds with up to seven decimal places, can be specified for fs. The value of fs must be between the range of 0.0000000 to 0.9999999, otherwise a handleable exception of the class CX_SY_CONVERSION_NO_DATE_TIME is raised. If the addition FRACTIONAL SECONDS is not specified, the value 0 is used implicitly.
An operand of the type c with length 1, containing the value "X" or " " can be specified for dst. This controls the behavior of the statement with respect to summer time.

If dst has the value "X", the value of tim is applied as the specified time in daylight savings time.

If dst has the value " ", the value of tim is applied as the specified time in winter time.

If dst has neither the value "X" nor " ", a handleable exception of the class CX_PARAMETER_INVALID_RANGE is raised.

If the time zone specified in tz does not have a summer time rule (for example, when "UTC" is specified), the addition DAYLIGHT SAVING TIME is ignored. If the addition DAYLIGHT SAVING TIME is not specified, the value of dst is set to "X" implicitly, if the data in tim and dat is in summer time and is set to " " for data in winter time. In the duplicate hour that is caused by switching from summer time to winter time, tim and dat are interpreted as a time in summer time and dst is set to the value "X". If the value in dst does not match the data in tim and dat (that is, if the value "X" is specified in winter time and the value " " in summer time), a handleable exception of the class CX_SY_CONVERSION_NO_DATE_TIME is raised.

A character-like operand, containing a time zone from the database table TTZZ, must be specified for tz.

If tz is initial, no time shift is calculated when converting to the time stamp.

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.

If the rule set for the specified time zone is incomplete, a non-handleable exception is raised.

The following can be specified for time_stamp:

An existing variable of the data type utclong.
An inline declaration DATA(var), where a variable of type utclong is declared.

If the following combinations of values are specified for DATE and TIME

"00000000" as dat and "000000" as tim
"00010101" as dat and "000000" as tim
"99991231" as dat and "235959" as tim

no time shift is calculated when the time stamp is created.

If dat and tim contain valid values but produce an invalid time stamp when combined with a valid time zone in tz, an exception of the class CX_SY_CONVERSION_NO_DATE_TIME is raised.

Notes

Current user-specific local times and the corresponding local time zones are stored in the system fields sy-datlo, sy-timlo, and sy-zonlo.
Specifying daylight saving time and winter time after DAYLIGHT SAVING TIME enables different UTC time stamps to be created from matching local time stamps within the extra hour when switching from daylight saving time to winter time.
When the switch is made from winter to daylight saving time, an hour is lost. For example, in the "CET" time zone in the year 2009, on March 29, the hour between 02:00 and 03:00 does not exist. Any attempt to convert a time during this missing hour raises an exception.
Usually, an invalid time stamp can be created from a valid date and time only by combining the first valid date 00010101 with time zones east of UTC or the last valid date 99991231 with time zones west 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", the settings apply that are described in the example for CONVERT UTCLONG in the rule set for time stamps. By specifying the daylight savings time and winter time, two different UTC time stamps 2019-11-03T05:30:00.0000000Z and 2019-11-03T06:30:00.0000000Z are created from one specified local time. Without the addition DAYLIGHT SAVING TIME, the UTC time stamp 2019-11-03T05:30:00.0000000Z is created.

DATA(dat) = CONV d( '20191103' ). 
DATA(tim) = CONV t( '013000' ). 

CONVERT DATE dat 
        TIME tim 
        DAYLIGHT SAVINGS TIME 'X' 
        TIME ZONE 'EST' 
        INTO UTCLONG DATA(time_stamp). 
cl_demo_output=>write_data( time_stamp ). 

CONVERT DATE dat 
        TIME tim 
        DAYLIGHT SAVINGS TIME ‘ ' 
        TIME ZONE 'EST' 
        INTO UTCLONG time_stamp. 
cl_demo_output=>write_data( time_stamp ). 

CONVERT DATE dat 
        TIME tim 
        TIME ZONE 'EST' 
        INTO UTCLONG time_stamp. 
cl_demo_output=>write_data( time_stamp ). 

cl_demo_output=>display( ).

Example

The example demonstrates the special handling of the invalid time 240000.

CONVERT DATE CONV d( '20191104' ) 
        TIME CONV t( '240000' ) 
        DAYLIGHT SAVINGS TIME ‘ ' 
        TIME ZONE 'UTC' 
        INTO UTCLONG DATA(time_stamp1). 

CONVERT DATE CONV d( '20191105' ) 
        TIME CONV t( '000000' ) 
        DAYLIGHT SAVINGS TIME ‘ ' 
        TIME ZONE 'UTC' 
        INTO UTCLONG DATA(time_stamp2). 

ASSERT time_stamp1 = time_stamp2.

Executable Example

Convert Time Stamp to Time Stamp Field.

Exceptions

Handleable Exceptions

CX_SY_CONVERSION_NO_DATE

Cause: An invalid date was specified for DATE.
Runtime error: CONVT_INVALID_DATE

CX_SY_CONVERSION_NO_TIME

Cause: An invalid time was specified for TIME.
Runtime error: CONVT_INVALID_TIME

CX_SY_CONVERSION_NO_DATE_TIME

Cause: An invalid value was specified for FRACTIONAL SECONDS.
Runtime error: CONVT_INVALID_FRAC_SEC
Cause: The value for DAYLIGHT SAVING TIME does not fit the values for DATE and TIME.
Runtime error: INVALID_POINT_IN_TIME
Cause: An invalid time stamp would be generated.
Runtime error: INVALID_POINT_IN_TIME
Cause: Invalid time zone in tz.
Runtime error: INVALID_TIME_ZONE

CX_PARAMETER_INVALID_RANGE

Cause: An invalid value was specified for DAYLIGHT SAVING TIME.
Runtime error: PARAMETER_INVALID_RANGE

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