home *** CD-ROM | disk | FTP | other *** search
/ ftp.wwiv.com / ftp.wwiv.com.zip / ftp.wwiv.com / pub / MISC / FTSER10.ZIP / ADTDV2.ZIP / howto.txt < prev    next >
Text File  |  1997-01-26  |  6KB  |  150 lines
  1.  
  2.         This is the second and probably last version of td.lib.
  3.         A few minor tweaks were made to enhance code efficiency.
  4.  
  5. If you have not read the "readme.txt" file, please take a minute to
  6. do so, it contains system requirements and other important info.
  7.  
  8. The main reason for this library is to make working with time and dates
  9. as flexible and easy as possible. It is targeted toward the beginning
  10. C programmer. However, anyone that has had to do much time and date progr
  11. amming will appreciate it's simplicity.
  12.  
  13. It provides three main advantages over the ANSI standard
  14. functions:
  15.  
  16. 1. It is easier to use.
  17. 2. It provides accurate date and time calculations with greater
  18.    flexibility for practical work.
  19. 3. Dates and times from Jan. 1, 1 A.D. are allowed.
  20.  
  21.  
  22. I have received some questions about whether Unix systems have
  23. the same time/date draw-backs as MSDOS does. The answer is YES.
  24. More precisely, it is not the particular system your working with
  25. that makes time and date routines a pain to code, but rather it is
  26. the way the ANSI committee has defined the various time/date functions.
  27. Therefore, if your using ANSI compliant C code, which to my knowledge
  28. just about all Unix systems do, you will encounter the same difficulties
  29. previously mentioned on a Unix system.
  30.  
  31. Another question was "Can td.lib be used on a Unix system?".
  32. The answer is no, not directly.
  33. The ".lib" (short for library) extension is for MSDOS only.
  34. Unix uses "archives" that have a ".a" extension. The functions
  35. in td.lib will work on a Unix system but you will either have to
  36. get the source code to create a Unix archive (library) yourself
  37. or obtain td.lib in a Unix format. (Which I have not released.)
  38.  
  39. I will provide the source code for td.lib, along with instructions
  40. for creating a Unix version of td.lib, or create a Unix td.a
  41. for those who need it for a limited time. 
  42. (See "readme.txt" for contact info.)
  43.  
  44.  
  45.  
  46.  
  47. Here are the basics for using the library:
  48.  
  49. To work with the current time and date settings on your system, simply
  50. declare a pointer to a tdtype like this:
  51.  
  52. tdtype *date;
  53.  
  54. Now to initialize the date and time fields with the current data, make
  55. this call:
  56.  
  57. date = TimeDate();
  58.  
  59. That's it. The structure that is created is like the tm structure defined
  60. in the time.h header file except only the first six fields are used or
  61. needed.
  62.  
  63. You can now make function calls or print out any of the fields by making
  64. a call to TDFormat();
  65.  
  66. To use TDFormat(), you will need to declare an output char array of the
  67. size you need to hold all the characters in your output.
  68. The arguments to the function are:
  69.  
  70. TDFormat(tdtype *, char *, int, char *);
  71.  
  72. For example to print out the current time and date you could use these
  73. declarations and statements:
  74.  
  75.  
  76. tdtype *date;
  77. char *output[40];
  78.  
  79. date = TimeDate();
  80. TDFormat(date, output, 40, "The current date and time is: %x %I %p ");
  81.  
  82.  
  83. This is very similar to using strftime(). In fact I've made everything
  84. as close to the ANSI standard as possible but without some of its
  85. limitations. To do this I had to completely rewrite the format specifiers
  86. so that they would work with more date/time information. I also rearranged
  87. the order of the parameters to strftime() to make them easier to remember.
  88.  
  89. To create multiple date/time structures make calls to  CreateDate().
  90. Then you can prompt the user for the date/time data and load the data
  91. into the structure with  LoadDate(). Any structures that you create in
  92. this way should be "freed" when you are finished with them by calling
  93. FreeDate() to return system memory.  e.g. FreeDate(&date);
  94. As with any dynamically allocated type, remember to "free" it only once
  95. and not use it's pointer again until you reallocate memory!
  96.  
  97. Note: do not free any pointer used with TimeDate()! This function uses
  98. the current system settings and works with the standard tm structure.
  99.  
  100.  
  101. Look at the two sample files "cal.c" and "demo.c" to see examples of
  102. using the functions. Everything is really very easy to use.
  103.  
  104. See the header file "datelib.h" for function descriptions, function
  105. arguments, and return types.
  106.  
  107.    To compile your file use either bcc or tcc:
  108.              bcc yourfile.c td.lib
  109.  
  110.    If your turboc.cfg file does not have the small memory model (-ms) set
  111.    then use:
  112.              bcc -ms yourfile.c td.lib
  113.  
  114. (Don't forget to include "datelib.h" in your main source file.)
  115.  
  116.  
  117.  
  118. Microsoft and Watcom compilers can also be used in the small memory
  119. model.
  120.  
  121.  
  122.  
  123. /*---------------------------[ Format options ]----------------------------*
  124.  
  125. %n  Two-digit hour and minutes with AM or PM
  126. %r  Day, month, and year with full names
  127. %%  Displays the % character
  128. %a  Abbreviated weekday name
  129. %A  Full weekday name
  130. %b  Abbreviated month name
  131. %B  Full month name
  132. %c  Date and time   (Unix style yuk!)
  133. %d  Two-digit day of month (01 - 31)
  134. %H  Two-digit hour (00 - 23)
  135. %I  Two-digit hour (01 - 12)
  136. %M  2-digit minute (00 - 59)
  137. %p  AM or PM
  138. %S  Two-digit second (00 - 59)
  139. %j  Three-digit day of year (001 - 366)
  140. %m  Two-digit month as a decimal number (1 - 12)
  141. %U  Two-digit week number where Sunday is the first day of the week (00 - 53)
  142. %w  Weekday where 0 is Sunday (0 - 6)
  143. %W  Two-digit week number where Monday is the first day of the week (00 - 53)
  144. %x  Date
  145. %X  Time
  146. %y  Two-digit year without century (01 to 99)
  147. %Y  Year with century
  148. %Z  Time zone name, or no characters if no time zone
  149.  
  150. *-------------------------------------------------------------------------*/