In this SAP Press book chapter excerpt, you'll find an introduction to SAP ABAP date and time data types. Read on to find strategies for creating calculations using the built-in date and time data, working with timestamps in ABAP and using the SAP Calendar.

Advanced ABAP operations with elementary data types

Working with ABAP date and time data types

Understanding ABAP programming bits and bytes

2.2 Date and Time Processing

Online transaction processing (OLTP) systems such as the ones that make up the
SAP Business Suite maintain quite a bit of time-sensitive data, so it’s important
that you understand how to work with the built-in date and time types provided
in ABAP. In the following subsections, we discuss these types and explain how to
use them to perform calculations and conversions.

 

2.2.1 Understanding ABAP Date and Time Types

ABAP provides two built-in types to work with dates and times: the D (date) data
type and the T (time) data type. Both of these types are fixed-length character types
that have the form YYYYMMDD and HHMMSS, respectively. In addition to these built-in
types, the ABAP Dictionary types TIMESTAMP and TIMESTAMPL are being used more
and more in many standard application tables, and so on, to store a timestamp in the
UTC format.1 Table 2.2 shows the basic date and time types available in ABAP.

1 The term “UTC” is an abbreviation for “Consolidated Universal Time,” which is a time standard
based on the International Atomic Time standard. UTC is roughly equivalent to the Greenwich
Mean Time standard (or GMT) which refers to the mean solar time at the Royal Observatory in
Greenwich, London. Collectively, these standards define a global time standard that can be used
to convert a given time to local time, and vice versa.

Data Type	Description
D	A built-in fixed-length date type of the form YYYYMMDD. For example, the value 20100913 represents the date September 13, 2010.
T	A built-in fixed-length time type of the form HHMMSS. For example, the value 102305 represents the time 10:23:05 AM.
TIMESTAMP (Type P – Length 8 No decimals)	An ABAP Dictionary type used to represent short timestamps in the form YYYYMMDDhhmmss. For example, the value 20100913102305 represents the date September 13, 2010 at 10:23:05 AM.

TIMESTAMPL (Type P - Length 11 Decimals 7)

An ABAP Dictionary type used to represent long timestamps in the form YYYYMMDDhhmmssmmmuuun. The additional digits mmmuuun represent fractions of a second.

Table 2.2 ABAP Date and Time Data Types

2.2.2 Date and Time Calculations

When you’re working with dates, you often need to perform various calculations
to compute the difference between two dates, make comparisons, or determine
a valid date range. As we mentioned in Section 2.2.1, Understanding ABAP Date
and Time Types, the built-in date and time types in ABAP are character types, not
numeric types. Nevertheless, the ABAP runtime environment allows you to perform
basic numeric operations on these types by implicitly converting them to
numeric types behind the scenes.

The code excerpt shown in Listing 2.3 demonstrates how these calculations work.
Initially, the variable lv_date is assigned the value of the current system date (e.g.,
the system field SY-DATUM). Next, we increment that date value by 30. In terms of
a date calculation in ABAP, this implies that we’re increasing the day component
of the date object by 30 days. Here, note that the ABAP runtime environment is
smart enough to roll over the date value whenever it reaches the end of a month,
and so on. In other words, you can rely on the system to ensure that you don’t
calculate an invalid date value (e.g., 01/43/2011).

DATA: lv_date TYPE d.
lv_date = sy-datum.
WRITE: / 'Current Date:', lv_date MM/DD/YYYY.

lv_date = lv_date + 30.
WRITE: / 'Future Date:', lv_date MM/DD/YYYY.

Listing 2.3 Performing Date Calculations in ABAP

Time calculations in ABAP work very similarly to the date calculations shown in
Listing 2.3. With time calculations, the computation is based upon the seconds
component of the time object. The code in Listing 2.4 shows how we can increment
the current system time by 90 seconds using basic time arithmetic.
DATA: lv_time TYPE t.
lv_time = sy-uzeit.
WRITE /(60) lv_time USING EDIT MASK
'The current time is __:__:__'.
lv_time = lv_time + 90.
WRITE /(60) lv_time USING EDIT MASK
'A minute and a half from now it will be __:__:__'.

Listing 2.4 Performing Time Calculations in ABAP

In addition to typical numeric calculations, you also have the option of working
with date/time fields using normal character-based semantics. For instance, you
can use the offset/length functionality to initialize date or time components. The
code excerpt in Listing 2.5 demonstrates how you can adjust the date 02/13/2003
to 01/13/2003 using offset/length semantics.

DATA: lv_date TYPE d VALUE '20030213'.
WRITE: / lv_date MM/DD/YYYY.
lv_date+4(2) = '01'.
WRITE: / lv_date MM/DD/YYYY.

Listing 2.5 Manipulating a Date Using Offset/Length Functionality

2.2.3 Working with Timestamps

If you’ve been working with some of the newer releases of the products in the
SAP Business Suite, you may have encountered certain applications that use the
TIMESTAMP or TIMESTAMPL data types to store time-sensitive data. As you can see in
Table 2.2, these ABAP Dictionary types store timestamps with varying degrees of
accuracy. Interestingly, though these types aren’t built-in types like D or T, ABAP
does provide some native support for them in the form of a couple of built-in statements.
In addition, SAP also provides a system class called CL_ABAP_TSTMP, which
can be used to simplify the process of working with timestamps. We investigate
these features in the following subsections.

\You can retrieve the current system time and store it in a timestamp variable using
the GET TIME STAMP statement whose syntax is demonstrated in Listing 2.6. The
GET TIME STAMP statement stores the timestamp in a shorthand or longhand format
depending upon the type of the timestamp data object used after the FIELD addition.
The timestamp value is encoded using the UTC standard.

DATA: lv_tstamp_s TYPE timestamp,
lv_tstamp_l TYPE timestampl.
GET TIME STAMP FIELD lv_tstamp_s.
WRITE: / 'Short Time Stamp:', lv_tstamp_s
TIME ZONE sy-zonlo.
GET TIME STAMP FIELD lv_tstamp_l.
WRITE: / 'Long Time Stamp: ', lv_tstamp_l
TIME ZONE sy-zonlo.

Listing 2.6 Using the GET TIME STAMP Statement

Looking at the code excerpt in Listing 2.6, you can see that we’re displaying the
timestamp using the TIME ZONE addition of the WRITE statement. This addition formats
the output of the timestamp according to the rules for the time zone specified.
In Listing 2.6, we used the system field SY-ZONLO to display the local time zone
configured in the user’s preferences. However, we could have just as easily used a
data object of type TIMEZONE, or even a hard-coded literal such as 'CST'.

Time Zones

For a complete list of time zones configured in the system, have a look at the contents of ABAP Dictionary Table TTZZ.

 

Converting Timestamps

You can convert a timestamp to a date/time data object and vice versa using the
CONVERT statement in ABAP. Listing 2.7 shows the syntax used to convert a timestamp
into data objects of type D and T. The TIME ZONE addition adjusts the UTC
date/time value within the timestamp in accordance with a particular time zone.
Additionally, the optional DAYLIGHT SAVING TIME addition can be used to determine
whether or not the timestamp value happens to coincide with daylight savings
time. If it does, the lv_dst variable has the value 'X'; otherwise, it’s blank.

This feature can be helpful in differentiating between timestamp values that lie
within the transitional period between summer time and winter time.2

CONVERT TIME STAMP lv_tstamp TIME ZONE lv_tzone
INTO [ DATE lv_date ] [ TIME lv_time ]
[DAYLIGHT SAVING TIME lv_dst].

Listing 2.7 Syntax of CONVERT TIME STAMP Statement

Listing 2.8 shows how the CONVERT TIME STAMP statement is used to convert the
current system timestamp to date/time data objects using the local time zone.

TYPE-POOLS: abap.
DATA: lv_tstamp TYPE timestamp,
lv_date TYPE d,
lv_time TYPE t,
lv_dst TYPE abap_bool.

GET TIME STAMP FIELD lv_tstamp.
CONVERT TIME STAMP lv_tstamp TIME ZONE sy-zonlo
INTO DATE lv_date TIME lv_time
DAYLIGHT SAVING TIME lv_dst.

WRITE: / 'Today's date is: ', lv_date MM/DD/YYYY.
WRITE: /(60) lv_time USING EDIT MASK
'The current time is: __:__:__'.

IF lv_dst EQ abap_true.
WRITE: / 'In daylight savings time...'.
ELSE.
WRITE: / 'Not in daylight savings time...'.
ENDIF.

Listing 2.8 Converting Timestamps to Date/Time Objects

To create a timestamp using a date/time object, you can use the syntax variant of
the CONVERT statement shown in Listing 2.9. The date/time values are qualified
using the TIME ZONE addition so that the appropriate offsets can be applied as the
UTC timestamp is generated.

2 For a complete list of daylight savings time rules, have a look at the contents of the ABAP Dictionary table TTZDV.

CONVERT DATE lv_date
[TIME lv_time [DAYLIGHT SAVING TIME lv_dst]]
INTO TIME STAMP lv_tstamp TIME ZONE lv_tzone.

Listing 2.9 Syntax of CONVERT DATE Statement

The code excerpt in Listing 2.10 shows how the CONVERT DATE statement can be
used to generate a timestamp object from a date/time object.

TYPE-POOLS: abap.
DATA: lv_tstamp TYPE timestamp,
lv_date TYPE d,
lv_time TYPE t,
lv_dst TYPE abap_bool.

lv_date = sy-datum.
lv_time = sy-uzeit.

CONVERT DATE lv_date TIME lv_time
INTO TIME STAMP lv_tstamp TIME ZONE sy-zonlo.

WRITE: / 'Time Stamp Value:', lv_tstamp TIME ZONE sy-zonlo.

Listing 2.10 Creating a Timestamp from a Date/Time Object

CL_ABAP_TSTMP

+ ADD( ) + SUBTRACT( ) + SUBTRACTSECS( ) + TD_ADD( ) + TD_SUBTRACT( ) + ISDOUBLEINTERVAL( ) + SYSTEMTSTMP_SYST2LOC( ) + SYSTEMTSTMP_LOC2SYST( ) + SYSTEMTSTMP_UTC2SYST( ) +SYSTEMTSTMP_SYST2UTC( ) + TD_NORMALIZE( ) + NORMALIZE( )

Figure 2.4 UML Class Diagram for Class CL_ABAP_TSTMP

Timestamp Operations Using System Class CL_ABAP_TSTMP

Unlike the native D and T types, the ABAP runtime environment doesn’t have
built-in functionality to perform calculations on timestamps (e.g., add or subtract,
etc.). Instead, SAP provides a system class called CL_ABAP_TSTMP for this purpose.
Figure 2.4 contains a UML class diagram that shows the publicly available methods
provided in this class. As you would expect, there are various forms of ADD() and SUBTRACT() methods to perform timestamp calculations. In addition, a series of
conversion methods (e.g., SYSTEMTSTMP_SYST2LOC(), etc.) can be used to convert
a timestamp to various time zones, a Boolean method called ISDOUBLEINTERVAL()
can be used to determine if a timestamp is in daylight savings time, and a couple
of methods can be used to normalize a timestamp. Here, normalization implies that
an invalid time value such as 10:30:60 would be adjusted to the value 10:31:00.

In UML class diagram notation, methods that are underlined are defined as class
methods. Class methods can be invoked without first creating an instance of the
class in which they are defined, as evidenced in the code excerpt shown in Listing
2.11. Here, we’re using the class method ADD() to add 75 seconds to the current
system time.

DATA: lv_tstamp TYPE timestamp,
lv_date TYPE d,
lv_time TYPE t.

GET TIME STAMP FIELD lv_tstamp.
WRITE: / 'Time Stamp Value:', lv_tstamp TIME ZONE sy-zonlo.

TRY.
CALL METHOD cl_abap_tstmp=>add
EXPORTING
tstmp = lv_tstamp
secs = 75
RECEIVING
r_tstmp = lv_tstamp.
CATCH CX_PARAMETER_INVALID_RANGE.
CATCH CX_PARAMETER_INVALID_TYPE.
ENDTRY.

WRITE: / 'Time Stamp Value:', lv_tstamp TIME ZONE sy-zonlo.

Listing 2.11 Working with Timestamps Using CL_ABAP_TSTMP

The call signatures of most of the other methods in class CL_ABAP_TSTMP are similar
to the ADD() method demonstrated in Listing 2.11. For more details concerning the
functionality of particular methods in this class, see the class/method documentation
for this class in the Class Builder (Transaction SE24).

2.2.4 Calendar Operations

So far, our discussion on dates has focused on raw calculations and conversions. However, many typical use cases in the business world require that we look at
dates from a semantic point of view. For example, you might ask whether or
not the date 1/13/2010 is a working day, or whether 4/4/2010 is a holiday. The
answers to these kinds of questions require the use of a calendar. Fortunately, SAP
provides a very robust set of calendaring features straight out of the box with SAP
NetWeaver AS ABAP.

The SAP Calendar is maintained in a client-specific manner inside the SAP Customizing
implementation guide (Transaction SPRO ). Depending on how your system
is set up, you might have a project-specific implementation guide. However, for
the purposes of this discussion, we assume that you’re using the default SAP Reference
Implementation Guide (IMG). You can access this guide by clicking on the
button labeled SAP Reference IMG on the initial screen of Transaction SPRO (see
Figure 2.5).

Figure 2.5 Initial Screen of Transaction SPRO

Inside the SAP Reference IMG, you can fi nd the SAP Calendar under the navigation
path SAP NetWeaver • General Settings • Maintain Calendar (see Figure 2.6).

Figure 2.6 Navigating to the SAP Calendar in the IMG

Figure 2.7 shows the main menu of the SAP Calendar transaction . From here, you
can configure subobjects such as public holidays, holiday calendars, and factory
calendars. By default, an SAP NetWeaver system comes preconfigured with some
typical settings in these subareas. However, you’re also free to create customized
holidays and calendars as needed.

Figure 2.6 Navigating to the SAP Calendar in the IMG

Figure 2.7 Maintaining the SAP Calendar in the IMG

After the SAP Calendar is confi gured properly, you can use this data to perform
various types of calculations. Table 2.3 shows some useful function modules that
leverage this data to determine whether or not a given date is a working day, holiday,
and so on. You can fi nd out more information about these function modules
in the documentation provided for each module in the Function Builder (Transaction
SE37).

Function Name	Description
DATE_COMPUTE_DAY	Computes the day of the week for a given date. Day values are calculated as 1 (Monday), 2 (Tuesday), and so on.
DATE_COMPUTE_DAY_ENHANCED	Computes the day of the week just like DATE_ COMPUTE_DAY; also returns the day value as text (e.g., TUESDAY, etc.).

DATE_CONVERT_TO_FACTORYDATE	Calculates the factory date value for a given date. Also provides an indicator that confirms whether or not the given date is considered a working day according to the selected factory calendar.
DATE_GET_WEEK	Determines the week of the year for the given date. For example, the date 9/13/2010 would be the 37th week of the year 2010.
FACTORYDATE_CONVERT_TO_DATE	Converts a factory date value back into a date object.
HOLIDAY_CHECK_AND_GET_INFO	Tests to determine whether or not a given date is a holiday based on the configured holiday calendar.

WEEK_GET_FIRST_DAY

Calculates the first day of a given week.

Table 2.3 Useful Date Functions in Function Group SCAL