# DATES

> [HTML Version](datessbr.htm)

_Reviewed and revised April 2024_

**xcall DATES, opcode, result, <params...>**

DATES performs several different date utility functions and has several calling formats, as shown below.   

**Parameters**

_opcode_  ([Num](num.htm.md))  \[in\]

specifies operation to perform:

| **Symbol** | **Value** | **Operation** | **Syntax** |
|------|------|------|------|
| DTOP\_CVTFMT | 1 | Convert one format (_date1_) to another (_date2_) | xcall DATES, 1, result, date1, date2 |
| DTOP\_DATEAFTER | 2 | Compute date (_date2_) which is a specified number of days (_days_) after _date1_ | xcall DATES, 2, result, date1, date2, days |
| DTOP\_DAYSAFTER | 3 | Compute number of days _date1_ is after _date2_ | xcall DATES, 3, result, date1, date2, days |
| DTOP\_YWD | 4 | Compute _date2_ based on year, week, day of week in X,6 or X,5 format of _date1_ | xcall DATES, 4, result, date1, date2 |
| DTOP\_YWMD | 5 | Compute _date2_ based on year, month, week and day of week in X,6 format of _date1_ | xcall DATES, 5, result, date1, date2 |
| DTOP\_EOM | 6 | Compute _date2_ as last day of month in _date1_ | xcall DATES, 6, result, date1, date2 |
| DTOP\_ODTIM | 7 | Output formatted date (similar to [ODTIM](odtim_sbr.htm.md)) | xcall DATES, 7, result, testdate, time, flags, outbuf'or'chan |
| DTOP\_IDTIM | 8 | Input formatted date (similar to [IDTIM](idtim_sbr.htm.md)) | xcall DATES, 8, result, inputstr, flags, outdate, outtime |
| DTOP\_RANGE | 9 | Return _out'of'range_ (F) <>0 if _testdate_ is not between _lodate_ and _hidate_ (inclusive) | xcall DATES, 9, result, testdate, lodate, hidate, out'of'range |


**Definition file: [ashell.def](ashell_def.htm.md)**



_result_  ([Num](num.htm.md))  \[out\]

returns a code indicating if the operation was successful or what kind of error occurred: 

| **Value** | **Meaning** |
|------|------|
| 0 | OK |
| 1 | Function number out of range (1-9) |
| 2 | Error in conversion of input date |
| 3 | Invalid format for date |
| 4 | Improper number/type of parameters |
| 5 | Invalid format for _days_ |
| 6 | Error locating file channel (_opcode_ 7) |




_days_  (Signed [Num](num.htm.md))  \[out\]

for DTOP\_DAYSAFTER, returns number of days _date2_ is after _date1_

_out'of'range_  ([Num](num.htm.md))  \[out\]

for DTOP\_RANGE, returns zero if _testdate_ is within range defined by _lodate_ and _hidate _(inclusive); else non-zero.

_date1, date2, testdate, lodate, hidate _

used for input and output, depending on the operation, with the format based on the way they are mapped:

MAP1 ADATE,S,8          \! MM/DD/YY or DD/MM/YY; see note below

MAP1 BDATE,S,10         \! MM/DD/CCYY or DD/MM/CCYY; see note below

MAP1 XDATE              \! Separated format (3 to 7 bytes)

    MAP2 MONTH,B,1

    MAP2 DAY,B,1

    MAP2 YEAR,B,1

    MAP2 DOW,B,1         \! 1=Monday...7=Sunday (optional)

    MAP2 YWEEK,B,1       \! Week of year (1-52)     (optional)

    MAP2 MWEEK,B,1       \! Week of month (1-5)     (optional)

    MAP2 MDAYS,B,1       \! Days in month (1-31)    (optional)

MAP1 IDATE,B,4          \! Internal true Julian

MAP1 BDATE,B,3          \! Std AMOS date (same as 3 byte XDATE

MAP1 CDATE,B,2          \! Century Julian (days since 1/1/1900)

MAP1 JDATE,B,2          \! Yearly Julian (days since start of yr)

MAP1 FDATE,F,6          \! Special case (0=today on input)



_inputstr  _([String](string.htm.md))  \[in\]

should be set to the date and/or time to be converted, with the time following the date (with a space separator) if both date and time are included. (Also see _flags_ parameter, which indicates if date and/or time are present.) The date, if present, should be in MM-DD-\{CC\}YY or DD-MM-\{CC\}YY format, depending on your language definition file specification for date order. The separator character, however, need not be a dash or even match the language definition file; it can be any non-numeric character. The time format is HH:MM\{:SS\} \{AM/PM\}. Legal examples would be:

12/30/24 13:01

01-01-2024 10:15:33 PM

23:01:10

05.03.1915



If only two digits are specified for the year, it is assumed to be in the twentieth century (19xx) unless the SBR=[CCYY](ccyy.htm.md) is included in miame.ini, in which case it will determine the YY cutoff below which we assume 20xx instead of 19xx. 

_outdate  _([Structure](structure.htm.md))  \[out\]

will return the date in system separated format, or zero if the date is not included in the input string. Note that to access the individual fields while still being able to test the overall value for 0, it should be mapped as an overlay per the following:

MAP1 Sepdate

   MAP2 Mon,B,1              \! Month 1-12

   MAP2 Day,B,1              \! Day 1-31

   MAP2 Yr,B,1               \! Year-1900

   MAP2 Dow,B,1              \! Day of week (0=Mon, 6=Sun)

MAP1   Bdate,B,4,@Sepdate    \! B,4 version of Sepdate, as used by

                             \!  the DATE system function

MAP1   Idate,F,6             \! F,6 version as needed by IDTIM



xcall IDTIM, StringFmt, Idate, Itime, Flags, Status

Bdate = Idate

Print "Separated date: ";Mon;Day;Yr;Dow

Bdate = DATE                 \! Get today's date (for comparison)

Print "Today's separated date: ";Mon;Day;Yr;Dow



_outtime  _([Bitmap](bitmap.htm.md) 4)  \[out\]

will return the internal format time (i.e. seconds since midnight) or zero if the time is not present.

_flags  _([Num](num.htm.md))

should be set to 0 to process both the date and time; 1 if the string is expected to contain only the time, and 2 if it is expected to contain only the date.

**Notes**

•	DATES considers a 4 byte binary input date to be in internal Julian format, rather than in the standard AMOS system date format (which is actually a separated date format). A common mistake is to pass DATES a date in B4 format which was returned from the system DATE function or IDTIM, leading to massive confusion, especially when using the range testing operation (9).

•	The system parameter setting SBR=CCYY:## is used to determine the century cutoff on input dates in MM/DD/YY format. For more details, see the [SBR](sbr_sp.htm.md) command.

•	The order of the parts of an eight or ten character string date is based on the [LANG'DATE'FORMAT](gtlangsbr.htm.md) field in the current language definition file, which is month first for the US, day first for most of the rest of the world.  

**Counting Weeks**

DATES counts the days of each week from Monday=1 to Sunday=7. (That may be a little strange, since most calendars show Sunday as the first day of the week instead of the last. But DATES is a port of some existing AMOS routine, so it was A-Shell's task to preserve the existing behavior, not to justify it.)

The weeks are counted like rows in a calendar, again taking into account that our calendar weeks start with Monday and end with Sunday. So for 2011, the first week had only 2 days: Saturday and Sunday. Jan 3 was the start of the 2nd week.

If you want to convert to a more standard calendar arrangement, where each week starts with Sunday and ends with Saturday, then just add +1 to Mon-Sat and for Sunday, set it back to 1 and add +1 to the week.

On the other hand, if you want to say that each week of the year, including the first one, has seven days, then the week is simply the "yearly Julian" (DATES option 6) divided by seven, truncating the fractional remainder and then addding one (so the first week is one rather than zero). Under that scheme, Mar 15 is the 74th day; 74/7 = 10.57; truncate to 10 and then add 1 to get the 11th week (which it is).



**History**

July 2017, A-Shell 6.4.1551:  Bug fix: Opcode 3 (DTOP\_DAYSAFTER) was failing to handle the negative case properly, returning a large positive number instead of a negative number if date1 was before date2. Problem was introduced around 6.3.1516. Same fix as 6.5.1610.

2017 February, A-Shell 6.4.1543:  Bug fix: DATES was outputting mm/dd/yy when it should have been mm/dd/ccyy—i.e. when the output string length >= 10.