Programmer 7500

home *** CD-ROM | disk | FTP | other *** search

/ Programmer 7500 / MAX_PROGRAMMERS.iso / VISUAL_B / ARQS_ZIP / DATEMA.ZIP / DATECALC.TXT < prev next >

Wrap

Text File | 1993-01-21 | 12.8 KB | 339 lines

DATEMATH Working Days Calculator (c) 1993 Table of Contents 1. Introduction (What Is DATEMATH ?) 2. A Simple Tutorial 3. The Calendar Text File 4. Compiling the Calendar File 5. DATEMATH's Library Functions 6. Oddities of Calendar Math 7. Coming Soon From Expertec 8. Registration & Legal Info 1. Introduction (What Is DATEMATH ?) ----------------------------------------------------------------------- DATEMATH is a dynamic link library that allows developers to give their applications the ability to real date math. While most programming languages give you some minimal capabilities for date manipulation, DATEMATH will allow you to add accuracy to your programs. For instance, most language products could tell you that there is 59 days between Jan 1, 1993 and Mar 1, 1993. But while DATEMATH can tell you that, it can also tell you that there is 39 work days between those dates. ( If company allows more holidays, the number of work days could be even less ). There are three basic elements to DATEMATH. They are: A. The DATEMATH DLL B. The Calandar Text File C. The Calendar Binary File A. The DATEMATH DLL handles the three eccential date functions consisting of DCalDIF ( a function that returns the difference in working days between two dates), DCalADD (a function that allows you to add x number of work days to a start date and returns the finish date), and DCalSUB ( a function that allows you to subtract x number of work days from a finish date and returns the start date). DATEMATH also includes functions for loading and unloading various user calendars. Registered users of DATEMATH will also be given access to additional functions in DATEMATH as well as a Calendar Maintanence program. B. The Calendar Text File is a simple ASCII file that contains a listing of the two basic rest types, namely Rest Days and Holidays. An example of a Rest Day is SUNDAY. Rest Days refer to Days of the Week. An example of a Holiday is 12/25/93. Holidays refer to a specific date in time. More on the calendar text files later. C. The Calendar Binary File is produced when the program CalMaint.EXE compiles the calendar text file. The DATEMATH DLL reads the calendar binary file when the LoadCalendar Function is called. The program CalMaint.EXE is a windows based program that is not included with the demo version of DATEMATH. However when you register DATEMATH you will recieve a copy of the CalMaint program at no additional cost. More on this later. 2. A Simple Tutorial --------------------------------------------------------------------- When you start the program the cursor will blinking in a text box labeled start date. Type 1/1/93 and hit the {TAB} key. In the next box type 2/1/93 and hit the {TAB} key. Next Click the Difference button and note the answer in the Results box. Next try selecting different calendars from the Calendar Group box. As you select different calendars the results boxes will clear. Click again on the Difference and note the new results. Its that simple. 3. The Calendar Text File --------------------------------------------------------------------- The Calendar Text is a simple text file that allows the developer to define up to eight seperate work calendars. The Calendar text holds calendar names and their respective rest and holiday information. There is three types of data that can be in a calendar text file. They are Rest Lines, Holiday Lines and Comment Lines. Rest Lines and Holiday Lines are made up of two parts. The first part is the calendar name and the second part is the day value. Here are some examples of Rest Lines: FiveDay Saturday FiveDay Sunday In the above example we have created a calendar called FiveDay and specified Saturday and Sunday as rest days. Please note the calendar name 'FiveDay'. One of the only rules we have when your using DATEMATH is that calendar names cannot exceed 8 characters and the first character must be a letter. Here are some examples of Holiday Lines: FiveDay 18-Jan-93 FiveDay 15-Feb-93 In this example we have specified 18-Jan-93 ( Dr. Martin Luther Kings Birthday ) and 15-Feb-93 ( Presidents Day ) as non-work days. Each calendar can have up to 200 holidays. Here are some example of Comment lines // Anything That Doesn't Look */ Like a Rest or Holiday ; line gets interpeted as a Comment. Below is the Calendar Text File Used in the Sample application. //This is the Calendar Text File (CALDATA.TXT). // Note that the file can contain blank lines for clarity //First I will set up a 5 day work week calendar called FiveDay. //Calendar names can be up to 8 characters long and MUST start //with a letter. //Calendar FiveDay will have rest on Saturday and //Sunday but no holidays. //Holidays for FiveDay //Rest for FiveDay FiveDay sat FiveDay sun //Next I will set up a six day calendar that rests only on Sunday //and has no holidays. //Holidays for SixDay //Rest for SixDay SixDay sun //Finally I will setup a calendar that rests on Saturday and Sunday //and has standard US Holidays for 1993. //Holidays for HolsFive HolsFive 18-jan-93 HolsFive 25-feb-93 HolsFive 31-may-93 HolsFive 5-jul-93 HolsFive 6-sep-93 HolsFive 11-nov-93 HolsFive 25-nov-93 HolsFive 24-dec-93 HolsFive 31-dec-93 //Rest for HolsFive HolsFive sat HolsFive sun 4. Compiling the Calendar File --------------------------------------------------------------------- Before DATEMATH can use the user defined calendars, the calendar text text file must be compiled. This is done with the program CalMaint.EXE. CalMaint first examines the calendar text file and produces a matrix display of the users calendars. Once the you is statisfied with the results CalMaint will compile the text file into a binary. The default name for the Calendar Text file is Caldata.TXT. The default name for the calendar binary file is Caldata.BIN. The program CalMaint.EXE is not included in the demo version of DATEMATH. However the user may test the software completely in there own programs with the Caldata.BIN file provided. As shown in the previous section, this calendar file has three user defined work calendars in it. 1. FiveDay - Rest on Saturdays & Sundays, No Holidays 2. SixDay - Rest on Sundays, No Holidays 3. HolsFive- Rest on Saturdays & Sundays plus Std US Holidays for 1993 If you choose to register DATEMATH you will recieve CalMaint.exe ( so you can compile your own calendars ) at no extra cost. 5. DATEMATH's Library Functions --------------------------------------------------------------------- The five functions included in the DATEMATH DLL are as follows: Function Name Ord Rcv/Snd Type Parameter Description/Sample --------------------- --- ------- ----- --------- ------------------- LoadCalendar 1 (R) LPINT nMemRef memory tag (S) LPSTR szCalFile 'c:\caldata.bin' DCalDIF 2 (S) LPINT nMemRef memory tag (S) LPSTR szCalendar 'ADMIN' (S) LPSTR szStartDate '1993-01-01' (S) LPSTR szFinDate '1993-01-31' (R) LPINT nDaysDif result difference in days DCalADD 3 (S) LPINT nMemRef memory tag (S) LPSTR szCalendar 'ADMIN' (S) LPSTR szDateIn '1993-01-01' (R) LPSTR szDateOut date result (S) LPINT nDaysAmt days to add DCalSUB 4 (S) LPINT nMemRef memory tag (S) LPSTR szCalendar 'ADMIN' (S) LPSTR szDateIn '1993-01-01' (R) LPSTR szDateOut date result (S) LPINT nDaysAmt days to substract DestroyCalendar 5 (R) LPINT nMemRef releases calendar memory They are defined in Visual Basic AS: Declare Function LoadCalendar Lib "DateMath.DLL" (nMemRef%, ByVal szCalFile$) As Integer Declare Function DCalDIF Lib "DateMath.DLL" (nMemRef%, ByVal szCalendar$, ByVal szStart$, ByVal szFinish$, nDaysDif%) As Integer Declare Function DCalADD Lib "DateMath.DLL" (nMemRef%, ByVal szCalendar$, ByVal szStart$, ByVal szFinish$, nDaysDif%) As Integer Declare Function DCalSUB Lib "DateMath.DLL" (nMemRef%, ByVal szCalendar$, ByVal szStart$, ByVal szFinish$, nDaysDif%) As Integer Declare Function DestroyCalendar Lib "DateMath.DLL" (nMemRef%) As Integer 6. Oddities of Calendar Math --------------------------------------------------------------------- If you're new to doing 'Work Day' calendar math you may occasionally come across results you don't expect. The best way to illustrate this is with an example. First lets consider the months of January 1993 & February 1993. January 1993 February 1993 Su Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa 1 2 1 2 3 4 5 6 3 4 5 6 7 8 9 7 8 9 10 11 12 13 10 11 12 13 14 15 16 14 15 16 17 18 19 20 17 18 19 20 21 22 23 21 22 23 24 25 26 27 24 25 26 27 28 29 30 28 31 Assuming that all Saturdays and Sundays are rest days, consider the following two statements: The difference between 1-Jan-93 and 31-Jan-93 is 21 work days. The difference between 1-Jan-93 and 1-Feb-93 is 21 work days. Both these statemnts are true. ( Since 31-Jan-93 is a rest day) Continuing along line, consider these statements: 1-Jan-93 plus 21 work days equals 1-Feb-93. 31-Jan-93 minus 21 work days equals 1-Jan-93. When adding or subtracting work days from a date the result is always a work day. Hopefully this breif explantion will help you if you find yourself confused about the results DATEMATH produces. 7. Coming Soon From Expertec --------------------------------------------------------------------- Expertec Incorporated has been in the business of writing custom software for Fortune 500 companies since 1989. At Expertec we specialize in the development of Project Management and Expert Systems. The majority of our work is in the client-server arena primarily on Windows,Windows NT, and Unix platforms. DATEMATH comes from the Project Management side of the house and is primarily the of work Paul Onstad. Another of Mr. Onstads programs that may be of interest is the Expertec CPM Engine. The CPM Engine is a set of DLL's that allow the developer to perform Critical Path Analysis routines on there databases. The product generates all standard CPM dates including Early Start, Early Finish, Late Start, Late Finish as well as Total and Free floats. The CPM engine also allows six different Target Date types and uses the same calendar files as DATEMATH. The product is currently available for developers using Gupta Technologies SQLWindows language and will be available for Microsoft Access developers in the 2nd Qtr. 1993. Suggested Retail Price for the CPM engine is $99.95 8. Registration & Legal Info --------------------------------------------------------------------- Money Stuff: DATEMATH is not free. It is a commercial Shareware product. You are permited to evaluate this product for 15 days. After that time you must register or discontinue using the program. The use of unregistered copies of DATEMATH, beyond the evaluation period, by any person, business, corporation, government agency or any other entity is strictly prohibited. The basic registration fee for DATEMATH is $24.95($15.00 before 31-Mar-93). For instructions on how to register, see the file REGISTER.TXT. Whether or not you choose to register, I'd enjoy hearing your comments on the program. Please send all suggestions, gripes, bug reports and anything else to any of these addresses: Expertec, Inc. Attn: Chet Kloss 340 North Main Street - Suite 304 Plymouth, MI 48170 CIS: 72311,743 The latest version of DATEMATH can be found on the MSBASIC forum of CIS. Legal Stuff: No guarantee is made, expressed or implied, pertaining to the use, misuse,or any problems caused by this program. Should the program prove defective, the purchaser or evaluator assumes the risk of paying the entire cost of all necessary servicing, repair, or correction, and any incidental or consequential damages. In no event will the author be liable for any damages whatsoever arising out of the use or the inability to use this product. A limited license is granted to copy and distribute DATEMATH for the evaluation use of others, as long as it is distributed without modification, complete with all files. No fee, charge or other compensation may be requested with these exceptions: Operators of electronic bulletin board systems may make DATEMATH available for downloading, so long as there is no specific charge for the download of DATEMATH. Vendors of user-supported or shareware software may distribute DATEMATH, so long as any duplication and handling fees do not exceed five dollars, and notice is clearly given that such fees do not grant the evaluator a license to use DATEMATH beyond the evaluation period.