

	-------------------------------------------------
	Notes on building/running SAOimage on VMS (Jun91)
	-------------------------------------------------


These notes describe how to build and run this release of SAOimage
on a VAX/VMS system.  VMS/IRAF imtool usage is also discussed. 


--------
Building
--------


DCL command procedures with input file lists are used to build SAOimage
on VMS.  They are designed to run on any VMS system with the DEC VAX C
compiler and are not dependent on any special build software such as DEC
MMS or IRAF mkpkg.  A rudimentary Make-like strategy is used. 

In the top-level SAOimage source directory and the [.BTNLIB] and
[.VMS] subdirectories, the following files perform the build:

	MAKE.COM	DCL command procedure to compile local source
			files and insert them into an object library;
			top-level MAKE.COM also links the executable

	MAKE.LST	input list of SAOimage source files


To build SAOimage:

1.  Verify the build options.  These are set in the "/define=(...)"
    part of the "compile" command definition in each MAKE.COM file.
    The current options that can be changed on VMS:

      IFLAGS: image reading code to be built into SAOimage

	FITS   - reads array files with FITS headers
	OIF   - reads IRAF .imh/(.pix) files with detached headers
	IMTOOL - support imtool interactions with IRAF
	DEBUG  - turn on various internal debug messages

      MFLAGS: machine or library specific code

	XV11R2  - Xlib not up to full XV11R3 standards (leave enabled for VMS)
	PSCRIPT - hard copy output to a PostScript printer (else no hardcopy)
	LSB	- (least signif. byte) byte swap relative to FITS standard

    For example, if you do not want IRAF imtool support, change the
    "IMTOOL" to "NOIMTOOL"

    There is no need to define VMS or VAX; these are automatically defined
    by the VAX C compiler.

2.  From the main directory of SAOimage source, execute the MAKE.COM
    procedure via @MAKE.  (Running this as a subprocess or batch job
    with the output to a log file is advisable; it can take a while.)

Note:  If [.VMS]ZFIOVI.C will not build, compile it separately (without
       defining IMTOOL) or change ZFIOVI.C to !ZFIOVI.C in [.VMS]MAKE.LST
       and ignore the linker complaints.  This source is currently used
       for IRAF imtool support only.


To update VMS/IRAF (imtool support only):

1.  Verify that the file IRAFDISK:[IRAF.VMS.GDEV...]ZFIOVI.C exists.

    Verify that the file IRAFDISK:[IRAF.VMS.GDEV]ZFIOGD.X references
    the routine "zopnvi".

    Note: The IRAF top-level directory may be different on your system.

2.  If the above is verified, then VMS/IRAF already supports imtool,
    and there is no need to go further with this step.

    If not, then update VMS/IRAF and rebuild as follows:

	From [.VMS] subdirectory ...

	$ copy ZFIOGD.X IRAFDISK:[IRAF.VMS.GDEV]
	$ copy ZFIOVI.C IRAFDISK:[IRAF.VMS.GDEV]
	$ copy MKPKG.   IRAFDISK:[IRAF.VMS.GDEV]

	In IRAFDISK:[IRAF.VMS.GDEV] ...

	$ mkpkg					! update the LIBSYS library

	Then, either

		- rebuild the VMS/IRAF shareable image
		- relink all of IRAF
	    or
		- rebuild some executables without the shareable image:

		pkg/cl/			(for stdimage cursor)
		pkg/images/tv/display/	(for images.display task)
		noao/proto/		(for noao.imexamine and tvmark tasks)

		$ mkpkg -vz update


------------
Installation
------------


Install the SAOimage executable and the startup .COM file, along with the
configuration file needed for communication with IRAF.  If you intend to
install the files in a system location, you must be logged in as SYSTEM.
For our purposes here, let's assume you are going to put the files in
SYS$LOCAL:[SAOIMAGE].

        $ @[.vms]install SYS$LOCAL:[SAOIMAGE]	   # or wherever

All of the "run-time" files (there are 4) are installed in the same place
on VMS systems.

You may wish to install the help information in a standard help library
on your system:

        $ lib/help/log sys$help:localtools SYS$LOCAL:[SAOIMAGE]saoimage.hlp

You may wish to set up a symbol that users can use to run the startup
command procedure; global symbols such as this are often defined in
SYS$MANAGER:SYLOGIN.COM.

        $ saosetup :== @SYS$LOCAL:[SAOIMAGE]saosetup

The file SAOSETUP.COM performs the following setup functions for users:

    A foreign command needs to be defined to run the program from DCL
    with command line arguments a la C/Unix conventions, for example,

	$ saoimage :== $disk:[directory]saoimage.exe

    SAOSETUP makes this definition based on its own location.  (SAOSETUP.COM
    and SAOIMAGE.EXE should be in the same directory.)

    If your site supports PostScript printer output, the R_DISPOSE foreign
    command should define a command which prints (and deletes) a PostScript
    file, for example,

	$ r_dispose :== print/delete/notify/queue=... "%s"

    There are several choices for the r_dispose symbol in SAOSETUP.COM;
    you should uncomment the relevant definition.  Read the comments in
    SAOSETUP.COM for more information.  Note that the "%s" string will be
    replaced with the filename by SAOimage.  (It is in double quotes
    because the "s" must be lower case in SAOimage.)

    SAOSETUP also accepts a nodename argument that will be set up as
    a remote display.  (If there is no command line argument, the local
    display is used.)

There is no special setup for running under DECwindows.  The standard
"SET DISPLAY" command can be used to define which workstation will be
used as the display.  Alternatively, the "-d" option can be supplied
as an argument to SAOimage, for example,

	$ saoimage -d mynode::0.0 imagefile.imh 

where "mynode" is replaced by the DECnet node name of the workstation. 

The command line options are documented in the User Manual [.DOC]MANUAL.TEX
as well as the help page [.VMS]SAOIMAGE.HLP.


--------
VMS/IRAF
--------


Using SAOimage in imtool mode with VMS/IRAF is the same as on Sun or
DECstation systems, except for the usual VMS/Unix differences in file
names, etc.  There may also be differences in the window environments
and window managers (i.e., DECwindows vs various Unix X servers, etc). 

The imtool configuration file that is supplied with SAOimage is used by
default.  If users want to have custom frame buffer configurations, they
should make a personal copy of the configuration file.  (The default
file is pointed to by the IMTOOLRC logical name after SAOSETUP is run,
so users could `copy imtoolrc sys$login:.imtoolrc' to get a copy.)
The custom imtoolrc file should be in the user's home directory (named
SYS$LOGIN:.IMTOOLRC) or else the logical name IMTOOLRC should point
to this file, for example,

	$ DEFINE IMTOOLRC DISK:[USER.IRAF]IMTOOL.RC

A sample IMTOOLRC file is attached below, if one can't be found otherwise.

SAOimage is started as an imtool server with

	$ saoimage +imtool		OR
	$ spawn/nowait/in=nl: saoimage +imtool

This is typically run in one window, while the IRAF CL is running in
another.  On the IRAF side, set stdimage to your favorite imtool
configuration in the login.cl file (or interactively).  The standard
configurations are listed below in the sample IMTOOLRC file. 

Once SAOimage and IRAF are both running, the standard IRAF tv.display,
noao.imexamine, and noao.tvmark tasks can be used to display and control
the image display window supported by SAOimage. 


--------------------
Sample IMTOOLRC file
--------------------


# IMTOOL -- Defined frame buffer configurations.  Note that the given nframes
# is only a starting point, and may be modified during execution, hence smaller
# values are preferred.  The configuration numbers may be given in any order,
# but must be unique and in the range 1-64.  NOTE - corresponding entries must
# be present in the dev$graphcap file, for use with IRAF.
#
# Format:  configno nframes width height

 1  2  512  512		# imt1|imt512
 2  2  800  800		# imt2|imt800
 3  2 1024 1024		# imt3|imt1024
 4  1 1600 1600		# imt4|imt1600
 5  1 2048 2048		# imt5|imt2048
 6  1 4096 4096		# imt6|imt4096
 7  1 4096 1024		# imt7|imt4x1
 8  1 1024 4096		# imt8|imt1x4
 9  2 1144  880		# imt9|imtfs	full screen (1152x900 minus frame)
10  2 1144  764		# imt10|imtfs35	full screen at 35mm film aspect ratio
11  2  128  128		# imt11|imt128
12  2  256  256		# imt12|imt256

# Some site specific formats for NOAO.
20  2  388  576		# imt20|imtgec	GEC CCD detector format
21  1 3040  976		# imt21|imtkpca	KPCA detector format (also 2D-Frutti)
22  1  128 1520		# imt22|imt2df1 2D-Frutti
23  1  256 1520		# imt23|imt2df2 2D-Frutti
24  1  512 1520		# imt24|imt2df5 2D-Frutti
25  1  960 1520		# imt25|imt2df9 2D-Frutti
26  1  512  800		# imt26|imtcryo Cryogenic Camera
27  1  348  800		# imt27|imtgcam Gold Camera
28  1  976 3040		# imt28|imt2df9x3 2D-Frutti 
