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.
For more information on this title
In this SAP Press book chapter excerpt, you'll find an introduction to SAP ABAP date and time data types.
This excerpt from ABAP Cookbook: Programming Recipes for Everyday Solutions by James Wood is reprinted here with permission from SAP Press, copyright 2010. Download a PDF of this chapter.
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.
||A built-in fixed-length date type of the form YYYYMMDD. For example, the value 20100913 represents the date September 13, 2010.|
||A built-in fixed-length time type of the form HHMMSS. For example, the value 102305 represents the time 10:23:05 AM.|
||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.|
||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'.
For a complete list of time zones configured in the system, have a look at the contents of ABAP Dictionary Table TTZZ.
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
Daylight savings time
For a complete list of daylight savings time rules, have a look at the contents of the ABAP Dictionary table TTZDV.
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
+ 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).
||Computes the day of the week for a given date. Day values are calculated as 1 (Monday), 2 (Tuesday), and so on.|
||Computes the day of the week just like DATE_ COMPUTE_DAY; also returns the day value as text (e.g., TUESDAY, etc.).|
||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.|
||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.|
||Converts a factory date value back into a date object.|
||Tests to determine whether or not a given date is a holiday based on the configured holiday calendar.|
||Calculates the first day of a given week.|
Table 2.3 Useful Date Functions in Function Group SCAL
Advanced ABAP operations with elementary data types
Understanding ABAP programming bits and bytes
Read this special report on ABAP jobs