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: /* Sir2000 topic list */ edit section title

2018-02-02T22:02:02Z

Sir2000 topic list: edit section title

New page

==Overview==
The <var class="product">Sir2000 User Language Tools</var> 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 <var>[[The Sir2000 APPDATE command|APPDATE]]</var> 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
(<var>CENTSPAN</var>/<var>SPANSIZE</var>) 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 <var>CENTSPAN</var> argument supplies the beginning of year of the up to 100-year range of dates covered by the two-digit years.

<var>CENTSPAN</var> provides both of these: 
<ul>
<li>An absolute specification, in which the full 4-digit start year is specified </li>

<li>A relative specification, in which the start year is specified relative to the current time, for example, 50 years ago </li>
</ul>

The default <var>CENTSPAN</var> value is <code>-50</code>. 

To reduce the ambiguities caused by mapping two-digit years into four digit years,
<var>SPANSIZE</var> is used to limit the number of years mapped. <var>SPANSIZE</var> and its relationship to <var>CENTSPAN</var> is explained in [[Sir2000 datetime processing considerations#CENTSPAN|CENTSPAN]]. The default <var>SPANSIZE</var> is <code>90</code>. 

====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 <var>USER</var> and <var>SYSTEM</var> switches of <var>DATE_ERR</var>. The <var>DATE_ERR</var> switches can be set by an <var>APPDATE</var> command with a <var>DATE_ERR</var> clause or by the <var>$Sir_Date_Err</var> function.

<var>DATE_ERR</var> 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:

<table class="thJustBold">
<tr><th>CANCEL</th>
<td>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. </td></tr>

<tr><th>REPORT</th>
<td>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. </td></tr>

<tr><th>IGNORE</th>
<td>If a datetime $function detects an error, the appropriate standard error value is returned by the $function. </td></tr>
</table>

The errors that are detected include:
<ul>
<li>Invalid datetime format specification </li>

<li>Datetime string not matching format </li>

<li>Datetime out of range for the format </li>

<li>Invalid <var>CENTSPAN</var> value </li>

<li>Datetime out of range for <var>CENTSPAN</var>/<var>SPANSIZE</var> combination. </li>
</ul>

In addition, an <var>APPDATE</var> command with a <var>DATE_ERR</var> 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 subroutines for FUNU|assembler language (FUNU) $functions]] to obtain the current
date and time using the appropriate <var>APPDATE</var> 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 <var class="product">Sir2000 User Language Tools</var> documentation consists of the pages listed below. This list is also available as a "See also" link from each of the pages.

Also:
<ul>
<li>See [[List of Model 204 messages#msir|MSIR. messages]] for information about product error messages. </li>

<li>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]].</li>
</ul>

===Sir2000 UL Tools topic list===
{{Template: Sir2000 topic list}}

[[Category: Sir2000 User Language Tools]]

Sir2000 User Language Tools - Revision history

Admin: 1 revision imported

JAL: /* Sir2000 topic list */ edit section title