Sir2000 User Language Tools $functions

From m204wiki
Jump to navigation Jump to search

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

$Function Description Exclusive to
Sir2000 UL Tools?
$Sir_Date_Err Set and query default error handling at request level Yes
$Sir_DateChgAdd some days to datetime Yes
$Sir_DateChkCheck if datetime matches format Yes
$Sir_DateCnvConvert datetime to different format Yes
$Sir_DateDifCalculate difference between two dates Yes
"Sir_Datexxx" functions
$Sir_DateGet current datetime No
$Sir_DateFmtValidate datetime format No
$Sir_DateN/ND/NM/NSCurrent date and time as integer No
$Sir_Date2N/ND/NM/NSConvert datetime string to integer No
$Sir_ND2Date/NM2Date/NS2Date/N2DateConvert datetime integer to string No

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.

  • On a system-wide or thread-only basis, by using an APPDATE DATE_ERR command
  • On a request level, by using the $Sir_Date_Err function
  • In The $Sir_Datexxx and Sir2000 $function calls, by coding a special argument

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

If you intend to use the $function error handling features of Sir2000 User Language Tools, you should also be sure to use the DEBUG feature of APPDATE. The DEBUG 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 $Sir_Date_Err, if any, or the switches established by the relevant APPDATE command with DATE_ERR clause.

See 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 Error incrementing date:

%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 APPDATE DATE_ERR DEBUG 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:

  • The error conditions detected by the $function
  • The value returned by the $function in case of an error with IGNORE or REPORT specified or defaulted.

See also