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

CALL IS8601_CONVERT( convert-from, convert-to, <from-variables> , <to-variables>,
<date-time-replacements>

Required Arguments

convert-from

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.

Optional Arguments

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.

Requirements	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 that is returned from invoking the CALL ISO8601_CONVERT routine.
	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.
	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 a character variable that is 16-bytes in length or greater.
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.

Default

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

1	month
1	day
0	hour
0	minute
0	second

Requirement

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.

Example

This DATA step uses the ISO8601_CONVERT function to perform the following tasks:

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