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