home *** CD-ROM | disk | FTP | other *** search
/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 426.lha / Udate_v1.14c / date.doc < prev    next >
Text File  |  1990-10-03  |  14KB  |  412 lines
  1.  
  2.     Program:  udate (can be renamed to 'date' if desired)
  3.  Programmer:  George Kerber
  4.  
  5.     Written:  06/28/89 - 01/14/90   
  6.     Version:  1.14c
  7.  
  8.  
  9. PURPOSE:
  10. --------
  11. Output a date/time string to stdout similar to the AmigaDOS date command,
  12. will also emulate the UNIX date command by allowing almost total user
  13. allowing an almost total user determined formatting of the date and/or time.
  14.   
  15. Automatically adjusts the system clock for daylight savings time when
  16. in effect.
  17.  
  18. Sets the computer date and time, completely replacing the AmigaDOS 
  19. date command.
  20.  
  21.  
  22. SYNTAX:
  23. -------
  24.  
  25.     udate 
  26.     udate hh:ss
  27.     udate mm/dd[/yy]
  28.     udate ["format string"]
  29.     udate [-s -d -n -m xx ] 
  30.     udate [?] (helpscreen)
  31.  
  32.          ?  Help screen.
  33.     -s  Prompts the user through setting the date and time.
  34.      hh:mm  Set time with no prompts.
  35. mm/dd[/yy]  Set date, with no prompts.  Year is optional.
  36.         -d  Increments the system clock by 1 hour when daylight
  37.             savings time is in effect.
  38.         -n  Prevents a NEWLINE from being output after the date string
  39.             is displayed.  Works the same as the NOLINE option using
  40.             the AmigaDOS echo command.
  41.         -m  xx  Begins the date string at xx character position.
  42.  
  43.  
  44. DESCRIPTION:
  45. ------------
  46. If no argument is given, the current date and time are displayed in 
  47. standard AmigaDOS format with the timezone name displayed if the TIMEZONE
  48. variable is set.  (explained later)  The 'default' date display can be
  49. changed by the user.  (explained later)
  50.  
  51.     dddddd dd-mmm-yy hh:ss tzn*
  52.             
  53. If a string argument exists, the output of udate is under control of user. 
  54.  
  55. Sets the computer date and time, using prompts or command line options.
  56.  
  57. Automatically adjusts the system clock for daylight savings time.
  58.  
  59.  
  60. All field descriptors must be 'escaped' by the current escape value.  The
  61. default escape value is a '*', following the escape value that the AmigaDOS
  62. AmigaDOS echo command uses.  If desired, the escape value can be changed to
  63. make it more 'normal'.  To change the escape value, use the AmigaDOS
  64. setenv command.
  65.     
  66. Example:  to set the escape value to a backslash.
  67.              
  68.     1> setenv ESCAPE=\ <enter>
  69.  
  70. The udate helpscreen will always display the escape value.
  71.  
  72.  
  73. To print a literal character of the escape value you must 'escape' it.
  74. If the escape value was a '*', to print one you must enter a double *.
  75. See the examples below.  The * escape character was made the default to
  76. provide compatibility with the AmigaDOS echo command.  It uses a * as the
  77. escape character.  (Am I the only one that thinks this is silly)
  78.  
  79. Note that the ARP version of 'echo', a version of 'echo' and 'fortune' that
  80. I wrote allow the escape value to be changed as described above.
  81.  
  82. All other characters are copied to the output without change.  If the
  83. argument contains embedded blanks it must be quoted (see the EXAMPLE).
  84.  
  85.  
  86. INSTALLATION:
  87. -------------
  88. Copy the udate & datehelp programs to the sys:c directory.
  89.  
  90. It is recommended that you delete the AmigaDOS date program and replace it
  91. with the udate program renamed to date.  The date/udate and datehelp
  92. program should be copied to your "c" directory. 
  93.  
  94.     1>  copy udate c:date
  95.     1>  copy datehelp c:
  96.  
  97. This will copy the udate to your c: directory and overwrite and overwrite
  98. the original AmigaDOS date program.
  99.  
  100. NOTE:  The datehelp program is not necessary to use udate, but including
  101. it in your sys:c directory will provide a very complete help screen.  The
  102. datehelp command is provided to reduce the program size of the udate
  103. command.  The datehelp program can't be executed directly, the udate
  104. command calls datehelp when udate is given a ? as an argument.
  105.  
  106.  
  107. FIELD DESCRIPTORS:
  108. ------------------
  109. ( must be preceded by the current escape value, which is a '*' by default ):
  110.  
  111.     a  abbreviated weekday name
  112.     A  full weekday name
  113.     b  abbreviated month name
  114.     B  full month name
  115.     D  date as mm/dd/yy
  116.     d  day of month - 01 to 31
  117.     e  day of month -  1 to 31 (single digits preceded by a blank)
  118.     h  abbreviated month name (alias for 'b')
  119.     H  hour - 00 to 23
  120.     I  hour - 01 to 12
  121.     j  julian day of current year
  122.     m  month of year - 01 to 12
  123.     M  minute - 00 to 59
  124.     n  insert a new-line character
  125.     p  string containing "AM" or "PM" depending on current hour.
  126.     r  time as hh:mm:ss pp, where pp is "AM" or "PM", 
  127.        hh is 01 to 12
  128.     R  time as hh:mm
  129.     S  second - 00 to 59
  130.     t  insert a tab character
  131.     T  time as hh:mmm:ss, hh is 00 to 23
  132.     w  day of week - Sunday = 0
  133.     y  year within century - 00 to 99
  134.     Y  year as ccyy (4 digits)
  135.     Z  timezone name*
  136.  
  137.     Additions for AmigaDOS:
  138.  
  139.     x  string containing day of month extension (th, st, rd, nd)
  140.     u  date/time as ddd mmm dd hh:mm:ss tzn* yyyy 
  141.       (standard UNIX date format)
  142.     i  hour - 1 to 12
  143.     W  day of week - Sunday = 1
  144.     J  days remaining in current year.
  145.     q  print a literal quote.
  146.     o  output is: "Good Morning|Afternoon|Evening"
  147.     k  output is: 
  148.        "Today is dddddd, mmmmmm dd, yyyy at hh:mm tzn"
  149.     g  Greeting message, same as "*o!   *k"
  150.     $  same as standard AmigaDOS date string, with timezone.
  151.        (same as udate with no options)
  152.     0  blue pen color
  153.     1  white pen color
  154.     2  black pen color
  155.     3  orange pen color
  156.     4  default colors
  157.     5  boldface
  158.     6  underline
  159.     7  italics
  160.     )  blue background
  161.     !  white background
  162.     @  black background
  163.     #  orange background
  164.     C  ddd dd-mmm-yy hh:mm tzn*
  165.  
  166.  
  167.     Enter the 'escape' character twice with no space to print a
  168.     literal 'escape' character.
  169.     
  170.      *  Timezone will be displayed if set as described below. 
  171.         No errors are shown if the timezone variable is not set.    
  172.             
  173.      Z  if this descriptor is used, udate will TRY and locate an
  174.         environmental variable called TIMEZONE.  If TIMEZONE exists and is
  175.         defined correctly, the current timezone will be displayed.  See the
  176.         section below for instructions on how to set the TIMEZONE variable.
  177.                 
  178.         If TIMEZONE is not set, nothing will be displayed and
  179.         no error will occur.
  180.  
  181.      x  this descriptor will display a character string extension
  182.         corresponding to the current day of the month
  183.         (ex: st for 1, nd for 2, rd for 3 etc....).
  184.      u  the UNIX date command with no options displays a date/time string
  185.         with this format.  The timezone variable will be printed if set as
  186.         described below.
  187.      4  There is no need to use a %4 (default colors) after changing the
  188.         color, udate does this automatically on termination.
  189.  
  190.  
  191. EXAMPLES:
  192. ---------
  193. (assume the current date is July 4th, 1989 at 2:42:05pm)
  194.  
  195. If the 'escape' value was changed using the setenv command, then
  196. replace all *'s with the new escape value.
  197.  
  198.    1> udate <enter>
  199.    Tuesday 04-Jul-89 14:42:05 MDT
  200.    1>
  201.  
  202.    1> udate *u <enter>
  203.    Tue Jul  4 14:42:05 MDT 1989
  204.    1>
  205.  
  206.    1>udate "The TIME is *M:*S" <enter>  (argument must be quoted
  207.    The TIME is 14:42                     for embedded blanks)
  208.    1>
  209.  
  210.    1> udate *v <enter>                   (v is not a valid option)
  211.  
  212.    ERROR:  Bad Conversion. (%v)   
  213.  
  214.    1> udate "DATE: *m/*d/*y*nTIME: *H:*M:*s" <enter>
  215.    DATE: 07/04/89
  216.    TIME: 14:42:05
  217.    1>
  218.   
  219.    1> udate "It is now *M minutes past the hour."
  220.    It is now 42 minutes past the hour"
  221.    1>
  222.  
  223. Add this to your startup-sequence (The env: variable TIMEZONE must have
  224. been previously set as described below to get the MDT):
  225.  
  226.    1> udate -m 6 "*3Today is:  *4*$"
  227.          Today is:  Monday 04-Jul-89 14:42:05 MDT
  228.    1>
  229.  
  230.    1> udate "\n\t\o George,\n\k\n"
  231.  
  232.            Good Afternoon George,
  233.  
  234.            Today is Monday, July 4th, 1989 at 4:42 PM (MDT)
  235.  
  236.    1>
  237.  
  238.  
  239. SETTING THE DATE & TIME:    
  240. ------------------------ 
  241. Execute 'udate' witht the '-s' option and you will be prompted through
  242. setting the date and/or time.  Or the date and/or time can be changed
  243. directly from the command line.
  244.  
  245. If udate is executed with a string that resembles a date or time, then    
  246. udate will attempt to change the computer clock to the new date or time.    
  247.     
  248. Change Time:  udate hh:mm    
  249.    
  250.               The seconds are automatically set to 00 each time the time   
  251.               is changed.     
  252.     
  253. Change Date:  udate mm/dd[/yy]    
  254.       
  255.               The year is optional, if no year is entered, then the    
  256.               current year will be retained.     
  257.     
  258. NOTE:  The 'udate' program can be used as an 'echo' command if desired.    
  259. Because of how 'udate' determines if the user is trying to change the date
  260. or time, you can't simply 'echo' a constant date or time using udate.
  261. For example, if you enter:    
  262.     
  263.     udate 12/23/89    
  264.     
  265. udate will change the date to 12/23/89, rather than 'echo' 12/23/89 to the
  266. screen.  You could enter:    
  267.     
  268.     udate  "12/23/89 "   
  269.     
  270. to actually 'echo' 12/23/89 to the screen.  Notice the extra literal space
  271. at the end, this 'tricks' udate into thinking that you are not entering a
  272. valid date.   
  273.     
  274.  
  275. CHANGING THE DEFAULT DATE DISPLAY
  276. ---------------------------------
  277. Normally the default date display for 'date' is:
  278.  
  279.     dddddd dd-mmm-yy hh:ss tzn
  280.  
  281. If desired, this can be changed to anything you want by setting an
  282. environmental variable named 'DEFAULT'.  Set DEFAULT to any valid formatted
  283. date string using the AmigaDOS setenv command.  Example:
  284.  
  285.         setenv DEFAULT="\g  \S"
  286.  
  287. Then whenever 'udate' is executed with no arguments, the default will be
  288. '\g   \S' instead of the default as shown above.  
  289.  
  290.  
  291. SETTING THE TIMEZONE VARIABLE:    
  292. ------------------------------    
  293. Add the following line to your s:startup-sequence file:   (if desired) 
  294.     
  295.     setenv TIMEZONE=tzn[:dst]    
  296.     
  297. where 'tzn' = the current standard timezone for your area.    
  298. (EST, CST, MST, PST, etc)  All three characters must be used.    
  299.     
  300. where 'dst' = the optional timezone for your area when daylight savings time
  301.  
  302. is in-effect.  (EDT, CDT, MDT, PDT, etc)  If your area does not observe
  303. daylight savings time, then only enter 'tzn' as described above.    
  304. If 'dst' is used, you must use all three characters and use an ':' as    
  305. a field separator.    
  306.     
  307. Examples:
  308.  
  309.     1> setenv TIMEZONE=EST:EDT    
  310.     1> setenv TIMEZONE=MST:MDT    
  311.         1> setenv TIMEZONE=PST    
  312.   
  313. The TIMEZONE variable must be set exactly as shown or 'udate' will  
  314. completely ignore it.  Setting the TIMEZONE is optional, but the current 
  315. timezone will not be displayed if it isn't set. 
  316.  
  317.     
  318. AUTOMATIC DAYLIGHT SAVINGS TIME ADJUSTMENT    
  319. ------------------------------------------    
  320. udate will automatically keep your clock set for the correct time while    
  321. daylight savings time is in effect and while it's not.
  322.     
  323.     
  324. Example:  Add this line to your startup-sequence after any commands
  325. necessary to read your battery clock.    
  326.     
  327.     1> udate -d    
  328.     
  329. Set your battery clock to standard time in your area and add the    
  330. above line to your startup-sequence file.  If a command is necessary in the
  331. startup-sequence to read the battery clock, the 'udate -d' line must    
  332. follow the readclock command.    
  333.     
  334. The 'udate -d' command should only be executed once per login session. 
  335. If setup properly, you will NEVER have to do the twice yearly ritual of    
  336. resetting your computer clock for daylight savings time.    
  337.  
  338.  
  339. PURE/RESIDENT?
  340. --------------
  341. If I understand 'pure' programs, they cannot contain any global variables.
  342. This version has no global variables and should be able to be made
  343. resident using the AmigaDOS 'resident' command.  I have tested this and
  344. have had no problems making udate resident with the pure bit set.
  345.     
  346.  
  347. PROGRAMMING NOTES:
  348. ------------------
  349. The AmigaDOS date command is very limited in the way it will output the
  350. date/time to the screen, you only get one way to do it.  Sometimes the user
  351. will want to only display part of the date/time in a particular way.
  352. The UNIX date command will allow this easily.  This new AmigaDOS udate
  353. command will totally emulate the UNIX date with many additions.
  354.  
  355. This was written in "C" using Lattice 5.04.  Compared to UNIX "C", I had to
  356. do this the hard way.  UNIX "C" contains a function called "cftime"
  357. which will take the format descriptors directly, instead of having to use
  358. a long "switch" statement like I had to with Lattice.
  359.  
  360. I have a version of udate for MS-DOS that works the same as this version.
  361.   
  362. I added a few descriptors beyond what UNIX offers.  Using the descriptors,
  363. the user can add color and date extensions to the day number.  If desired,
  364. this udate command could be used as an "echo" command.
  365.  
  366. Most of the field descriptors emulate the UNIX descriptors.  This was done
  367. to avoid confusion with those that use UNIX too.  On the other hand, I 
  368. could see no reason to have to use a '+' before the descriptor string
  369. like UNIX needs.  To maintain compatibility with AmigaDOS, the
  370. 'escape' value will default to a '*' like the AmigaDOS echo command.
  371.  
  372.  
  373. NOTE TO AMIGADOS 1.2 USERS:
  374. ---------------------------
  375. You can still use this udate command with v1.2, and get the timezone
  376. displayed.  Just add the following lines to your startup-sequence:
  377.  
  378.     makedir ram:env
  379.         assign env: ram:env
  380.         echo > env:TIMEZONE "MST:MDT"  ; or whatever your timezone is
  381.  
  382.  
  383. STATUS:
  384. -------
  385. 'udate' is public domain and can be freely distributed.  But I insist on
  386. being kep at the author and that all documentation is left intact and
  387. distributed with the program.  Please leave the name of the program as
  388. 'udate' when distributing the program, but feel free to rename it to
  389. date for your use.
  390.  
  391.  
  392.                            George Kerber
  393.                            19756 E. Linvale Drive
  394.                            Aurora, Colorado  80013
  395.                            303-692-2890
  396.  
  397.                            Compuserve 74010,2132
  398.  
  399.  
  400. 10/07/89 v1.11:  Removed the need to begin each string argument with a '!'.
  401.                  This was an attempt to make udate work similar to the UNIX
  402.                  version of date.  Also made the escape value default to
  403.                  a '*', but changeable using the setenv command.  The 
  404.                  similarity between the UNIX date and udate is going away...
  405. 12/29/89 v1.14:  Added the daylight savings time function to the udate code
  406.                  eliminating the need for a separate 'dst' program.  Udate
  407.                  now allows the date and time to be set via prompts or
  408.                  directly from command line strings.
  409.                  Removed all global variables.  Pure?
  410.                  For whatever it's worth.... udate will display the year
  411.                  correctly until 2079. 
  412.