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 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_DateChg	Add some days to datetime	Yes
$Sir_DateChk	Check if datetime matches format	Yes
$Sir_DateCnv	Convert datetime to different format	Yes
$Sir_DateDif	Calculate difference between two dates	Yes
"Sir_Datexxx" functions
$Sir_Date	Get current datetime	No
$Sir_DateFmt	Validate datetime format	No
$Sir_DateN/ND/NM/NS	Current date and time as integer	No
$Sir_Date2N/ND/NM/NS	Convert datetime string to integer	No
$Sir_ND2Date/NM2Date/NS2Date/N2Date	Convert 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

• Sir2000 User Language Tools
• The Sir2000 APPDATE command
• Sir2000 User Language Tools $functions
• Sir2000 datetime processing considerations
• Assembler language subroutines for FUNU