Functions and CALL Routines

CALL IS8601_CONVERT Routine

Converts an ISO 8601 interval to datetime and duration values, or converts datetime and duration values to an ISO 8601 interval.

Category:

Date and Time

Syntax
Arguments
Examples

Syntax

CALL IS8601_CONVERT( convert-from, convert-to, <from-variables>, <to-variables>, <date_time_replacements>

specifies a keyword in single quotation marks that indicates whether the source for the conversion is an interval, a datetime and duration value, or a duration value. convert-from can have one of the following values:

'intvl'	specifies that the source value for the conversion is an interval value.
'dt/du'	specifies that the source value for the conversion is a datetime/duration value.
'du/dt'	specifies that the source value for the conversion is a duration/datetime value.
'dt/dt'	specifies that the source value for the conversion is a datetime/datetime value.
'du'	specifies that the source value for the conversion is a duration value.

convert-to

specifies a keyword in single quotation marks that indicates the results of the conversion. convert-to can have one of the following values:

'intvl'	specifies to create an interval value.
'dt'/du'	specifies to create a datetime/duration interval.
'du/dt'	specifies to create a duration/datetime interval.
'dt/dt'	specifies to create a datetime/datetime interval.
'du'	specifies to create a duration.
'start'	specifies to create a value that is the beginning datetime or duration of an interval value.
'end'	specifies to create a value that is the ending datetime or duration of an interval value.

from-variable

specifies one or two variables that contain the source value. Specify one variable for an interval value and two variables, one each, for datetime and duration values. The datetime and duration values are interval components where the first value is the beginning value of the interval and the second value is the ending value of the interval.

Requirement:	An integer variable must be at least a 16-byte character variable whose value is determined by reading the value using either the $N8601B informat or the $N8601E informat, or the integer variable is an integer value returned from invoking the CALL ISO8601_CONVERT routine.
Requirement:	A datetime value must be either a SAS datetime value or an 8-byte character value that is read by the $N8601B informat or the $N8601E informat, or by invoking the CALL ISO8601_CONVERT routine.
Requirement:	A duration value must be a numeric value that represents the number of seconds in the duration or an 8-byte character value whose value is determined by reading the value using either the $N8601B informat or the $N8601E informat, or by invoking the CALL ISO8601_CONVERT routine.

to-variable

specifies one or two variables that contain converted values. Specify one variable for in interval value and two variables, one each, for datetime and duration values.

Requirement:	The interval variable must be at least a 16-byte character variable.
Tip:	The datetime and duration variables can be either numeric or character. To avoid losing precision of a numeric value, the length of a numeric variable needs to be at least eight characters. Datetime and duration character variables must be at least 16 bytes; they are padded with blank characters for values that are less than the length of the variable.

date_time_replacements

specifies date or time component values to use when a month, day, or time component is omitted from an interval, datetime, or duration value. date_time_replacements is specified as a series of numbers separated by a comma to represent, in this order, the year, month, day, hour, minute, or second. Components of date_time_replacements can be omitted only in the reverse order, seconds, minutes, hours, day, and month. If no substitute values are specified, the conversion is done using default values.

Defaults:

The following are default values for omitted date and time components:

month	1
day	1
hour	0
minute	0
second	0

Requirements:

A year component must be part of the datetime or duration value, and therefore is not valid in date_time_replacements. A comma is required as a placeholder for the year in date_time_replacements. For example, in the replacement value string, ,9,4,,2,', the first comma is a placeholder for a year value.

Examples

This DATA step uses the ISO8601_CONVERT function to do the following:

create an interval by using datetime and duration values
create datetime and duration values from an interval that was created using the CALL IS8601_CONVERT routine
create an interval from datetime and duration values, using replacement values for omitted date and time components in the datetime value

For easier reading, numeric variables end with an N and character variables end with a C.

data _null_;

   /**  declare variable length and type                         **/
   /** 	Character datetime and duration values must be at least  **/
   /**  16 characters. In order not to lose precision, the      **/
   /**  numeric datetime value has a length of 8.                **/

   length dtN duN 8 dtC duC $16 intervalC $32;

   /** assign a numeric datetime value and a      **/
   /** character duration value.                  **/

   dtN='15Sep2008:09:00:00'dt;
   duC=input('P2y3m4dT5h6m7s', $n8601b.);
   put dtN=;
   put duC=;

   /** Create an interval from a datetime and duration value   **/
   /** and format it using the ISO 8601 extended notation for  **/
   /** character values.                                       **/

   call is8601_convert('dt/du', 'intvl', dtN, duC, intervalC);

   put '**  Character interval created from datetime and duration values **/';
   put intervalC $n8601e.;
   put ' ';

   /** Create numeric datetime and duration values from an interval    **/
   /** and format it using the ISO 8601 extended notation for          **/
   /** numeric values.                                                 **/
   
   call is8601_convert('intvl', 'dt/du', intervalC, dtN, duN);

   put '**  Character datetime and duration created from an interval  **/';
   put dtN=;
   put duN=;
   put ' ';

   /** assign a new datetime value with omitted components              **/

   dtC=input('2009---15T10:-:-', $n8601b.);

   put '** This datetime is a character value. **';
   put dtC $n8601h.;
   put ' ';

   /** Create an interval by reading in a datetime value       **/
   /** with omitted date and time components.  Use replacement **/
   /** values for the month, minutes, and seconds.             **/

 
   call is8601_convert('du/dt', 'intvl', duC, dtC, intervalC,,7,,,35,45);

   put '**  Interval created using a datetime with omitted values,      **';
   put '**  inserting replacement values for month (7), minute (35)     **';
   put '**  seconds (45).                                               **';
   put intervalC $n8601e.;
   put ' ';

run;

The following output appears in the SAS log:

dtN=1537088400
duC=0002304050607FFC
**  Character interval created from datetime and duration values **/
2008-09-15T09:00:00.000/P2Y3M4DT5H6M7S

**  Character datetime and duration created from an interval  **/
dtN=1537088400
duN=71211967

** This datetime is a character value. **
2009---15T10:-:-

**  Interval created using a datetime with omitted values,      **
**  inserting replacement values for month (7), minute (35)     **
**  seconds (45).                                               **

P2Y3M4DT5H6M7S/2009-07-15T10:35:45
NOTE: DATA statement used (Total process time):
      real time           0.04 seconds
      cpu time            0.03 seconds

Top of Page

CALL IS8601_CONVERT Routine

Syntax

Arguments