Working with ABAP date and time data types

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.

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.

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'.

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.

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).

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

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.

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).

Table 2.3 Useful Date Functions in Function Group SCAL