Admin: 1 revision imported

2018-02-08T22:00:52Z

1 revision imported

← Older revision	Revision as of 22:00, 8 February 2018
(No difference)

JAL: remove detailed function descriptions

2018-02-08T21:51:53Z

remove detailed function descriptions

New page

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 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 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_Datexxx" 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_Datexxx 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_Datexxx 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.

For example, since the input date doesn't match the provided format, the following
fragment prints <code>Error incrementing date</code>:

%NEW_DT = $SIR_DATECHG('MM/DD/YY', '96/01/01', 7,, 'IGNORE')
IF %NEW_DT EQ '' OR $SUBSTR(%NEW_DT, 1, 1) = '*' THEN
PRINT 'Error incrementing date'
END IF 

The following fragment causes the request to be cancelled: 
%NEW_DT = $SIR_DATECHG('MM/DD/YY', '96/01/01',7,, 'CANCEL') 

The cancellation comes with an error message: 
 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 

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: 
 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 

Each $function description on this page includes: 
<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]]

Sir2000 User Language Tools $functions - Revision history

Admin: 1 revision imported

JAL: remove detailed function descriptions