************************************************************
* *
* *
* T E R R A * T I M E *
* *
* Version 2.1 *
* *
* (C)opyright 1988 *
* All Rights Reserved *
* *
*==========================================================*
* *
* GeoGraphics Software *
* 126 Mountain View Road *
* Glastonbury, CT 06033 *
* *
*----------------------------------------------------------*
* *
* Terra*Time is user-supported software provided to *
* you at no charge on a trial basis. If you use this *
* software and find it of value please register your *
* copy for $15.00 and support the shareware concept. *
* Registered users will be provided with information *
* about program updates. Please make checks payable *
* to G. K. Marek at the above address. *
* *
* You are encouraged to share this software with *
* others provided that it is distributed complete *
* with documentation and in unmodified form and *
* that no fee or other consideration is charged or *
* accepted. All commercial, business and government *
* users must register each copy in use. *
* *
* We hope you enjoy using Terra*Time. Your comments and *
* suggestions to improve this product are always welcome. *
* *
* *
* *
************************************************************





PROGRAM DESCRIPTION

Terra*Time is a program which tracks and displays the local time in as
many as 44 cities all around the globe. Unlike other programs of this
type, Terra*Time accounts not only for time zone effects but also for
daylight savings time at each city. Information is provided on a
full-screen color non- graphics display. Windows and menu-driven
commands are used for program modifications. Program options provide
users with the ability to tailor the display for their specific needs.
As many or as few cities as desired can be displayed. Military or 12
hour clock can be selected and the layout of the world map can be varied
to suit the user. Additional program features include time zone
differences and great circle distances between cities and a special
alarm feature which can be set for any world city time.


HARDWARE REQUIREMENTS

This program is designed for IBM Personal Computers and close
compatibles. It will execute on the IBM-PC, PC-XT, and PC-jr. DOS
Version 2.0 or later is required. Terra*Time does not require an internal
clock and will accept the time set by you during DOS boot-up. Of
course, the use of the internal clock will allow for automatic
timekeeping.

Since the program relies extensively on color, a color monitor is
recommended. The program will run, however, unmodified, on the Compaq.
Terra*Time requires about 64K of memory and does not require BASIC to
operate.


PROGRAM FILES

The Terra*Time system comes in five files:

TT.EXE executable program module
TT.DAT default settings and cities information
TT.DOC documentation file (ASCII); (this file)
TTDAT.BAK a back-up duplicate copy of TT.DAT
TTREAD.ME a short program description with latest changes

The first two files must reside on the current directory or path for the
program to be accessible.

None of these files is copy-protected and it is suggested that a set of
backup files be made and saved in a separate place with your other
archive and backup files. Save all five files in their original state
to preserve initial program default settings and cities information and
to have a complete package to provide to other users. Or, save the
original archive file TERRA.EXE and just run it again for a fresh
copy of all the files (TERRA.EXE is a self-extracting archive file).

Terra*Time is executed from the current directory or path with this
command at the DOS prompt: TT

There are no optional arguments.


PROGRAM START-UP

Upon execution, Terra*Time will load from the current directory and access
the TT.DAT data file to load current settings and cities information.
Once the program and data are loaded, the program no longer requires
these files unless a new configuration is saved to disk for future use.
The program is virtually self-explanatory and uses menus extensively.
The program will load into [AutoTime] mode incorporating the default
values and cities information in TT.DAT at time of execution.


GENERAL PROGRAM FEATURES

Terra*Time generates a stylized world map with cities indicated by three
letter codes. The map is divided into 24 time zones each of which is
further divided into three twenty-minute segments. One timezone,
normally the one you are in, is specially designated as the "local"
timezone. The local timezone (initially set by the program defaults to
New York) is indicated on the top scale by a magenta symbol. Time and
date details about the local time zone as indicated in the center of the
black area below the world map. The local time indication is standard
time if it is shown in yellow and daylight savings time if it is shown
in brown.

The black background on the map itself indicates the portion of the
globe between 6PM and 6AM (that is, approximately "nighttime") and moves
with the time in twenty minute intervals. A gray band will appear
momentarily around the display border while the map is being updated.
Cities are indicated on the map in bright yellow if they are presently
on standard time and in brown if they are presently on daylight savings
time.


HOUR-DAY SCALE

Across the bottom of the world map is an hour-day scale with some
features in white and some in yellow. The white (upper) scale indicates
the STANDARD time in that particular world zone. One point on this top
scale is the yellow letter M which represents midnight; N indicates
noon. The lower scale, in yellow, is in the form:

<< Sun | Sat >>

and is used to determine the day of the week for any time zone. The
symbol | represents the International Date Line in the central Pacific
Ocean. From this symbol to the left (west), it is Sunday until the M
(midnight) symbol is encountered on the scale above. It is Saturday
toward the east until the M symbol. Of course, the scale wraps around
at the left and right edges of the map.


A WORD ABOUT TIME SYSTEMS

Terra*Time displays time using the standard US AM/PM 12 Hour Clock and the
International (or Military) 24 Hour Clock. However, for simplicity, all
INPUTS to Terra*Time must be given using the 24 Hour Clock (the same as
DOS). Some examples of the relationships between the two systems are
shown below:


US/12 Hr Intl/24 Hr Input Input
HH:MM:SS HHMM

MIDNIGHT 12:00 AM 00.00 00:00:00 0000
12:37 AM => 00.37 00:37:00 0037
1:24 AM 01.24 01:24:00 0124
11:08 AM 11.08 11:08:00 1108

NOON 12:00 PM 12.10 12:00:00 1200
12:15 PM => 12.15 12:15:00 1215
3:59 PM 15.59 15:59:00 1559
11:49 PM 23.49 23:49:00 2349



The ACTUAL local time (whether daylight or standard) should be input and
Terra*Time will take care of the rest. If you have an internal computer
clock, you must set it forward and back during switches between daylight
and standard time just as you do with your other clocks.

Some computers have clocks that lose the seconds when time is reset.
For example, the time 10:15:53 would be set to 10:15:00 and 53 seconds
would be lost. In these cases time adjustments should be made just
after the minute has turned to minimize time loss effect.



PROGRAM FEATURES

Terra*Time incorporates a number of special features and options which are
explained below. These features are accessed by selecting the letter
[F] from the [AutoTime] mode.


CITY CODES

Some features require that a particular world city be identified. Each
city has been assigned a three letter abbreviation. These abbreviations
can be changed to suit the user. For example, the code NYC could be
changed to JFK to represent Kennedy airport, or to HQ, for Corporate
Headquarters (Three letters is a maximum for this code). It could even
be altered to HFD, for Hartford, Connecticut, a nearby city with the
same parameters as New York.


ALARM

The Terra*Time alarm can be set for a specific time in a specific world
city. This could be the local time or the time in a foreign location.
For example, assume that you are in New York. You can set the clock to
ring when it is 7PM (1900) in Paris without having to compute time
differences simply by indicating PAR and 1900 when the alarm is set.
Terra*Time keeps track of the timezones and any savings time that might be
in effect at either city.

Activating the alarm will illuminate a note in the lower left corner of
the screen. The alarm will ring at the appropriate time, chiming every
five seconds for one minute or until any key is selected to stop it.
The alarm will be turned off once it has rung and will have to be
activated again even to ring again at the same time on the next day.
The command [Activate] will engage the alarm with the current settings
unchanged. The [LOC] city code can be used for local time alarm. Be
sure to input the alarm time in HHMM format, two digits for the hours
and two for the minutes using a 24 Hour clock.


TIMEZONES

The [TimeZones] feature allows you to check the number of hours
(timezones) any city is ahead or behind any other. A base zone is
initially set to the local city but can be moved to any other city, one
zone at a time, with the [W]est or [E]ast keys.


DISTANCES

Terra*Time can also compute the distance between any of the cities in the
program database (not just those shown on the map). A listing of cities
can be selected. The distance shown is the "great circle distance,"
which is the shortest distance between the two points on a globe. This
distance is provided in statute miles (ordinary measure) or in nautical
miles, a system used extensively in navigation. One nautical mile is
about 1.151 statute miles.


TIMESET/DATESET

Times and dates must be valid and follow the format specified. Dates
cannot precede 1980 since DOS will not recognize any date before
1-Jan-1980. Since the Local Time display also computes the
day-of-the-week, this feature will allow the determination of the
day-of-the-week on which some future date will occur, such as a birthday
or Christmas.


MAPSHIFT

The displayed map can be centered on the US, on Europe, or on the Far
East with this option. There is no effect on the time.


12/24 HOUR SELECTION

The times displayed with the cities on the map can be presented in
either US 12/Hr format or Intl 24/Hr format using this option.


LOCALZONE

Any city in the Terra*Time city list can be designated the Local time
city. The Local Time strip in the black area below the map will take on
the attributes of this designated city and the LocalZone marker on the
top scale will move. When a new LocalZone is selected the times in all
cities remain unchanged. Only the alarm, local time strip and other
features using the local time are affected.


HELP COMMAND

A Help Screen with a Brief description of these features is available in
a window within the [Settings] option of the program.


FILE COMMAND

When you have chosen a configuration of features and cities that you
prefer, they can be saved to the TT.DAT file and subsequently
automatically loaded with the program. Any changes made in program
features or options will be in effect only for the remainder of the
current session unless they are saved with the [File] command. Once a
new configuration is saved (in file TT.DAT) the previous configuration
is lost. Be sure a backup copy of the original program and data files
has been saved in case you want to start over or reinstate the original
options. A file called TTDAT.BAK is provided as a backup duplicate of
the original TT.DAT file. Ensure that the file containing the
information to be displayed is called TT.DAT before the program is run.


CITIES COMMAND

The [Cities] settings command allows the user to see and change the
attributes of the cities provided in the Terra*Time database. For
example, any city can be excluded or included from the map display. The
following information about each city is displayed and can be altered as
indicated.

CODE - The city code is a one to three letter designation. This code is
used to identify the city on the map and to select and save city
features. Any code except LOC can be selected. For example, NYC could
be replaced by MAN (for Manhattan).

INCLUDE/EXCLUDE - If this parameter is set to INCL, the city is included
in the map display; if EXCL is selected, the city will not be displayed.
The [List] command will provide a list of all of the cities in the
Terra*Time database, indicating whether or not they are included in the
display. Although the default settings do NOT include all of the
cities, all cities are designed to fit on the display map without
overlap (although leaving a somewhat cluttered appearance).

ZONE - The zone parameter represents the number of timezones east
(positive) or west (negative) of the Prime Meridian (Greenwich, England)
that the subject city lies. For example New York Zone is -5.0 and Paris
is 1.0. Some cities are in timezones which are not an exact integer
number of hours from GMT (Greenwich Mean Time). Bombay, India, for
example, is 5 and one-half hours ahead of GMT. Its zone is indicated as
5.30, with the 30 indicating 30 minutes more advance than five hours.
The zone parameter is for information purposes and should not ordinarily
be changed.

DAYLIGHT

This parameter is either 1 (if Daylight Savings Time is ever applicable
to this city) or 0 (if is not).


START

This is a four digit value which indicates the month and day that is the
first day of daylight savings time. It is specified in the form MMDD,
so 0531 would mean May 31st is the first day of daylight savings time.
DD can be specified as 00 to indicate that the day should be the last
Sunday of that particular month; for example 0400 would mean that
daylight savings time should start the last Sunday of April.


END

This value indicates the LAST day of daylight savings time. Otherwise,
the comments indicated above for START apply. Note that it is possible
for the END date to precede the START date when summer comes in the
months of December, January and February as it does in the Southern
hemisphere.


DAYLIGHT SAVINGS TIME

Daylight savings time is a convenience adopted by many localities during
the summer months depending upon their particular needs and their
geographic location. The information provided for the cities in
Terra*Time was accurate for 1987-1988. But these rules are subject to
change depending upon legislation in each country. For this reason
Terra*Time allows the changing and saving of information relating to
daylight savings time in the [Cities] menu. Data regarding country time
zones and daylight savings time rules is available from the local
library or in a reference called the Official Airline Guide (copyright
Reuben Donnelly & Co.) which is published monthly and used by most
travel agents in the United States.


ADVANCED PROGRAMMING CONSIDERATIONS

Terra*Time is compiled in Basic and reads all of the city information as
well as the default settings from an ASCII file called TT.DAT. This
file can be editted with any text editor. The first line of the data
file contains a 30 character header which will appear centered on the
top portion of the display. This line can be revised to display any
heading the user desires. The next two lines of the file contain
default settings, followed by 44 lines of city data and a terminating
line. Only advanced users should revise this file since its formatting
is critical to ensure proper reading of the data by the program. Always
keep a backup copy just in case. There is little value to changing the
second and third (default values) lines of this file, but it may be
useful to edit the cities data on the next 44 lines if extensive
revisions are desired. The format of some typical city data lines is
presented here:

COLUMN 1 2 3 4 5 6 7
12345678901234567890123456789012345678901234567890123456789012345678901

FIELD A B C D E F G H I J K

"CAPETOWN", 0, "CPT", 231, 18, 2.0, 0, 0, 0, -32.83, -17.88
"CARACAS", 1, "CAR", 50, 13, -4.0, 0, 0, 0, 11.00, 67.63
"CHICAGO", 0, "CHI", 71, 8, -6.0, 1, 405, 1000, 42.63, 88.50




A comma must delimit each field and the alpha characters must be in
quotes as shown. The fields have the following meanings:

A => The city name
B => Code to include plotting on map for that city (1) or not (0)
C => One to three letter city code for plotting on map
D => A code for horizontal plotting location of that city (see below)
E => A code for vertical plotting location of that city (see below)
F => The time zone from Greenwich, England, with eastbound positive
G => Code to indicate daylight savings time is applicable (1) or not (0)
H => Code for start of daylight savings time (described in START above)
I => Code for end of daylight savings time (described in END above)
J => Latitude of city in Degrees and Minutes, with North positive
K => Longitude of city in Degrees and Minutes, with West positive

The 44 cities have been carefully selected and plotted so they remain
true to their intended time zone but so that no two can overlap no
matter how they are displayed. Thus any or all cities can be displayed
at once. Changing Code D or E will cause different plotting locations
and could result in overlaid data or program problems.

Code E is a number between 6 and 19 which represents the vertical
plotting location for the given city. The sixth row down is the highest
(northernmost) plotting location. The 13th row represents cities that
fall along the equator such as Dakar, in Africa. The 19th row is the
southernmost plotting position and Auckland, New Zealand, is at this
lower latitude. You will be able to tell where to plot a new city by
looking at the value of Code E for the cities around it. All selections
for this parameter must be integers from 6 to 19. The remainder of the
screen is reserved and other values will produce unpredictable results.

Code D is a value which determines the horizontal plotting location of a
particular city. This code is more complicated than Code E and must be
deciphered to be understood. The map grid is divided into 24 horizontal
areas, each of which allow three plotting positions, for a total of 72
horizontal plotting locations. If the last digit of Code D is dropped,
the remaining value is always between 1 and 24. This code represents
one of the 24 plotting regions starting with London as 1 and moving
westward with New York as 6, Hong Kong as 16, Bombay as 20, and finally
Paris as 24 (since it is east of the Prime Meridian). Note that the
last digit of the code is always a 0, 1, or 2. This digit represents
the plotting position of the point within the main region with 0
westmost, 1 central and 2 eastmost plotted. Thus Chicago, with Code D
of 71, is plotted in the central portion of the 7th zone west of zero
degrees latitude (London). Note that from west to east the plotting
codes would follow a sequence such as 70,71,72,60,61,62,50,51 etc.
Again, unpredictable results will occur if these conventions are not
followed.

Remember that some of the cities in the program have been moved slightly
from their true geographic positions so that they could all fit on the
map at once if so desired. If you plan to use fewer cities they could
probably be plotted more precisely without worry of overlap.

Since there has been much interest in plotting other US cities, below is
a list of more precise plotting codes for some of them. Turn off (or
"EXCLude") the US cities you don't want that would overlap and replace
one of them with the info for your home city. You can have no more than
44 cities in the data file (although you can have fewer). Never delete
the last line of the data file since it is a signal for the program that
all the city data has been read in.

City Code D Code E
-------------- ------- -------
Atlanta 60 11
Boston 62 10
Chicago 60 10
Dallas 82 11
Denver 80 10
Detroit 60 10
Los Angeles 92 11
Miami 60 11
Minneapolis 70 9
Montreal 62 9
New York 62 10
San Francisco 91 10
Seattle 91 9
Washington DC 62 10
Vancouver 91 9

This program uses special functions from the excellent Advanced Function
Library for the Basic Compiler called ADVBAS.LIB v3.4, (C) Thomas Hanlin
III, Alexandria, VA, available on many bulletin boards.

Some copies of Terra*Time are distributed via an excellent self-
extracting archive program called PKARC version 3.5, dated 27 April
1987, and available from PKWARE, Inc., 7032 Ardara Avenue, Glendale, WI
53209.

I hope Terra*Time will prove to be of value to you. Please contact the
author with any problems, useful comments or suggestions at the address
at the top of this file.