This file explains how to use the SAOimage communictions interface software on an OpenVMS machine. The enhanced version of SAOimage (v. 1.2E) allows loading multiple independent images, cursor and vector drawing, cursor readback, and lookup table control from a user program. Video is also possible. The OpenVMS version of the software has been tested on a VAXstation. All executables referred to in this document pertain to VAX only. 1. A new version of SAOimage is required. If you have access to the MIIPS package you can simply copy SAOIMAGE.EXE from MIIPS$DISK:[MIIPS.X_WINDOW.SAOIMAGE]. If you wish to recompile, you will have to obtain copies of all the files in the above directory and its subdirectories, and retain the directory structure, or download the file saoimage.tar-gz, from the link at http://www.astro.gsu.edu/~gudehus/enhanced_saoimage.html. All files will compile under VAX C, and may not necessarily compile under other compilers. Therefore you may need to define CC as CC/VAXC if another C compiler is installed on your system. To recompile a single module, enter @MAKE module_name and the module will be recompiled with the proper switches and placed in the library. To simply relink, enter @MAKE LINK. To rebuild everything, enter @MAKE. Again, it is simpler to copy SAOIMAGE.EXE. Installation under UNIX is more complicated. 2. A new version of IMTOOLRC. is required. Copy this from the above directory and put it in the same directory as SAOIMAGE.EXE on your machine. Note that the first 13 configurations in IMTOOLRC are assumed by the demo programs. 3. To run the demonstration programs, copy SAODEMO.EXE, SAODEMO2.EXE, SAODEMO3.EXE, SAODEMO4.EXE, SAODEMO5,EXE, SAODEMO6.EXE, SAODEMO7.EXE, SAODEMO8.EXE, SAODEMO9.EXE, SAODEMO10.EXE, and SAOSAMPLE.EXE from MIIPS$DISK:[MIIPS.DISPLAY] to your private directory. Alternately, download sao_vax_executables.zip from the link at http://www.astro.gsu.edu/~gudehus/enhanced_saoimage.html. After entering "UNZIP SAO_VAX_EXECUTABLES.ZIP", you will obtain a backup save set. Enter "BACKUP SAO_VAX_EXECUTABLES.BCK/SAVE *", and the files will be restored to your current directory. SAODEMO8 uses the MIIPS plot package and is included as an example of graphics plotting on SAOimage. 4. Define the foreign commands $ SAOIMAGE :== $your_disk:[your_directory]SAOIMAGE.EXE -g 886x886-2+134 -q -one +coord +magnifier $ SAO:==SPAWN/NOWAIT/INPUT=NL: SAOIMAGE Upper or lower case may be used. The geometry should be adjusted if the display area on your monitor is not big enough. The above command assume a 19-inch monitor with 100 dots/inch, giving a 1240 by 1024 available pixel area. With a 75 dots/inch display a geometry of 600x775-2+84 may give better results. The effect of the -one switch is different than in previous versions of SAOimage. The switches zero, half, and one, assign the starting pixel corner to (0.0, 0.0), (0.5, 0.5), and (1.0, 1.0), respectively. The effect of the former "one" switch is now accomplished by use of the "half" switch. This relationship is more intuitive. Also, +magnifier now enables the magnifier window. Finally simply enter $ SAO and SAOimage will come up. Then try running the demos from the same window that you entered the SAO command from and have fun. 5. If you want to compile the demos, create a new demo, or display images from a custom application on SAOimage, you will have to copy several files to your account before compiling and linking them. The source code for these files and that of the demonstration programs can be obtained by downloading sao_demos_vms_source.zip from the link at http://www.astro.gsu.edu/~gudehus/enhanced_saoimage.html. After entering "UNZIP SAO_DEMOS_VMS_SOURCE.ZIP", you will obtain a backup save set. Enter "BACKUP SAO_DEMOS_VMS_SOURCE.BCK/SAVE *", and the files will be restored to your current directory. If you have access to the MIIPS software, copy the following files: Name Location on MIIPS$DISK Description IBMI2.FOR [MIIPS.FOR] Required lower level routine IBMI4.FOR [MIIPS.FOR] Required lower level routine IEEEFLT.C [MIIPS.UNIX.DISPLAY] Required lower level routine IMTOOLCHECKSUM.FOR [MIIPS.DISPLAY] Required lower level routine KEPLER.FOR [MIIPS.FOR] Solves Kepler's equation This is only used in demo #9 MAKE_SAO_DEMOS.COM [MIIPS.DISPLAY] Command file to compile and link all the executables PLOT.OLB [MIIPS.LIB] Plot package library. This is only used for demo #8. PLOTDEVICES.FOR [MIIPS.PLOT] User plot device selection PLOTERRS.DAT [MIIPS.INCLUDE] Plot package error file PLOTPAR.FOR [MIIPS.INCLUDE] Plot package include file SADERRS.DAT [MIIPS.INCLUDE] Lower level error file SADPAR.FOR [MIIPS.INCLUDE] Lower level include file SAOCAPTION.FOR [MIIPS.DISPLAY] User routine to display a message on SAOimage. It also reinitializes the world coordinate system in SAOimage. SAOCONVLT.FOR [MIIPS.DISPLAY] User routine to control the lookup table SAODEMO.FOR [MIIPS.DISPLAY] Demo #1 (shows all capabilities) SAODEMO2.FOR [MIIPS.DISPLAY] Demo #2 (focusing sequence) SAODEMO3.FOR [MIIPS.DISPLAY] Demo #3 (contact binary) SAODEMO4.FOR [MIIPS.DISPLAY] Demo #4 (cursor readback) SAODEMO5.FOR [MIIPS.DISPLAY] Demo #5 (vector drawing) SAODEMO6.FOR [MIIPS.DISPLAY] Demo #6 (polygon drawing) SAODEMO7.FOR [MIIPS.DISPLAY] Demo #7 (random colored areas) SAODEMO8.FOR [MIIPS.DISPLAY] Demo #8 (3 gravitating bodies) SAODEMO9.FOR [MIIPS.DISPLAY] Demo #9 (video of binary) SAODEMO10.FOR [MIIPS.DISPLAY] Demo #10 (displays FITS files) SAODOT.FOR [MIIPS.DISPLAY] User routine to display a single dot SAOERAS.FOR [MIIPS.DISPLAY] User routine to erase the image buffer SAOFACTS.FOR [MIIPS.INCLUDE] User include file SAOFIRST.FOR [MIIPS.DISPLAY] User routine to set up the coordinate system and erase the screen of all items. SAOLOAD.FOR [MIIPS.DISPLAY] User routine to load an image or images SAOSAMPLE.FOR [MIIPS.FOR] Simple sample SAOSTART.FOR [MIIPS.DISPLAY] User routine to prompt the user for the frame buffer size if not already selected SAO_CURN.FOR [MIIPS.DISPLAY] User routine to read back cursor positions (desktop, frame, and file) SAO_DISPLAY_VECT.FOR [MIIPS.DISPLAY] User routine to display a set of vectors already written into frame SAO_DRAW.FOR [MIIPS.DISPLAY] User routine to display cursors SAO_ERASE_CURSOR.FOR [MIIPS.DISPLAY] User routine to erase cursors SAO_LOAD_VLT.FOR [MIIPS.DISPLAY] User routine to download a custom video look-up table SAO_VECT.FOR [MIIPS.DISPLAY] User routine to draw vectors (2 modes) TV.OLB [MIIPS.LIB] Display package library. This is only used for demo #8. ZFIOVI.C [MIIPS.C] Required lower level routine The demonstration programs make use of the USRINP subroutine and dynamic memory. To use these, you will need: Name Location on MIIPS$DISK Description ALPHA.FOR [MIIPS.FOR] Required lower level routine DCD.FOR [MIIPS.FOR] Required lower level routine DELAY.FOR [MIIPS.FOR] User routine to delay exection DO.FOR [MIIPS.FOR] Required lower level routine DYNAMIC.FOR [MIIPS.FOR] User routine to obtain dynamic memory ERROR.FOR [MIIPS.FOR] Required lower level routine MAPSCRAT.FOR [MIIPS.FOR] Required lower level routine MESSAGE.FOR [MIIPS.FOR] User routine to print messages on terminal and in log file NEL.FOR [MIIPS.FOR] Required lower level routine NELD.FOR [MIIPS.FOR] Required lower level routine NUMARGS.MAR [MIIPS.FOR] Required lower level routine PRTMSG.FOR [MIIPS.FOR] Required lower level routine SAVE.FOR [MIIPS.FOR] Required lower level routine STRKEY.FOR [MIIPS.FOR] Required lower level routine STRLUDEF.FOR [MIIPS.FOR] Required lower level routine USRINP.FOR [MIIPS.FOR] User routine for generalized character and numerical input There are also some sample FITS files available: Name Location on MIIPS$DISK Description NGC1316O.FITS [MIIPS.SAMPLES] INTEGER*2 format TST0004.FITS [MIIPS.SAMPLES] INTEGER*4 format TST0005.FITS [MIIPS.SAMPLES] REAL*4 format The most straightforward way to proceed, whether you have obtained each of the files from the MIIPS package, or whether you have downloaded the backup save set, is to run the command file MAKE_SAO_DEMOS.COM. Enter @MAKE_SAO_DEMOS This will compile the files, put them into a library and link. Before running the programs, enter ASSIGN MY_DISK:[MY_DIR] LBY: where MY_DISK and MY_DIR refer to the location of the file PLOTERRS.DAT. It is possible to build a UNIX and Linux version of SAOimage from the same code in [MIIPS.X_WINDOW.SAOIMAGE]. UNIX versions of the communications interface routines and demos can also be found in the MIIPS package. One should first read the file SAO_INSTRUCTIONS_UNIX.TXT in the MIIPS$DISK:[MIIPS.UNIX.DISPLAY] directory, or download the file from the link at http://www.astro.gsu.edu/~gudehus/enhanced_saoimage.html. Any questions should be directed to Donald Gudehus at gudehus@astro.gsu.edu.