DATEPUP32 DLL - A DATE UTILITY

© 2002, 2003, Brad Moore

author website:

Liberty Basic Connection

Home

Tip Cornner

Alyce's Favorite LB Sites

Haiku For Programmers

Haiku Generator

API File Operations

OS Selection

Binary Coding

Beginning Programming 3

DatePup32 DLL

Newsletter Help

Index

DatePup32.dll - An Introduction:

Sometime ago I worked with a business system that had an integrated set of Date routines that allowed simple data math and manipulation of dates, including comparisons and the like. I had been thinking for quite a while about creating a set of date routines for Liberty Basic users so they would have similar tools at their disposal. Just a few weeks after I had started work on the date routines Carl released the Liberty Basic version 3.01 which had an enhanced Date$ function that returned a serial number for the current date (calculated from Jan 1, 1901). At the time I was working with Julian Day values, which are calculated based on the Julian calendar based on an 8000+ year epoch. I saw what Carl was doing and added my own adjusted date value that matched Liberty Basic's and allowed the programmer to pass the serial date value generated by Date$ to be passed back into the DLL function and return a valid formatted date. Liberty Basic at the time was not capable of doing this (Carl added that feature with the release of LB 3.02).

In addition to the serialized date values (which allow easy date math) I added many more functions that would give the user great utility. Functions that returned the day number, the week number, the number of weeks in the year, and whether the current year was a leap year. Direct date math functions and a date comparison function and much more.

I finished the DLL based utility tool set in late 2002 and released it under the name DatePup32. After all this DLL is the "hound that loves to fetch dates" as the website where it is hosted purports.

I am publishing the DLL in the April issue (number 107) of the Liberty Basic Newsletter to let people know about this tool in the hopes that more people will use it. It is easy to use, and the demo program that accompanies the DLL has all the functions already encapsulated for ease of use and to speed integration into your own programs. I would love to hear if anyone finds this useful.

Here is the actual documentation that accompanies the DLL. The DLL and example programs can be found in the zip file that accompanies the newsletter. Thanks so much - Brad Moore

Purpose:

A DLL for fetching and manipulating dates for use by other 32 bit languages. It is a 32bit DLL. I have specifically designed the DLL with Liberty Basic 3.0x in mind, but it should work well with other languages such as C and C++.

For those interested in Liberty Basic - please check them out on the web at [http://www.libertybasic.com].

This DLL is distributed by the author from the Liberty Basic Connection website [http://www.freewebz.com/lb-connection]. LB Connection and Brad Moore are in no way associated with Shoptalk Systems or Liberty Basic.

Foundation Information:

I have made some compromises when writing the DLL. One is to limit it to dates that occur in the current era (AD). Specifically the function only operates on dates between 01/01/0001 and 12/31/3600. These dates correspond roughly with the Julian Day (JD) values 1721426 through 2914695. Functions return Monday as the first day of the week as defined by the ISO8601 standard (see below for references).

All dates passed to the functions of the DLL must be in the format MM/DD/YYYY (example: 05/09/2001). It is the responsibility of the programmer to insure that dates are in the correct format. A error condition will be returned by the called function if dates are passed in the wrong format. Only the "DateFmt" function can except alternately formatted dates and pass such dates back.

Liberty Basic now has an extension to its own Date$ function that is able to return a serial numbered day counted out from 01/01/1901. For compatibility the DatePUP32 DLL also supports this feature and can use that value to convert serial date values back to Gregorian dates as well as produce compatible serial date values. I call the adjusted Julian Day values in the rest of the documentation as they are simply a Julian Day adjusted to 01/01/1901.

Many of the calls depend on the Liberty Basic Struct feature. This allows a single definition of a user defined data type to exist in the Liberty Basic program. The user defined data type definition also is the variable. So when declaring a struct we are creating a single instance of a variable that contains other variables. There are five different user defined data types that the DLL implements. You may need to create a struct for one or more of them depending on the functions you are using. The definitions for each follows the function explanations.

DLL functions:

GetDays(date as string) as long

Returns the number of days since Jan 1, 1901 to the date passed to it. (Value returned is an adjusted Julian day - Same as the value Liberty Basic returns using Date$ function.) The date passed must be a null terminated string. A negative value is returned in an error condition.

GetDate(value as Jul2Greg) as long

Values are passed and returned in a user defined data type (see below). Pass values from Liberty Basic in the form of a STRCT. See documentation. Accepts an adjusted Julian day (counted from 01/01/1901) and returns a Gregorian date. A negative value is returned in an error condition.

GetJulian (date AS string) AS LONG

Returns the number of days (A true Julian Day value) since 01/01/0001 to the date passed as a null terminated string. A negative value is returned in an error condition.

GetGregorian (value AS Jul2Greg) AS LONG

Values are passed and returned in a user defined data type (see below). Pass values from Liberty Basic in the form of a STRCT. See documentation. Accepts a true Julian day (see limitations above) and returns a Gregorian date. A negative value is returned in an error condition.

DateValidate (date AS ASCIIZ) AS LONG

Accepts a date value (format MM/DD/YYYY) and returns a status code (see negative error conditions below) as a POSITIVE value. Zero indicates the date passed is a valid date. Any other value indicates an error. Errors are positive returning from this function.

isLeapYear (year AS LONG) AS LONG

Accepts a year value as a long and will return a zero if the year is a leap year and returns a ONE (1) if it is NOT a leap year. Returns a negative value if it has been passed an invalid value.

One method of using this is to assign a variable a value of 366 (as in days) the make a call to the function. It will either return a 0 or a 1. Subtract the returned value from the number of days. Years that were not leap years are suddenly 365 days.

DayOfWeek (value AS WeekDay) AS LONG

Values are passed and returned in the user defined data type called WeekDay (see below). Pass values from Liberty Basic in the form of a STRCT. See documentation. Pass the date (in format mm/dd/yyyy) in the struct, returns day index (Monday = 1, Tuesday = 2, etc) and the day name in long form. Return value (a long) is zero for successful call, negative values indicate an error.

GetDateStat (value AS DateStat) AS LONG

Values are passed and returned in the user defined data type called DateStat (see below). Pass values from Liberty Basic in the form of a STRCT. See documentation. Pass the date (in format mm/dd/yyyy) in the struct, returns days left in the year, week number the date falls into, and the day number of the year as a part of the same struct. Days in year are based on actual days (not days in weeks) from 01/01/year to 12/31/year (standard 365 day year (plus leap days) from Jan 1). Return value (a long) is zero for successful call, negative values indicate an error.

Week numbers are defined by the ISO8601 - Weeks begin on Monday. The first week of the year contains the first Thursday of the year. This means that some years week 1 can start as early as Dec 29 or as late as Jan 4th.

GetWkNumStat (value AS WeekStat) AS LONG

Values are passed and returned in the user defined data type called WeekStat (see below). Pass values from Liberty Basic in the form of a STRCT. See documentation. Pass the year (as a long) in the struct, returns dates formatted as mm/dd/yyyy for first day of the first week in the year (not necessarily 1/1/year - weeks always begin on a Monday and a year can start anywhere from 12/28 until 1/4. The function also returns the Monday's date of the last week of the year and how many weeks are in the year (this is usually 52, but some years have 53). This function follows the ISO week number convention. Return value (a long) is zero for successful call, negative values indicate an error.

IncDate (value AS DateMath) AS LONG

Values are passed and returned in the user defined data type called DateMath (see below). Pass values from Liberty Basic in the form of a STRCT. See documentation. Pass the initial date on which to operate as a string in the struct, also pass number of days to increment the date. Resulting date is passed back in the struct. All dates are passed and returned in the format mm/dd/yyyy. Return value (a long) is zero for successful call, negative values indicate an error.

DecDate (value AS DateMath) AS LONG

Values are passed and returned in the user defined data type called DateMath (see below). Pass values from Liberty Basic in the form of a STRCT. See documentation. Pass the initial date on which to operate as a string in the struct, also pass number of days to decrement the date. Resulting date is passed back in the struct. All dates are passed and returned in the format mm/dd/yyyy. Return value (a long) is zero for successful call, negative values indicate an error.

CompareDate (value AS DateMath) AS LONG

Values are passed and returned in the user defined data type called DateMath (see below). Pass values from Liberty Basic in the form of a STRCT. See documentation. Pass the dates to compare as strings in the struct (date in first element is subtracted from the date in the second element to get a result). The result is passed back as a long value in the struct. Dates must be passed in the format mm/dd/yyyy. Return value (a long) is zero for successful call, negative values indicate an error.

DateFormat (value AS DateFormat) AS LONG

This function reformats the date passed. Valid formats are:

  1. ) dd/mm/yyyy
  2. ) month dd, yyyy (long date)
  3. ) mmm dd, yyyy (short date)
  4. ) mm/dd/yyyy (Default for all other functions)

Values are passed and returned in the user defined data type called DateFormat (see below). Pass values from Liberty Basic in the form of a STRCT. See documentation. The function expects a source date to be passed in element dateIn. You must tell the function the format of you date being passed in the element named formatIn. Spacing and punctuation count when passing a long and short date value. Refer to the format chart above for exact format requirements. Also pass the desired format of output string in the element named formatOut. If dates are valid then a date is passed back in the desired format in the element named dateOut. Return value (a long) is zero for a successful call, a negative values indicate an error.

Version () AS LONG

Opens a messagebox and displays version information about DatePup32 including author, copyright, version number and release date.

User Defined Data Types:

Below are the definitions of the user defined data types used in the above functions – matching structs will need to be created in Liberty Basic in order to use the functions that are based on these:

* Jul2Greg : julian AS unsigned long, greg AS STRING * 10
* WeekDay : date AS STRING * 12, dayindex AS LONG, dayname AS STRING * 10
* DateStat : date AS STRING * 12, daysleft AS LONG, weeknum AS LONG, daynum AS LONG
* WeekStat : year AS LONG, w1date AS STRING * 10, wLdate AS STRING * 10, yearweeks AS LONG
* DateMath : dateIn AS STRING *12, days AS LONG, dateOut AS STRING * 12
* DateFormat : dateIn AS STRING * 30, formatIn as long, formatOut AS LONG, dateOut AS STRING * 30

Error Conditions:

The following list explains the possible negative error conditions that can be returned by the functions. Note that all of these error conditions are generated by the function calling ValidateDate internally. ValidateDate is the only function that will return positive versions of these error codes. The definitions are still the same, only the sign has changed.

Also note that some functions will return a general error value of -99999 which means that an error has occurred but the error has not been defined further. It is probably one of the errors below. Functions that return a string value in a struct can also return a value of "ERROR" in the string value in some cases. This is a general error condition. Most of these also will returns an error value as a result of the call that will be in the list below, providing a better description of the problem.

Error Values:

-1 : Date string passed is too long or too short
-2 : Improperly formatted date - Missing separators
-3 : Month out of range
-4 : Year passed is out of range or invalid (range is 0001 to 3600 AD)
-5 : Day passed is out of range
-6 : Other passed parameters are out of range

More Information:

The DLL comes with an example LB3.x program that demonstrates each of the functions. The program has each of the functions encapsulated in an LB Function (or Sub Program) to make them more transportable to your next project. Also in the source code is the structs declared and ready for use. These are also encapsulated in a Sub Program to make them more portable.

The following websites also were used in gathering critical information regarding Julian Days, the Gregorian calendar and ISO week definitions.

Learn about Julian dates at : [http://www.friesian.com/numbers.htm]

Learn about ISO week number at: [http://www.phys.uu.nl/~vgent/calendar/isocalendar.htm]

and also at: [http://utopia.knoware.nl/~ocorten/timex/wkcalc.htm]

More good info on dates and conversions can be found at: [http://home.capecod.net/~pbaum/date/date0.htm]

Licensing and miscellaneous:

DatePup32 was written in PowerBasic 6.0 DLL/Compiler. The source code is available upon request. The author retains all rights to the source code for DatePup32, and the help file. The example program called Datepuptestergui.bas is Public domain as of 10/15/2002. No other component of this package is public domain.

You are authorized to distribute the DLL with you applications you write, whether commercial or personal without further requirement to notify the author. No royalties are required to use this DLL. This DLL can be distributed with significant new works as desired. The DLL and documentation may not be distributed in their unaltered state by an party for a fee, as a part of a compiled CD, or on other websites or archives unless authorized by the author.

The author makes no guarantees as to fitness for any given application of this tool or accompanying files. This product is distributes as-is. There are no warranties on this product or accompanying files, either explicit or implicit.

Please send bug reports to bjaz.moore@verizon.net.

DLL Package Contents:

This archive should contain six files:

If files are missing or problems are encountered - please download a new copy from the DatePup32 home: [http://www.freewebz.com/lb-connection]


Home

Tip Cornner

Alyce's Favorite LB Sites

Haiku For Programmers

Haiku Generator

API File Operations

OS Selection

Binary Coding

Beginning Programming 3

DatePup32 DLL

Newsletter Help

Index