View source for Sir2000 datetime processing considerations

==Introduction==
This page presents date processing issues, including usage of the Sir2000 User
Language Tools past the year 1999, an explanation of its processing of dates, and any
rules and restrictions you must follow to achieve correct results using date values with the Sir2000 User Language Tools.

===Sir2000 User Language Tools dates===
The Sir2000 User Language Tools uses dates in the following ways:
<ul>
<li>To examine the CPU clock (as returned by the STCK hardware instruction) to
determine the current date, in case the Sir2000 User Language Tools is under a
rental or trial agreement. </li>

<li>As arguments to various $functions, and as returned values from them. </li>

<li>To set a date for testing with the <var>APPDATE</var> command. </li>

<li>See [[SirLib]] and [[SirPro]] for date processing considerations for those products as part of the Sir2000 User Language Tools. </li>
</ul>

===Two views of datetime $functions===
<p>
This page refers to datetime $functions in two product groups: </p>
<ul>
<li>The [[SOUL $functions#datetime|$Sir_Date<i>xxx</i> $functions]]
<p>
These date $functions are available to users of multiple Model&nbsp;204 add-on products, as well as to Sir2000 User Language Tools users. </p></li>

<li>The [[Sir2000 User Language Tools $functions]]
<p>
These $functions are available only to users of the Sir2000 User Language Tools. </p></li>
</ul>
<p>
In <i>operational</i> terms, there are two classes of datetime $functions: </p>
<ul>
<li>$functions using a numeric value to represent a datetime, where 0 represents
<code>12:00 AM, 1 January 1900</code>; for example, <var>[[$Sir_Date2NM]]</var> and <var>[[$Sir_NM2Date]]</var> (number of milliseconds since the start of 1900).
<p>
These $functions, and <var>[[$Sir_Date]]</var>, have the following error return values: </p>
<ul>
<li>-9.E12 for numeric result $functions </li>

<li>null string for string result $functions </li>
</ul>
<p>
They also perform non-strict matching of date strings to date formats. For example,
a leading blank is allowed for the <var>HH</var> token. </p>
<p>
All numeric datetime $functions, and <var>$Sir_Date</var>, are part of the <var class="product">[[Sirius Functions]]</var>. </p></li>

<li>Other $functions that only manipulate strings and associated datetime formats
(<var>$Sir_Date</var> not included in this class); for example, <var>[[$Sir_DateChg]]</var> (add number of days to given date).
<p>
These $functions have error return values of a variable number of asterisks (or, in
the case of <var>[[$Sir_DateDif]]</var>, the value 99,999,999). They also perform strict matching of date strings to date formats; for example, a leading blank is not allowed for the <var>HH</var> token. These $functions produce the same results as standard SOUL [[SOUL $functions#datex|$Date<i>xxx</i> functions]], with additional enhancements. </p>
<p>
These string-format datetime $functions are available only with the Sir2000 User
Language Tools. </p>
<p>
See [[#Strict and non-strict format matching|Strict and non-strict format matching]] for a discussion of strict and non-strict format matching, including a technique for accomplishing strict date checking using the non-strict $functions. </p></li>
</ul>
<p>
See [[Sir2000 User Language Tools $functions#Errors in datetime $functions|Errors in datetime $functions]] for information about error handling for datetime $functions. </p>

==Datetime formats==
The string representation of a date is determined by a <b>datetime format</b>.
This value is a character string, composed of the concatenation of these:
<ul>
<li>Tokens 
<p>
For example, <var>YYYY</var> for a four-digit year, and <var>MI</var> for
minutes.</p></li>

<li>Separator characters
<p>
For example, forward slash (<tt>/</tt>) in <var>MM/DD/YY</var> for two-digit month, day, and year separated by slashes.</p></li>
</ul>
<p>
These datetime format strings are used in several Rocket Model&nbsp;204 add-on products in addition to <var class="product">Sir2000</var>.
The additional products using datetime format strings are: </p>
<ul>
<li><var class="product">[[Fast/Unload]]</var> </li>

<li><var class="product">[[Media:JoclrNew.pdf|Janus Open Client]]</var> </li>

<li><var class="product">[[Media:JosrvrNew.pdf|Janus Open Server]]</var>
</li>

<li><var class="product">[[Media:JsdsrNew.pdf|Janus Specialty Data Store]]</var> </li>

<li><var class="product">[[Janus Web Server]]</var> </li>

<li><var class="product">[[SirDBA]]</var> </li>

<li><var class="product">[[Sirius Functions]]</var> </li>

<li><var class="product">[[Media:SirfieldNew.pdf|Sir2000 Field Migration Facility]]</var> </li>
</ul>
<!-- Note: all the above products imbed the SCRIPT file COMDATE except Janus Web -->
<p>
The rules for these datetime format strings are consistent throughout all these products, though certain uses of these strings might impose extra restrictions.
For example, a leading blank is allowed for the <var>HH</var>, <var>DD</var>, and <var>MM</var> parts of a date argument using a non-strict date $function (such as
<var>[[$Sir_Date2NS]]</var>), but such a blank is not allowed for the strict date $functions ([[Sir2000 User Language Tools $functions]]). </p>
{{Template:Datetime rules, tokens, and separators}}

==Valid datetimes==
For a datetime string to be valid it must meet the following criteria:
<ul>
<li>Its length must be less than 128 characters. </li>

<li>It must be compatible with its corresponding format string. </li>

<li>It must represent a valid date and/or time. 
<p>
For example, at most <code>23:59:59.999</code> for a time, <code>01-12</code> for a month, <code>01-31</code> or less (depending on the month) for a day. February 29 is only valid
in leap years (only centuries divisible by 4 are leap years: 2000 is but neither 1800, 1900, nor 2100 are). 
</p>
<p class="note"><b>Note:</b> Weekdays are not checked for consistency against the date. For example, both <code>Saturday, 02/15/97</code> and <code>Friday, 02/15/97</code> are valid. </p> </li>

<li>It must be within the date range allowed for the corresponding format.
<p>
A datetime string used with a <var>CYY</var> or <var>ZYY</var> format can only represent dates from 1900 to 2899, inclusive.
A datetime string used with a <var>YY</var> format can only represent
dates in a range of 100 or less years, as determined by <var>CENTSPAN</var> and
<var>SPANSIZE</var> (described below).
The valid range of dates for all other formats is from <code>1 January 1753</code>
thru <code>31 December 9999</code>. </p></li>
</ul>

==Processing dates with two-digit year values==
{{Template:Processing dates with two-digit year values}}
 
==Strict and non-strict format matching==
As mentioned in [[#Datetime formats|Datetime formats]], for some of the $functions,
the input format rule for a token is the same as the output format rule.
This is the definition of "strict date format matching."
However, non-strict $functions sometimes allow a string to match a token on input that would not be produced by that token on output.
<p>
The types of strict matching are as follows: </p>
{{Template:Datetime format matching}}

The strict functions are available only with the <var class="product">Sir2000 User Language Tools</var>. If you want to use non-strict date $functions to check a datetime string using strict rules, you can use the following technique:
<p class="code">If <i>date</i> Eq &apos;' Or <i>date</i> NE $Sir_NM2Date(-
   $Sir_Date2NM(<i>date</i>, <i>fmt</i>), <i>fmt</i>) Then
   <i>error handling</i>
End If
</p>

==Datetime and format examples==
There is an extensive set of format tokens, as shown in [[#Datetime format tokens|Datetime format tokens]]. These tokens and the various separator characters
can be combined in almost limitless possibility, giving rise to an extremely large set of datetime formats.
This section provides examples of some common datetime formats, and it
also tries to explain the use of some of the format tokens that might not be obvious.
<p>
This section also has examples for
formats used with <var class="product">Sir2000 Use Language Tools</var> that differ from their usage with other <var class="product">Model&nbsp;204</var> products.
These are noted in the examples. </p>
<p>
Each example format is explained and is also presented with some matching
datetimes, demonstrating only a few of the very many ways these tokens can be combined. It is assumed that these examples are invoked sometime between the
years 1998-2040, as the basis for relative <var>CENTSPAN</var> calculations.
</p>
{{Template:Datetime and format examples}}

==CENTSPAN argument of $Sir_Datexxx functions==
<p>
Many of the $Sir_Date<i>xxx</i> functions accept an optional argument
containing a <var>CENTSPAN</var> value to be used for the call.
The default value of any <var>CENTSPAN</var> argument is <code>-50</code>, excepting the [[$Web_Date2D, $Web_Date2N, $Web_Date2ND, $Web_Date2NM, $Web_Date2NS|$Web_Date2<i>xx</i>]] functions without a format argument, in
which case the <var>CENTSPAN</var> argument is ignored and a <var>CENTSPAN</var> of <code>1990</code> is used. 
The default value should be adequate in most cases. If you carefully determine it should be different in some application, code the value on the relevant $function invocations.</p>
<p>
For a different approach, see the description of the <var>[[CENTSPLT parameter|CENTSPLT]]</var> and <var>[[DEFCENT parameter|DEFCENT]]</var> parameters and $function arguments.</p>

==Benefits of Sir2000 datetime processing==
<p>
Following is a list of benefits offered by <var class="product">Sir2000</var>
and $Sir_Date<i>xxx</i> datetime processing. To provide concrete comparisons, there
are some references to the standard <var class="product">SOUL</var> date $functions. </p>
{{Template:Benefits of $Sir Datexxx datetime processing}}
 
==See also==
{{Template:Sir2000 topic list}}

[[Category:Sir2000 User Language Tools]]