NEW DATE INTRINSICS FOR MPE/iX
==============================
This is a preliminary draft document proposing the new date intrinsics
in MPE/iX. These intrinsics are targeted to support both existing as
well as ISO 8601 date formats.
We first take a look at the various categories of intrinsics required
and propose some `Standard date formats'. Later in the document, we
follow this up with the description of the proposed intrinsics, with
examples. Your input on the items presented in the discussion section
at the end of the document would be highly appreciated.
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.
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
40 ASCII variable User desired format --- ---
(e.g., "YYYY-MM-DD")
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.
The date type 40, represents the date according to the format
specification string, whose format is:
[{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
Thus, `YYYY.MON.DAY', `YY/MM/DD', 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.
U16 * U16 * U16A
HPDATECONVERT(inputcode,inputdate,outputcode,outputdate,error)
PARAMETERS
inputcode It is 16 bit unsigned integer passed
by value its value should be one of
the date type codes listed in TABLE 1,
except the value `40'. 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 16-bit unsigned integer
passed by value and its value should
be one of the date type codes listed
in TABLE 1. When the code for the
output date is `40', the output would
be formatted as per the contents of
the format specification provided in
the `outputdate' character string.
outputdate Returns the date as per the format
chosen by the `outputcode' parameter.
The type of this variable depends
`outputcode' parameter. When the
`outputcode' is `40', this parameter
would carry a format specification.
Format specification is a character
string literal representing the format
of the output date. The syntax is
explained 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
=======
{ This is how you might include the date intrinsics }
$sysintr 'dateintr.pub.sys'$
Program test(input,output);
VAR
date1, temp_date : integer;
date2_str : packed array [1..20] of char;
print_str : packed array [1..20] of char;
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);
{ Let us use the flexibility in converting the date to
a string. }
print_str := 'YY.ZMM.ZDD';
HPDATECONVERT(15,date1_15,40,print_str,error);
{ Check error appropriately. }
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.
DISCUSSION
==========
* Would the proposed intrinsics meet your requirements to a large
extent?
* While converting the dates from one format to another, when the
destination format supports a four digit/four field year, what
should be the century portion of the converted date? Should it be
zeros or should it use the proposed HPYYYY CI variable?
* Is an intrinsic routine, HPDATECOMPARE, to compare two dates
required? Such an intrinsic compares two dates in one of the
standard formats described above. It would report their
relationship (less than, equal, or greater).
With the currently proposed intrinsics, two dates can be compared
by following the following steps. (Assumption: Dates to be
compared are in the same standard format.)
1. Convert the first date to standard format `18' through
HPDATECONVERT.
2. Convert the second date to standard format `18' through
HPDATECONVERT.
3. Subtract the converted second date from the converted first
date. The result would be:
0 if the dates are the same.
+ve if the first date is later compared to the second one
-ve if the second date is later compared to the first one
* How useful would it be to have an intrinsic to check the validity
of a given date with respect to one of the Standard Date Formats?
--
With Best Regards,
Kishore,
CSY R&D India.
mailto:[log in to unmask]
|
