Using Date-Time Functions

In this section:

The functions described in this section operate on fields in date-time format (sometimes called H format).

However, you can also provide a date as a character string using the macro DT, followed by a character string in parentheses, presenting date and time. Date components are separated by slashes '/'; time components by colons ':'.

Alternatively, the day can be given as a natural day, like 2004 March 31, in parentheses. Either the date or time component can be omitted. For example, the date-time format argument can be expressed as DT(2004/03/11 13:24:25.99) or DT(March 11 2004).

The following is another example that creates a timestamp representing the current date and time. The system variables &YYMD and &TOD are used to obtain the current date and time, respectively:

-SET &MYSTAMP = &YYMD | ' ' | EDIT(&TOD,'99:$99:$99') ;

Today's date (&YYMD) is concatenated with the time of day (&TOD). The EDIT function is used to change the dots (.) in the time of day variable to colons (:).

The following request uses the DT macro on the alphanumeric date and time variable &MYSTAMP:

TABLE FILE CAR 
  PRINT CAR NOPRINT 
  COMPUTE   DTCUR/HYYMDS = DT(&MYSTAMP);
  IF RECORDLIMIT IS 1; 
END

Top of page

x
Date-Time Parameters

In this section:

The DATEFORMAT parameter specifies the order of the date components for certain types of date-time values. The WEEKFIRST parameter specifies the first day of the week. The DTSTRICT parameter determines the extent to which date-time values are checked for validity.



x
Specifying the Order of Date Components

The DATEFORMAT parameter specifies the order of the date components (month/day/year) when date-time values are entered in the formatted string and translated string formats . It makes the input format of a value independent of the format of the variable to which it is being assigned.



x
Syntax: How to Specify the Order of Date Components in a Date-Time Field
SET DATEFORMAT = option							

where:

option

Can be one of the following: MDY, DMY, YMD, or MYD. MDY is the default value for the U.S. English format.



x
Specifying the First Day of the Week for Use in Date-Time Functions

The WEEKFIRST parameter specifies a day of the week as the start of the week. This is used in week computations by the HDIFF, HNAME, HPART, and HSETPT functions. The WEEKFIRST parameter does not change the day of the month that corresponds to each day of the week, but only specifies which day is considered the start of the week.

The HPART, HYYWD, and HNAME subroutines can extract a week number from a date-time value. To determine a week number, they can use ISO 8601 standard week numbering, which defines the first week of the year as the first week in January with four or more days. Any preceding days in January belong to week 52 or 53 of the preceding year. The ISO standard also establishes Monday as the first day of the week.

These functions can also define the first week of the year as the first week in January with seven days. This is the definition they used in prior releases.

You specify which type of week numbering to use by setting the WEEKFIRST parameter.

Since the week number returned by HNAME and HPART functions can be in the current year or the year preceding or following, the week number by itself may not be useful. The function HYYWD returns both the year and the week from a given date-time value.



x
Syntax: How to Set a Day as the Start of the Week
SET WEEKFIRST = {value|7}

where:

value

Can be:

1 through 7, representing Sunday through Saturday with non-standard week numbering.

or

ISO1 through ISO7, representing Sunday through Saturday with ISO standard week numbering.

Note: ISO is a synonym for ISO2.

The ISO standard establishes Monday as the first day of the week, so to be fully ISO compliant, the WEEKFIRST parameter should be set to ISO or ISO2.



Example: Setting Sunday as the Start of the Week

The following designates Sunday as the start of the week:

SET WEEKFIRST = 1


x
Syntax: How to View the Current Setting of WEEKFIRST
? SET WEEKFIRST

This returns the integer value of the first day of the week. For example, the integer 1 represents Sunday.



x
Controlling Processing of Date-Time Values

Strict processing checks date-time values when they are input by an end user, read from a transaction file, displayed, or returned by a subroutine to ensure that they represent a valid date and time. For example, a numeric month must be between 1 and 12, and the day must be within the number of days for the specified month.



x
Syntax: How to Enable Strict Processing of Date-Time Values
SET DTSTRICT = {ON|OFF}

where:

ON

Invokes strict processing. ON is the default value.

Strict processing checks date-time values when they are input by an end user, read from a transaction file, displayed, or returned by a subroutine to ensure that they represent a valid date and time. For example, a numeric month must be between 1 and 12, and the day must be within the number of days for the specified month.

If DTSTRICT is ON and the result would be an invalid date-time value, the function returns the value zero (0).

OFF

Does not invoke strict processing. Date-time components can have any value within the constraint of the number of decimal digits allowed in the field. For example, if the field is a two-digit month, the value can be 12 or 99, but not 115.


Top of page

x
Supplying Arguments for Date-Time Functions

Reference:

Date-time functions may operate on a component of a date-time value. This topic lists the valid component names and abbreviations for use with these functions.



x
Reference: Arguments for Use With Date and Time Functions

The following component names, valid abbreviations, and values are supported as arguments for the date-time functions that require them:

Component Name

Abbreviation

Valid Values

year
yy

0001-9999

quarter
qq

1-4

month
mm

1-12 or a month name, depending on the function.

day-of-year
dy

1-366

												day or day-of-month 											
dd

1-31 (The two component names are equivalent.)

week
wk

1-53

weekday
dw

1-7 (Sunday-Saturday)

hour
hh

0-23

minute
mi

0-59

second
ss

0-59

millisecond
ms

0-999

microsecond
mc

0-999999

nanosecond
ns

0-999999999

Note:

  • For an argument that specifies a length of eight, ten, or 12 characters, use eight to include milliseconds, ten to include microseconds, and 12 to include nanoseconds in the returned value.
  • The last argument is always a USAGE format that indicates the data type returned by the function. The type may be A (alphanumeric), I (integer), D (floating-point double precision), H (date-time), or a date format (for example, YYMD).


iWay Software