File: G:\Long-Term Storage\DATA\SunCalc\SunCalc.

guide 3/6/1998, 8:49:50 PM

@database 0218f020-1
@master SunCalc.guide
@$VER: 1.0
@remark Created with Heddley v1.1 (c) Edd Dumbill 1994

@node "Main" "Table of Contents"

======================================================================

@{b}SunCalc V1.1a

Brian Savage (C)1998@{ub}

======================================================================

@{"Distribution" link "Document_0" 0}

@{"Introduction" link "Document_1" 0}

@{"Installation" link "Document_2" 0}

@{"Usage" link "Document_3" 0}

@{"Contacting the Author" link "Document_4" 0}

@{"References" link "Document_6" 0}

@{"Acknowledgements" link "Document_7" 0}

@{"History" link "Document_5" 0}

@endnode

@node "Document_0" "Program and Distribution Notes"

@{b}Program and distribution notes@{ub}

SunCalc is (C) 1998 by Brian Savage and it is freely distributable as long as

all of its files are included in their original form without additions,
deletions, or modifications of any kind, and only a nominal fee is charged
for its distribution.

SunCalc is EmailWare and as such is completely FREE! All I ask is that if

you like SunCalc and find it useful, please send me an @{"email" link "Document_4" 0}
giving your name
and the country that you live in.

Permission is required by the author for inclusion of SunCalc on magazine

disks or CDROMS with the exception of the Aminet CD.

This software is provided "AS IS" without warranty of any kind, either
expressed or implied.
@endnode

@node "Document_1" "Introduction"

@{b}Introduction@{ub}

SunCalc is a Shell based program which calculates Sunrise and Sunset for a
particular location given the longitude & latitude, time zone and date.

I have tested it for various locations throughout Canada and found it to be

accurate to within 1 minute when compared to the same locations on
Environment Canada's website: http://www.tor.ec.gc.ca/forecasts/ and when
compared with times given by @{"The Old Farmer's Almanac" link "Document_6" 0}.

Thanks to @{"several users" link "Document_7" 0} in Australia and New Zealand who

Page: 1
File: G:\Long-Term Storage\DATA\SunCalc\SunCalc.guide 3/6/1998, 8:49:50 PM

provided feedback
for Version 1, I can now say that SunCalc has been tested in the Southern
Hemisphere.

SunCalc requires WorkBench 2.04+. I have tested SunCalc with Workbench 2.1
and 3.1.

@{u}To Do@{uu}

Items still on the "to do" list include:

1. SunCalc GUI

2. Moon phases, rising & setting

If you have any other ideas @{"please let me know" link "Document_4" 0}.

I hope you find SunCalc useful.

@endnode

@node "Document_2" "Installation"

@{b}Installation@{ub}

Two versions of SunCalc have been included in this archive;

SunCalc - for all Amigas; and

SunCalc.030fpu - for Amigas equipped with at least a 68030

cpu and either a 68881 or 68882 math coprocessor. Do not use
this version if your machine doesn't meet these criteria as it may
crash.

Copy the appropriate version of SunCalc to the directory of your choice;

preferably in the command path - such as your c directory. Note - If you're
using SunCalc.030fpu, it can be renamed to 'SunCalc'.
@endnode

@node "Document_3" "Usage"

@{b}Usage@{ub}

Running SunCalc without any arguments calculates the Sunrise and Sunset for
the default location (where I live in Halifax/Dartmouth Nova Scotia, Canada)
for the current system date with the Daylight Savings Time flag set to
FALSE/OFF/0 (ie. Standard Time).

Note: You can change the defaults by adding environmental variables - @{"see" link
"Document_3" 176}
@{"below" link "Document_3" 176}.

SunCalc was written mainly as a Shell/CLI program but it can also be used
from @{"WorkBench" link "Document_3" 146}.

@{u}Shell/CLI Usage@{uu}

Command format:

'SunCalc [?][date=dd-mm-yy][latitude=xx.xxx][longitude=xx.xxx]
[tz=xx][dst][text="output message"][odf=x][otf=x]'

@{u}Options:@{uu}

Page: 2
File: G:\Long-Term Storage\DATA\SunCalc\SunCalc.guide 3/6/1998, 8:49:50 PM

[date=dd-mm-yy] date to calculate (defaults to current system date)

[latitude=xx.xxx] latitude in decimal form (defaults to 44.8N)

[longitude=xx.xxx] longitude in decimal form (defaults to 63.52W)

[tz=xx] timezone (defaults to -4)

[dst] daylight savings time flag - TRUE if present

[text=output message] enter any string here for program output;

SunCalc will parse this string looking for Sunrise
($SR), SunSet ($SR) and Date ($DATE) variables
and replace them with calculated values. Further
customize output by adding newlines (\\n) and tabs
(\\t).

example: 'text="Sunrise and Sunset times on $DATE

for New York City are:\\n\\n\\tSunrise:
$SR\\n\\tSunset: $SS\\n"'

This will be output as;

'Sunrise and Sunset times on Saturday, 31 January

1998 for New York City are:

Sunrise: 7:35 hrs

Sunset: 16:35 hrs'

Make sure you enclose this string in double

quotations if string contains spaces. Date and
time formats for this string may be changed using
ODF and OTF arguments

ODF=x Output Date Format - choice of 4 possible formats

0 - dd Mmmmmm yyyy; ie. "31 January 1998"

1 - Weekday, dd Mmmmmm yyyy; ie. "Saturday, 31

January 1998"

2 - Mmmmmm dd, yyyy; ie. "January 31, 1998"

3 - Weekday, Mmmmmm dd, yyyy; ie. "Saturday, January

31, 1998"

OTF=x Output Time Format - choice of 2 formats:

0 - 24hr format in the form "1332 hrs"

1 - 12hr format in the form "1:32 pm"

[?] displays the argument template:

Page: 3
File: G:\Long-Term Storage\DATA\SunCalc\SunCalc.guide 3/6/1998, 8:49:50 PM

"DATE/K,LATITUDE/K,LONGITUDE/K,TZ/K,DST/S,
TEXT/K,ODF/K,OTF/K:"

Type "?" again to obtain full HELP message.

Notes: Do not enter latitudes and/or longitudes in

degrees/minutes/seconds - convert them to their decimal
eqivalents; ie. 45 deg 30 seconds = 45.5 degrees.

@{b}Examples@{ub}

1. Calculate the sunrise and sunset times for Boston, Mass. on 10 March 1986
at longitude 71.05 degrees W longitude and 42.37 degrees N latitude. The time
zone correction for Boston is GMT-5 (use -5 hours). The Daylight Savings
Time flag is not required as 10 March is Standard Time.

The correct command line arguments are:

suncalc date=10-3-86 longitude=71.05W latitude=42.37N tz=-5

The resulting program output is:

'Sunrise: 0605 hrs Sunset: 1744 hrs'

2. Using the data from example 1 above, add a text string to the output;
namely: 'For Boston, Mass. Sunrise at: $SR Sunset at: $SS'.

The correct command line arguments are:

suncalc date=10-3-86 longitude=71.05W latitude=42.37N tz=-5 dst=0

"text=For Boston, Mass. Sunrise at: $SR Sunset at: $SS"

The resulting program output is:

For Boston, Mass. Sunrise at: 0605 hrs Sunset at: 1744 hrs

3. Using the data from example 1 and 2 above, customize the output using
OTF, ODF, newline and TAB characters:

The correct command line arguments are:

suncalc date=10-3-86 longitude=71.05W latitude=42.37N tz=-5

text="\\nFor Boston, Mass. on $DATE\\n\\n\\tSunrise
at:\\t$SR\\n\\tSunset at:\\t$SS\\n" otf=1 odf=3:

The resulting program output is:

"For Boston, Mass. on Monday, March 10, 1986

Sunrise at: 6:05 am

Sunset at: 5:44 pm"

@{u}WorkBench Usage@{uu}

SunCalc may also be used from the WorkBench using the above arguments as
ToolTypes with the supplied icon. For example, lets try example 3 above from

Page: 4
File: G:\Long-Term Storage\DATA\SunCalc\SunCalc.guide 3/6/1998, 8:49:50 PM

the WorkBench instead of from the Shell.

Enter the following ToolTypes in the SunCalc icon:

date=10-3-86
longitude=71.05W
latitude=42.37N
tz=-5
text=\\nFor Boston, Mass. on $DATE\\n\\n\\tSunrise
at:\\t$SR\\n\\tSunset at:\\t$SS\\n
otf=1
odf=3

Save these TolTypes and double click on the icon. A small window will be
opened and the following text will be displayed:

"For Boston, Mass. on Monday, March 10, 1986

Sunrise at: 6:05 am

Sunset at: 5:44 pm"

To calculate sunrise & sunset for the current date, delete the DATE
tooltype.

Note that double quotations are not required around the string for the
'text' variable.

@{u}Environmental Variables@{uu}

To change SunCalc's default settings environmental variables may be used. The

names of these variables correspond to SunCalc argument and ToolType names.
These variables are as follows:

longitude
latitude
tz
dst
text
otf
odf

The only SunCalc argument which does not have an environmental variable
equivalent is 'date'. The default date is the system date. This default
cannot be changed.

SunCalc looks for its environmental variables in the "env/suncalc" directory.

If Suncalc doesn't find these variables here it will resort to using my hard
coded defaults (which aren't much use to anyone else). Environmental
variables are created using the AmigaDos 'setenv' command. To create an
environmental variable for 'longitude', try this from a Shell window:

setenv suncalc/longitude=75.05W

Now whenever SunCalc is used, the value of 75.05W will be used for
'longitude' as long as it is not overridden by a 'longitude' shell argument
or tooltype. In order for this environmental variable to remain in effect
after a reboot, you must copy the contents of your ENV:suncalc directory to
the ENVARC: directory prior to shutting down your computer or rebooting. See
your AmigaDOS manual for more information on environmental variables.

Page: 5
File: G:\Long-Term Storage\DATA\SunCalc\SunCalc.guide 3/6/1998, 8:49:50 PM

Example:

Let's try the 3rd example for the city of Boston once again this time using
environmental variables. From the a Shell window enter the following:

setenv env:suncalc/longitude=71.05W

setenv env:suncalc/latitude=42.37N

setenv env:suncalc/tz=-5

setenv env:suncalc/text="\\nFor Boston, Mass. on $DATE\\n\\n\\tSunrise

at:\\t$SR\\n\\tSunset at:\\t$SS\\n"

setenv env:suncalc/otf=1

setenv env:suncalc/odf=3

If Boston is your hometown you'll probably want to save this settings. If so

now type:

copy env:suncalc envarc: all quiet

Now whenever you use SunCalc, the above settings (as well as the system date)
are the defaults (When you reboot your computer there is a line in the
'startup-sequence' that copies the contents of ENVARC: to ENV:). To find
sunrise & sunset times as in the example on 10 March 1986, type:

suncalc date=10-3-86

The resulting program output is:

"For Boston, Mass. on Monday, March 10, 1986

Sunrise at: 6:05 am

Sunset at: 5:44 pm"

Remember that the values of these environmental variables are overridden by

Shell arguments and WorkBench tooltypes. Therefore to change only the output
date format to 2 (instead of 3) and leave everthing else the same, type:

suncalc date=10-3-86 odf=2

@endnode

@node "Document_4" "Contacting the Author"

@{b}Contacting the author@{ub}

Brian Savage
9 Wilton Cresent
Dartmouth, Nova Scotia,
Canada B2V 2S9

tel: 902-434-2993

@{u}email@{uu}: [email protected]

The latest version of SunCalc as well as many other programs I have

written for the Amiga are available from my homepage at:

@{u}http@{uu}://home.istar.ca/~bsavage
@endnode

Page: 6
File: G:\Long-Term Storage\DATA\SunCalc\SunCalc.guide 3/6/1998, 8:49:50 PM

@node "Document_5" "History"

@{b}History@{ub}

Version 1.0 (first Aminet release 23Dec97)

Version 1.1 (second Aminet release 14Feb98)

1. Corrected a bug which was causing sunrise & sunset times for some areas
Southern Hemisphere to be offset by 24hours.

2. Added better @{"Shell argument handling" link "Document_3" 15} - now uses DOS
Readargs
function.

3. Added ability to select output time and date formats

4. Added capability to further customize output string using TABS and

line feeds.

5. Added @{"environmental variable" link "Document_3" 176} support to override default

(hard coded)
settings.

6. As SunCalc makes heavy use of double precision floating point math, I

have included a version of SunCalc compiled for '030 cpus fitted with
a math coprocessor (68881/882). I personally haven't noticed any
difference between the two versons although you may.

7. Icon provided with instructions on how to use SunCalc from the WorkBench.

Version 1.1a (third Aminet release 7 March 1998)

1. recompiled 68000 version with SAS standard math library instead of

IEEE library as some math functions were giving incorrect results
(ie bugs). This was evident with weekday output variable which was
offset by one day. Executable now about 4k larger.

2. added cpu type to help screen in both 68000 and 68030fpu versions.
@endnode

@node "Document_6" "References"

@{b}References@{ub}

The astronomical algorithms used by SunCalc were derived from those as

presented by Peter Duffet-Smith in his book titled "Practical Astronomy with
your Calculator", Third edition 1988, ISBN 0 521 35699 7 published by the
Cambridge University Press.

Sunrise and sunset times were verified using in part "The Old Farmer's
Almanac", 1995 version, copyright 1994 by Yankee Publishing Incorporated,
Dublin, NH 03444.
@endnode

@node "Document_7" "Acknowledgements"

@{b}Acknowledgements@{ub}

I wish to thank Michael Johnstone in New Zealand and Frank Bunton in

Australia who provided feedback on using SunCalc in the Southern Hemisphere.
Frank Bunton has also written an Arexx script which adds environmental
variable support for Version 1 of SunCalc and is available on Aminet
(misc/sci) as Suncalc.rexx.

Page: 7
File: G:\Long-Term Storage\DATA\SunCalc\SunCalc.guide 3/6/1998, 8:49:50 PM

Thanks also goes to Kevin Glynn of Calgary, Canada for finding an icon for
SunCalc from the MWBarchive.lha on Aminet. To use this icon with SunCalc see
@{"Usage" link "Document_3" 146}.
@endnode

Page: 8