UDF Date Extensions for Magic RAD software Version 0.2 Copyright © 1999 Andreas Sedlmeier Contact: sedlmeier@hotmail.com
MGDATUTL Magic Date Utilities UDF Date Extensions for Magic RAD software
THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY
EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR
PURPOSE.
Alphabetical list of
functions
|
not yet implemented ...
|
For your convenience, I
added Magic's Date and Time functions to this document,
also:
|
A few words to parameters and
return values:
Unfortunately it is not possible to
use parameters (even if passed by reference) to return data to
Magic. Magic passes always a reference to a copy of the
variable (used as parameter). I decided to code
different values into a string, whenever a function has to return
more than one value and return that. It's up to you, to decode
that string to get the different values.
Usually the returned Alpha Strings look like (without the quotes) 'E,YYYYMMDD', where E is '1' to signal success and '0' for failure; 'YYYY' will be a year (e.g. '1999') .... You can use DVAL() with a proper picture to decode the date or STRTOKEN or some MIDs ...
Whenever I return a null
terminated string pointer, it would be necessary to allocate
dynamic memory for the data (If I'd use static memory, the dll
would not be thread safe). This solution tends to be a source for
many bugs, because you would be respobisble to deallocate these
ressources. It is not possible to wait until Magic frees the
library and do that automatically in some circumstances (consider
a batch over a very large table and you call a UDF which
allocates a certain amount of memory in every record loop).
So, I decided to leave that
challenge to the engine. I am always writing to memory, that you
pass as a parameter. Therefore there are always two additional
parameters "strRetBuff" and "bufLen".
Typically you SELECT a Virtual for strRetBuff and call the
function with something like udf('mgdatutl.duX', ..., A, LEN(A)).
As an alternative you could use someting like udf('mgdatutl.duX',
..., FILL(' ', 100), 100) (if you dont want to select a virtual
for the call).
The function will return (address
of) A. The variable should be declared long enough. If it is not
long enough to contain *all* return values, I fill it up with
question marks.
| duDOW | |
|---|---|
| returns the number of the day of week of the date constituted by year, month and day (of month). It is similar to Magic's DOW, but it returns 1 for monday and 7 for sunday (ISO2015-1971 or DIN 1355). | |
| Syntax | udf('mgdatutl.duDOW', Year, Month, Day) |
| Parameters | Year (Numeric)
Month (Numeric) Day of Month (Numeric) |
| Returns | Numeric |
| Example | |
| Note | In the Hebrew calendar
(on which the Christian calendar is based), the week
starts with Sunday and ends with the Sabbath (Saturday),
where according to the Genesis the Lord rested from
creating the world. In medieval times, catholic popes have decreed the Sunday to be the official day of rest, in order to dissociate the Christian from the Hebrew belief. |
| duDOY | |
|---|---|
| duDOY returns the number of the day (Day Of Year) of the given date constituted by year, month and day (of month) | |
| Syntax | udf('mgdatutl.duDOY', Year, Month, Day) |
| Parameters | Year (Numeric)
Month (Numeric) Day of Month (Numeric) |
| Returns | Numeric |
| Example | |
| Note | This function can be considered as a shortcut for a calculation using Magic's DVAL |
| duEasterSunday | |
|---|---|
| calculates the date of Easter Sunday for the given year. | |
| Syntax | udf('mgdatutl.duEasterSunday(Year, strRetBuff, bufLen) |
| Parameters | Year (Numeric) strRetBuf (Alphanumeric) bufLen (Numeric) |
| Returns | Alpha String (E,YYYYDDMM) |
| Example | MID(UDF('mgdatutl.duEasterSunday(1999, A, LEN(A)), 7, 2) & MID(UDF('mgdatutl.duEasterSunday(1999, A, LEN(A)), 9, 2) |
| Note | If you have the date of
Easter Sunday, you can use ADDDATE to get following holydays: Carnival Monday / Rosenmontag / Veille du Mardi Gras = -48 days Mardi Gras / Karnevalsdienstag / Mardi Gras = -47 days Ash Wednesday / Aschermittwoch / Mercredi des Cendres = -46 days Palm Sunday / Palmsonntag / Dimanche des Rameaux = -7 days Easter Friday / Karfreitag / Vendredi Saint = -2 days Easter Saturday / Ostersamstag / Samedi de Paques = -1 days Easter Monday / Ostermontag / Lundi de Paques = +1 days Ascension of Christ / Christi Himmelfahrt / Ascension = +39 days Whitsunday / Pfingstsonntag / Dimanche de Pentecote = +49 days Whitmonday / Pfingstmontag / Lundi de Pentecote = +50 days Feast of Corpus Christi / Fronleichnam / Fete-Dieu = +60 days |
| duRFCDate | |||||||
|---|---|---|---|---|---|---|---|
| returns a date/time stamp as e.g. used for HTTP/1.1 | |||||||
| Syntax | udf('mgdatutl.duRFCDate(strWhich, strRetBuff, bufLen) | ||||||
| Parameters | strWhich (Alphanumeric)
strRetBuf (Alphanumeric)
|
||||||
| Returns | Alpha String | ||||||
| Example | udf('mgdatutl.duRFCDate('RFC1123',
FILL(' ', 256), 256) returns Sun, 06 Nov 1994 08:49:37 GMT |
||||||
| Note | All HTTP date/time
stamps MUST be represented in Greenwich Mean Time (GMT),
without exception. For the purposes of HTTP, GMT is
exactly qual to UTC (Coordinated Universal Time). This is
indicated in the first two formats by the inclusion of
"GMT" as the three-letter abbreviation for time
zone, and MUST be assumed when reading the asctime format.
HTTP-date is case sensitive and MUST NOT include
additional LWS beyond that specifically included as SP in
the grammar.
|
||||||
| ADDTIME | |
|---|---|
| Performs
calculation on a time variable Constructs a time out of an input time and 3 values to be added to that time: Hours, minutes and seconds. The resulting time is the original input time plus the number of hours, minutes, and seconds added to it. |
|
| Syntax | ADDTIME (time,hours,minutes,seconds) |
| Parameters | time : A time value.
hours : The number of hours to add to time minutes: The number of minutes to add to time. seconds: The number of seconds to add to time. |
| Returns | Time value. |
| Example | ADDTIME('12:00:00'TIME,1,2,3) returns 13:02:03 |
| See also | TVAL |
| Note | Zero values of these parameters are ignored. |
| BOM | |
|---|---|
| Beginning
of month Returns the date of the start of the month specified in the parameter. |
|
| Syntax | BOM(date) |
| Parameters | a date or a date expression |
| Returns | Value of type DATE |
| Example | BOM ('05/10/93'DATE) returns '05/01/93' |
| See also | BOY, EOM, EOY, ADDDATE, CDOW |
| Note | |
| BOY | |
|---|---|
| Beginning
of year Returns the date of the start of the year specified in the parameter. |
|
| Syntax | BOY(date) |
| Parameters | a date or a date expression |
| Returns | Value of type DATE |
| Example | BOY ('10/05/93'DATE) returns '01/01/93' |
| See also | BOM, EOM, EOY, ADDDATE, CDOW |
| Note | |
| CDOW | |
|---|---|
| Character
Day of Week Returns the name of the day (e.g., Sunday, Monday) from a date or a date expression. |
|
| Syntax | CDOW(date) |
| Parameters | date: A date or a date expression. |
| Returns | day in character string |
| Example | CDOW('01/28/92'DATE) returns 'Tuesday' where x contains, in effect, the date 01/28/92 (Tuesday), then CDOW(x+1) returns 'Wednesday' |
| See also | DAY, DOW, NDOW |
| Note | The use of DATE following '01/28/92' identifies the string as a date literal string, and should not be confused with the DATE() function. You can control the length of the day name by manipulating the length of the alpha variable that will hold it. For example, if you input the result of a CDOW operation to a 3-character alpha variable, Magic displays the first three letters of the day name (e.g., 'Mon', 'Tue'). |
| CMONTH | |
|---|---|
| Character
Month Returns the name of the month (e.g., January, February) from a date or a date expression. |
|
| Syntax | CMONTH(date) |
| Parameters | date: A date or a date expression. |
| Returns | Alpha string |
| Example | CMONTH('01/28/92'DATE)
returns 'January' If X contains, in effect, the date 01/28/92, then CMONTH(X+30) returns 'February' |
| See also | MONTH, NMONTH |
| Note | he use of DATE
following '01/28/92' identifies the string as a date
literal string, and should not be confused with the DATE()
function. You can control the length of the month name by manipulating the length of the alpha variable that will hold it. For example, if you input the result of a CMONTH operation to a 3-character alpha variable, Magic displays the first three letters of the month name (e.g., 'Jan', 'Feb'). |
| DATE | |
|---|---|
| System Date
Returns the system date. |
|
| Syntax | DATE() |
| Parameters | none |
| Returns | Date |
| Example | If the system date is
01/28/92, DATE() returns 28/01/92. DATE()+5 returns 02/02/92. |
| See also | MDATE,DSTR, DVAL |
| Note | Magic automatically converts the date to the date format set in the Environment dialog (default), or to the picture of the variable that holds it. If the system date is set to the European format, you can display or print the system date in American format by changing the relevant parameter in the Environment dialog, or by defining a suitable picture for the variable that holds the date. |
| DAY | |
|---|---|
| Day of
Month Returns the day portion of a date, i.e., a number 1-31. |
|
| Syntax | DAY(date) |
| Parameters | date: A date or a date expression. |
| Returns | Number |
| Example | DAY('01/28/92'DATE)
returns 28. The following expression displays the word "Overdue" if the system date is later than the 15th of the month: IF(DAY(DATE())15,'Overdue','') |
| See also | CDOW, DOW, NDOW |
| Note | |
| DOW | |
|---|---|
| Day of Week
Returns the number of the day of the week from a date , where Sunday is 1, Monday is 2, and so on. |
|
| Syntax | DOW(date) |
| Parameters | date: A date . |
| Returns | Number |
| Example | DOW('29/01/92'DATE) (representing
a Wednesday) returns 4.The following expression displays
a message if the system date is a Sunday: IF(DOW(DATE())=1,'Never on Sunday','') |
| See also | CDOW, DAY, NDOW |
| Note | |
| DSTR | |
|---|---|
| Date to
Picture String Conversion Converts a date or a date expression to a character string, according to a format. |
|
| Syntax | DSTR(date, picture) |
| Parameters | date : A date picture: The format of the resulting character string. For more information see Pictures |
| Returns | Alpha string |
| Example | DSTR ('01/28/92'DATE,'WWWWWWWW, MMMMMMMM DD, YYYY') returns 'Tuesday, January 28, 1992' |
| See also | DVAL |
| Note | The use of DATE following '01/28/92' identifies the string as a date literal string, and should not be confused with the DATE() function. |
| DVAL | |
|---|---|
| Date String
to Numeric Value Converts a date entered or stored as a character string to a numeric value. The numeric value represents the number of days elapsed since the day before the first day of the 1st century (01/01/01) until the date that is being converted. |
|
| Syntax | DVAL(datestring, picture) |
| Parameters | datestring: A character
string or an alpha expression that can be interpreted as
a date (e.g., '01/01/92', 'Jan 1, 1992'). picture: The format for datestring. This parameter is required for Magic to read and interpret the character string or expression. |
| Returns | Number |
| Example | DVAL('01/01/92','MM/DD/YY')
and DVAL('Jan 1, 1992','MMM DD, YYYY') each return 727198.
Where variable A contains 'January 1, 1992' DVAL(A,'MMMMMMMMM DD, YYYY') also returns 727198 |
| See also | DSTR |
| Note | If picture does not correspond to the format of datestring, the function returns 0. |
| EOM | |
|---|---|
| End of
month Returns the date of the end of the month specified in the parameter. |
|
| Syntax | EOM(date) |
| Parameters | a date or a date expression |
| Returns | Value of type DATE |
| Example | EOM ('05/05/93'DATE) returns '05/31/93' |
| See also | BOY, BOM, EOM, ADDDATE, CDOW |
| Note | |
| EOY | |
|---|---|
| End of year
Returns the date of the end of the year specified in the parameter. |
|
| Syntax | EOY(date) |
| Parameters | a date or a date expression |
| Returns | Value of type DATE |
| Example | EOY ('11/17/93'DATE) returns '12/31/93' |
| See also | BOY, BOM, EOM, ADDDATE, CDOW |
| Note | |
| HOUR | |
|---|---|
| Hour of
Time Returns a number that represents the hours part of a time value or a time expression. |
|
| Syntax | HOUR(time) |
| Parameters | time: A time value or a time expression. |
| Returns | Number (01-99) |
| Example | HOUR('12:00:00'TIME)
returns 12 Where the variable A contains the time value 14:00:00, the expression HOUR(A)+2 returns 16. |
| See also | MINUTE, SECOND |
| Note | |
| MDATE | |
|---|---|
| Query Magic's
Date Returns the Magic date (the date entered in the Logon window). |
|
| Syntax | MDATE() |
| Parameters | none |
| Returns | Date |
| Example | MDATE()+5 returns a date that is five days later than the Magic date. The numbers added or subtracted are interpreted as numbers of days. |
| See also | DATE |
| Note | |
| MINUTE | |
|---|---|
| Minutes
Value of Time Value Returns a number that represents the minutes part of a time value. |
|
| Syntax | MINUTE(time) |
| Parameters | time: A time value. |
| Returns | Number, 0-59 |
| Example | MINUTE('12:15:00'TIME)
returns 15 If A contains the time value '12:15:00', MINUTE(A)+2 returns 17. |
| See also | SECOND, HOUR, TIME |
| Note | The use of the TIME literal following '12:15:00' should not be confused with the TIME() function. |
| MONTH | |
|---|---|
| Month Value
of a Date Value Returns the month portion of a date. |
|
| Syntax | MONTH(date) |
| Parameters | date: A date input. |
| Returns | Number, 1-12 |
| Example | MONTH('01/28/1992'DATE) returns 1 |
| See also | DAY, YEAR |
| Note | The use of the DATE literal following '01/28/1992' should not be confused with the DATE() function. |
| NDOW | |
|---|---|
| Day of Week
Number to Day Conversion Converts the number of the day of the week (e.g. 1, 2) to the corresponding name (e.g., Sunday, Monday). |
|
| Syntax | NDOW(day of week) |
| Parameters | day of week: A number that represents the day of the week. |
| Returns | Alpha string (containing day-of-week description) |
| Example | NDOW(1) returns 'Sunday'.
NDOW(DOW('01/28/1992'DATE)) returns 'Tuesday'. |
| See also | DOW, CDOW |
| Note | If the day of week is greater than 7, it is reduced by 7; e.g., 0,7,14,21... = Saturday. |
| NMONTH | |
|---|---|
| Month
Number to Name Conversion Converts the number of the month, 1-12, to the corresponding name, January-December. |
|
| Syntax | NMONTH(month) |
| Parameters | month: A number that represents the month of the year, 1 to 12. |
| Returns | Alpha string |
| Example | NMONTH(1) returns 'January'.
NMONTH(MONTH('01/28/1992'DATE)) returns 'January'. |
| See also | MONTH, CMONTH, NDOW |
| Note | |
| SECOND | |
|---|---|
| Seconds
Value of a Time Value Returns a number that represents the seconds part of a time value. |
|
| Syntax | SECOND(time) |
| Parameters | time: A time value or a time expression. |
| Returns | Number, 0-59 |
| Example | SECOND('12:15:48'TIME)
returns 48 If A contains the time value '12:15:48', SECOND(A)+2 returns 50 |
| See also | MINUTE, HOUR |
| Note | |
| TIME | |
|---|---|
| System Time
Returns the system time |
|
| Syntax | TIME() |
| Parameters | None |
| Returns | Current Time value |
| Example | TIME() returns 17:08:42.
TIME()+5 adds 5 seconds to the system time, returning 17:08:47. |
| See also | DATE, MDATE |
| Note | |
| TSTR | |
|---|---|
| Translate
Time to Character Converts a time to a alpha string, according to a picture. |
|
| Syntax | TSTR(time, picture) |
| Parameters | time: A time to
be converted. picture: The format of the resulting character string. For more information see Pictures. |
| Returns | Alpha string containing converted date |
| Example | TSTR ('14:30'TIME,'HH:MM PM') returns '2:30 PM' |
| See also | TVAL, DSTR, DVAL |
| Note | NOTE: A blank picture converts using "HH:MM:SS". |
| TVAL | |
|---|---|
| Alpha to
Time conversion Converts a time value stored as a alpha character string to a numeric value, according to a picture. |
|
| Syntax | TVAL(string,picture) |
| Parameters | string: An alpha
string that can be interpreted as a time value (e.g., '02:30:00
PM'). picture: The format for string in which the time is stored. This parameter helps Magic read and interpret the character alpha string. For a full description see pictures or see Chapter 3, Data Items, of The Magic Reference |
| Returns | Time value |
| Example | TVAL('02:30:00 PM','HH:MM:SS PM') returns 14:30:00 |
| See also | TSTR, DVAL, DSTR |
| Note | |
| YEAR | |
|---|---|
| Year Value
of Date Value Returns the year portion of a date, in four digits. |
|
| Syntax | YEAR(date) |
| Parameters | date: Input date. |
| Returns | Number of years |
| Example | If the System Date is 01/28/92, YEAR(DATE()) returns 1992 |
| See also | DAY, MONTH |
| Note | |
Recomended Readings
Claus Tondering's
highly recomended most comprehensive collection Calendar FAQ
Royal Greenwich
Observatory leaflet The Date of Easter
Richard Thompson
for IPS Radio & Space Services, Sidney, Australia: Determining the Date of
Easter
Home Page forCalendar Reform