47.53. $strToDate

$strToDate produces a MAINSAIL date given a STRING. The date specified may be in any of the formats produced by $dateToStr.

A two-digit year is generally assumed to be a year in the current century; a year in the first century may be specified by terminating the date STRING with A.D.; e.g., 17 A.D. represents the year 17, not 2017.

s need only start with a valid date STRING. remS is that part of s that remains after the part containing the date STRING has been removed.

If s does not begin with a valid date, 0L is returned, success is set to FALSE, and the value of remS is unspecified. 0L is a valid return value if the STRING represents a date difference, so success must be examined if an invalid date difference STRING may be input.

The valid ctrlBits bits are $localTime, $gmt, and errorOK.

$localTime and $gmt are ignored if a time zone abbreviation (either GMT or the abbreviation of the local time zone) appears in s; in this case, the returned value is in the specified format. If no time zone abbreviation appears in s, then if $localTime is specified (or if neither $localTime nor $gmt is specified), the STRING is interpreted as a local date and returned in local date format; if $gmt is specified, a GMT format date is returned.

Unless errorOK is specified, an error message is generated for erroneous input values.

The standard MAINSAIL date and time formats are described in Section 24.1.

47.53.1. twoDigitCutoffYear

The STRING-valued global symbol twoDigitCutoffYear governs the interpretation of two-digit years in $strToDate (and $strToDateAndTime, which calls $strToDate). The value of twoDigitCutoffYear is treated as an INTEGER whose value is used to establish a year called the “cutoff year”, as described below.

Dates passed to $strToDate that contain a two-digit year Y and do not contain a disambiguating A.D. or B.C. are interpreted according to the value of the cutoff year. Call the cutoff year's century (i.e., the cutoff year DIV 100) C, and its year in that century (i.e., the cutoff year MOD 100) Z. Then if Y is greater than or equal to Z, Y is treated as if it were in century C; otherwise, it is considered to be in century C + 1. Specifically:

IF Y GEQ Z THEN
    treat Y as C * 100 + Y
EL  treat Y as (C + 1) * 100 + Y

For example, if the cutoff year is 1960, then C is 19 and Z is 60. If Y is 99, then Y is interpreted as 1999, because 99 is greater than or equal to 60. If Y is 07, which is less than 60, then Y is treated as 2007.

twoDigitCutoffYear establishes the cutoff year as follows:

• If twoDigitCutoffYear is specified and is positive, then the cutoff year is twoDigitCutoffYear (e.g., 1960).

• If twoDigitCutoffYear is specified and is nonpositive, then the cutoff year is the current year plus twoDigitCutoffYear. For example, if twoDigitCutoffYear is -50, and it is now 1999, then the cutoff year is 1949 (in other words, 2-digit years are treated as being within about 50 years of the current year).

• If twoDigitCutoffYear is unspecified or not a valid INTEGER, the cutoff year is the current year with the last two digits changed to zeros (in other words, (the current year DIV 100) * 100). This is the behavior before the introduction of twoDigitCutoffYear. For example, if it is now 1999, the cutoff year is 1900, and a two-digit year 07 would mean 1907.

You may set twoDigitCutoffYear using the MAINEX GLOBALSYMBOL subcommand, e.g.:

GLOBALSYMBOL twoDigitCutoffYear -50

to make the cutoff year 50 years before the current year.

You can issue the GLOBALSYMBOL subcommand anywhere a MAINEX subcommand could appear. For example, if you put it in the site.cmd file on the MAINSAIL directory, then each MAINSAIL process using that directory would have the specified cutoff year (unless overridden in that process).

You must be careful to ensure that the cutoff year used by each MAINSAIL process is consistent with the data manipulated by that process.