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
IGNOREorREPORTspecified or defaulted.