xcall DATES, opcode, result, <params...>
DATES.SBR performs several different date utility functions and has several calling formats, as shown below.
Parameters
opcode (Num) [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) |
xcall DATES, 7, result, testdate, time, flags, outbuf'or'chan |
|
DTOP_IDTIM |
8 |
Input formatted date (similar to IDTIM) |
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 | |||
result (Num) [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) [out]
for DTOP_DAYSAFTER, returns number of days date2 is after date1
out'of'range (Num) [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 format
MAP1 BDATE,S,10 ! MM/DD/CCYY format
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)
|
Value |
Meaning |
|
>=0 |
# of bytes processed; should match bytes |
|
-1 |
bad data type for srcdata |
|
-2 |
bad digtype |
|
-3 |
bad digest type or size |
|
-4 |
file not found |
Notes
• DATES considers a 4 byte binary 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.SBR, leading to massive confusion, especially when using the range testing operation (9).
• the miame.ini parameter SBR=CCYY:## is used to determine the century cutoff on input dates in MM/DD/YY format. For more details, see the SBR command in the miame.ini configuration file.
DATES.SBR 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.SBR 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).