Repatch (from linux) of OSX IRAF

1 files changed, 572 insertions, 0 deletions

diff --git a/doc/vmsprog.hlp b/doc/vmsprog.hlp
new file mode 100644
index 00000000..bd8c7b2e
--- /dev/null
+++ b/doc/vmsprog.hlp
@@ -0,0 +1,572 @@
+.help vms Nov85 "VMS/IRAF Programming Notes"
+.ce
+\fBVMS/IRAF Programming Notes\fR
+.ce
+Doug Tody
+.ce
+25 November 1985
+.sp 2
+.sh
+Preface
+
+    The purpose of this document is to serve as a guide to programming in the
+VMS version of the IRAF environment.  The discussion focuses on the
+peculiarities of the NOAO VMS/IRAF environment rather than on the basics of
+programming in IRAF; this is not an IRAF programming tutorial.  The discussion
+is intended for the practicing programmer using the NOAO/Tucson version of
+VMS/IRAF, which includes the Eunice UNIX emulator and which is embedded in
+a local network of four Vaxes and one Sun workstation.  The discussion
+describes the VMS version of IRAF as it currently exists at NOAO, with all
+its bugs and defects, hence the document will rapidly become dated.
+
+.nh
+Introduction
+
+    The foreign task interface is now working well enough in the VMS version
+of IRAF for me to recommend that IRAF software development and testing be
+done from within the IRAF environment rather than in DCL.
+All of the VMS facilities are easily and efficiently accessible,
+plus one has the many advantages of the CL, e.g.,
+multiple commands on a command line, i/o redirection, ease of
+spawning background jobs, logical directories, networking facilities etc.
+The environment provides the basic tools we are used to on our UNIX based
+systems (with help from Eunice), although the more subtle features of
+UNIX are missing (e.g., OS escapes in VI or the debugger, job control, etc.).
+
+.nh
+The NOAO VMS/IRAF Programming Environment
+.nh 2
+The USER Package
+
+    The USER package provides a way for the IRAF user to extend the IRAF
+environment by adding IRAF or foreign tasks of their own choosing.
+These extensions will normally be site dependent and will often vary from
+user to user.  In this section we describe the USER package for the IRAF
+login on the NOAO VMS systems.  The USER package is defined in the IRAF
+login.cl file (usr1:[iraf.local]login.cl), which uses VMS logical names
+defined in the IRAF login.com file (usr1:[iraf]login.com).
+
+The USER package is automatically loaded at login time since it is in the
+login.cl file.  The current contents of the package are summarized in the
+menu below ("?u" to print when in the CL).  The contents of this package
+change frequently but it is likely that the present package already contains
+the most frequently used utilities.  Note that the standard \fBsoftools\fR
+task are included for convenience.
+
+
+.ks
+.nf
+    adb      grep     mklib    ps       rlogin   ruptime  top      who
+    chmod    ls       mkpkg    purge    rpp      rwho     touch    wtar
+    diff     mail     mon      pwd      rsh      sed      update   xc
+    finger   make     od       rcp      rtar     su       vdir     xpp
+    generic  man      omake    replace  run      telnet   whereis  
+.fi
+.ke
+
+
+Many of the tasks shown here are simply foreign task definitions for the
+Eunice/UNIX tools, which are used just as they are on a UNIX system.
+Some of the others are less obvious and are described in the notes below.
+.ls 4
+.ls 10 adb
+Debug a VMS executable; short for "!run/debug".
+For example, "adb x_x" will run the VMS debugger on file "x_x.e".
+You should log in directly on the class 6 VAX rather than via \fBtelnet\fR,
+else the screen will scroll rather than be randomly updated.
+On VMS a process must be linked specially to be used with the debugger.
+To do this, add the "-x" flag to the XC command line.
+A task linked in this fashion CANNOT presently be run from the CL in the
+normal fashion, so always use the "-o" flag to give the debug executable
+a different name than the installed executable, e.g, "x_x.e".
+.le
+.ls run
+The opposite of ADB.  Runs a process linked with the debugger with DEBUG
+turned off (i.e., a VMS run/nodebug).  Will also run any normal (nondebug)
+executable.
+.le
+.ls generic
+The IRAF generic preprocessor.  Usually run explicitly on VMS since the
+Eunice MAKE has filename, etc. problems and cannot run many UNIX/IRAF
+makefiles.  Look in the UNIX makefile to get the command to feed to generic.
+.le
+.ls ls
+The Eunice/UNIX directory lister.  Used when you want to see multiple file
+versions (these are invisible in an IRAF "dir" listing),
+or when you want an "ls -lt" time sorted file listing.
+The disadvantages of LS for normal use are that it
+does not expand templates and does not unmap filenames.  Note also that
+recursive descent does not work in Eunice (at least not for me), hence commands
+like "ls -R" will hang.
+.le
+.ls mail
+Calls the VMS mail program.  Whenever possible use UNIX mail instead to send
+messages, unless you are sending mail to Nigel or some other diehard VMS type
+who reads their VMS mail frequently.
+.le
+.ls mklib
+The IRAF library maintenance utility.  Also available in the \fBsoftools\fR
+package.  Essentially equivalent capability to the UNIX version.
+A VMS manual page is appended.
+.le
+.ls mkpkg
+Make package.  Runs the "mkpkg.com" script in the current directory.
+This is the VMS/IRAF equivalent of the "make" used on a UNIX system to
+make or update a package.
+.le
+.ls mon
+Monitor system.  Equivalent to "!monitor system".  Not as useful as the
+UNIX task of the same name, but the output is prettier.
+.le
+.ls omake
+Makes an object version of a file if one does not already exist; needed because
+Make is not available on VMS.  The only alternative in VMS is "xc -c file"
+which is much slower since it always recompiles the named file.  Note that
+OMAKE does not check any include file dependencies.
+.le
+.ls ps
+The Eunice version of PS.  Contains a lot more information than the VMS
+"show sys".  The output from "ps -axu" is particularly useful.
+PS is currently about the only thing on VMS which can tell you what command
+another user is running.
+.le
+.ls purge
+The VMS purge-old-versions task.  Type "pu *.*" often when working in VMS.
+The form "pu [...]*.*" will purge all old versions in the current directory
+and below.
+.le
+.ls replace
+Replace the named module in the named LIB$ library, e.g.,
+
+	cl> replace read.x sys
+
+would recompile "read.x" and replace the object module in the library
+"lib$libsys.a", aka "iraflib:libsys.olb".  This is primarily of interest
+to systems programmers, since it works only on the system libraries in LIB$.
+NOTE: this is a dangerous utility, since it is easy to replace (insert)
+the module into the wrong library.
+.le
+.ls rtar
+The IRAF read tarfile task.  Used to unpack IRAF files from a tar tape,
+or more commonly, from a tar format disk file pushed through the Ethernet.
+A VMS manual page is appended.
+.le
+.ls telnet
+Used to log in on a remote node.  When logging onto a UNIX node from a VMS
+node, frequent <ctrl/q>'s will be necessary when using utilities like PAGE
+and VI to keep the terminal talking.
+.le
+.ls top
+Display the processes currently using the most cpu cycles.  Equivalent to
+a "!monitor proc/topcpu".  Similar to the UNIX "top" but takes no arguments
+and returns less information about the resources consumed by the processes.
+.le
+.ls update
+Update the named LIB$ system library by running MKLIB on the contents of
+the current directory.  This is like REPLACE except that it will hopefully
+find and replace all recently modified modules in the current directory.
+UPDATE is equivalent to the following sequence of VMS commands:
+
+.ks
+.nf
+	$ copy iraflib:libXXX.olb []
+	$ mklib libXXX.a
+	$ rename libXXX.olb iraflib
+.fi
+.ke
+
+Note the use of [] to signify the current directory, and the use of RENAME
+to move a file to another directory.
+.le
+.ls vdir
+The VMS directory lister.  Used when one wants to ask VMS questions about
+files, e.g., to query protections, get /full listings, etc.  The advantage
+of having this available as a foreign task (rather than just using an OS
+escape) is that the output can be redirected into a file.  For example,
+
+	cl> vdir /full [...]*.exe > _exec
+
+will save in file "_exec" a /full format directory listing of all executables
+in the current directory and below.
+.le
+.ls who
+Equivalent to a "!show users".
+.le
+.ls wtar
+The UNIX write tarfile utility.  Used to save a directory tree in a portable
+a UNIX "tar" format binary file.  Use this with the "-o" (omit binaries) flag
+to move sources back to UNIX.  For example,
+
+.ks
+.nf
+	cl> cd pkg
+	cl> wtar -of home:plarc [.plot]
+.fi
+.ke
+
+will make a tarfile "plarc" of the subdirectory "plot", assuming that HOME is
+defined as a VMS logical directory name.  Most variations on the command
+shown here do not currently work.
+A VMS manual page is appended.
+.le
+.ls xc
+The IRAF XC portable compile/link utility.  This task is also available in
+the \fBsoftools\fR package.  A VMS manual page is appended.
+.le
+.le
+
+
+The USER package described here may be extended by copying the package
+definition to your own login.cl file, then adding additional task definitions.
+
+.nh 2
+Foreign Tasks
+
+    New foreign tasks may easily be defined at run time, for example when one
+wants to capture the output of a VMS utility without having to edit a .com
+file and submit a batch job (many VMS tasks do however have a /OUTPUT switch
+which does much the same thing), or when one wants to run a foreign task
+in the background.  For example,
+
+
+.ks
+.nf
+	cl> task $vll = "$library/list/full"
+	cl> vll osfn("lib$libos.a") > _lib
+.fi
+.ke
+
+
+defines a new task VLL which uses the VMS library to list the contents of a
+library, then uses the new task to list the contents of the system library
+LIBOS, saving the output in the file "_lib".  Note the use of the string
+valued intrinsic function OSFN to generate a VMS filename for the foreign
+task.  To discard a foreign task definition (or any task definition), exit the
+package in which it was defined, or type "cl" before defining the task,
+followed by "bye" at some later time to discard everything back to the "cl".
+
+A foreign task command is parsed by the CL just like any other IRAF command,
+as is evident from the second example above.  The arguments to a foreign
+task may be arbitrary expressions; the CL reduces each such argument
+expression to a constant value and passes this value to the host system as
+a string.  Note that VMS will convert all arguments to a single case unless
+they are quoted.  For example,
+
+	cl> xc '"-cO"' file.x
+
+is the command to compile a file with optimization (the current XC default
+is to not optimize).
+Note that the first set of quotes are stripped off the by the CL, and the
+second by DCL.
+
+.nh 2
+Filenames
+
+    Avoid using the VMS meta-characters [ and $ in filenames when working
+within the IRAF environment (except in calls to foreign tasks).  To reference
+a file in an arbitrary VMS directory you must first define the VMS directory
+as an IRAF logical directory.  Directories which are frequently referenced
+should be defined in your login.cl file.
+
+
+.ks
+.nf
+	cl> set iis = sdk:[kpno.iis.prim]
+	cl> ed iis$foreign.f
+	cl> cd iis
+	cl> dir *.f
+	cl> back
+.fi
+.ke
+
+
+The example above defines a new logical directory IIS and uses it to edit a
+file therein, change to the directory, and so on.  A reference such as the
+following would fail because the system would try to do template expansion
+on the [] delimited field.
+
+	cl> page sdk:[kpno.iis.prim]foreign.for		# won't work
+
+The following should work and will work in a future version of the system,
+but does not work at present.
+
+	cl> page sdk:\[kpno.iis.prim]foreign.for
+
+The mixture of IRAF, Eunice, and VMS tasks present in the USER package can be
+confusing when it comes to filenames.
+Most references to files in the current directory
+are the same in all environments, but there are major differences
+when pathnames are involved.  To work effectively and without aggravation
+you must know what type of task you are calling and supply the appropriate
+type of filename.  This is the price we pay for having direct access to
+foreign tasks.
+
+.nh 2
+I/O Redirection and Background Execution
+
+    I/O redirection will now work on VMS/IRAF for foreign tasks as well as
+true IRAF tasks.  The input or output of a foreign task may be redirected
+on the command line; foreign tasks may be used in pipes.  This is particularly
+useful in combination with background execution, e.g.,:
+
+
+.ks
+.nf
+	cl> mkpkg >& spool &
+or
+	cl> xc -c file1.x,file2.x,file3.f >& spool &
+.fi
+.ke
+
+
+Background jobs currently run at a reduced priority on both UNIX and VMS.
+At present any IRAF background jobs will be terminated when you log out of VMS.
+Support for submission of IRAF background jobs to the VMS batch queues is
+being actively worked on and will be available in the near future.
+
+.nh 2
+Editor Interface
+
+    The NOAO VMS/IRAF editor interface currently supports the VI and EDT
+editors (Emacs is also supported but we do not have the actual editor at NOAO).
+One types "edit" or "ed" to invoke the editor; the choice of the actual
+editor to be used is controlled by the \fBeditor\fR environment variable,
+which may be set in your login file.
+
+The major limitation in the editor interface to VI is that template expansion
+is not currently supported (the template is passed to the Eunice VI but it
+is not expanded, since the UNIX shell normally does this for VI).
+The ":!" OS escape mechanism does not currently work (for all but a few
+commands) in the IRAF environment, although it does work in the Eunice cshell
+environment.  It is possible for the editor to have a different idea of the
+current default directory than IRAF; if you suspect that this is the case,
+type ":!pwd" to check and ":!cd /newdir" to fix it up.
+
+.nh 2
+Network Facilities
+
+    Network access is currently available for the class 1, 2, and 5 Vaxes
+from any other IRAF node, including the two VMS Vaxes and the Sun workstation.
+All binary and text files and the class 2 (lyra) IIS may be accessed over
+the network.  Access to VAX/8600 hosted resources from the 750's will be
+available shortly.  For example, to copy a file from lyra to the current
+directory when logged into IRAF on the 8600, any of the following equivalent
+commands would work:
+
+
+.ks
+.nf
+	cl> copy lyra!/iraf/lib/fio.h fio.h
+	cl> copy 2!/iraf/lib/fio.h .
+	cl> copy 2!lib$fio.h .
+.fi
+.ke
+
+
+Images may also be accessed over the network, provided there is a VAX at
+both ends (this restriction will be removed when the DBIO based IMIO is
+installed).
+
+
+.ks
+.nf
+	cl> set pix = 2!/tmp2/iraf/images/
+	cl> implot pix$canon
+	cl> imcopy pix$canon canon2
+.fi
+.ke
+
+
+Copying an image from the local node to a remote node does not work at
+present, even when IMDIR is defined to be on the remote node.  I have not
+yet had time to figure out why.
+
+Whenever a local process accesses a resource on a remote node the system will
+spawn a "kernel server" process on the remote node.  The kernel server
+remains connected for the life of the local process, hence there is a delay
+the first time a node is referenced (while the kernel server process is being
+spawned), but all subsequent commands execute almost as fast as on the local
+node.  For example, there is a fixed delay of several seconds when an image
+is first displayed from the 8600 on the lyra IIS, but thereafter image load
+will be quite fast, so long as the image load process remains in the process
+cache.
+
+The kernel server process must authenticate on the remote node with a login
+and a password.  By default the NOAO system currently uses the "ace" login for
+this purpose; this is adequate for most purposes but, for example, printer
+output will come out with an ACE jobname, and you will not have network write
+access to your own files and directories.  To have a fully functional network
+interface you must add the file ".irafhosts" to your host system login
+directory.  This structure of this file is very simple and is best explained
+by an example:
+
+
+.ks
+.nf
+	# Sample .irafhosts file.
+
+	aquila lyra carina 	: login1 password1
+	vela draco		: login2 password2
+	*			: login3 password3
+.fi
+.ke
+
+
+Each line in the file associates a login name and password with a set of
+hosts.  Use the "real" host names in this file (e.g., "lyra"), not the
+aliases (e.g., "2, class2").  The "*" line supplies a login and password
+for any host machine and terminates scanning of the file, hence should be
+given last.  In the simplest case, i.e., where your login name and password
+are the same on all hosts, the file may contain a single "*" type entry.
+If the file contains your password it should of course be read protected.
+For additional security the password may be given as "?" in which case you
+will be asked for the actual password whenever a kernel server is spawned.
+
+.nh
+VMS/IRAF Software Maintenance
+
+    The IRAF group currently maintains IRAF simultaneously on a UNIX 11/750
+(node \fIlyra\fR) and on the VMS cluster (including both of the nodes
+\fIdraco\fR and \fIvela\fR).  Software is written and tested on the UNIX
+11/750 and then installed and tested on the 8600, merging any bug fixes
+from the VMS testing back into the UNIX version of the system.  The UNIX 11/750
+is the primary software development system and contains the "master copy"
+of IRAF.  The 8600 is a production data processing machine and should not
+be used for routine software development (algorithm development requiring the
+speed of the 8600 is permitted, however).
+
+Each member of the IRAF group is responsible for installing and testing their
+software on the 8600.  Since the IRAF environment permits identical software
+to be run on all IRAF hosts, the procedure for doing this is quite
+straightforward.  For example, assume we want to install a new version of
+the PLOT package on the 8600.  The following sequence of commands would
+suffice to install an entire new version of the package.  Incremental changes
+are faster, but a full installation should be done occasionally to ensure
+that the same software is running on both nodes.
+
+
+.ks
+.nf
+	(login on the 8600, get into the CL)
+	cl> telnet lyra
+	    (log into lyra)
+
+	% cd plot
+	% tar -cf ~/plarc .		# make tar archive of plot
+	% rcp ~/plarc 6:		# move tarfile to node 6=draco
+	% logout			# go back to draco
+	
+	cl> cd pkg
+	cl> wtar -of usr0:[tody]plarc.bak [.plot]	# make backup
+	cl> cd plot
+	cl> !show default			# just in case...
+	cl> !del [...]*.*;*			# delete nondir files
+	cl> !set prot [...]*.*;*		# unprotect dir files
+	cl> !del [...]*.*;*			# delete directory files
+	    (repeat until all .dir files gone)
+
+	cl> rtar -xof usr0:[tody]plarc		# unpack new version
+	    (fix up mkpkg.com files, if necessary)
+	cl> mkpkg >& spool &
+	    (test everything once package is rebuilt)
+.fi
+.ke
+
+
+At present the VMS version of each package is maintained by a DCL
+"mkpkg.com" file.  This is the only machine dependent software in an
+IRAF package.  To avoid having to recover the mkpkg.com files from the
+WTAR savefile, you may wish to install the files in the UNIX version of
+the package.  The mkpkg.com files are quite simple since they just call
+the portable IRAF utilities MKLIB and XC, but hopefully we will be able
+replace the UNIX Makefiles and VMS mkpkg.com files by a single facility
+in the future.
+
+As an example, the MKPKG.COM file for the plot package is shown below.
+Note that the Makelib files, used by MKLIB to maintain the package libraries,
+are portable since MKLIB is an (bootstrap) IRAF utility.
+
+
+.ks
+.nf
+	$! Make the PLOT package (VMS)
+	$!
+	$ mklib -i libpkg.a
+	$!
+	$ omake x_plot.x
+	$ omake x_ncar.x
+	$ xc x_plot.o libpkg.a -lncar -lgks -lxtools -o x_plot.e
+	$ xc x_ncar.o libpkg.a -lncar -lgks -lxtools -o x_ncar.e
+.fi
+.ke
+
+
+Each time MKPKG is run new VMS versions of the executables will be added
+to the PLOT directory.  An occasional PURGE is necessary to remove the
+old versions.
+
+.nh 
+Debugging on VMS
+
+    Before an IRAF process can be debugged on VMS, the process must first
+be linked using the "-x" flag to XC.  For example the "x_plot.e" executable
+shown above in the example of a MKPKG.COM file would be relinked for
+debugging with the following command:
+
+	cl> xc -x x_plot.o libpkg.a -lncar -lgks -lxtools -o x_x.e
+
+Note that the new executable is NOT called "x_plot.e", in case someone tries
+to use the plot package while we are debugging it.  To debug the newly
+linked process we first check the ZZSETENV.DEF file to make sure that the
+pathnames therein are up to date; they won't be if the package was recently
+moved over from the UNIX system.
+
+Before debugging the executable make sure that you are logged in directly
+on the VMS machine; do not login remotely via \fBtelnet\fR.  Enter the
+following command to begin debugging the process:
+
+	cl> adb x_x
+
+For use in the IRAF environment the VMS debugger is run in screen mode,
+language MACRO (assembler language debugging).  Type GO to run the program
+(the IRAF main prompt will appear); type EXIT to exit the debugger when
+through debugging.  This will sometimes leave the screen in a funny state
+(a scrolling window less than the full screen may be defined).  If this
+happens, physically reset your terminal.  The initial state of the debugger
+is setup by the file "iraf$vms/init.dbg" which is referenced by the VMS logical
+name DBG$INIT (which should be defined in your VMS login.com file).
+You can change the initial state of the debugger by redefining DBG$INIT to
+reference your own initialization file.
+
+Instruction in the actual VAX/DEBUG commands is beyond the scope of this
+document; the best way to learn the debugger is to get an experienced IRAF
+programmer to give a demo.  The VMS document "Programming in VAX FORTRAN"
+is the best documentation currently available for the VMS debugger.
+
+.nh
+Comments on Performance
+
+    Process spawning and inter-process communication appear to be slow in the
+VMS operating system, compared to UNIX.  When programming in an equivalent VMS
+system (e.g., the VMS 11/750) all operations which involve process spawning
+or inter-process communication will be noticeable slow compared to UNIX.
+When programming on the VMS/8600 these operations seem to be comparable
+in speed to an 11/750 running UNIX (actual process execution is of course
+much faster on the 8600).  Large files will compile faster on VMS than on
+UNIX, but when compiling many small files the two systems are comparable.
+Linking takes about the same amount of time on the UNIX 750 and on the 8600,
+but the UNIX linker may actually be faster once the current cpu bound
+inefficiencies in the UNIX linker are corrected (UNIX may win in the end
+because of the UNIX buffer cache and the prelink facility provided by the
+UNIX linker, but if we ever get sharable libraries working on VMS then it
+may be faster).
+
+When it comes to actually executing a single scientific task, however,
+VMS is in general slightly faster than UNIX running on equivalent hardware,
+because the Fortran optimizer is slightly better, and VMS supports
+asynchronous i/o.  For these and other reasons (e.g., the availability of
+UNIX on virtually all machines, the facilities provided by UNIX for software
+development, etc.) it is best to do software development and other timesharing
+activities on UNIX, reserving VMS for production use, i.e., data processing.
+This is of course our current policy at NOAO.
+.endhelp