Using Standard Date Functions

In this section:

When using standard date functions, you need to understand the settings that alter the behavior of these functions, as well as the acceptable formats and how to supply values in these formats.

You can affect the behavior of date functions in the following ways:

For detailed information on each standard date function, see:

DATEADD: Adding or Subtracting a Date Unit to or From a Date

DATECVT: Converting the Format of a Date

DATEDIF: Finding the Difference Between Two Dates

DATEMOV: Moving a Date to a Significant Point

DATETRAN: Formatting Dates in International Formats

DPART: Extracting a Component From a Date Field

FIYR: Obtaining the Financial Year

FIQTR: Obtaining the Financial Quarter

FIYYQ: Converting a Calendar Date to a Financial Date

TODAY: Returning the Current Date

Specifying Work Days

In this section:

You can determine which days are work days and which are not. Work days affect the DATEADD, DATEDIF, and DATEMOV functions. You identify work days as business days or holidays.

Specifying Business Days

How to:

Business days are traditionally Monday through Friday, but not every business has this schedule. For example, if your company does business on Sunday, Tuesday, Wednesday, Friday, and Saturday, you can tailor business day units to reflect that schedule.

Syntax: How to Set Business Days

SET BUSDAYS = smtwtfs

where:

smtwtfs

Is the seven character list of days that represents your business week. The list has a position for each day from Sunday to Saturday:

  • To identify a day of the week as a business day, enter the first letter of that day in that day's position.
  • To identify a non-business day, enter an underscore (_) in that day's position.

If a letter is not in its correct position, or if you replace a letter with a character other than an underscore, you receive an error message.

Example: Setting Business Days to Reflect Your Work Week

The following designates work days as Sunday, Tuesday, Wednesday, Friday, and Saturday:

SET BUSDAYS = S_TW_FS

Syntax: How to View the Current Setting of Business Days

? SET BUSDAYS

Specifying Holidays

How to:

Reference:

You can specify a list of dates that are designated as holidays in your company. These dates are excluded when using functions that perform calculations based on working days. For example, if Thursday in a given week is designated as a holiday, the next working day after Wednesday is Friday.

To define a list of holidays, you must:

  1. Create a holiday file using a standard text editor.
  2. Select the holiday file by issuing the SET command with the HDAY parameter.

Reference: Rules for Creating a Holiday File

  • Dates must be in YYMD format.
  • Dates must be in ascending order.
  • Each date must be on its own line.
  • Each year for which data exists must be included or the holiday file is considered invalid. Calling a date function with a date value outside the range of the holiday file returns a zero for business day requests.

    If you are subtracting two dates in 2005, and the latest date in the holiday file is 20041231, the subtraction will not be performed. One way to avoid invalidating the holiday file is to put a date very far in the future in any holiday file you create (for example, 29991231), and then it will always be considered valid.

  • You may include an optional description of the holiday, separated from the date by a space.

By default, the holiday file has a file name of the form HDAYxxxx.err and is on your path, or on z/OS under PDS deployment, is a member named HDAYxxxx of a PDS allocated to DDNAME ERRORS. In your procedure or request, you must issue the SET HDAY=xxxx command to identify the file or member name. Alternatively, you can define the file to have any name and be stored anywhere or, on z/OS under PDS deployment, allocate the holiday file as a sequential file of any name or as member HDAYxxxx of any PDS. For information about using non-default holiday file names, see FILEDEF or DYNAM the Holiday File.

Procedure: How to Create a Holiday File

  1. In a text editor, create a list of dates designated as holidays using the Rules for Creating a Holiday File.
  2. Save the file.

    If you are not using the default naming convention, see FILEDEF or DYNAM the Holiday File. If you are using the default naming convention, use the following instructions:

    In Windows and UNIX: The file must be HDAYxxxx.ERR

    In z/OS: The file must be a member of ERRORS named HDAYxxxx.

    where:

    xxxx

    Is a string of text four characters long.

Syntax: How to Select a Holiday File

SET HDAY = xxxx

where:

xxxx

Is the part of the name of the holiday file after HDAY. This string must be four characters long.

Example: Creating and Selecting a Holiday File

The following is the HDAYTEST file, which establishes holidays:

19910325 TEST HOLIDAY
19911225 CHRISTMAS

The following sets HDAYTEST as the holiday file:

SET BUSDAYS = SMTWTFS
SET HDAY = TEST

This request uses HDAYTEST in its calculations:

TABLE FILE MOVIES
PRINT TITLE RELDATE
COMPUTE NEXTDATE/YMD = DATEADD(RELDATE, 'BD', 1);
WHERE RELDATE GE '19910101';
END

The output is:

TITLE                                    RELDATE   NEXTDATE
-----                                    -------   --------
TOTAL RECALL                             91/03/24  91/03/26

Syntax: How to FILEDEF or DYNAM the Holiday File

In all environments except z/OS under PDS deployment, use the following syntax.

FILEDEF HDAYxxxx DISK {app/|path}/filename.ext

where:

HDAYxxxx

Is the logical name (DDNAME) for the holiday file, where xxxx is any four characters. You establish this logical name by issuing the SET HDAY=xxxx command in your procedure or request.

app

Is the name of the application in which the holiday file resides.

path

Is the path to the holiday file.

filename.ext

Is the name of the holiday file.

On z/OS under PDS deployment, use the following to allocate a sequential holiday file.

DYNAM ALLOC {DD|FILE} HDAYxxxx DA qualif.filename.suffix SHR REU

On z/OS under PDS deployment, use the following to allocate a holiday file that is a member of a PDS.

DYNAM ALLOC {DD|FILE} HDAYxxxx DA qualif.filename.suffix(HDAYxxx) SHR REU

where:

HDAYxxxx

Is the DDNAME for the holiday file. Your FOCEXEC or request must set the HDAY parameter to xxxx, where xxxx is any four characters you choose. If your holiday file is a member of a PDS, HDAYxxxx must also be the member name.

qualif.filename.suffix

Is the fully-qualified name of the sequential file that contains the list of holidays or the PDS with member HDAYxxxx that contains the list of holidays.

Example: Defining a Holiday File

The following holiday file, named holiday.data in the c:\temp directory on Windows, defines November 3, 2011 and December 24, 2011 as holidays:

20111103
20111224

The following request against the MOVIES data source uses the FILEDEF command to define this file as the holiday file. The logical name in the FILEDEF command is HDAYMMMM, and the procedure issues the SET HDAY=MMMM command. It then defines the date November 2, 2011 and calculates the next business day:

FILEDEF HDAYMMMM DISK c:\ibi\holiday.data
SET HDAY = MMMM                                      
SET BUSDAYS = _MTWTF_                                
DEFINE FILE MOVIES
NEWDATE/YYMD = '20111102';
NEXTDATE/YYMD = DATEADD(NEWDATE, 'BD', 1); 
END
TABLE FILE MOVIES                                    
SUM COPIES NEWDATE NEXTDATE                                 
ON TABLE SET PAGE NOPAGE   
END

The output shows that the next business day after November 2 is November 4 because November 3 is a holiday:

Example: Allocating the Holiday File to a Sequential File on z/OS Under PDS Deployment

The following sequential file, named USER1.HOLIDAY.DATA, defines November 3, 2011 and December 24, 2011 as holidays:

20111103
20111224

The following request against the MOVIES data source uses the DYNAM command to allocate this file as the holiday file. The DDNAME in the DYNAM command is HDAYMMMM, and the procedure issues the SET HDAY=MMMM command. It then defines the date November 2, 2011 and calculates the next business day:

DYNAM ALLOC DD HDAYMMMM DA USER1.HOLIDAY.DATA SHR REU
SET HDAY = MMMM
SET BUSDAYS = _MTWTF_
DEFINE FILE MOVIES
NEWDATE/YYMD = '20111102';
NEXTDATE/YYMD = DATEADD(NEWDATE, 'BD', 1);
END
TABLE FILE MOVIES
SUM COPIES NEWDATE NEXTDATE
ON TABLE SET PAGE NOPAGE
END

The output shows that the next business day after November 2 is November 4 because November 3 is a holiday:

COPIES  NEWDATE     NEXTDATE  
------  -------     --------  
   117  2011/11/02  2011/11/04
Example: Allocating the Holiday File to a PDS Member on z/OS Under PDS Deployment

The following holiday file, member HDAYMMMM in a PDS named USER1.HOLIDAY.DATA, defines November 3, 2011 and December 24, 2011 as holidays:

20111103
20111224

The following request against the MOVIES data source uses the DYNAM command to allocate this file as the holiday file. The DDNAME in the DYNAM command is HDAYMMMM, the member name is also HDAYMMMM, and the procedure issues the SET HDAY=MMMM command. It then defines the date November 2, 2011 and calculates the next business day:

DYNAM ALLOC DD HDAYMMMM DA USER1.HOLIDAY.DATA(HDAYMMMM) SHR REU
SET HDAY = MMMM
SET BUSDAYS = _MTWTF_
DEFINE FILE MOVIES
NEWDATE/YYMD = '20111102';
NEXTDATE/YYMD = DATEADD(NEWDATE, 'BD', 1);
END
TABLE FILE MOVIES
SUM COPIES NEWDATE NEXTDATE
ON TABLE SET PAGE NOPAGE
END

The output shows that the next business day after November 2 is November 4 because November 3 is a holiday:

COPIES  NEWDATE     NEXTDATE  
------  -------     --------  
   117  2011/11/02  2011/11/04

Enabling Leading Zeros For Date and Time Functions in Dialogue Manager

How to:

If you use a date and time function in Dialogue Manager that returns a numeric integer format, Dialogue Manager truncates any leading zeros. For example, if a function returns the value 000101 (indicating January 1, 2000), Dialogue Manager truncates the leading zeros, producing 101, an incorrect date. To avoid this problem, use the LEADZERO parameter.

LEADZERO only supports an expression that makes a direct call to a function. An expression that has nesting or another mathematical function always truncates leading zeros. For example,

-SET &OUT = AYM(&IN, 1, 'I4')/100;

truncates leading zeros regardless of the LEADZERO parameter setting.

Syntax: How to Set the Display of Leading Zeros

SET LEADZERO = {ON|OFF}

where:

ON

Displays leading zeros if present.

OFF

Truncates leading zeros. OFF is the default value.

Example: Displaying Leading Zeros

The AYM function adds one month to the input date of December 1999:

-SET &IN = '9912';
-RUN
-SET &OUT = AYM(&IN, 1, 'I4');
-TYPE &OUT

Using the default LEADZERO setting, this yields:

1

This represents the date January 2000 incorrectly. Setting the LEADZERO parameter in the request as follows:

SET LEADZERO = ON
-SET &IN = '9912';
-SET &OUT = AYM(&IN, 1, 'I4');
-TYPE &OUT

results in the following:

0001

This correctly indicates January 2000.