previous next top contents index framed top this page unframed
Figure 33–9. $dateToStr
| STRING PROCEDURE $dateToStr (LONG INTEGER date; OPTIONAL BITS ctrlBits; OPTIONAL POINTER($area) area; OPTIONAL LONG BITS ctrlBits2); |
$dateToStr produces a STRING from a MAINSAIL date, which may be an absolute (local or GMT) date or a date difference. area specifies the destination area for the resulting STRING if new STRING text is generated; see Section 29.4.
The default format for $dateToStr if date is an absolute date is:
date month year B.C. if applicable GMT if applicable
e.g., 4 July 1776, 15 March 44 B.C., 29 February 1988 GMT. The STRING “A.D.” is appended to the output STRING if the year is between 1 A.D. and 99 A.D., inclusive, so that the STRING is not mistaken for an abbreviation of a year in the current century. GMT is added to the STRING if date is in GMT format unless the ctrlBits bit $doNotIncludeTimeZone is set.
Date differences are converted by default to the format:
{-}d day{s}
The - is included if date is negative.
The null STRING is returned if an invalid input value is detected.
The following predefined BITS constants are valid in ctrlBits:
| ctrlBits Bit | Meaning |
|---|---|
| $includeWeekday | The day of the week precedes the date and is separated from it by a comma and a space. |
| $reverseDateAndMonth | The month field precedes the date. The date is separated from the year by a comma and a blank unless $hyphenateDate is set. |
| $hyphenateDate | The month field is abbreviated to three letters, and only the last two digits of the year are given (unless $allYearDigits is specified in ctrlBits2). The date, month, and year fields are separated from each other by a hyphen (minus) character rather than a space. |
| $doNotIncludeTimeZone | If date is in GMT format, suppress the default addition of GMT to the returned STRING. |
| $includeTimeZone | If date is in local format, append the local time zone name, if known. |
| $briefFormat | If date is a date difference, convert it to [+|-]{d}d, e.g., +23d (23 days), -4d (4 days, negative). A zero difference has a plus sign (+0d). |
| errorOK | No error message is given if an invalid input value is detected. |
The following predefined LONG BITS constants are valid in ctrlBits2:
| ctrlBits2 Bit | Meaning |
|---|---|
| $allYearDigits | The number of digits in the year is always exactly as many digits as required to represent the year, regardless of the value of ctrlBits. |
| $twoYearDigits | The year is always displayed with two digits (the last two digits of the year), padding or truncating as necessary, regardless of the value of ctrlBits. Be careful of storing year numbers in this form; they will eventually be taken to refer to a different century. |
For a sample date of 9 August 1982, Greenwich Mean Time, the following STRING representations are possible if ctrlBits2 is not set:
| $includeWeekday | $hyphenateDate | $reverseDateAndMonth | $doNotIncludeTimeZone | Resulting STRING |
|---|---|---|---|---|
| clear | clear | clear | clear | "9 August 1982 GMT" |
| clear | clear | clear | set | "9 August 1982" |
| clear | clear | set | clear | "August 9, 1982 GMT" |
| clear | clear | set | set | "August 9, 1982" |
| clear | set | clear | clear | "9-Aug-82 GMT" |
| clear | set | clear | set | "9-Aug-82" |
| clear | set | set | clear | "Aug-9-82 GMT" |
| clear | set | set | set | "Aug-9-82" |
| set | clear | clear | clear | "Monday, 9 August 1982 GMT" |
| set | clear | clear | set | "Monday, 9 August 1982" |
| set | clear | set | clear | "Monday, August 9, 1982 GMT" |
| set | clear | set | set | "Monday, August 9, 1982" |
| set | set | clear | clear | "Monday, 9-Aug-82 GMT" |
| set | set | clear | set | "Monday, 9-Aug-82" |
| set | set | set | clear | "Monday, Aug-9-82 GMT" |
| set | set | set | set | "Monday, Aug-9-82" |
For a sample date of 8 March 1989, local time, the following STRING representations are possible if $dateToStr is called in the Pacific Standard Time zone (PST) and ctrlBits2 is not set:
| $includeWeekday | $hyphenateDate | $reverseDateAndMonth | $includeTimeZone | Resulting STRING |
|---|---|---|---|---|
| clear | clear | clear | clear | "8 March 1989" |
| clear | clear | clear | set | "8 March 1989 PST" |
| clear | clear | set | clear | "March 8, 1989" |
| clear | clear | set | set | "March 8, 1989 PST" |
| clear | set | clear | clear | "8-Mar-89" |
| clear | set | clear | set | "8-Mar-89 PST" |
| clear | set | set | clear | "Mar-8-89" |
| clear | set | set | set | "Mar-8-89 PST" |
| set | clear | clear | clear | "Wednesday, 8 March 1989" |
| set | clear | clear | set | "Wednesday, 8 March 1989 PST" |
| set | clear | set | clear | "Wednesday, March 8, 1989" |
| set | clear | set | set | "Wednesday, March 8, 1989 PST" |
| set | set | clear | clear | "Wednesday, 8-Mar-89" |
| set | set | clear | set | "Wednesday, 8-Mar-89 PST" |
| set | set | set | clear | "Wednesday, Mar-8-89" |
| set | set | set | set | "Wednesday, Mar-8-89 PST" |
For a time difference of 23L (23 days), the following STRING representations are possible:
| $briefFormat | Resulting STRING |
|---|---|
| clear | "23 days" |
| set | "+23d" |
The standard MAINSAIL date and time formats are described in Section 24.1.
MAINSAIL Language Manual, Section 33.9