home *** CD-ROM | disk | FTP | other *** search
/ Power-Programmierung / CD2.mdf / c / library / dos / datetime / navytime / navytime.doc < prev    next >
Encoding:
Text File  |  1987-08-15  |  9.0 KB  |  204 lines
  1.         NAVYTIME -- Get Date/Time from Naval Observatory    Page 1
  2.  
  3.  
  4.         Copyright 1987  Michael M Rubenstein
  5.  
  6.         This software may be freely distributed as long as no fee is
  7.         assessed and the copyright notice is retained.
  8.  
  9.         The functions contained in COMM.C, TIMER.C, ATFINISH.C, and
  10.         SETTZ.C may be distributed as part of an executable program
  11.         (even if a fee is charged) provided the following copyright
  12.         notice is included:
  13.  
  14.              Portions copyright 1987  Michael M Rubenstein
  15.  
  16.  
  17.         Changes in Version 1.1.
  18.  
  19.              - The interrupt service routine for the timer has been
  20.                rewritten to reduce the stack space required.  The
  21.                modification is based on a routine by Don Corbitt.
  22.  
  23.              - The RS232 interface is cleared after dialing.  This
  24.                prevents old messages from aborting the transfer.
  25.  
  26.              - Defines for TRUE and FALSE have been inserted so the
  27.                standard Turbo C include files may be used (the original
  28.                required my modified STDIO.H.
  29.  
  30.              - The file BUILTINS.MAK is now included.  This is required
  31.                for the makefile to work.
  32.  
  33.              - The documentation now mentions that getopt (distributed
  34.                with Turbo C in source form only) is required and
  35.                discusses the implications (the compiled version uses a
  36.                private version of getopt which does not respect the
  37.                switch character as does the one in the Turbo C
  38.                distribution.
  39.  
  40.  
  41.         Description.
  42.  
  43.         NAVYTIME calls the 1200 baud Naval Observatory time service for
  44.         digital clocks at (202) 653-0351 and sets the system time.
  45.         Because of delays in the phone system, the time may be off by as
  46.         much as .5 second.
  47.  
  48.  
  49.         Installation.
  50.  
  51.         Before using NAVYTIME certain things have to be set up.  The
  52.         program must know the time zone and whether daylight savings time
  53.         is used.  This is done by setting an environment variable TZ with
  54.         the command
  55.  
  56.              set TZ=xxxnyyy
  57.  
  58.         where xxx and yyy are any letters and n is the number of hours
  59.         NAVYTIME -- Get Date/Time from Naval Observatory    Page 2
  60.  
  61.  
  62.         behind Greenwich Mean time for standard time.  If yyy is omitted,
  63.         the NAVYTIME assumes that daylight savings time is NOT used.  xxx
  64.         and yyy are intended to be the abbreviation for the time used
  65.         (xxx for standard time, yyy for daylight savings time).
  66.  
  67.         For example, if the area you are in uses Eastern Standard/Eastern
  68.         Daylight time, the command would be
  69.  
  70.              set TZ=EST5DST
  71.  
  72.         (Eastern Standard is 5 hours behind GMT).  If Eastern Standard is
  73.         used throughout the year, the command would be
  74.  
  75.              set TZ=EST5
  76.  
  77.         Note that the number of hours behind GMT may be more than one
  78.         digit (in the Pacific) or may be negative (in most of Europe,
  79.         Africa, and Asia).  The program, however, determines if Daylight
  80.         savings time is in effect based on the United States conventions.
  81.  
  82.         It will also be necessary to modify the the configuration file,
  83.         NAVYTIME.RC.  Users not in the Washington DC local calling area
  84.         will have to change the phone number on the second line to
  85.         include the area code.  If your modem is not on COM1 or is not
  86.         compatible with the Hayes 1200, other changes will be required.
  87.  
  88.         The configuration file has a rather inflexible format.  Each line
  89.         has a specific meaning.  It is important that there be no spaces
  90.         at the ends of lines.  The lines have the following meanings
  91.  
  92.              Line      Meaning
  93.              ----      -------------------------------------------------
  94.                 1      The COM port to use.  Only 1 and 2 are supported.
  95.  
  96.                 2      The command to initialize the modem and dial.  It
  97.                        consists of any combination of the following
  98.  
  99.                             - Strings in quotes which are sent to the
  100.                               modem verbatim.
  101.  
  102.                             - Pairs of the form ^x where x is any
  103.                               printing character which results in the
  104.                               control character corresponding to x to be
  105.                               sent.  For example, to send a carriage
  106.                               return, include the pair
  107.  
  108.                                       ^m
  109.  
  110.                             - Integers which specify a delay in tenths of
  111.                               a second.  To pause one second include the
  112.                               integer 10.  Numbers larger than 3600 (if
  113.                               your modem needs a delay any where close to
  114.                               that, you have my deepest sympathy) will
  115.                               not work properly.
  116.         NAVYTIME -- Get Date/Time from Naval Observatory    Page 3
  117.  
  118.  
  119.                             - Any other characters, typically spaces,
  120.                               which are ignored.
  121.  
  122.                 3      The command to send to terminate a call.  This
  123.                        line may be empty if the modem is configured to
  124.                        disconnect when DTR is dropped.
  125.  
  126.                 4      The string to match to recognize establishment of
  127.                        a connection.  The modem must send a connection
  128.                        message terminated by a carriage return or line
  129.                        feed.  A message containing this string in any
  130.                        position (for example, NNEC will match CONNECT)
  131.                        will be taken as indicating that the connection is
  132.                        complete.  Upper and lower case letters are
  133.                        considered different.
  134.  
  135.              4-19      Up to 15 strings to match to recognize failure to
  136.                        make a connection.  These are matched in the same
  137.                        way as the connect string.
  138.  
  139.         An alternate configuration file for the Racal Vadic 2400V (and
  140.         possibly other Racal Vadic) modems is included as NAVYTIME.RV.
  141.  
  142.         Finally, it is necessary to inform the program where the
  143.         configuration file will be found.  Normally, it assumes that the
  144.         configuration file will be C:\ETC\NAVYTIME.RC.  If this is not
  145.         convenient, set the environment variable NAVYTIME to the full
  146.         name of the configuration file.  For example, if the file will be
  147.         D:\CONFIG\NAVYTIME.CFG, use the command
  148.  
  149.              set NAVYTIME=d:\config\navytime.cfg
  150.  
  151.  
  152.  
  153.         Using NAVYTIME.
  154.  
  155.         If invoked with no parameters, NAVYTIME will call the time
  156.         service and set the DOS time, displaying no messages if
  157.         successful.  If the command line parameter -v is given, the time
  158.         will be displayed.  If the parameter -vv is given, modem messages
  159.         will also be displayed.
  160.  
  161.         NAVYTIME does not set a battery backed up clock unless this is
  162.         done by MSDOS when the DOS time is set.  To set a battery backed
  163.         up clock, invoke NAVYTIME with a batch file includes a command to
  164.         set the battery clock from the MSDOS time.
  165.  
  166.  
  167.  
  168.         For the Hacker.
  169.  
  170.         NAVYTIME is written in Turbo C.  Since one of the reasons for
  171.         writing this program was to evaluate Turbo C, no attempt was made
  172.         to keep compatibility with other versions of C.  Most other C
  173.         compilers will have difficulty with the prototype declarations
  174.         NAVYTIME -- Get Date/Time from Naval Observatory    Page 4
  175.  
  176.  
  177.         and the inline assembly code of comm.c.
  178.  
  179.         The function getopt is used.  This function is included with
  180.         Turbo C in source form only.  If generating NAVYTIME.EXE, this
  181.         function must be included in CS.LIB or the makefile must be
  182.         modified to compile and link getopt.obj.
  183.  
  184.         Four files, COMM.C, TIMER.C, ATFINISH.C, and SETTZ.C will be of
  185.         general interest to Turbo C programmers.
  186.  
  187.         COMM.C implements simple interrupt driven output, polled input to
  188.         COM1 and COM2.  The main limitations are no checking for parity
  189.         or other errors and flow control is not implemented.
  190.  
  191.         TIMER.C is a simple stopwatch timer.  Because of MSDOS
  192.         limitations, timer completion must be polled with chk_timer().
  193.  
  194.         ATFINISH is similar to the library function ATEXIT except that
  195.         the registered function will always be executed when the program
  196.         terminates (ATEXIT functions are executed only on normal
  197.         termination).  Up to 8 functions may be registered.
  198.  
  199.         SETTZ sets the time zone from information in the DOS environment.
  200.  
  201.         These functions may be used for both free and commercial
  202.         distribution provided my copyright notice is included.
  203.         Commercial distributions may not include source or relocatables.
  204.