  This directory is provided for users who wish to modify existing Vista
subroutines or to add their own new subroutines.  We assume that you
(or someone) has already compiled and linked the distribution version
of Vista.

   There are two possibilities for modifying/adding routines.
If you are the system curator of Vista and wish to change routines for all
users, you will be making the modifications in the Vista directory tree.
If you wish to create your own private version of Vista in your own
directory tree and not have you changes accessible to everyone on the
system, it is easy to do so. To make your own personal version:

1. Find out the name of the full directory path of the
top level lickvista subdirectory (e.g. /usr/local/lickvista). 

2. In your own area, create yourself a vista subdirectory and change your 
working directory to put yourself there.

3. Execute the file whatever/lickvista/user.csh (whatever is top top level).
This will ask you for the full path name of the lickvista subdirectory. Enter
it without the trailing slash.  The user.csh file will then create for you
a user subdirectory and copy over the necessary makefiles for you to make
your own version.  You can then follow the instructions below for creating
a new version of Vista.  The only difference is that you will be entering:
                     make myxvista or 
		     make myvista 
instead of make xvista or make vista.


 i) Adding a new subroutine

    1. Write the subroutine.  It will be
helpful if you debug it as much as possible before trying to add it to
Vista, perhaps by running key sections of the routine as a separate
program. Make the name of the file holding the program the same as the
name of the subroutine itself, if possible.  For example, the
subroutine AVERAGE is found in average.F.  If you are running on a 
UNIX system, remember to put the C-preprocessor line #define Vista.h
at the top of your subroutine.  The filename of your subroutine should
have extension .F so that it is properly recognized as a file to C-preprocess.

    2.IMPORTANT:  Check that the name you have chosen for your
subroutine does not already exist in VISTA. This is probably most
easily accomplished by checking the list of subroutines in Appendix 5
of this guide. Alternatively, check the contents of the object
libraries in lickvista/source.

    3. Move your file into the lickvista/source/user subdirectory, or
your own user subdirectory if you are making a private version. Edit
the makefile there, and add the name of your subroutine in 3 places:
the lines which say OBJS=, LOBJS=, and VMSCODE=.  Follow the examples
shown there. NOTE: if you are writing a C subroutine, don't add the
name to the VMSCODE line.

    4. Compile the program by typing: make
when located in the lickvista/source/user (or your own user) subdirectory.
If the program does not compile successfully, fix the problems in it,
and try again.

    5.  Add the call to the subroutine to the command tree. This is
easily accomplished by modifying the file
lickvista/source/user/user.pgm, which is automatically included in the
main level VISTA program. At an appropriate place in the command tree,
add (in this case, since the subroutine requires an image)

	ELSE IF (COM .EQ. `somestring') THEN
	          NEEDIM = somenumber
	          IF (GO) CALL SUBROUTINENAME

Some examples are given in the user.pgm file. If your routine gets an
image passed to it, you will need to call a C subroutine which will
do the pointer translations that are required. In this case make the
call to a routine called   CCSUBROUTINENAME. See (6) below for how
to make this entry in the lickvista/source/user/user.c file.

    6. If your routine passes an image address,
you will need to make a corresponding C routine that translates the pointer
to this address which FORTRAN passes to the value of the address itself,
which your subroutine wants.  This is easily accomplished by adding
an entry in the file lickvista/source/user/user.c.  This file contains
the C translation routines. Follow the example there. Basically, the
C routines simply receive the arguments, and pass them straight back to
your routine, with exception of the argument which has the address of the
address of the data. For this argument, the C routines passes the address
of the data.

    7.  Link Vista.  From the lickvista/source subdirectory, execute 
the command:

	make xvista   (to make an X11 version), or
	make sunvista (to make a SunView version).

If you are making a private version, from your top level vista directory, type:

	make myxvista (to make an X11 version called xvista), or

	make myvista (to make a SunView version called vista)

    8.  Debug your program in the Vista system. 
If it does not work, return to step 1. If it seems to
work, make sure that it works under all circumstances. Try omitting
keywords, running it with varying image sizes and origins, etc. 

    9.  Find the helpfile lickvista/help/helpfile.hlp
Add a new entry according to the pattern of entries already there.
Place your new entry near those for programs that have similar
operation.  Make your entry a {\it complete} set of instructions for
the user. Run the program lickvista/help/makehelp which processes
helpfile.hlp into smaller helpfiles which the \V command HELP reads.
(This takes about a minute or so.) On a UNIX system, you will need to
delete all files in the lickvista/help subdirectory with suffix  .HLP
(in capitals, beware: DON'T DELETE FILES WITH LOWERCASE extensions!!!

  ii) Modifying an existing subroutine\rm}

	Here we again use AVERAGE as an example.

    1.  Copy the appropriate subroutine to the lickvista/source/user 
or to your own local user subdirectory and make changes to the
subroutine. Leave the old version where you found it - the link list
is ordered such that it should use your modified version even when the
old one still exists. Make your modifications.

    2.  Compile the program by typing: make
when located in the lickvista/source/user subdirectory.
If the program does not compile successfully, fix the 
problems in it. If the program compiles properly, continue to step 3. 

    3.  Link Vista.  From the lickvista/source subdirectory, execute the 
command:

	make xvista   (to make an X11 version), or
	make sunvista (to make a SunView version).
  or
	make myxvista (if you are making your own local private version)

    4.  Debug your program in the Vista system. If it does not work, 
return to step 1. If it seems to work, make sure that it works under 
all circumstances. Try omitting keywords, running it with varying 
image sizes and origins, etc. 

