Skip to content

ABAP Keyword Documentation →  ABAP − Reference →  Processing Internal Data →  Date and Time Processing →  Time Stamps →  Time Stamp Field with Time Stamp Type →  Time Stamp Functions 

utclong_add - Time Stamp Function

Other versions: 7.31 | 7.40 | 7.54

Syntax


... utclong_add( val  = time_stamp [days = days] 
   
                               [hours = hours] 

                 
                 [minutes = minutes] 

                 
                 [seconds = seconds] ) ...

Effect

This function adds the values passed to the optional parameters as a time stamp specified after val. The type of the return value is utclong.

A time stamp field of the type utclong must be passed to the argument val. This field must contain a valid time stamp. time_stamp is a time-stamp-like expression position. An initial time stamp is handled like the least possible value of a time stamp.

The added values are passed in the following parameters, of which at least one must be specified:

  • days expects a number of days as a number of the type i.
  • hours expects a number of hours as a number of the type i.
  • minutes expects a number of minutes as a number of the type int8.
  • seconds expects a number of seconds as a number of the type decfloat34.

Each parameter can be passed data objects that can be converted to the expected type. Both positive and negative numbers can be passed. These are numerical expression positions. Internally, the passed values are transformed to the appropriate number of seconds. Here, the value passed to seconds is rounded to seven decimal places. First, the days, hours, and minutes are added to or subtracted from the time stamp, and then the seconds. If an invalid time stamp value is produced by one of the intermediate steps, a catchable exception of the class CX_SY_ARITHMETIC_OVERFLOW is raised.


Notes

  • utclong_subtract is not provided, since its function is matched by passing negative numbers to the parameter utclong_add.

  • There are no parameters for years and months, since they do not match a fixed number of seconds.

  • The result of the function utclong_add is never the initial value of a time stamp. It is either a valid time stamp value or an exception is raised.


Example

This example demonstrates how the function utclong_add works. The appropriate number of seconds is subtracted from a time stamp field ts_new, which itself is produced by adding days, hours, and minutes. The statement ASSERT demonstrates how this reproduces the original time stamp.

DATA(ts) = utclong_current( ). 

DATA(ts_new) = 
  utclong_add( val     = ts 
               days    = 1000 
               hours   = 100 
               minutes = 10 ). 

ASSERT ts = 
  utclong_add( val     = ts_new 
              seconds = - ( 1000 * 86400 + 100 * 3600 + 10 * 60 ) ). 

cl_demo_output=>display( |{ ts }\n{ ts_new }| ).

Example

This example demonstrates how the initial value is handled. One second is added to a time stamp ts_ini passed as an initial value and one second is subtracted from the result in ts_1. The result ts_0 is the lowest valid time stamp value and is not the initial value.

DATA(o) = cl_demo_output=>new( ). 

DATA ts_ini TYPE utclong. 

IF ts_ini IS INITIAL. 
  o->write( 'ts_ini is initial' ). 
ENDIF. 
o->write( ts_ini ). 

DATA(ts_1) = 
  utclong_add( val     = ts_ini 
               seconds = 1 ). 

o->write( ts_1 ). 

DATA(ts_0) = 
  utclong_add( val     = ts_1 
               seconds = -1 ). 

IF ts_0 IS NOT INITIAL AND 
   ts_0 <> ts_ini. 
  o->write( 'ts_0 is neither initial nor equal to ts_ini' ). 
ENDIF. 
o->write( ts_0 ). 

o->display( ).

Example

This example shows how missing days due to the switch from the Julian to the Gregorian calendar are handled. Adding 100 ns to the time stamp "1582-10-04 23:59:59.9999999" produces the time stamp "1582-10-15T00:00:00.0000000".

DATA(ts) = conv utclong( '1582-10-04 23:59:59.9999999' ). 

DATA(ts_new) = 
  utclong_add( val     = ts 
               seconds    = '0.0000001' ). 

cl_demo_output=>display( |{ ts }\n{ ts_new }| ).

Exceptions

Handleable Exceptions

CX_SY_CONVERSION_NO_DATE_TIME

  • Cause: The time stamp specified for val is invalid.
    Runtime error: INVALID_UTCLONG

CX_SY_CONVERSION_ERROR

  • Cause: A passed parameter cannot be converted to the expected type.
    Runtime error: CONVT_OVERFLOW, BCD_OVERFLOW

CX_SY_ARITHMETIC_OVERFLOW

  • Cause: The parameters passed produce an invalid time stamp.
    Runtime error: UTCLONG_ADD_OVERFLOW

Non-Handleable Exceptions

  • Cause: An argument without a time stamp type is bound to val.
    Runtime error: TCHK_TYPE_LOAD