README for ASTRONET This directory is the top level directory for a program (starnet) that accesses the United States Naval Observatory's (USNO) star catalog A0.9 (and later) and returns a list of stars near a point specified by the user. The program has been developed for two systems: Sun/Solaris and MicroSoft/MS-DOS. Source code and executables are available for both systems. (Caution: The DOS code has been developed for only the first version. In the first version the program was called ASTRONET instead of STARNET so make all appropriate changes to this documentation.) There is now (19 Dec 1996) a second version (starnet 1.1) of the source code that contains more ways to select stars by magnitude. It also has an optional interface that can be used to bypass all command line switches. (This interface is now the default.) Finally, it fixed a few nitpicky problmes. I have stopped updateing the DOS version because this operation is taking too much time. DOWNLOADING THE SOFTWARE The software is available via ftp at ftp.lowell.edu/pub/koehn/starnet and in lower level directories. You may also download the software using your WWW browser. Start at http://asteroid.lowell.edu/ (and, at a future time, http://www.lowell.edu) and follow the links. INSTALLATION You will first need to get a copy of the USNO's catalog. The full version is 6 Gbytes in length and is supplied on 10 CDs. It is advisable to copy the catalog to large capacity magnetic disk drives if they are available. If not, the software will work using a single CD-ROM drive. Check the USNO's web page for availability: http://ww.usno.navy.mil/pmm/ USNO also has a single CD version of the catalog, SA1.0, that is also compatible with the software. The single CD version is a rather uniform network of stars suitable for calculating positions of asteroids, etc. Again, check the USNO's web page for availability. If you are using an IBM-compatible PC running MS-DOS, copy the DOS version of the program, astronet.exe, to your PC. If you are using a Sun computer running Solaris, copy the UNIX version of the program, starnet, to your computer. If you have neither of these computers but you have a FORTRAN compiler, copy the source code to your computer and try to compile it. There is a makefile to help with building the program on UNIX systems. Notice that the code for UNIX and DOS, while similar, does have differences so you may be sure that the source code will not compile on your system without some effort. The FORTRAN source code is not ANSI standard FORTRAN 77 and it contains calls to system routines so porting the code to other machines will generally be a non-trivial task. Finally, you must edit a file called catmap.dat. This file should contain the path (or directory) for all the files in the catalog. You will have to edit the file to reflect the way you have installed the catalog on your system. The next section provides some guidance on how catmap.dat should be constructed. EDIT CATMAP.DAT The USNO star catalog is a sequence of files that contain star information and catalog index information. There should be 48 files and each filename should begin with 'zone'. A four digit number follows zone. The number is related the the declination region of the stars contained in the file. There are 24 zones as follows: zone0000 zone0075 zone0150 zone0225 zone0300 zone0375 zone0450 zone0525 zone0600 zone0675 zone0750 zone0825 zone0900 zone0975 zone1050 zone1125 zone1200 zone1275 zone1350 zone1425 zone1500 zone1575 zone1650 zone1725 Each zone contains two files: *.acc and *.cat. The *.acc file is an index into the *.cat. ALWAYS PUT FILES OF THE SAME ZONE IN THE SAME DIRECTORY. The file catmap.dat expects a path name for each file. The path names are expected one per line in the order of the zones shown above. The path names are to be in the syntax of the operating system you are using. Assume you are using the DOS version of the program and you are using the SA1.0 catalog on a CD-ROM drive labeled E:\. You should edit catmap.dat to look like the following: E:\ Load CD #1 E:\ Load CD #1 E:\ Load CD #1 E:\ Load CD #1 E:\ Load CD #1 E:\ Load CD #1 E:\ Load CD #1 E:\ Load CD #1 E:\ Load CD #1 E:\ Load CD #1 E:\ Load CD #1 E:\ Load CD #1 E:\ Load CD #1 E:\ Load CD #1 E:\ Load CD #1 E:\ Load CD #1 E:\ Load CD #1 E:\ Load CD #1 E:\ Load CD #1 E:\ Load CD #1 E:\ Load CD #1 E:\ Load CD #1 E:\ Load CD #1 E:\ Load CD #1 The first 64 columns are available for the path name. The remaining columns are used as a comment printed to the terminal if the file cannot be found at the indicated location. Assume you are using the DOS version of the program with the full catalog on CD-ROM labeled E:\. Then catmap.dat would look like the folloiwng: E:\ 0000 CD #1 E:\ 0075 CD #1 E:\ 0150 CD #6 E:\ 0225 CD #4 E:\ 0300 CD #2 E:\ 0375 CD #1 E:\ 0450 CD #5 E:\ 0525 CD #3 E:\ 0600 CD #5 E:\ 0675 CD #6 E:\ 0750 CD #7 E:\ 0825 CD #1 E:\ 0900 CD #4 E:\ 0975 CD #1 E:\ 1050 CD #8 E:\ 1125 CD #9 E:\ 1200 CD #8 E:\ 1275 CD #10 E:\ 1350 CD #10 E:\ 1425 CD #10 E:\ 1500 CD #2 E:\ 1575 CD #3 E:\ 1650 CD #2 E:\ 1725 CD #3 Notice that if the program requests a file that is not present, it will print message indicating the CD that contains the file. Finally, assume you are using the UNIX version of the program with the full catalog on magnetic disks. Assume the catalog is placed on two 4 Gbyte drives nameed /mycpu/data1 and /mycpu/data2. Then catmap.dat could look like this: /mycpu/data1/ 0000 Missing /mycpu/data1/ 0075 Missing /mycpu/data1/ 0150 Missing /mycpu/data1/ 0225 Missing /mycpu/data1/ 0300 Missing /mycpu/data1/ 0375 Missing /mycpu/data1/ 0450 Missing /mycpu/data1/ 0525 Missing /mycpu/data1/ 0600 Missing /mycpu/data2/ 0675 Missing /mycpu/data2/ 0750 Missing /mycpu/data2/ 0825 Missing /mycpu/data2/ 0900 Missing /mycpu/data2/ 0975 Missing /mycpu/data2/ 1050 Missing /mycpu/data2/ 1125 Missing /mycpu/data2/ 1200 Missing /mycpu/data2/ 1275 Missing /mycpu/data2/ 1350 Missing /mycpu/data2/ 1425 Missing /mycpu/data2/ 1500 Missing /mycpu/data2/ 1575 Missing /mycpu/data2/ 1650 Missing /mycpu/data2/ 1725 Missing The file named catmap.dat should be in the same directory as the executable program. BEWARE: The catalog files consist of ASCII and binary files. The binary files can cause errors because of byte ordering. The byte ordering is correct for Sun and SGI computers but it is incorrect for DEC and IBM-compatible computers. A compiler option exists on DEC computers to make the files read correctly. You can also run a byte ordering routine after each catalog read to put things in the right order. A byte ordering routine is available in the source code of the DOS version of the program. REBUILDING THE PROGRAM FROM SOURCE CODE Try to avoid rebuilding the program if possible. But if you must rebuild, this section contains some suggestions and possible problems. This program is written in Sun's FORTRAN and I have freely used Sun extensions and library routines. The program is not ANSI compliant. The following are known problems if you are using an ANSI compliant compiler. 1. The programs are written in lowercase. ANSI requires uppercase. 2. Many names are longer than 6 characters. ANSI requires 6 characters or less. 3. 'Include' files are used. ANSI FORTRAN does not support include files. 4. IMPLICIT NONE statements are used which are unsupported in ANSI FORTRAN. 5. The underscore character is used in names. Also not supported in ANSI FORTRAN. 6. DO statements are terminated with END DO. Such constructs do not exist in ANSI FORTRAN 7. Length specifications are used (real*8) on non-character variables. Not allowed in ANSI FORTRAN 8. List directed internal I/O statements are used. Not allowed in ANSI FORTRAN. Actually, the DOS FORTRAN compiler would not allow this extension so they have been removed for the DOS version. All of the problems can be easily fixed to make the program ANSI compliant. The routine that calculates the universal time, 'ut.f', assumes Mountain Standard Time. In two locations, 7 is added to the local time because the Mountain time zone is 7 hours behind Greenwich. If you are in the Pacific standard time zone, this number should be 8, Central Standard time zone is 6, and so on. This change is optional because this routine is used only to put a timestamp on error messages. The other set of problems you may find is that some of the Sun library routines are not available on your machine. Specifically, ITIME, IDATE, IARGC and GETARG. If they are missing or work incorrectly, call me. MicroSoft FORTRAN has a set of similar functions called GETTIM, GETDAT, NARG and GETARG. The arguments were generally different but it was not complicated to fix. Finally, some of the I/O statement options I used may not be supported on the FORTRAN you use. More subtile I/O errors occured in porting between UNIX and DOS. For example, an I/O routine designed to reduce the number of catalog I/O's failed on DOS because UNIX attempts to complete a read when an error condition occurs and DOS does not. There seem to be no easy way around this problem so the read optimization routine was dropped from the DOS version. RUN THE MAKEFILE If you are on a UNIX system, type 'make', and the program will be compiled and linked (hopefully). If you are not on a UNIX system, you will have to compile and link with the tools that you have available. RUN THE PROGRAM On UNIX and MS-DOS systems, you may run the program by typing 'starnet' (or 'astronet if you are using the old MS-DOS executable) (your default directory must be the same as the location of the program). On other systems, do what you have to do. PROBLEMS I can give you limited debugging help. email is koehn@lowell.edu Telephone is 1-520-774-3358 BUGS The USNO's A0.9 catalog is based on the GSC and so it contains many of the problems associated with the GSC. The USNO will soon issue a much better catalog (A1.0) although it will also be based on the GSC. The new catalog should be the same format as A0.9 so this software should work with the new catalog (assuming it works with this catalog). No doubt there are countless software errors. However, the design document coveres many things that could go wrong so errors should be largely programming errors. USER'S GUIDE Please refer to a file called 'manpage'.