NOTE: This file contains both a user's guide and an installation manual
      for the bor_cord software.

                BOR_CORD  VERSION 2.0 USER GUIDE   (DRAFT)
                J. Newcomer and F. Irani, HSTX
                March 7, 1994


1.0 INTRODUCTION
----------------
The BOR_CORD program converts coordinates between the BOREAS X, Y grid
system, Latitude and Longitude and UTM Coordinates.  These coordinate
conversions are performed within and between the NAD27 and NAD83 datums.
Users may input coordinates interactively at the terminal or may use an
input ASCII file.  Either NAD27 or NAD83 datum coordinates for UTM or
latitude and longitude may be entered.  By definition the BOREAS X,Y grid
values are defined only in the NAD83 datum.  Program output is to the
terminal or to an ASCII BOR_CORD file. 
 

2.0  OVERVIEW AND FUNCTIONALITY
-------------------------------
BOR_CORD, developed for the Boreal Ecosystem-Atmosphere Study (BOREAS)
Information System (BORIS),  performs the geographic coordinate
conversions over the BOREAS study area of 51 degrees North to 60 degrees
North latitude and 111 degrees West to 93 degrees West longitude. 

The BOREAS grid is based on the ellipsoidal version of the Albers
Equal-Area Conic (AEAC) projection as defined within the North American
Datum 1983 (NAD83). The origin of the grid is at 111 degrees West, 51
degrees North and the standard parallels are set to 52.5 degrees North and
58.5 degrees North as prescribed in 'Map Projections - A Working Manual',
USGS Professional Paper 1395, John P. Snyder, 1987.  The projection
equations used in this program were all taken from this manual. The
BOR_CORD software will take input coordinates as Universal Transverse
Mercator (UTM) northing, easting and zone; decimal degrees of latitude and
longitude; or BOREAS (X, Y) grid coordinates. 


3.0 Running BOR_CORD
--------------------
Upon program invocation, BOR_CORD users are presented with a main menu
from which to select the type of coordinates which they intend to enter: 

        Input Coordinate Selection Menu.
        1) BOREAS X, Y
        2) UTM Northing, Easting
        3) Latitude, Longitude
        4) Exit
        Enter choice < 1 - 4 >: 2

Users are then prompted for input and output ASCII file names.  If no
input file name is given, input will be prompted for at the terminal.  If
no output file name is given output will be directed to the terminal.
Except when running under VAX/VMS, specification of a pre-existing output
file name will cause the pre-existing file to be destroyed and a new file
to be created with the same name. 

Users can enter q or Q at any time to quit from an option and return to
the main menu.  If the user enters quit, any file which had been opened
will be closed upon returning to the main menu.  Such files can be deleted
by the user after exiting the program or can be re-specified under
subsequent selections from the main menu.  Note that except when running
under VAX/VMS, any file re-opened for writing after a quit will not be
appended to but will be over-written such that pre-existing data in that
file will be lost. 

        Enter Input Filename or RETURN for keyboard input (q = quit)
        --> (User enters carriage return for keyboard input)

        Enter Output filename or RETURN for screen output (q = quit)
        --> UTM27.out

The file name specification for input and output
files should conform to the file naming conventions provided under the
operating system on which BOR_CORD is being run. 

 
        Enter datum shift file name (Default = datmshft.dat;  q = quit)
        --> User enters carriage return 

Note that the name of the datum shift file must be entered using the file
naming conventions provided by the users operating system (see DATUM SHIFT
FILE below). 

Users are prompted for the datum of the coordinates being supplied to the
program for conversion: 

        Enter the datum for the input latitude and longitude
        coordinates as 27 for NAD27 or 83 for NAD83. (q = quit)
        -->27

Note that which-ever datum is entered, calculations are made to convert to
the complementary datum. 

Interactive users are prompted for the coordinates differently according
to their type: 

        Boris XY:  Enter the X and Y BOREAS grid values as xxx.xx yyy.yy 
        Lat/Long:  Enter latitude longitude in decimal degrees as yy.yy xx.xx 
        UTM:       Enter northing  easting  zone 

BOREAS Grid Coordinates are entered in decimal kilometers.  Latitude and
longitude coordinates are specified in decimal degree units with west
longitude designated by a negative number.  UTM northing and easting
values are specified in decimal meters and UTM zone numbers are entered as
integers. 

If users specify an ASCII file as input, BOR_CORD processes all coordinate
pairs until the end of the input file is reached.  Processing control then
returns to the main menu (see Input File Formats below). 


4.0 INPUT FILE FORMATS
----------------------


        4.1 Datum Shift File
        --------------------
        By default, the BOR_CORD program accesses datum shift
        information contained in the ASCII text file named datmshft.dat.
        This file name should be specified such that it can be
        located under the naming conventions of the host operating
        system (see BOR_CORD installation guide). 


        4.2 Coordinate Specification Files
        ----------------------------------
        All input coordinate specification files are assumed to be ASCII
        files. No special header or other ancillary information should
        exist in any of these files. These files contain one coordinate
        pair, plus zone number for UTM, per line. Coordinate numbers are
        separated by blanks only.  The BOR_CORD program processes one
        coordinate pair at a time so that an unlimited number of
        coordinates can be placed into an input file for processing. 


                4.2.1 BOREAS Grid XY
                --------------------
                The BOREAS Grid specification ASCII file format
                consists of one pair of X Y decimal kilometer grid
                coordinates on a line. Examples of these are: 

                        0.0 0
                        100 1000.0
                        200 200
                        345.67 890.123
                        456.789 23.45


                4.2.2 Latitude/Longitude
                ------------------------
                Like BORIS Grid, latitude and longitude is specified as
                one coordinate pair per line of text.  Each coordinate
                pair consists of a latitude value, a blank separator
                and a longitude value.  Latitude and longitude is
                always specified in decimal degrees.  Note that west
                longitude is always specified as a negative number.
                Examples are: 

                        51 -110
                        56.0 -98
                        52 -109.0
                        58 -96.123
                        51.89037 -109.54819
                

                4.2.3 UTM
                ---------
                UTM Coordinates are specified in the same way as other
                coordinate types except that the zone number must also
                be specified on the line. Northings are specified
                first, followed by eastings, followed by zone numbers.
                Examples are: 

                        5649824.9 500000.0 12
                        5749841.1 599908.6 12
                        6291307.2 470168.2 14
                        6522766.7 471014.5 15


5.0 OUTPUT 
----------
Output coordinates for the BOREAS grid are always given under the NAD83
datum. Output coordinates for UTM and latitude longitude coordinates are
given under both NAD27 and NAD83 datums. 


6.0 ALGORITHM DESCRIPTION
-------------------------
Users specify input coordinates of a given type, as well as which of the
NAD27 or NAD83 datums their input specifications represent.  BOR_CORD then
reports all values for the same and complementary datum.  BOREAS Grid
coordinates are only specified and reported as NAD83 coordinates.  The
software handles conversion between NAD27 and NAD83 by applying datum
shift values that it interpolates for latitude longitude pairs.  If users
enter BOREAS Grid or UTM coordinates, BOR_CORD first converts these to
latitude longitude for the same datum input, then converts these latitude
longitude values to the complementary datum,  and finally derives the UTM
or BOREAS Grid coordinates from the converted latitude longitude values. 

The datum shift file represents a grid of datum shift values for every 5
minutes of latitude and 5 minutes of longitude from 48 to 60 degrees north
and from 89 to 112 degrees west.  Datum shift values above 60 degrees
north latitude were not available at the time of BOR_CORD development. For
this reason, northern edge coordinates are handled differently than
interior coordinates.  For interior coordinates, the four nearest datum
shift values surrounding the specified latitude and longitude value are
interpolated to get a datum shift adjustment to apply. For input edge
coordinates of 60 degrees north latitude, only the previous and following
datum shift values along the 60 degree line of latitude are used to
interpolate a datum shift value to be applied to the input coordinate
pair.  North latitude values can exceed 60 degrees in some cases where UTM
or Boreas Grid coordinates are first converted to latitude and longitude. 


7.0 BOR_CORD MESSAGES
---------------------
*** Problem interpreting input ***
*** Please re-enter response   ***
User entered a value other than 1, 2, 3 or 4 at the main menu prompt.
Enter a valid selection. 

*** Error writing header records to output file ***
An error occurred while attempting to write header records to the user
specified output file.  Check file protections and other file handling
conventions for your operating system. 

*** Error reading from terminal ***  
An error occurred while attempting to receive input from the terminal.
Try re-entering response or see your system manager.  

*** Error extracting input datum from input record ***
User entered more than a single numeric value for the input datum. Specify
27 if you are entering NAD27 coordinates to be converted to NAD83, or
specify 83 if you are entering NAD83 coordinates to be converted to NAD27.
 Do not make more than one entry for this response. 

*** Invalid input datum (string)              ***
*** Datum values need to be given as 27 or 83 ***
User entered a value other than 27 or 83 for the input datum.  Enter the
value 27 to convert NAD27 coordinates or 83 to convert NAD83 coordinates. 

*** Error writing coordinates to output ***
An error occurred while attempting to write specified coordinates to the
user specified output file.  Check file protections and other file
handling conventions for your operating system.  Also check for sufficient
disk space. 

*** End of input file reached ***
This is an informational message.  The last record of the input coordinate
list file was reached.  Processing continues as normal. 

*** No coordinates found on input record ***
User entered something other than a valid pair or set of coordinates
numbers.  Enter all required coordinates as numeric characters. 

*** Specified [data type] coordinate is outside ***
*** anticipated range.  Only [data type] values ***
*** between [min] and [max] are accepted        ***
User entered coordinates beyond the extreme useable boundaries of the
BOR_CORD interpolation grid. Re-enter values within the range permitted
for the input coordinate type. 


*** Error extracting [coordinate type] from input record ***
User made an invalid entry on input.  Re-enter a valid set of coordinates.

*** Error reading from datum shift file            ***
*** Error extracting datum shift values from input ***
BOR_CORD was unable to read from the datum shift file.  Check spelling and
directory syntax as will as access permission.  See system manager. 

 *** Input or calculated longitude of ___ is east of datum shift boundary. ***
This condition should not have occurred under the original design of
BOR_CORD for BOREAS purposes.  This message should only occur if a
longitude value was calculated to be less than W 89 degrees longitude. 

*** Input or calculated longitude of ___ is west of datum shift boundary. ***
This condition should not have occurred under the original design of
BOR_CORD for BOREAS purposes.  This message should only occur if a
longitude value was calculated to be greater than W 112 degrees longitude.

*** Input or calculated latitude of ___ is south of datum shift boundary. ***
This condition should not have occurred under the original design of
BOR_CORD for BOREAS purposes.  This message should only occur if a
latitude value was calculated to be less than N 48 degrees latitude. 

*** Input or calculated latitude of _ is north of 60.            ***
*** Latitude shifts will be handled as if at 60 degrees          ***
*** Note that datum shift file edge coordinates are interpolated ***
*** differently than interior coordintes.                        ***
A UTM northing or Boreas Grid Y coordinate was converted to a value
greater than 60 degrees north latitude for conversion from one datum to
another.  This message is notifying the user that the shift values applied
to the latitude and longitude have been interpolated differently than are
coordinates which lie within the interior of the datum shift file. 

*** End of datum shift file reached ***
BOR_CORD has calculated a byte number to access which is beyond the end of
file for the datum shift file.  This error is not likely to occur unless
the datum shift file has become corrupted.  Check the integrity of the
datum shift file. 


*** Unable to open filename for input ***
User has specified a file name which could not be opened. Check spelling
and directory syntax as will as access permission.  See system manager. 

*** Unable to open filename for output ***
User has specified a file name which could not be opened. Check spelling
and directory syntax as will as access permission.  See system manager. 


8.0 FURTHER HELP AND INQUIRIES
------------------------------
Further inquiries into the BOR_CORD software can be made through:

        Beth McCowan
        Code 923
        Goddard Space Flight Center
        Greenbelt, Maryland
        20771
        (301) 286-4005


9.0 REFERENCES AND ACKNOWLEDGEMENTS
-----------------------------------     
The BORIS Project thanks the Geodetic Survey of Canada for providing the
datum shift file and the associated datum shift interpolation algorithm
that made this program possible. 

Construction of the BOREAS grid and algorithms for converting from
latitude and longitude to UTM were based on algorithms and concepts
described in: 'Map Projections - A Working Manual', USGS Professional
Paper 1395, John P. Snyder, 1987.  The projection equations used in this
program were all taken from this manual. 


BOR_CORD SYSTEM INSTALLATION GUIDE  (DRAFT)
F. Irani and J. Newcomer, HSTX
March 1994


1.0 OVERVIEW
------------
The BOR_CORD program was developed at the NASA Goddard Space Flight Center
(GSFC) for the Boreal Ecosystem-Atmosphere Study (BOREAS) Information
System (BORIS). The purpose of the program is to allow users to enter
latitude longitude, UTM and BOREAS Grid coordinates taken from either the
NAD27 or NAD83 datum and convert these coordinates to the other coordinate
systems and between datums.  The software is written entirely in the C
language using the standard C Input/Output and math libraries. No
operating system dependencies exist in the software.  Certain
considerations must be addressed, however, depending on the hardware
platform on which the program is built and run. 


2.0 CANDIDATE HARDWARE PLATFORMS
--------------------------------
The BOR_CORD program was built and tested on several different hardware
platforms representing four different generic processing environments:
Macintosh, IBM Compatible PC, VAX /VMS and the UNIX operating system. More
specifically, the system was built and tested on a Macintosh Centris 650
and a Macintosh II ci, a VAX 6410, Gateway and WIN 386 IBM Compatible PCs
and on Silicon Graphics IRIS (SGI) and SUN workstations. 


3.0 C COMPILERS
----------------
You can adapt bor_coord.c to build under any C compiler that is compatible
with the computer and operating system being used.  The BORIS project used
the THINK C Version 5.0 compiler for testing on the Macintosh computer.
The VAX/VMS VAX C Run Time Library and compiler were used for testing
under VMS , the Borland  and Turbo C compilers were used on the PCs and
the cc and gcc compilers were used for testing on the UNIX workstations. 


4.0 GSC NATIONAL TRANSFORMATION DATUM SHIFT FILE
------------------------------------------------
The BOR_CORD application software comes with an 800K-byte ASCII datum
shift file, with a default name of datmshft.dat from which correct datum
shift values are interpolated for latitude and longitude coordinates. The
name or location of this file may be changed so long as users are able to
specify the correct name and location of the file in response to the
BOR_CORD prompt.  Under VMS a logical name can be defined to point to the
file as a convenience to users.  The system manager can create such a
logical name and announce its availability to bor_cord users (see
INSTALLATION PROCEDURE). 
 
The purpose of the datum shift file is to provide a grid of datum shift
values at 5 minute intervals of latitude and longitude to cover the
area of interest for BOREAS investigators. The file was provided by the
Geodetic Survey of Canada (GSC) and is being used in its ASCII form for
compatibility with a variety of hardware platforms.  This file takes the
form of variable length records under VAX/VMS and on IBM PC's.  On
Macintosh and UNIX systems this is a fixed length file with line
terminators.  Because the C function fseek is used to access calculated
byte locations in the datum shift file it is important that the correct
record length is defined in the bor_cord.c source code at compile time.
This specification is performed prior to compiling the source code (see
INSTALLATION PROCEDURE). 

  
5.0 CONFIGURATION CONSIDERATIONS
--------------------------------
For bor_cord, the major hardware consideration is the general
accessibility of the application and the datum shift file to users. It is
up to the user to determine where the datmshft.dat file will be stored and
how to invoke the program.  The datmshft file should be placed in a
location with the appropriate file protection settings that will allow it
to be be accessed by the BOR_CORD software at run time.  PC and Macintosh
users may choose to place this file in the same location as the BOR_CORD
application.  In any case, the user must be able to type in the exact
location and name of this file unless the default entry name of
datmshft.dat is sufficient for the operating system to locate this file.
Care should also be taken that this file be given read only protection. 


6.0 GENERIC INSTALLATION PROCEDURE
----------------------------------
Although the means to implement specific installation steps vary between
computers, the main objective of each step is the same for all systems.
The following installation steps are given in terms of their desired
objectives.  Any hardware-specific notes follow some steps. 

Step 1. Create a directory or folder to hold the source code,
        documentation, and the datum shift file and copy these from the
        delivery media to this location. 

Step 2. Modify the source code to specify the appropriate number of
        bytes per record by commenting out or uncommenting the source
        code lines: 

           #define NRECBYTES 22 /* (VAX/VMS AND PC)  */
           #define NRECBYTES 21 /* (Macintosh and UNIX) */

Step 3. Invoke your C compiler to compile and link the source code and
        move or copy the application, documentation and datum shift file
        to a location that is generally accessible.  Note that the
        software uses the C math library and math.h include files. 

        - Our source would not compile under our configuration of the cc
          compiler on the SUN, but did compile under the gcc compiler.  We
          compiled successfully using the  cc compiler on the SGI.  The
          problem under the SUN configuration was related to the  version
          of include files that were existing on our SUN. The compile
          commands used on the SGI and SUN computers were as follows: 

                 SGI:    cc  bor_cord.c -o bor_cord -lm
                         SUN:  gcc bor_cord.c -o bor_cord -lm

        - Under VMS, a symbol can be defined to allow users to invoke
          the bor_cord executable  image such as: 
  
          $ BOR_CORD :== RUN $DISK:[DIRECTORY1.DIRECTORYN]BOR_CORD.EXE 

        BOR_CORD can also be set up as a command under VMS using the $
        SET COMMAND feature of the VMS operating system. 


        Likewise, under UNIX, the c shell %set path command  can be used
        to point to the executable image location for ease of user
        invocation. For example: 

        set path=($path /usr/local/bin/bor_cor)


        Under Macintosh environment the datmshft.dat file must co-exist
        in the same folder or on the desk-top with the bor_cord
        application to use the default, datmshft.dat, specification to
        reach the datum shift file, otherwise users must specify the
        exact location of this file e.g.: 

        Enter datum shift file name (Default = datum.shft;  q = quit)
        --> Macintosh HD:Utilities:bor_cord:datmshft.dat


Step 4. Print the 12-14 pages of documentation and review it before
        running the program. 
                
 
7.0 ACKNOWLEDGEMENTS 
--------------------
The BOREAS Information System (BORIS) project thanks the Geodetic Survey
of Canada for the FORTRAN-77 subroutine source code and datum shift
information files that have made this project possible.