View source for Sir2000 User Language Tools $functions

This section lists the $functions that are only available with the Sir2000 User Language Tools, as well as related $functions that are not exclusive to Sir2000 User Language Tools. In addition to a link to each $function's description page, the listing includes a brief phrase denoting its use.

The $function list is followed by a discussion of datetime error handling.

==Sir2000 UL Tools $functions==
The following $functions are provided with Sir2000 User Language Tools, some of which are also available to other Model&nbsp;204 products. Those $functions that are available only to the Sir2000 User Language Tools product are indicated as "exclusive."
<table>
<tr class="head"><th>$Function</th>
<th>Description</th>
<th>Exclusive to <br>Sir2000 UL Tools?</th></tr>

<tr><td>[[$Sir_Date_Err]]</td>
<td>Set and query default error handling at request level </td>
<td>Yes</td></tr>

<tr><td>[[$Sir_DateChg]]</td><td>Add some days to datetime </td>
<td>Yes</td></tr>

<tr><td>[[$Sir_DateChk]]</td><td>Check if datetime matches format </td>
<td>Yes</td></tr>

<tr><td>[[$Sir_DateCnv]]</td><td>Convert datetime to different format </td>
<td>Yes</td></tr>

<tr><td>[[$Sir_DateDif]]</td><td>Calculate difference between two dates </td>
<td>Yes</td></tr>

<tr class="head"><th colspan="3">"Sir_Date<i>xxx</i>" functions</th></tr>

<tr><td>[[$Sir_Date]]</td><td>Get current datetime </td>
<td>No</td></tr>

<tr><td>[[$Sir_DateFmt]]</td><td>Validate datetime format </td>
<td>No</td></tr>

<tr><td>[[$Sir_DateN|$Sir_DateN/ND/NM/NS]]</td><td>Current date and time as integer </td>
<td>No</td></tr>

<tr><td>[[$Sir_Date2N|$Sir_Date2N/ND/NM/NS]]</td><td>Convert datetime string to integer </td>
<td>No</td></tr>

<tr><td nowrap>[[$Sir_ND2Date|$Sir_ND2Date/NM2Date/NS2Date/N2Date]]</td><td>Convert datetime integer to string </td>
<td>No</td></tr>
 </table>

==Errors in datetime $functions==
Sir2000 User Language Tools provides you with several ways to detect datetime related errors and control the action taken by the system when these errors occur. 
<ul>
<li>On a system-wide or thread-only basis, by using an [[The Sir2000 APPDATE command#Error handling control with DATE_ERR|APPDATE DATE_ERR command]] </li>

<li>On a request level, by using the <var>[[$Sir_Date_Err]]</var> function </li>

<li>In The $Sir_Date<i>xxx</i> and Sir2000 $function calls, by coding a special argument </li>
</ul> 

You can also control error handling in some standard SOUL date $functions by using 
<code>APPDATE DATE_ERR</code> or <var>$Sir_Date_Err</var>.

If you intend to use the $function error handling features of Sir2000 User Language
Tools, you should also be sure to use the [[The Sir2000 APPDATE command#Setting default error handling with the APPDATE command|DEBUG feature of APPDATE]]. The <var>DEBUG</var> feature saves line number, procedure, and file information for date-related $functions.
This information, along with argument values, is then displayed and reported to greatly simplify debugging.

The $Sir_Date<i>xxx</i> and Sir2000 $functions provide an optional error control argument for some datetime $functions. If you omit the error control argument and an error is detected in the $function, the action taken depends upon the latest invocation of <var>$Sir_Date_Err</var>, if any, or the switches established by the relevant <var>APPDATE</var> command with <var>DATE_ERR</var> clause.

See [[The Sir2000 APPDATE command#Error handling control with DATE ERR|Error handling control with DATE_ERR]] for a complete description of
the type of errors encountered by date $functions, and for the control and detection approaches available to you with the Sir2000 User Language Tools.
<p>
For example, since the input date doesn't match the provided format, the following
fragment prints <code>Error incrementing date</code>:
</p>
<p class="code">%NEW_DT = $SIR_DATECHG('MM/DD/YY', '96/01/01', 7,, 'IGNORE')
IF %NEW_DT EQ &apos;&apos; OR $SUBSTR(%NEW_DT, 1, 1) = '*' THEN
PRINT 'Error incrementing date'
END IF </p>
<p>
The following fragment causes the request to be cancelled: </p>
<p class="code">%NEW_DT = $SIR_DATECHG('MM/DD/YY', '96/01/01',7,, 'CANCEL') </p>
<p>
The cancellation comes with an error message: </p>
<p class="output"> I DATERR
 *** 1 MSIR.0323: Error in $SIR_DATECHG call, no Sirius debug info
 - Invalid date
 *** MSIR.0326: $SIR_DATECHG - argument 1 = 'MM/DD/YY'
 *** MSIR.0326: $SIR_DATECHG - argument 2 = '96/01/01'
 *** MSIR.0326: $SIR_DATECHG - argument 3 = '7'
 *** MSIR.0326: $SIR_DATECHG - argument 5 = 'CANCEL'
 *** 2 CANCELLING REQUEST: MSIR.0324: Cancelling request because of
$SIR_DATECHG error </p>
<p>
If the <code>APPDATE DATE_ERR DEBUG</code> option is in effect, the SOUL procedure
name and line number will be reported, along with more detail about the error: </p>
<p class="output"> APPDATE USER DATE_ERR DEBUG
 I DATERR
 *** 1 MSIR.0321: Error in $SIR_DATECHG call in line 523, procedure
DATERR, file PROCFILE - Invalid date
 *** MSIR.0326: $SIR_DATECHG - argument 1 = 'MM/DD/YY'
 *** MSIR.0326: $SIR_DATECHG - argument 2 = '96/01/01'
 *** MSIR.0326: $SIR_DATECHG - argument 3 = '7'
 *** MSIR.0326: $SIR_DATECHG - argument 5 = 'CANCEL'
 *** 2 CANCELLING REQUEST: MSIR.0324: Cancelling request because of
$SIR_DATECHG error </p>
<p>
Each $function description on this page includes: </p>
<ul>
<li>The error conditions detected by the $function </li>

<li>The value returned by the $function in case of an error with <code>IGNORE</code> or <code>REPORT</code> specified or defaulted. </li>
</ul>

==See also==
{{Template:Sir2000 topic list}}

[[Category: Sir2000 User Language Tools]]