Epoch Conversion (E)

 Top  Previous  Next

 

Epoch values represent a moment in time in a time zone independent manner. They are stored as a number of seconds since 1 January 1970 GMT (more correctly UTC).

 

The epoch conversion code converts an epoch value from its internal day number to one of a number of external formats or vice versa.

 

The full format of this conversion code is an extension of the D date conversion code:

 

E {U} {y} {c} {fmt} {[f1, f2, f3, f4, f5, f6, f7]}

 

where

 

UIgnores the current time zone setting and converts to UTC.

 

yis a digit in the range 0 to 4 specifying the number of digits to appear in the year number. This defaults to 4.

 

cis the character to be used to separate the year, month and day components of the converted date. If omitted, a space is used. Specifying c as the digit 0 suppresses insertion of a separator between the year, month and day components.

 

fmtspecifies the components to be present in the converted date. Multiple characters may be chosen from the following list subject to restrictions shown below. If fmt is omitted it defaults to MDY if American date mode is in use or DMY if European date mode is in use.
AASCII format date/time (e.g. Thu 16 Apr 15:02:21 2009). No other elements may be included in the same conversion.
DDay of month.
DOOrdinal day of month (1st, 2nd, 3rd, etc)
EToggles European date format (day, month, year). See also DATE.FORMAT.
JJulian date (days since the start of the year).
LAlphabetic month and day names are to appear with only the first character in uppercase instead of entirely in uppercase.
MMonth in format determined by format modifiers. If no format modifiers are present, a two digit month number is used unless c is present in which case a three letter alphabetic month is used.
MAMonth name.
MBBrief month name.
O{:}Offset from GMT in the form +hh:mm or -hh:mm. The colon separator is only present if included in the code.
QQuarter number (1 to 4).
T{H}{S}{s}Time. The H, S and s elements are as for the MT conversion code, specifying 12 hour clock format, inclusion of seconds, and an alternative separator for the components of the time value.
WDay of week number. Monday is day 1.
WAWeekday name.
WBBrief weekday name.
WIISO week number.
XANSI X12 format date (YYYYMMDD with no separators).
YYear.
YIISO year number. This is not always the same as the calendar year as a date may be in the last week of the previous ISO year or in the first week of the following ISO year.
ZTime zone code

 

 

[f1,f2,f3,f4,f5,f6,f7]These format modifiers affect the way in which the above formats are handled. Up to seven modifiers may be specified and they are associated with the formats in the order in which they appear in fmt. Format modifiers are
nUse n characters.
ADisplay as alphabetic (applies to month component only).
AnDisplay as n alphabetic characters (applies to month component only).
ZSuppress leading zeros.
ZnDisplay as n digits with leading zeros replaced by spaces.
"text"Uses the supplied text as the separator after the associated component.
n"text"Use n characters and then use the supplied text as the separator after the associated component.

 

The following special codes are recognised as part of the E conversion code for ISO8601 format output. These may not be used with any other conversion elements:

 

ISO8601WyyyyWwwd

Four digit year number, two digit ISO week number, one digit day of week.

 

ISO8601W-yyyy-Www-d

Four digit year number, two digit ISO week number, one digit day of week with hyphen separators.

 

ISO8601TyyyymmddThhmmss

Four digit year number, two digit month number, two digit day number, two digit hours, two digit minutes, two digit seconds.

 

ISO8601T-yyyy-mm-ddThh:mm:ss

Four digit year number, two digit month number, two digit day number, two digit hours, two digit minutes, two digit seconds with separators.

 

 

Time Zones

 

Conversion of an epoch value to an external form date and time is dependent on the time zone for which the conversion is performed. On entry to QM, the time zone to be used is taken from the operating system TZ environment variable for the user's process. If this has not been set, the value of the TZ variable when QM was started is used. If this is also not set, GMT is used.

 

The time zone name is stored in a private configuration parameter named TIMEZONE. This can be modified from, for example,  the LOGIN paragraph, using the CONFIG command or from within a program using the QMBasic SET.TIMEZONE statement.

 

 

Output Conversion of Epoch Values

 

The following examples show the result of output conversion of a value of 1234567890 in time zone EST with various conversion codes. Where affected by DATE.FORMAT setting, both forms are shown.

 

Code

Result

European date

'E'

13 FEB 2009

 

'E2'

13 FEB 09

 

'E4'

13 FEB 2009

 

'ET'

18:31

 

'E/'

02/13/2009

13/02/2009

'E '

02 13 2009

13 02 2009

'E2/'

02/13/09

13/02/09

'E/E'

13/02/2009

02/13/2009

'E2 E'

13 02 09

02 13 09

'E.YJ'

2009.44

 

'E2:JY'

44:09

 

'E YMD'

2009 02 13

 

'E YMDTS'

2009 02 13 18:31:30

 

'EX'

20090213

 

'E MY[A,2]'

FEBRUARY 09

 

'E4DOMAYL'

13th February 2009

 

'E4DOMAYLTS[,A3]'

13th Feb 2009 18:31:30

 

'E DMY[,A3,2]'

13 FEB 09

 

'E DMY[,A9,2]'

13 FEBRUARY  09

 

'E/MDY[Z,Z,2]'

2/13/09

 

'E DMYL[,A,]'

13 February 2009

 

'EDMYL[Z,A,2]'

13 February 09

 

'EYMD[2,2,2]'

09 02 13

 

'EW'

5

 

'EWA'

FRIDAY

 

'EWAL'

Friday

 

'EMA'

FEBRUARY

 

'EMAL'

February

 

'EQ'

1

 

'E-YIWI'

2009-07

'EA'

Fri Feb 13 18:31:30 2009

'EWALMALDTSZY[A3,A3]'

Fri Feb 13 18:31:30 EST 2009

'EWADMYTSZL[3", ",,A3]'

Fri, 13 Feb 2009 18:31:30 EST

'EISO8601W'

2009W075

'EISO8601W-'

2009-W07-5

'EISO8601T'

20090213T183130

'EISO8601T-'

2009-02-13T18:31:30

 

 

 

Input Conversion of Epoch Values

 

Input conversion with the E code is much more restricted than the range of formats possible on output conversion. In practical use of the epoch date system, it is likely that the date and time are entered as separate items. In this case, it may be more flexible to use the D and MT conversions on the two components separately and then use the MVEPOCH() function to convert these to an epoch value.

 

The input data must always consist of a date followed by a time. The date must contain all three elements (day, month, year).

 

The simplest E conversion is just the letter E. This may be followed by the D, M and Y elements to override the default sequence of the date components. Use of a trailing T to represent the time is valid for consistency but is otherwise ignored as it must be the last element in the data to be converted. Use of any other conversion code elements may have unspecified effects.

 

There is some flexibility to the order in which the components of the date may occur in the input data. Where an alphabetic month name is used, this is processed first and must be at least three characters. Numeric components are then assumed to be in the order of the remaining elements of the conversion code. Thus with a code of EDMY, '1 Jun 94' and 'Jun 1 94' would both be treated as 1 June 1994.

 

For dates entered as two digits, year number values in the range 30 to 99 are assumed to be 1930 to 1999 and 0 to 29 are assumed to be 2000 to 2029. This 100 year window can be moved using the YEARBASE configuration parameter. and the order of these defaults to day.

 

The time must be entered in the form hh:mm:ss or hh:mm where the colon may be any non-numeric character. If the seconds are omitted, a default of zero is used.

 

 

See also:

Date, Times and Epoch Values, EPOCH(), MVDATE(), MVDATE.TIME(), MVEPOCH(), MVTIME(), SET.TIMEZONE