This is the revised proposal for the new date intrinsics. The changes
from the previous version include:
* Adding a new intrinsic HPDATEFORMAT to support conversion of
dates to user defined formats (earlier date type 40).
* Removal of date type `40' from the Standard formats.
* Addition of HPDATEVALIDATE intrinsic.
* HPDATECONVERT would choose century based on YY:Split method,
while converting two-digit years to four-digit years (i.e.,
00..49 = 2000-2049 and 50..99 = 1950-1999).
The `error' parameter for the intrinsics is compatible with the 32-bit
`hpe_status' type.
We welcome a discussion on this revised proposal.
PROPOSAL
========
The proposed date intrinsics can be broadly categorized as:
1 intrinsic returning the dates a chosen standard format.
2 Conversion of dates from one standard format to another.
3 Intrinsics to perform arithmetic operations like
adding/subtracting two given dates.
4 Adding/subtracting an offset (days) to/from the given date.
5 Validating the given date for conformance to a standard date
format.
Standard Formats
================
The various date types used in MPE/iX are presented in the table below.
The `Sorted' and `Y2K ready' fields answer the following two questions:
1. Can the dates be sorted as they are?
2. Can the format be used to represent dates in 21st century?
Table 1: Date types
====================
Date
Type Storage
Code Type #Bytes Explanation Sorted? Y2K
ready?
----- ------- ------ ----------------------------------- -------
----------
1 longint 8 MPE time-stamp (microseconds yes yes
since
1970-01-01)
2 integer 4 Upper 2 bytes: year yes yes
next byte: month of year
bottom byte: day of month
3 integer 4 Upper 2 bytes: year yes yes
bottom 2 bytes: day of year
4 integer 4 Upper 23 bits: year yes yes
bottom 9 bits: day of the year.
(analogous to the existing
CALENDAR format.)
10 integer 4 POSIX time-stamp (seconds since yes no
1970-01-01)
14 shortint 2 yyddd (as defined by the yes no
CALENDAR intrinsic)
15 integer 4 YYMMDD date yes no
16 integer 4 MMDDYY date no no
17 integer 4 DDMMYY date no no
18 integer 4 YYYYMMDD date yes yes
25 ASCII 6 YYMMDD date yes no
26 ASCII 6 MMDDYY date no no
27 ASCII 6 DDMMYY date no no
35 ASCII 6 YYMMDD date YY:MM3000 date yes yes
36 ASCII 6 MMDDYY date YY:MM3000 date no no
37 ASCII 6 DDMMYY date YY:MM3000 date no no
38 ASCII 8 YYYYMMDD date yes yes
Notes:
"integer" and "longint" are binary values.
"ASCII" means ASCII character code.
Most of the standard date types are naturally sorted. This
means that if they are viewed as sequence of ASCII bytes, and
arranged in ascending alphabetic order, they are also in
ascending chronological order. An example of this kind of date
is YYMMDD dates.
User Desired Formats
====================
User desired formats (with restrictions) are allowed. The format
specification strings can have the following syntax:
[{FormatElement}{Punctuation}]+
The valid `FormatElement's are:
CC Century (00 to 99)
YYYY Year (0000 to 9999)
YY Year of century (00 to 99)
ZYY Year of century with leading
zeros suppressed(0 to 99).
Q Quarter of the year (1 to 4)
MM Month of the Year (00 to 12).
ZMM Month of the Year with leading
zeros suppressed (0 to 12).
DD Day of the Month (01 to 31).
ZDD Day of the Month with leading
zeros suppressed (1 to 31).
DDD Day of the Year (000 to 366).
ZDDD DDD with leading zeros
suppressed (1 to 366).
D Day of the week (1 to 7).
WW Week of the year (01 to 53).
ZWW Week of the year with leading
zeros suppressed (1 to 53).
MON Month of the year in ASCII
format (ex., Jan, Feb, etc.).
DAY Day of the week in ASCII
format (ex., Sun, Mon, etc.).
Valid `Punctuation' characters are :
`-' Hyphen
`/' Slash
`.' Dot
` ' Blank
`,' Comma
`' Null
Thus, `YYYY.MON.DAY', `YY/MM/DD', `DDMONYY', and `DD-ZMM-YYYY'
are valid date formats.
Description of New Proposed Intrinsics
======================================
HPCALENDAR
==========
The new HPCALENDAR intrinsic returns the date in the standard date
format 4 listed in Table 1.
SYNTAX
U32
date := HPCALENDAR ;
The upper 23 bits of the returned value represent the year relative to
the year 1900, and it is a signed 23 bit integer. The lower 9 bits
represent the day of the year as an unsigned 9 bit integer.
HPDATECONVERT
=============
This intrinsic would convert the dates from one standard format to
another. While converting dates with two digit year formats to those
with four digit year formats, the century portion would be `19' if the
year portion is >= 50. It would be `20' otherwise.
U32 * U32 * U16A
HPDATECONVERT(inputcode,inputdate,outputcode,outputdate,error)
PARAMETERS
inputcode It is 32 bit unsigned integer passed
by value. Its value should be one of
the date type codes listed in TABLE 1.
This is an input parameter.
inputdate The type of this variable depends on
`inputcode' parameter. the data types
for different input codes are listed
in Table listed in TABLE 1. This is
an input parameter.
outputcode This is a 32-bit unsigned integer
passed by value and its value should
be one of the date type codes listed
in TABLE 1.
outputdate Returns the date as per the format
chosen by the `outputcode' parameter.
The type of this variable depends
`outputcode' parameter.
error 16-bit unsigned integer array. The
first element is the error number; the
second element is reserved and always
returns 0.
HPDATEFORMAT
============
This routine can be used to format the dates in ISO8601 format and
variants of it. The syntax is:
S32 CA CA U32 U16A
HPDATEFORMAT(date,formatspec,fmtdate,fmtdatelen,error)
PARAMETERS
date This is an integer parameter passed by
value. It holds the date to be
formatted as per `formatspec'. This
date should be in the format `18'
specified in Table 1.
formatspec This is a character array passed by
value. It should contain a string as
per the syntax in the section ``User
Desired Formats''. (ex.,
"YYYY-ZMM-DD&"). A non alpha numeric
and non punctuation character is
treated as the end of format
specification (the Character `&' in
this example).
fmtdate This is a character array passed by
reference. Its size should be at
least `formatlen'. On return, it
would contain the `date' formatted as
per the `formatspec'.
fmtdatelen This is an unsigned integer passed by
reference. On return, it would
contain the number of characters in
`fmtdate' that are filled-in by the
intrinsic.
error 16-bit unsigned integer array. The
first element is the error number; the
second element is reserved and always
returns 0.
Example
=======
{ This is how you might include the date intrinsics }
$sysintr 'sysintr.pub.sys'$ { date intrinsics would be in `sysintr' itself}
Program test(input,output);
VAR
date1, temp_date : integer;
date2_str : packed array [1..20] of char;
fmt_str : packed array [1..20] of char;
print_str : packed array [1..20] of char;
fmt_len,prt_len : integer;
error : packed array [1..2] of bit16;
date1_15,
date2_15 : integer;
begin
date2_str := '960121'; { The YYMMDD date in Standard format `25'. }
date1 := 230196; { The DDMMYY date in standard format `17'. }
{ Convert `date1' to the YYMMDD integer format.}
HPDATECONVERT(17,date1,15,date1_15,error);
{ Check the `error' appropriately. }
{ Convert the `date2_str' to a YYMMDD integer format.}
HPDATECONVERT(25,date2_str,15,date2_15,error);
{ Check the `error' appropriately. }
{ Let us compare the two dates now.}
temp_date := date1_15 - date2_15;
if( temp_date < 0) then
writeln(date2_str,' is later compared to',date1)
else if (temp_date > 0) then
writeln(date1,' is later compared to',date2_str)
else
writeln(date1,' is same as ',date2_str);
HPDATECONVERT(15,date2_15,18,date2_18,error);
{ Let us use the flexibility in converting the date to
a string. }
fmt_str := 'YY.ZMM.ZDD%'; { `%' is the End of string. }
HPDATEFORMAT(date2_18,fmt_str,print_str,print_len,error);
{ Check error appropriately. }
{ print_len would be:7 }
writeln('The converted date is: ',print_str);
{The example is done.}
end.
The expected output from the program is:
230196 is later compared to 960121
The converted date is : 96.1.23
HPDATEADD
=========
This intrinsic performs the operation of adding/subtracting dates.
The input parameters should be in date format `18'. The output would
also be in the same format.
SYNTAX
S32 S32 S32 U16A
HPDATEADD(inputdate,datetoadd,outputdate,error)
PARAMETERS
inputdate The input date is a signed integer and
should be in the format `18' specified
in TABLE 1.
datetoadd The date to be added to the
`inputdate'. This parameter is a
signed integer and should be in the
format `18' specified in TABLE 1. If
this date is a positive value, an
addition operation is performed. A
negative date to add would result in
that date being subtracted from the
`inputdate'.
outputdate The result of the date addition
operation. Its format is same as
the `inputdate'.
error 16-bit unsigned integer array. The
first element is the error number; the
second element is reserved and always
returns 0.
Example
=======
{ To add. }
date1 := 19960120; { 20 Jan 1996 }
date_to_add := 10120; { 1 Year 1 month and twenty days. }
HPDATEADD(date1,date_to_add,result1,error);
{ `result1' will be: 19970312 (for 12 March 1996). }
{ To subtract. }
date1 := 19960120;
date_to_sub := -10010; { 1 Year and ten days. (note the -ve sign) }
HPDATEADD(date1,date_to_sub,result2,error);
{ `result2' will be : 19950110 (for 10 Jan 1995). }
HPDATEOFFSET
============
This intrinsic can be used to add/subtract a specified offset to/from
the given date.
SYNTAX
S32 S32 S32 U16A
HPDATEOFFSET(inputdate,offset,outputdate,error)
PARAMETERS
inputdate The input date is a signed integer and
should be in the format `18' specified
in TABLE 1.
offset A signed integer parameter carrying
the number of days to be added to the
input date. A negative value would
result in a subtraction.
outputdate The result of the date addition
operation. It would be in the format
`18' specified in Table 1.
error 16-bit unsigned integer array. The
first element is the error number; the
second element is reserved and always
returns 0.
Example
=======
{ Adding offset. }
date1 := 19960101; { 01 Jan 1996 }
offset := 60; { 60 days. }
HPDATEOFFSET(date1,offset,result1,error);
{ Month of Feb has 29 days in 1996. }
{ The result would be: 19960301 (01 March 1996) }
{ Subtracting offset. }
date1 := 19960121; { 21 Jan 1996 }
offset := -45; { What is the date 45 days earlier. }
HPDATEOFFSET(date1,offset,result2,error);
{ `result2' would be : 19951207 (7 Dec 1994) }
HPFMTCALENDAR
=============
This a new routine to handle HPCALENDAR format. It does the same job
as FMTCALENDAR except that it accepts the 32-bit integer returned by
HPCALENDAR intrinsic. The syntax is:
SYNTAX
U32 CA
HPFMTCALENDAR(date,formatdate)
PARAMETERS
date This is an unsigned integer parameter
passed by value. It holds the
calendar date, in the same format as
the HPCALENDAR intrinsic.
formatdate Returns the formatted calendar date in
a 17-character array. If the day of
the month is less than 10, a blank
precedes it, for example,
FRI, JAN 6, 1989
HPNLFMTCALENDAR
===============
This is a new routine to handle HPCALENDAR format. This intrinsic
would be same as the NLFMTCALENDAR except that it accepts the 32-bit
integer returned by the HPCALENDAR intrinsic.
HPNLFMTLONGCAL
==============
This is a new routine to handle HPCALENDAR format. This intrinsic
would be same as the NLFMTLONGCAL except that it accepts the 32-bit
integer returned by the HPCALENDAR intrinsic.
HPDATEVALIDATE
==============
This procedure can be used to check the validity of the given date
with respect to the standard formats given in Table 1.
S32 U32 *
result := HPDATEVALIDATE(inputcode,inputdate)
PARAMETERS
inputcode It is 32 bit unsigned integer passed
by value. Its value should be one of
the date type codes listed in TABLE 1.
This is an input parameter.
inputdate The type of this variable depends on
`inputcode' parameter. the data types
for different input codes are listed
in Table listed in TABLE 1. This is
an input parameter.
result This is a signed integer returned.
Its value would be `0' if the
`inputdate' conforms to the date
format represented by `inputcode'. If
it is not so, its value would be
positive. If an error has occurred in
evaluating the conformance, its value
would be negative.
Example
=======
var
date1 : packed array [1..20] of char;
poor_date : integer;
result : integer;
date1 := "19961205";
result := HPDATEVALIDATE(38,date1); { result would be `0'. }
date1 := "961205";
result := HPDATEVALIDATE(38,date1); { result would be +ve. (invalid!)}
result := HPDATEVALIDATE(38,poor_date);{ result would be -ve. (error!)}
--
With Best Regards,
Kishore,
CSY R&D India.
mailto:[log in to unmask]
|
