Earth&Sun Program for the Palm OS
Version 2.0*

Description

Earth&Sun is a program for the Palm OS to show the Sun Illuminated area of the Earth.
It will also display: Earth&Sun can be used as a realtime clock if you have a Palm that can run in its charging cradle, or use a Palm simulator on your computer.

Because of time zone irregularities some will consider Earth&Sun to fall into the category of "fun and games".
We hope you find Earth&Sun useful and enjoy it.

What's new in Version 2.0

About This Documentation

Earth&Sun is intuitive and easy to use. This documentation probably seems large, but you really should read it to fully understand all of the features.
For a Quick Start read Installation. Then after trying it out please return to this documentation to learn all of the features. Sections:

Installation

This archive file includes:
earth20.prc
The executable file.
MathLib.prc
The required mathematics library -- V1.1
earth&sun.html
This file -- earth&sun.html.
es2xsolid.gif, es4xgray.gif, esDisp1.gif, esDisp2.gif, esMenu.gif, esPref.gif, esRef.gif, esTimeInc.gif
Images for earth&sun.html

Be Aware -- If you have any Version 1.x of Earth&Sun installed, you must delete it before installation of this V2.0 version

Use the Palm desktop installer to install earth20.prc. Earth&Sun requires MathLib.prc*. If you already have MathLib.prc installed just install earth20.prc, otherwise install both earth20.prc and MathLib.prc.
The included MathLib.prc is the latest version (V1.1 dated 4/14/1999). You may update with this one if you desire.


Using the Program

The shaded area is that part of the world that is dark at the current time. The location where the Sun is directly overhead is shown by a little icon which is a + sign outlined in reverse 'color'. It is difficult to see in the screen shots shown here. You can find it located near the equator just south of Florida in the image at the top right.

Hopefully program usage is pretty much self evident once you have followed these instructions.
Earth&Sun has two modes of operation: Time Mode, and Distance Mode. Initially it is in the Time Mode.

Upon first use you will be greeted with a message requesting you to tell Earth&Sun the time zone to which the Palm's clock is set. This is an offset from GMT (Greenwich Mean Time). If you do not set this the display will always be incorrect!
Do this using the Commands/Prefs.. menu. The Command menu choices are shown to the right.

First just set the Palm's Clock Time Zone and check Daylight Time if applicable.
(See GMT offset time zone table if you do not know what to enter.)
Don't forget to use the pop-up choice menu to select your location either 'West' or 'East' of Greenwich.

The 'Done' button will set the value and return to the main screen.
Below is a discussion on the 'Night Shading' and 'RealTime Clock' in the Prefs.. menus. Ignore them at first.

Time Mode

To understand the following instructions first tap the pen on an earth location.
Look at the first and second rows of the text output display area from left to right.
For the tapped location: Looking at the third row of the output display from left to right: Looking at the fourth row of the output display from left to right: Hardware Scroll Buttons
The Up/Down hardware scroll buttons in the lower center of the Palm allow you to simulate time changes in increments of: 1, 3 and 6 hours. Pressing the Up bottom advance time and the Down button decreases time. You can change the time increment/decrement value using the Time Incr menu. Wrapping time around for 24 hours does not change the date.

Distance Mode

You switch between the Time and Distance Modes with the Commands menu, or simply by tapping the word 'Time' ('Loc') on the first line below the map.

In the Distance mode the text output display area changes as shown on the right.
Tap a location on the map. For the tapped location:

Next tap the '2' button on the third line and it will become highlighted. Then tapping the map will fill in the data for Loc 2 and change the distance to reflect the new location. 'Br:' is the great circle bearing from Loc 1 to Loc 2.

Show Ref.

A Reference Location is for you to enter a location for which you would frequently like to find the sunrise and sunset; your home for example.
The 'Show Ref.' menu item simply displays the current time/rise/set information (second text line) for the reference location set by the 'Import Ref.' or 'Set Ref.' menu items. See below.

There are two additional ways to display the reference data.

Import Ref. Menu

The 'Import Ref.' menu item imports the currently selected location from the GeoDB database into Earth&Sun's reference.
When 'Import Ref.' is tapped nothing will appear to happen except that the Command menu will disappear. However, you can then obtain the data for that location by any one of the there methods discussed in the 'Show Ref.' paragraph above.
Of course, GeoDB must be installed on your Palm and a location in GeoDB must have been selected.

You can view the imported data by tapping the 'Set Ref.' menu item.

If you don't have GeoDB it is available at: http://www.40-below.com/palm/. It is a small application and the installation is simple.

Set Ref. Menu

You may enter the Reference Location data manually using the 'Set Ref.' menu. The format to enter latitude and longitude is:
  1. Degrees -- e.g. 44.6427
  2. Degrees:Minutes -- e.g. 44:38.562
  3. Degrees:Minutes:Seconds -- e.g. 44:38:33.72
    The only allowable input characters are: digit, '.' and ':'. That is, digit, period, and colon.

Be sure to set the correct direction for the location -- West, East, North or South using the pop-up selection list to the right. The pop-up selector lists choices are only East or West, or North or South.



Pref.. Menu

Night Shading
Returning to the Pref.. Menu, you have a choice of how the night shading is displayed. For each of the map scales you can select the shading to be stripped solid lines of the entire night area grayed. Simply use the pop-up choice menus to select your desired shading. The advantage of gray shading is that the country/state boundaries will show through the shading, as seen on the right.

RealTime Clock


If you have a Palm which is plugged into external power (such as Palm V or a computer Palm simulator) you may use Earth&Sun as a real time clock. Simply check the 'RealTime Clock (Palm V)' checkbox.
When that box is checked and the Palm is plugged into external power, the Time Selector box will be in synchronism with the Palm clock and the map will be updated every 5 minutes. Five minutes is the smallest time which can show a Sun shadow change. When the external power is removed the updating will stop.

More on Palm's Clock

If you live in an area of the world that uses a clock set one-half hour off from the usual 1 hour time zone offsets (and your Palm Clock is set to the local time), you may set the GMT Offest on the half hour. For example in South Australia you would set the offset to: 9.5 East.
In this case tapping various locations the time shown will be correct for those locations that are on the usual hour offset. This means that tapping at your own location, it will be shown on an hour offset. However if your reference is set to your home the time shown for the reference will be correct.

Sometimes it may be required to tap a location twice the first time that Earth&Sun is activated to get the time synchronized.


More Details

Sunrise/Set Time Values
You may find that the sunrise and sunset times may be different in the 1X, 2X and 4X modes. The reason for two different calculation is a matter of accuracy of pen positioning. On the 1X display it is difficult to locate a particular latitude/longitude.

The sunrise/set times are accurate for the displayed latitude/longitude. See for discussion on the Normal/Freeze Button which follows. This gives an example of different times at different longitudes.

Back to the first row discussion.

Normal/Freeze Button
Since the time zone is based solely on longitude the Normal/Freeze button allows you to freeze a time zone so that in the 2X and 4X modes you can find sunrise/set times for locations which do not follow normal time zone rules. For example: Alaska which extends over 4 time zones, Russia and China which extend over 3 times zones. Also there are locations like western Texas where the time zone boundary is very much west of where it should be.

To use this feature put the pen down on a location which is in the desired time zone. For example: Alaska time is 9W, so tap the map on eastern Alaska and verify that the time zone is 9W. Then observe the sunrise/set times. Next tap the (N) button. It will change to (F) -- Freeze. Then tap the western part of Alaska and the sunrise/set time should be about 2 hours later. Now tap the far western Aleutians Islands and see the sunrise/set advance another hour. Note that the time zone still reads 9W.

With a frozen time zone it is possible that the sunset could occur in the next morning. In this case the time might be, e.g. 24:10. The same is true for sunrise except it might occur the previous night, with a sunrise e.g. of 23:45. Note: In these cases the Date Selector does not change.

Back to the third row discussion.

Contact Info

Earth&Sun was created by David W. Bray, Potsdam, NY;
Copyright © 1999-2004 David W. Bray, All Rights Reserved.

The Bray Palm OS Page can be found at: http://www.40-below.com/palm/

Registering

Earth&Sun is freeware no registration is required. We hope you enjoy using it.

This archive may be freely redistributed, provided it is made available only in its complete, unmodified form with no additional files and for noncommercial purposes only. Any other use must have prior written authorization from David W. Bray.

Unauthorized commercial use includes, but is not limited to:

Disclaimer

This program is provided without warranty and the user accepts full responsibility for any damages, consequential or otherwise, resulting from its use.

Foot Notes

* Many thanks to Rick Huebner, the author of MathLib, for his excellent routines and making them freely available.

GMT Time Zone Offset is the number of hours the Palm's local clocks differ from that of Greenwich Observatory in England. Set the Time Zone menu to correspond to the following table according to your location.

United StatesAround the World
Time ZonesOffsetTime ZonesOffset
Eastern 5 West British Isles 0 East
Central 6 West Western Europe 1 East
Mountain 7 West Eastern Europe 2 East
Pacific 8 West So. Africa 2 East
Alaska 9 West Russia 3 East
Hawaii 10 West Japan 9 East
  South Australia 9.5 East
  Eastern Australia 10 East

Back to "Using the Program"

*Program Changes in Version 2.0

Earth&Sun Version 2.0 differs from earlier versions in:
  1. Distance Mode is added. (V1.1)
  2. Reference Location for quick data update entry added. (V1.1)
  3. Palm V RealTime Clock mode added. (V1.1)
  4. East/West/North/South letter indicators changed from uppercase (E/W/N/S) to lowercase (e/w/n/s). The S looked too much like a 5. (V1.1)
  5. Map display shows terminator line by one dot in reverse 'color'. (V1.1)
  6. Improved display for all time values when the timezone Freeze mode is in effect (See Normal/Freeze button above.) (V1.1)
  7. Removed Reference Timezone rounding to make it exact for both 1X & 2X. (V1.2)
  8. Changed title to be left justified and added tap of data line for Reference Info. (For OS3.5). (V1.2)
  9. Added a menu entry 'Ref. Info.' had Ref. Info. be displayed at application start-up. (V1.2)
  10. Added a mark on the the map at the tapped location. (V2.0 Bld:249)
  11. Added a 4x map and a choice of stripped or grayed night. (V2.0 Bld:249)
  12. Added a name for the 'Ref. Info.' and display it when tapping the title. (V2.0 Bld:249)
  13. Added the ability to import the 'Ref. Info.' from GeoDB. (V2.0 Bld:249)
  14. Allow 1/2 hour clock GMT offset. (V2.0 Bld:249)
  15. Bug in Palm TxtCharIsDigit() - replaced by local routine. (V2.0 Bld:303)
  16. Changes to improve OS4 compatibility (V2.0 Bld:316)
  17. Fixed bug in D/S mode rise time. (V2.0 Bld:320)
  18. Palm GUI fix to default to item 0 for trigger popups. (V2.0 Bld:340)
A Bld: (build) has been added to the version number in the 'About' box. To be sure that your version is up-to-date check the Bld: number in the description of Earth&Sun at: http://www.40-below.com/palm/

The original release of Earth&Sun V2.0 is Bld:249.
The current Bld: is 320.