Travel Documentation
--------------------

By David F. Kurth

INTRODUCTION
If you have taken small kids on long trips  to  Grandma's  house,
you  may be interested in this program.  It takes a list of towns
and mileage between them and displays things like how far  you've
traveled  and  how  soon  you'll  be  there.   If  you don't have
traveling companions that ask "Are we there yet?", it's just  one
more  thing to help occupy your mind on long monotonous stretches
of road.

If you take trips where you go straight to your  destination  and
want  to get there as soon as possible, you may find this program
useful.  If you are the type that goes nowhere in particular  and
doesn't  care  when you arrive or how many site-seeing side trips
you take, this program may not be too helpful to you.

For an example of what the program does, I drive my  family  home
each  summer  from  Colorado Springs to Chippewa Falls Wisconsin.
We stop  in  Council  Bluffs  Iowa  on  the  first  day,  and  in
Burnsville  Minnesota on the second.  The night before I leave, I
get the map out  and  plan  my  route.   I  enter  the  following
information into the calculator for the first day.

   COS               Origin of trip
   DENVER   70.0     Denver CO
   FT MOR   77.9     Fort Morgan CO
   JULES   104.8     Julesburg CO
   NORTHP   85.2     North Platte NE
   KEARNY   99.6     Kearny NE
   LINCOL  132.9     Lincoln NE
   CBLUFS   64.5     Council Bluffs IA, Destination of trip
   -------------
   TOTAL   634.9

Bright and early in the morning, we pile in the car and back  out
of  the  garage.  I get my calculator and enter the starting time
(6:04AM) and odometer mileage (53213.0).  After getting  from  my
house  to  the freeway, I update the time and mileage again (6:15
and 53218.5).  The calculator then tells  me  I've  traveled  5.5
miles,  I  have 64.5 more miles to go to Denver, and I have 629.4
miles more to go to my Council Bluffs.  I've been on the road for
11  minutes.  My current and average speed is 30 mph, and at that
rate I'll get to Denver at 8:24, and Council Bluffs at 3:13AM the
next day!

Not yet discouraged, I continue driving down the  freeway  at  65
mph  (of  course).   I  do  another  update at 6:51AM and 53258.0
miles.  My current speed is  now  65.8  mph  (oops,  it  must  be
downhill) and I will drive 25.0 more miles to arrive in Denver at
7:13:47.  My average speed from my departure to now is 57.4  mph.
At  this  speed,  I  can  expect  to  arrive in Council Bluffs at
5:07PM.  The time to the next town is always calculated using the
current  speed  (between the last two updates), while the time to
the destination is always  determined  using  the  average  speed
(between  the current update and the departure time).  This gives
a more realistic arrival time  at  the  destination  due  to  gas
stops, meal breaks, and restroom trips.  After using this program
for a while, you will know what average  speed  can  you  expect.
You  can  then  quite accurately determine your arrival time very
soon after you start.

The program also keeps a running total of gasoline: gallons  used
and  dollars  spent.   The  program  can use the miles per gallon
value from the last fill-up to predict how  many  miles  you  can
drive until the next fill-up.

Once I pass Denver, the program will then  automatically  display
mileage  and  information  for the next town in the list.  If I'm
getting hungry and wonder at what time I  will  I  get  to  North
Platte,  I  can set that town as a checkpoint.  Then all time and
mileage will be computed for that town instead.

The program also keeps a list of all trips you  have  entered  to
save  retyping  the information.  It also allows you to edit town
names and mileage distances.  If  you  get  to  a  town  and  the
calculator  says  you  still have 10 miles to go (due to detours,
sidetrips, maps that lie, or  shrinking  rulers),  you  can  just
change   the  mileage  number  and  everything  will  recalculate
accordingly.  If you get to Grandma's house and then want to turn
around  and  go  home using the same route, the program will also
reverse a trip so you can use the same town list going both ways.


HOW TO USE THE PROGRAM

To use this program, you will first want to do one  customization
step.   In  the  user  RPL  or  PDL  versions,  find the variable
FULLTANK and replace the number there with the number of  gallons
your  gas  tank holds when it is full.  You can then download the
file to your calculator.  The other method  is  to  download  the
file in its present form, and then edit the variable FULLTANK and
change it for your gas tank  capacity.   As  long  as  you  don't
reload the program, the FULLTANK value will be correct.

I have provided three forms of the program to  download  in  your
calculator.   The  PDL  and  RPL versions will require some extra
free memory to load, but these versions contain all  my  comments
and  allow  you  to  edit and change the code to suit your needs.
The the binary version will require the least amount of memory to
download and will load the fastest.

After the program  is  loaded  into  the  calculator,  check  the
variable  FULLTANK  and  verify  that  its value is equal to your
vehicle's gas tank capacity.  The next step is  to  set  up  your
first trip list.

Hit the CST key on the calculator to bring up  the  custom  menu.
The first level menu will be displayed.  The first level keys are
the most commonly used keys when you are actually traveling.  Hit
the  NXT  key  to bring up the second level keys.  These keys are
used for editing and changing data with respect  to  the  current
trip.   (The third level keys are for saving and retrieving trips
from memory and reports.)

With the second level keys visible, you will see the  SETUP  key.
This  starts  a  new  town  list.   If  you want to play with the
program and don't have a town list handy, you can skip this step.
The  town  list in the example given above is already loaded into
memory.

If you start SETUP, the first information prompted for is TOWN OF
ORIGIN.   Enter  the name of the town you are starting from.  All
town names are limited to the first six characters you enter  (to
keep  the  displays  manageable  and  consistent).   You are then
prompted for the number of towns  in  your  trip.   This  is  the
number  of  towns  you  want  to  keep  track  of  including  the
destination town.  In the example given above, there a  7  towns.
There  is no limit on the number of towns you can have on a trip,
but more towns require more memory (no memory  checks  are  done)
and more towns slow down the speed of updates.

After this prompt, you enter the town name of the  next  town  in
your  trip, and then the miles from the previous town to the next
town. After all towns and mileages are entered, the program stops
and  you are ready to begin your trip.  If you made a mistake, or
want to change a town name or mileage, you can use the  EDIT  key
which  is  described  below.   The  program will not allow you to
remove or add a town once the town list is entered.  If you  want
to do this, just run SETUP again and enter the new information.

Since this is the first leg or day of your trip, you will want to
clear  and  initialize  the  gas  and mileage information.  To do
this, press the INIT key.  You will be prompted for the  odometer
mileage  at  your  last gas fill-up, and your estimated miles per
gallon that your car will do on the highway.  These  values  will
allow  the  calculator  to  estimate  gallons of gas left in your
tank,  and  the  amount  a  gas  it  will  take  to  reach   your
destination.  The INIT key should only be used once when starting
a new trip to initialize variables.  If you use this key during a
trip, the total gallons of gas used and dollars on gas spent will
be reset to zero.

The calculator is now ready to start your trip.  When you get  in
your  car to back out of your driveway, push the BEGIN key.  This
will prompt you  for  your  current  odometer  mileage,  and  the
current  time  (which is taken from the calculator's clock).  The
starting time and mileage is saved and used  to  calculate  total
trip time, mileage, and average speed.

After you BEGIN your trip, the key menu will switch back to level
one.   The first key is the UPDAT (update) key.  Push this key to
enter your current time and mileage information.  The odometer in
my car does not have a tenths digit.  The trip odometer does, but
the two are almost never in sync.  So I've set the program up  to
allow me to enter the mileage first.  I look at the odometer, and
if it says 55555, I'll enter 55556.0 at the prompt.  The  program
then waits for me to hit ENTER to mark the time.  So I wait until
the odometer goes from 55555 to 55556, and then  push  the  ENTER
key. This give a fairly accurate mileage and time reading for the
rest of the calculations.

I've tried to make the mileage prompt as easy as possible.   It's
a  bad  idea to drive 65 mph trying to type a 7 digit string into
the calculator and pay attention to the traffic at the same time.
So  the  mileage  prompt  puts  up  the last mileage entered, and
positions the cursor on the hundreds digit.  This  way  you  only
have  to  enter  3  digits  (assuming you don't change the tenths
digit).  When the odometer thousands digit rolls over,  you  will
have  to  use  the arrow key to change the thousands digit on the
calculator.  Unless you travel more than 1000 miles in a day, you
should only have to do this at most once.  I've found this method
of entering mileage to be the easiest for me.

After the mileage  and  time  is  entered,  the  calculator  then
proceeds to display all the following information.

TOT MILES= total miles from      TOT TIME=  total time (in
           the start of the                 HR:MM:SS) from the
           trip to the last                 start of the trip to
           entered mileage.                 the last entered
                                            time.

TO townx=  miles to the next     TO townd=  miles to the destina-
           closest town ahead.              tion town.  The right
           The left half of                 half of the screen has
           screen has the in-               the information for
           formation for the                the destination town.
           next town.

ETA        estimated time of     ETA        estimated time of
           arrival at townx.                arrival at townd.
           This is based on                 This is based on the
           the current speed.               average speed.

EFA        estimated fuel at     EFA        estimated fuel at
           arrival at townx.                arrival at townd.
           This is based on                 This is based on the
           the MPG from the                 MPG from the last
           last fill-up.                    fill-up.  If negative,
                                            its the amount of gas
                                            needed to get to the
                                            destination.

CUR SPD=   current speed         AVE SPD=   average speed based
           based on this up-                on this update and
           date and the                     the starting time
           previous update.                 and mileage.

FUEL=      estimated gallons     MPG=       calculated miles per
           of gas left in                   gallons from the last
           your tank based on               fill-up.
           MPG value and
           mileage.

TOT GAL=   total gallons of      COST=      total cost of gas pur-
           gas purchased since              chased since INIT
           INIT (start of trip).            (start of trip).

LAST       odometer reading      (time)     time at last update
           at last update

If the EFA at the destination town is  negative,  one  additional
line  is  displayed  on the bottom of the display which indicates
how many more miles you can drive before  you  run  out  of  gas.
This  is just an estimate based on the MPG from the last fill-up.
If the wind  blows  harder,  changes  direction,  or  you  change
altitude  as  you  drive, the previous MPG value may no longer be
realistic.  In this case, the EFA and miles until no gas  may  be
quite a ways off.  You can use the FUEL= value and your gas gauge
to estimate if your present gas mileage is better or  worse  than
before.

To exit the update display, hit any key on  the  keyboard  except
ATTN/ON.   When you want to update again, just use the UPDAT key.
If you want to see all the information  again  without  updating,
use  the  UPDAT  key,  but  do  not change the mileage value when
prompted to do so.  Just hit the enter key.  The mileage and time
will  not  be  updated,  and  the  previous  information  will be
redisplayed.

This is the basic operation of the program.  The other  keys  are
explained below.

The GRAF key will draw a vertical line with the starting town  at
the top, and the destination town at the bottom.  The other towns
will be shown with their mileage values scaled accordingly.  Your
present  position  will  be marked with an arrow.  The display is
two screens high, so use the up and down arrows  to  scroll  back
and  forth.   You  can show your kids the progress you have made,
and it may give them some idea how much longer you  have  to  go.
Exit this mode by pushing the ATTN/ON key.

The VIEW key give a list of the towns and mileages of  the  trip.
You  can  use  this  if you don't remember all the details of the
town list you entered.  This is also a scrollable display, so use
the arrow keys to go up and down if the whole list is not visible
at once.  Exit this mode by pushing the ATTN/ON key.

The CHKP key sets or clears a checkpoint.  If you  want  to  know
the time you will arrive at the third town instead of the current
town, push the CHKP key.  Enter the number of the town  you  want
to  set for a checkpoint.  If there are more than 8 towns in your
town list, you can use the NEXT and PREV keys to display the next
or  previous page of towns.  Enter the town number and then press
CONT.  You will then notice  user  flag  2  will  be  set.   This
indicates  that  a checkpoint is set.  If you now press the UPDAT
key, the time and mileage information  for  the  checkpoint  town
will be displayed.  There will also be a "*" in the miles to town
line that indicates that this is mileage to  a  checkpoint  town,
not  the  next town (unless they are the same town).  To remove a
checkpoint, just press the CHKP key again.  User flag 2  will  be
cleared,  and the update display will again show mileage and time
to the next town.

If you press the NXT key to get to the second level of menu keys,
the  first  key  is  the  EDIT  key.   If you get to town and the
program says it is still 5 miles away, use the EDIT key to change
the  mileage.   The display will first show the town names with a
number.  Enter the number of the town you want to change.  If you
have  more  than  8  towns in your trip, you can use the NEXT and
PREV keys to display the next or previous page of  towns.   After
entering  the  town  number, push the CONT key.  You can now edit
the town name.  Use the arrow keys or the backarrow key to change
the  town name. When you are finished, push ENTER.  If you do not
want to change the town name, just push ENTER.  You can now enter
the  mileage.   When  you are done, push ENTER.  The program will
then display the trip list and mileages  so  you  can  check  the
results.  Push the ATTN/ON key to end the edit mode.

The second key on the second level is the GAS key.  When you fill
up with gas, use this key to enter the mileage (used in miles per
gallon), time, number of gallons, and the cost of the  gas.   You
will  then be returned to the level one key menu.  You can now do
an update to display the gas information and MPG value.

The SETUP, BEGIN, and INIT keys have been described  above.   The
last  key  on  level two is the REVR key.  This key will take the
current trip and reverse it.  This will  allow  you  to  go  from
point  A  to  point  B, and then reverse the trip and travel from
point B to point A.  Obviously, this should not be done during  a
trip,  as  things  will get confused.  However, if you accidently
push this key, just push  it  again  to  get  the  original  trip
direction back.

Push the NXT key to get to the third level of  menu  keys.   This
level  brings  up  the trip save/retrieve and report keys. If you
travel the same routes, you can save your current trip so you can
use  it again next week or next year.  The first key is SHOW, and
this  will  display  all  trips  currently  saved.   This  is   a
scrollable  list,  so  you  can use the arrow keys to move up and
down when the list  gets  long  enough  to  fill  more  than  the
display.  If you want to retrieve a trip, note the trip number on
the left hand side of the screen.  The trips  are  identified  by
the  origin  and destination towns, and the trip mileage.  If you
have two different routes between the same two towns, the mileage
number  will  be  the  only  thing  that  is different.  Push the
ATTN/ON key to exit this display.

The SAVET key saves the current town list  into  the  trip  list.
The  town  list  is  tacked onto the end of the trip list, and no
check is made to see if this is a duplicate trip.

The USETR key retrieves a town list from the trip list to use  as
the current town list.  You must supply the town list number that
is displayed when using SHOW.  If you do not know the  town  list
number, then enter 0 and the list will be displayed.

The DELTR key removes a trip from the trip list.  If  you  get  a
duplicate trip, or you want to make room for another trip, or you
just want to save some memory, this key will delete a  town  list
from  the  trip list.  There is no "undo" key however, so be sure
you pick the intended town list number when deleting.

The last two keys on the third level key menu don't have anything
to  do  with  saving  trips,  but I didn't want to go to a fourth
level.  These two keys produce reports that will  give  you  trip
summary  information.  The first key give the entire trip summary
from when you leave your house until when  you  get  back.   This
only  gives mileage, gas and cost information. The second is just
a report that gives how far you traveled for just one leg of your
trip, and how long it took you.

The SRPRT key gives the entire trip summary report  from  leaving
your house to the arrival again after a bunch of traveling.  This
report does not give any time information, but  only  reports  on
the total miles traveled, the total gallons of gas purchased, and
the total cost of gas  purchased.   It  also  then  computes  the
average  miles per gallon, cost per gallon, and cost per mile for
your trip.  For this information to be  the  most  accurate,  you
should arrive home with your gas tank with the same amount of gas
as when you left.  I try to leave on my trips with the  gas  tank
full  from a fill-up the night before. When I arrive back home at
the end of my trip, I first unpack the car. Then either that  day
or later, I'll fill the car back up and use the GAS key to record
the gallons and cost.  Then I can use the SRPRT  key  to  produce
the summary report.

The REPRT key gives a short trip summary of the  current  leg  of
your  trip.   It  simply takes the starting time and mileage, and
using the current time and mileage,  it  shows  the  total  time,
mileage,  and  average  speed for the trip.  I like to write this
information down when I reach my destination  so  I  can  compare
this  years  trip  with  last year's.  For this information to be
correct, you must take one final UPDAT when you  arrive  at  your
destination.   This  will hold the final time and mileage for the
report.


TIP, HINTS, AND WARNINGS

When I get to Grandma's house, I don't bother  entering  all  the
trip  information  I  do for just local running around.  But when
the gas tank is empty, I record the fill-up information using the
GAS  key anyway.  The time and mileage information will be out of
sync  (wrong  day  and  a  couple   hundred   miles   past   your
destination),  but the total gallons, dollars spent, and mile per
gallon will be updated correctly.  When I start  the  trip  home,
the time and mileage information will be corrected.  If I do want
to drive 60 miles to see something, I can still enter a new  town
list  and  BEGIN  a  trip.   The FUEL left and MPG values will be
used, and they should still be fairly accurate  although  my  in-
town  mileage  is less than my hi-way mileage.  I can always edit
the variable MPG (see varible list below) and store  a  different
value if I want.  This way the gas remaining will be "used up" at
a rate that will be more accurate.

I do not save any of the calculator flags or states.  I use  user
flags  one through six which are described below.  I chose not to
attempt to save  flags  because  the  program  is  set  up  as  a
collection  of  mini  programs.  I could see no easy way to enter
and exit the travel program so I could  control  the  saving  and
restoring  of  the  flags and status.  I do feel that this has an
advantage of allowing me to go to any other directory at  anytime
to  play  a  game or find the last digit of PI :-).  The graphics
area is also clobbered.  So any information stored there will  be
erased.   I use PDIM to change the size of the graphics screen to
accomodate my displays, but I have tried to insure that PDIM gets
set back to the normal default size.

This program will only handle trips lasting less than  24  hours.
I  only  store time in hours, not the days.  I don't like driving
for than 8 hours anyway.  If you are going to drive more than  24
hours, I can only suggest you split your town lists into parts so
each is less than 24 hours.

There is also no provision for driving through time zones.  If my
trip  starts  in  one time zone and ends in another, I either set
the calculator's time to the new zone and leave it,  or  keep  my
watch  and the calculator in the current time zone and not change
anything until I get to my destination.


FILE SIZES and CHECKSUMS

The program is 10659.5 bytes long.  I'm amazed that such a simple
program  can  get  so  long.  You will also need more memory than
this to hold the graphic displays also.


IMPORTANT VARIABLES

You may find the following list of variables useful.

M0              The starting mileage.

M1              The mileage at the previous update.

M2              The mileage at the last update.

T0              The starting time (H.MMSS format).

T1              The time at the previous update (H.MMSS format).

T2              The time at the last update (H.MMSS format).

TOWN            The list of town names and mileages.

TRIPS           The list of all saved town lists.

TM              The total miles for the current trip.

TGAL            The total gallons of gas purchased.

T$              The total dollars of gas purchased.

MPG             The miles per gallon value calculated at the last
                gas fill-up.

MFILL           The mileage at the last gas fill-up.

FULLTANK        The fuel capacity of your gas  tank  in  gallons.
                This  should  be changed by you to equal the fuel
                tank capacity of your vehicle.

FUEL            The remaining gallons of fuel estimated to be  in
                your tank.



FLAGS USED

1       Indicates INIT was used and when  set  allows  the  BEGIN
        routine  to  save the starting mileage as the entire trip
        starting mileage.   This  value  is  used  in  the  SRPRT
        routine.

2       When set, indicates  that  a  checkpoint  town  has  been
        selected.   All  mileage  and  time  information  will be
        calculated for the checkpoint town instead  of  the  next
        town.   This flag causes a "*" to display in the miles to
        checkpoint town line in the update display.

3       Set when you  do  not  have  enough  gas  to  reach  your
        destination town.  When set, it causes the update display
        to add an extra line at the  bottom  of  the  display  to
        estimate  how  many  more miles you can travel before you
        run out of fuel.

4       Used to determine if time displays use AM or PM.

5       Used by the edit and checkpoint routines to indicate  the
        next or previous page should be displayed.

6       Used to check if flag -40 is set.  This flag  continously
        displays time, and if left on will overwrite my displays.
        Flag 6 is used to temporary turn off -40 if it was set.


DISCLAIMER:  I wrote this program for  my  enjoyment,  and  I  am
sharing  it  with  you.   If  you  crash your car because you are
looking at the calculator,  I  assume  no  responsibility.   I've
tried  to  make sure the calculations are correct, but if you run
out of gas in the middle of the desert  or  a  blizzard  and  the
calculator   says   you  have  1.7  gallons  left,  I  assume  no
responsibility.  Have fun with this program, change  it  all  you
like,  but  please don't blame me for your problems.