Sir2000 User Language Tools: Difference between revisions

Latest revision as of 22:00, 8 February 2018

Overview

The Sir2000 User Language Tools is a package of products designed to help you change and test User Language (SOUL) applications for correct operation across the millennium rollover. The package consists of several components that are described below.

The APPDATE command

The APPDATE command allows you to control the operation of date and time oriented User Language $functions.

Date $functions

Sir2000 User Language Tools includes $functions that manipulate datetime values, support improved datetime formats, while providing enhanced 2-digit year handling (CENTSPAN/SPANSIZE) and improved error handling. These $functions replace and/or augment some standard Model 204 date-related functions.

Datetime formats

The $functions included with the Sir2000 User Language Tools allow you to specify formats for datetime values that include all of the tokens and separator characters for any common application, including mixed case, variable length, and day of week. Date and time are handled uniformly, and there are no special $function names, special arguments, nor customization parameters to control the date formats.

To get the current date in a different format with the standard Model 204 date $functions, you must specify a special switch and/or use combinations of different $functions, frequently involving string concatenation or substring to deal with composite date and time formats.

With the Sir2000 date $functions, each function performs some datetime related calculation, and you can specify a combination of tokens to determine the format, which may include time of day. For example, the following SOUL code fragment is required to print the current day of the week using the standard $functions provided with Model 204:

PRINT $DAY($DAYI($DATECNV('CYY-MM-DD', 'CYYDDD', $DATE(2))))

With the Sir2000 User Language Tools, this set of nested $function calls becomes:

PRINT $SIR_DATE('Wkday')

You can also get the current date and time conveniently for a report:

%D STRING LEN 40 %D = $SIR_DATE('Wkday, DAY Month YYYY @ HH:MI:SS AM') SET HEADER 1 %D

This sets a line such as the following at the top of each page:

Monday, 1 January 2001 @ 01:11:10 PM

Processing two digit years (CENTSPAN/SPANSIZE)

The $functions included with the Sir2000 User Language Tools provide a robust technique for handling 2-digit years. An optional CENTSPAN argument supplies the beginning of year of the up to 100-year range of dates covered by the two-digit years.

CENTSPAN provides both of these:

An absolute specification, in which the full 4-digit start year is specified
A relative specification, in which the start year is specified relative to the current time, for example, 50 years ago

The default CENTSPAN value is -50.

To reduce the ambiguities caused by mapping two-digit years into four digit years, SPANSIZE is used to limit the number of years mapped. SPANSIZE and its relationship to CENTSPAN is explained in CENTSPAN. The default SPANSIZE is 90.

Error handling

The $Sir_Datexxx and Sir2000 datetime $functions that process user-provided datetime format strings or datetime values accept an optional last argument that is a character string specifying the action to be taken if the function detects an error. If this argument is omitted, the action taken upon an error is determined by the current state of the USER and SYSTEM switches of DATE_ERR. The DATE_ERR switches can be set by an APPDATE command with a DATE_ERR clause or by the $Sir_Date_Err function.

DATE_ERR allows the interception of date processing errors at their source, making it much easier to perform ad-hoc testing and validation of date processing. The following error actions can be specified:

CANCEL	If a datetime $function (including the non-Sirius functions) detects an error, an error message is produced describing the nature of the error and the current request is cancelled. Sirius datetime $functions produce detailed error messages describing the precise nature of the error.
REPORT	If a datetime $function detects an error, a warning message is produced describing the nature of the error, and the appropriate standard error value is returned by the $function.
IGNORE	If a datetime $function detects an error, the appropriate standard error value is returned by the $function.

The errors that are detected include:

Invalid datetime format specification
Datetime string not matching format
Datetime out of range for the format
Invalid CENTSPAN value
Datetime out of range for CENTSPAN/SPANSIZE combination.

In addition, an APPDATE command with a DATE_ERR clause can specify that warning and error messages should include the procedure name and line number of the failing $function.

Subroutines for FUNU

Included with the Sir2000 User Language Tools is a set of subroutines that can be invoked by user-provided assembler language (FUNU) $functions to obtain the current date and time using the appropriate APPDATE clock, if any. They are compatible with the similar set of subroutines Rocket Model 204 provides for current date only, with an additional entry point which allows you to obtain the current date and time using any of the Sirius datetime formats.

SirPro

SirPro provides a highly productive integrated environment for the development and maintenance of Model 204 applications. SirPro efficiently manages very large procedure files while providing high performance search and global replace features. SirPro also provides a full screen interface for commonly used Model 204 commands.

SirLib

SirLib is a comprehensive change management system for Model 204 SOUL applications. SirLib enables multiple programmers to simultaneously work on the same procedures, with tools for resolving update conflicts and backing out individual changes or projects. SirLib is modeled on the change control system used by IBM and virtually all large scale mainframe product developers. SirLib support is integrated within SirPro to minimize its intrusion into the development process.

Documentation topics

The Sir2000 User Language Tools documentation consists of the pages listed below. This list is also available as a "See also" link from each of the pages.

Also:

See MSIR. messages for information about product error messages.
See the List of $functions for documentation for all $functions except the Sir2000-specific $functions, which are documented in List of Sir2000 User Language Tools $functions.

Sir2000 UL Tools topic list