Initial commit

1 files changed, 2375 insertions, 0 deletions

diff --git a/doc/vmsiraf.ms b/doc/vmsiraf.ms
new file mode 100644
index 00000000..f0156a93
--- /dev/null
+++ b/doc/vmsiraf.ms
@@ -0,0 +1,2375 @@
+.RP
+.de XS
+.DS
+.ps -1
+.vs -2p
+.ft CB
+..
+.de XE
+.DE
+.ft R
+.ps
+.vs
+..
+.TL
+VMS/IRAF Installation and Site Manager's Guide
+.AU
+Doug Tody, Suzanne Jacoby
+.br
+IRAF Group
+.br
+.sp
+Nigel Sharp
+.br
+CCS
+.AI
+.# National Optical Astronomy Observatories
+.br
+.K2 "" "" "\(dg"
+June, 1993
+
+.AB
+.ti 0.75i
+This document describes how to install or update the VMS version of the
+portable IRAF system (Image Reduction and Analysis Facility).  Installation
+instructions as well as procedures for improving performance, minimizing
+disk and memory usage, configuring the system for the local site, and
+interfacing local devices are given.
+.AE
+
+.bp
+.ce
+\fBContents\fR
+.sp
+1.\h'|0.4i'\fBIntroduction\fP\l'|5.6i.'\0\01
+.sp
+2.\h'|0.4i'\fBInstalling VMS/IRAF\fP\l'|5.6i.'\0\02
+.br
+\h'|0.4i'2.1.\h'|0.9i'Prepare the root IRAF directory\l'|5.6i.'\0\02
+.br
+\h'|0.9i'2.1.1.\h'|1.5i'If updating an existing IRAF installation...\l'|5.6i.'\0\02
+.br
+\h'|0.9i'2.1.2.\h'|1.5i'If installing IRAF for the first time...\l'|5.6i.'\0\03
+.br
+\h'|0.4i'2.2.\h'|0.9i'Read in the distribution files\l'|5.6i.'\0\04
+.br
+\h'|0.9i'2.2.1.\h'|1.5i'Installing from a network distribution\l'|5.6i.'\0\04
+.br
+\h'|0.9i'2.2.2.\h'|1.5i'Installing from tape\l'|5.6i.'\0\04
+.br
+\h'|0.9i'2.2.3.\h'|1.5i'Merge local revisions back into the new system\l'|5.6i.'\0\04
+.br
+\h'|0.4i'2.3.\h'|0.9i'Edit the system configuration files\l'|5.6i.'\0\05
+.br
+\h'|0.9i'2.3.1.\h'|1.5i'[IRAF.VMS.HLIB]IRAFUSER.COM\l'|5.6i.'\0\05
+.br
+\h'|0.9i'2.3.2.\h'|1.5i'[IRAF.VMS.HLIB]INSTALL.COM\l'|5.6i.'\0\06
+.br
+\h'|0.9i'2.3.3.\h'|1.5i'[IRAF.VMS.HLIB.LIBC]IRAF.H\l'|5.6i.'\0\07
+.br
+\h'|0.4i'2.4.\h'|0.9i'Complete the initial system configuration\l'|5.6i.'\0\07
+.sp
+3.\h'|0.4i'\fBTesting a Newly Installed or Updated System\fP\l'|5.6i.'\0\08
+.br
+\h'|0.4i'3.1.\h'|0.9i'Configuring the IRAF account\l'|5.6i.'\0\08
+.sp
+4.\h'|0.4i'\fBConfiguring the IRAF Environment\fP\l'|5.6i.'\0\09
+.br
+\h'|0.4i'4.1.\h'|0.9i'[IRAF.VMS.HLIB]ZZSETENV.DEF\l'|5.6i.'\0\09
+.br
+\h'|0.4i'4.2.\h'|0.9i'The template LOGIN.CL\l'|5.6i.'\0\10
+.sp
+5.\h'|0.4i'\fBConfiguring the Device and Networking Files\fP\l'|5.6i.'\0\10
+.br
+\h'|0.4i'5.1.\h'|0.9i'[IRAF.DEV]TAPECAP\l'|5.6i.'\0\10
+.br
+\h'|0.4i'5.2.\h'|0.9i'[IRAF.DEV]DEVICES\l'|5.6i.'\0\11
+.br
+\h'|0.4i'5.3.\h'|0.9i'The DEVICES.HLP file\l'|5.6i.'\0\11
+.br
+\h'|0.4i'5.4.\h'|0.9i'[IRAF.DEV]TERMCAP\l'|5.6i.'\0\11
+.br
+\h'|0.4i'5.5.\h'|0.9i'[IRAF.DEV]GRAPHCAP\l'|5.6i.'\0\11
+.br
+\h'|0.4i'5.6.\h'|0.9i'[IRAF.DEV]HOSTS, UHOSTS, and IRAFHOSTS\l'|5.6i.'\0\12
+.sp
+6.\h'|0.4i'\fBVector Graphics and Image Display using X Windows\fP\l'|5.6i.'\0\14
+.br
+\h'|0.4i'6.1.\h'|0.9i'Xterm\l'|5.6i.'\0\14
+.br
+\h'|0.4i'6.2.\h'|0.9i'SAOimage\l'|5.6i.'\0\14
+.sp
+7.\h'|0.4i'\fBAdditional System Configuration Issues\fP\l'|5.6i.'\0\15
+.br
+\h'|0.4i'7.1.\h'|0.9i'New networking driver\l'|5.6i.'\0\15
+.br
+\h'|0.9i'7.1.1.\h'|1.5i'DECNET networking\l'|5.6i.'\0\15
+.br
+\h'|0.9i'7.1.2.\h'|1.5i'Proxy logins\l'|5.6i.'\0\16
+.br
+\h'|0.9i'7.1.3.\h'|1.5i'Configuring a VMS host as a TCP/IP server\l'|5.6i.'\0\17
+.br
+\h'|0.9i'7.1.4.\h'|1.5i'Network security alarms\l'|5.6i.'\0\17
+.br
+\h'|0.4i'7.2.\h'|0.9i'New magtape driver\l'|5.6i.'\0\18
+.br
+\h'|0.9i'7.2.1.\h'|1.5i'Allocation\l'|5.6i.'\0\18
+.br
+\h'|0.9i'7.2.2.\h'|1.5i'Density\l'|5.6i.'\0\18
+.br
+\h'|0.9i'7.2.3.\h'|1.5i'Status output logging\l'|5.6i.'\0\18
+.br
+\h'|0.9i'7.2.4.\h'|1.5i'Using tape drives over the network\l'|5.6i.'\0\19
+.br
+\h'|0.4i'7.3.\h'|0.9i'Configuring user accounts for IRAF\l'|5.6i.'\0\19
+.br
+\h'|0.4i'7.4.\h'|0.9i'VMS quotas and privileges required to run IRAF\l'|5.6i.'\0\20
+.br
+\h'|0.4i'7.5.\h'|0.9i'Interfacing new graphics devices\l'|5.6i.'\0\21
+.br
+\h'|0.9i'7.5.1.\h'|1.5i'Graphics terminals\l'|5.6i.'\0\21
+.br
+\h'|0.9i'7.5.2.\h'|1.5i'Graphics plotters\l'|5.6i.'\0\21
+.br
+\h'|0.9i'7.5.3.\h'|1.5i'Image display devices\l'|5.6i.'\0\22
+.sp
+8.\h'|0.4i'\fBTuning Considerations\fP\l'|5.6i.'\0\22
+.br
+\h'|0.4i'8.1.\h'|0.9i'Stripping the system to reduce disk consumption\l'|5.6i.'\0\22
+.br
+\h'|0.4i'8.2.\h'|0.9i'Installing executable images\l'|5.6i.'\0\23
+.br
+\h'|0.4i'8.3.\h'|0.9i'Rendering large runtime files contiguous\l'|5.6i.'\0\23
+.br
+\h'|0.4i'8.4.\h'|0.9i'Precompiling TERMCAP and GRAPHCAP entries\l'|5.6i.'\0\24
+.sp
+9.\h'|0.4i'\fBSoftware Management\fP\l'|5.6i.'\0\24
+.br
+\h'|0.4i'9.1.\h'|0.9i'Shared libraries\l'|5.6i.'\0\24
+.br
+\h'|0.4i'9.2.\h'|0.9i'Layered software support\l'|5.6i.'\0\24
+.br
+\h'|0.4i'9.3.\h'|0.9i'Software management tools\l'|5.6i.'\0\25
+.br
+\h'|0.4i'9.4.\h'|0.9i'Modifying and updating a package\l'|5.6i.'\0\26
+.br
+\h'|0.4i'9.5.\h'|0.9i'Installing and maintaining layered software\l'|5.6i.'\0\27
+.br
+\h'|0.4i'9.6.\h'|0.9i'Configuring a custom LOCAL package\l'|5.6i.'\0\27
+.br
+\h'|0.4i'9.7.\h'|0.9i'Updating the full IRAF system\l'|5.6i.'\0\28
+.br
+\h'|0.9i'9.7.1.\h'|1.5i'The BOOTSTRAP\l'|5.6i.'\0\28
+.br
+\h'|0.9i'9.7.2.\h'|1.5i'Updating the system libraries\l'|5.6i.'\0\28
+.br
+\h'|0.9i'9.7.3.\h'|1.5i'Relinking the IRAF shared library\l'|5.6i.'\0\29
+.br
+\h'|0.9i'9.7.4.\h'|1.5i'Relinking the main IRAF system\l'|5.6i.'\0\30
+.sp
+10.\h'|0.4i'\fBMiscellaneous Notes\fP\l'|5.6i.'\0\30
+.sp
+Appendix A.\h'|0.9i'\fBPrivate TMP and IMDIR Directories\fP\l'|5.6i.'\0\31
+
+
+.nr PN 0
+.bp
+.NH
+Introduction
+.PP
+Before installing VMS/IRAF, one must 1) obtain the VMS/IRAF
+distribution, e.g., from the IRAF network archive on \f(CWiraf.noao.edu\fR
+(or by ordering a tape distribution from NOAO), 2) select the server or node
+on which the system is to be installed and arrange for sufficient disk space
+to hold the system, and 3) set aside sufficient time to do the
+installation.  If these directions are followed carefully and mistakes are
+avoided the basic installation should only take an hour or so.
+Additional time may be required to customize the system to configure the
+local tape drives and other devices, set up IRAF networking, and so on.
+.PP
+V2.10 VMS/IRAF supports VMS versions 5.2 through 5.5.  The amount of disk
+space required to install IRAF, including both the core system and NOAO
+package sources and all binaries, is about 78 Mb.  If desired about half
+of this space can be reclaimed after installation by stripping the system
+of all but the runtime files.
+.XS
+$ dir/size=all \fIirafdisk\fP:[iraf...]
+Grand total of 401 directories, 10507 files, 144566/157008 blocks.
+.XE
+.LP
+The distributed system is a snapshot of our local (NOAO/Tucson) VMS/IRAF
+installation.  The device and system configuration tables come edited for
+our system, and will have to be modified as part of the installation
+process.  These modifications are discussed in detail in this document.  To
+simplify the installation process as well as future upgrades, we have tried
+to isolate the site dependent files to the minimum number of directories,
+i.e., \f(CWdev\fP, \f(CWhlib\fP, and \f(CWlocal\fP and its subdirectories
+(the equivalent VMS pathnames are [IRAF.DEV], [IRAF.VMS.HLIB], and
+[IRAF.LOCAL]).  The remainder of the system should not require any
+modifications.
+.PP
+Feel free to contact the IRAF Hotline for assistance if any problems should
+arise during the installation, or for help in interfacing new devices.
+.TS
+center;
+c s
+l l.
+.sp 1
+\fBIRAF SUPPORT SERVICES\fP
+.sp
+Internet:	iraf@noao.edu
+NSI-DECNET:	noao::iraf or 5355::iraf
+.sp 0.5
+IRAF Hotline:	(602) 323-4160
+FAX:	(602) 325-9360
+.sp 0.5
+Network Archive:	ftp iraf.noao.edu
+(anonymous ftp)	ftp 140.252.1.1
+.sp
+.TE
+
+.NH
+Installing VMS/IRAF
+.PP
+The steps required to install VMS/IRAF are summarized below.  This summary
+is provided only to introduce the installation procedure: it is important to
+read the detailed installation instructions for additional information, to
+avoid certain errors or omissions which are otherwise likely (IRAF does not
+always follow VMS conventions!).
+.XS
+\fR# Prepare the root IRAF directory.\fP
+if new installation
+    create iraf account
+else if updating an old installation
+    save locally modified files; delete old system
+
+\fR# Read in the distribution files.\fP
+login as iraf
+unpack the distribution files from a network distribution or tape
+
+\fR# Modify IRAF system and device configuration files.\fP
+edit site dependent files in hlib, hlib/libc and dev directories
+if updating an old installation
+    merge locally modified files back into new system
+
+\fR# Complete the Initial Installation as SYSTEM.\fP
+add global symbol "iraf" to SYLOGIN.COM
+copy edited hlib$libc/iraf.h file to SYS$LIBRARY
+install in system memory IRAF shared library and other executables
+
+\fR# Checkout the new system.\fP
+run test procedure from iraf account
+.XE
+.PP
+If problems should arise during the installation, help is available from the 
+IRAF Hotline (602-323-4160), or by sending email to \f(CWiraf@noao.edu.\fP
+.NH 2
+Prepare the root IRAF directory
+.NH 3
+If updating an existing IRAF installation...
+.PP
+If you are updating an existing IRAF installation, you will be replacing
+IRAF by the new version and IRAF should already have an account and root
+directory on the desired host system.  You should first log in as IRAF and
+save any locally modified files before deleting the old system.  Ordinarily
+the only directories containing files you may wish to save are \f(CWdev\fP,
+\f(CWhlib\fP, and \f(CWlocal\fP.  The safest and easiest way to do this is
+to save the entire contents of those directories.  For example:
+.XS
+$ set default [iraf]
+$ rename dev.dir,local.dir,[.vms]hlib.dir [\fIdirectory\fP]
+.XE
+.LP
+This would physically move (not copy) the \f(CWdev\fP, \f(CWlocal\fP, and
+\f(CWhlib\fP directories to the named directory, which must be on the same
+disk device as [IRAF].  Many variations on this are possible.  The
+destination directory should be somewhere \fIoutside\fP the [IRAF...]
+directory tree, else it may get deleted when you delete the old system.
+.PP
+Although it is probably simplest and safest to save entire directories as in
+the example, in practice only a few files are likely to have been modified.
+These are the following:
+.XS
+[iraf.dev]tapecap.
+[iraf.dev]graphcap.
+[iraf.dev]termcap.
+[iraf.dev]hosts.
+[iraf.dev]uhosts.
+[iraf.dev]irafhosts.
+[iraf.dev]devices.
+[iraf.dev]devices.hlp
+.XE
+.XS
+[iraf.vms.hlib]motd.
+[iraf.vms.hlib]login.cl
+[iraf.vms.hlib]extern.pkg
+[iraf.vms.hlib]install.lst
+[iraf.vms.hlib]irafuser.com
+[iraf.vms.hlib]zzsetenv.def
+[iraf.vms.hlib.libc]iraf.h
+[iraf.local]login.com
+.XE
+.LP
+Having temporarily preserved all the locally modified files, it is now
+time to delete the old system and read in the new one.  If you are
+the cautious (prudent?) type you may wish to first preserve the entire
+existing IRAF system on a backup tape.  Using only the standard
+VMS utilities, the old system may be deleted as follows (assuming IRAF
+owns all the files in [IRAF...]).
+.XS
+$ set default [iraf]
+$ delete [...]*.*;* /nolog/noconfirm
+$ set protection=(owner:wd) [...]*.*;*
+$ delete [...]*.*;* /nolog/noconfirm
+    \fR(repeat delete command with <ctrl/b> until done)\fP
+.XE
+.LP
+It is normal for the \fIdelete\fP command shown to generate lots of messages
+during execution warning that it cannot delete directories because they are
+not yet empty.  When the command finally executes without any warning messages
+this means the directory tree has been fully deleted.
+.PP
+Once the old system has been deleted you are ready to install the new one,
+as described in \(sc2.2.  It is important to delete the old system first to
+avoid creating junk files or directories when the new system is installed
+(due to file or directory name changes or deletions).  Once the new system
+has been restored to disk, do \fInot\fR merely restore the files saved above,
+as you will need to carefully merge local changes into the versions of the
+files supplied with the new IRAF release.
+.NH 3
+If installing IRAF for the first time...
+.PP
+If you are installing IRAF for the first time then the first step is to set
+up a new account for the user `iraf'.  This is necessary for IRAF system
+management, which should always be done from the IRAF account.  Having an
+IRAF account provides a convenient place (the IRAF system manager's login
+directory) to keep scratch files created during system configuration.
+.PP
+System management policies vary from site to site, so we do not give
+specific instructions for \fIhow\fP to create the account (e.g.,
+\f(CW$ run sys$system:authorize\fP),
+but the account itself should be structured as follows:
+.RS
+.IP \(bu
+Select a disk device with sufficient free space for the system (about 75
+Mb for V2.10).  If necessary, the system can be stripped after installation 
+to save space (\(sc8.1), but the full amount of space will be needed during
+installation.  The disk should not be a "rooted logical" \(dg.
+.FS
+\(dgA rooted logical might be something like \f(CWlocal_disk =
+dub4:[local.]\fR, with the IRAF disk set to \f(CWlocal_disk\fR.
+This will not work.
+.FE
+.IP \(bu
+The root directory for the IRAF account should be set to [IRAF], as
+this name is explicitly assumed in various places in the configuration
+files.  A "rooted logical" directory will not work.
+.IP \(bu
+The \fIlogin\fR directory for the IRAF account should be set to
+[IRAF.LOCAL] rather than [IRAF] as one would expect, as we
+want to keep all the locally modified files in subdirectories off the iraf
+root directory, to simplify site management and future updates.  If this
+point is missed the iraf environment will not be set up properly, and later
+problems are sure to result.
+.IP \(bu
+Do not create a LOGIN.COM for IRAF; one will be read from the
+distribution tape, as will the [IRAF.LOCAL] directory.  (If for some
+local management reason the directory [IRAF.LOCAL] is created at
+this time, make sure it has the proper protections [e.g.,
+"\f(CWset protection = (s:rwd,o:rwd,g:r,w:r)\fR"].)
+.IP \(bu
+There is no need to worry about VMS quotas and privileges yet; this is not
+a concern during installation and is discussed in a later section (\(sc7.4).
+.RE
+.NH 2
+Read in the distribution files
+.PP
+If you are installing from tape skip forward to \(sc2.2.2.  If you are
+installing from a network distribution (i.e., from disk) continue with the
+next section.
+.NH 3
+Installing from a network distribution
+.PP
+VMS/IRAF is available over the network via anonymous ftp from the node
+\f(CWiraf.noao.edu\fR, in the subdirectory \f(CWiraf/v\fInnn\fP/VMS5\fR,
+where "\f(CWv\fInnn\fR" is the IRAF version number, e.g., subdirectory
+iraf/v210/VMS5 for V2.10 VMS/IRAF.  Complete instructions for
+retrieving IRAF from the network archive are given in the
+README file in this directory.  The retrieval can be accomplished with 
+UNIX FTP, VMS FTP or VMS DECNET.
+.PP
+The subdirectory ia.vms5.vax contains the network version of the
+distribution file IA.VMS5.VAX.  This single file contains the entire
+VMS/IRAF distribution, including both sources and binaries.  The file
+IA.VMS5.VAX is stored in this directory as a compressed VMS backup save
+file, split into 512 Kb segments.  To reconstruct the original backup save
+file, the segments must be transferred, uncompressed and concatenated.  This
+can be done in several ways, as described in the README file.  Once the disk
+save set has been reconstructed on your local disk, you can proceed with the
+installation.
+.PP
+Login as IRAF (ignore any LOGIN.COM not found error message) and
+run the VMS \fIbackup\fP utility to read the backup save set, named v210.bck
+in this example:
+.XS
+$ set default \fIdisk\fP:[iraf]
+$ backup v210.bck/select=[iraf...] [...]/own=iraf/prot=w:r
+.XE
+.LP
+In this and all the following examples, names like \fIdisk:\fP,
+etc., denote site dependent device names for which you must supply values.
+.NH 3
+Installing from tape
+.PP
+Login as IRAF (ignore any LOGIN.COM not found error message) and 
+run the VMS \fIbackup\fP utility to read the backup tape or tapes provided.
+.XS
+$ mount/foreign \fItape-device\fP:
+$ set default \fIdisk\fP:[iraf]
+$ backup/rew \fItape\fP:v210.bck/select=[iraf...] [...]/own=iraf/prot=w:r
+.XE
+.LP
+The tape may be restored while logged in as SYSTEM if desired, but the switch
+/OWNER=IRAF should be appended to give the IRAF system manager
+(anyone who logs in as IRAF) write permission on the files.
+.PP
+It typically takes twenty minutes to half an hour to read the tape on a
+lightly loaded system.
+.NH 3
+Merge local revisions back into the new system
+.PP
+If this is a new IRAF installation this step can be skipped.  Otherwise,
+once the new system has been restored to disk any local revisions made to
+the previous IRAF installation should be merged back into the new system.
+See \(sc2.1.1 for a list of the files most likely to be affected.
+When propagating revisions made to these files, be sure to not replace the
+entire file with your saved version, as the version of the file in the new
+release of IRAF will often contain important additions or changes which
+must be preserved.  It is best to merge your revisions into the version of
+the file which comes with the new IRAF.
+.PP
+This task will be easier if the revisions have been localized as far as
+possible, e.g., keep all \f(CWtermcap\fP additions together at the head of
+the file, so that they may merely be transferred to the new file with the
+editor.  The task of propagating revisions will also be much easier if
+detailed notes have been kept of all revisions made since the the last
+release was installed.
+.PP
+Beginning with IRAF version 2.8, one should no longer install locally added
+software in the core system LOCAL package.  This significantly complicates
+updates and is no longer necessary as, due to the layered software
+enhancements introduced in V2.8 IRAF, it is now straightforward for each
+site to maintain their own custom LOCAL package external to the core IRAF
+system.  The core system LOCAL is now only a \fItemplate-local\fR to be
+copied and used as the starting point for a custom LOCAL layered package.
+The layered software enhancements, and the procedure for building a custom
+LOCAL, are discussed in \(sc9 of this manual.
+.NH 2
+Edit the system configuration files
+.PP
+The files listed below must be edited before the system can be run.
+The principal change required is to change the pathnames of the major IRAF
+logical directories for the local machine.  If any of these files are edited
+while logged in as SYSTEM, be sure to do a \f(CWset file/owner=iraf\fP to
+restore ownership of the edited file to IRAF.
+.NH 3
+[IRAF.VMS.HLIB]IRAFUSER.COM
+.PP
+This file defines the VMS logical names and symbols needed to run IRAF.
+The site dependent ones are grouped at the beginning of the file.  The
+top of the distributed file looks like this:
+.XS
+$! IRAFUSER.COM -- VMS symbols and logicals for using IRAF.
+$!
+$! The following logical names are system-dependent.  IMDIRDISK and
+$! TEMPDISK should be public devices and may be the same device.
+$!
+$  define/job IRAFDISK   USR$3:    ! Disk IRAF resides on
+$  define/job IMDIRDISK  SCR$4:    ! User image subdirectories go here
+$  define/job TEMPDISK   SCR$2:    ! Runtime (scratch) files go here
+$  define/job IRAFGMTOFF -7        ! Offset from GMT in hours
+$! define/job IRAFUHNT   (file)    ! Use (file) instead of dev$uhosts
+$!
+.XE
+.IP \f(CWIRAFDISK\fP
+.br
+Set to the name of the disk the [IRAF] directory is on; this may
+be another logical name but not a "rooted logical".
+
+.IP \f(CWIMDIRDISK\fP
+.br
+Set to the name of a public scratch device, if available.  The \fImkiraf\fP
+script will try to create the default user image storage directories on this
+disk, e.g., IMDIRDISK:[\fIusername\fP].  All potential IRAF users should
+have write permission and quota on this device.
+.sp 0.4
+A public scratch device is desirable because this is where bulk image data
+will be stored by default.  It is often best for this to be on a different
+disk than that used for user logins, to minimize the amount of disk that has
+to be backed up on tape, and to permit a different quota and file expiration
+date policy to be used for large datafiles than is used for the small,
+relatively long lived files normally kept on the user disk.
+.sp 0.4
+Note for sites that use "rooted logicals": the VMS/IRAF kernel does not
+support rooted logicals.  If you use one, e.g., for IMDIRDISK,
+batch jobs that need to access it will fail.  To avoid problems, you must
+either choose IMDIRDISK to be truly just a disk specification, or inform all
+users to edit their IRAF login.cl files after a \fImkiraf\fR.
+.sp 0.4
+For example, if you define IMDIRDISK to be "DATA_DISK:", where DATA_DISK is
+a logical name for dub4:[data.], user ICHABOD's login.cl would have "set
+imdir = DATA_DISK:[ICHABOD]", but this would not work for batch jobs.  The
+user should edit login.cl after a \fImkiraf\fR to use an expanded directory
+specification, in this case "set imdir = dub4:[data.ichabod]".
+
+.IP \f(CWTEMPDISK\fR
+.br
+Set to the name of a public scratch device on which you have created a
+public directory named [IRAFTMP].  The device may be the same as is used for
+IMDIRDISK if desired.  The IRAF logical directory "tmp" (known as IRAFTMP in
+the IRAFUSER.COM file) is defined as TEMPDISK:[IRAFTMP].\(dg
+.FS
+\(dgIf local system management or accounting policies require that private
+tmp and imdir directories be defined for each user, rather than the public
+ones we recommend, see Appendix A.
+.FE
+The IRAF system will create temporary files in this directory at runtime.
+These files are always deleted immediately after use (unless a task aborts),
+hence any files in IRAFTMP older than a day or so are garbage and
+should be deleted.  It is best if IRAFTMP points to a public directory
+which is cleaned periodically by the system, e.g., whenever the system is
+booted, so that junk temporary files do not accumulate.  This is a good
+reason for using a single public directory for this purpose rather than
+per-user private directories.  The files created in IRAFTMP are rarely
+very large.
+.sp 0.4
+See note under IMDIRDISK concerning rooted logicals, if you plan to
+locate TEMPDISK at a rooted logical.
+
+.IP \f(CWIRAFGMTOFF\fP
+.br
+The value of IRAFGMTOFF is the offset in hours to convert Greenwich mean
+time (GMT) to local standard time.  It is used by the VMS/IRAF versions of
+\fIrtar\fR and \fIwtar\fR to restore file dates properly when moving files
+between UNIX and VMS systems.  For example, Tucson is 7 hours west of
+Greenwich so IRAFGMTOFF is defined as -7.
+
+.IP \f(CWIRAFUHNT\fP
+.br
+Define IRAFUHNT to be the name of the internet host table for the local
+system, if this exists and is in the correct format for use by IRAF (i.e.,
+the same format as the file dev$uhosts).  On VMS systems there is no
+standard internet host table comparable to the /etc/hosts file used on unix
+systems.  The VMS/IRAF implementation of TCP/IP networking therefore uses
+its own host table, dev$uhosts, which is what is used if IRAFUHNT is not
+defined.  Some VMS networking implementations (e.g., Multinet) have their
+own host tables.  If this is the case then IRAF can make use of the system
+host table by uncommenting and defining the logical name IRAFUHNT to point
+to the file.
+
+.IP \f(CWFAST,BATCH,SLOW\fP
+.br
+These are the logical names of the standard IRAF logical batch queues.
+They should be redefined to reference the queues used on your machine,
+e.g., the standard VMS batch queue SYS$BATCH (all three names
+may point to the same batch queue if desired).  The fast queue is intended
+for small jobs to be executed at interactive priorities, the batch queue
+is for medium sized jobs, and the slow queue is for large jobs that need
+a lot of system resources and are expected to run a long time.
+.NH 3
+[IRAF.VMS.HLIB]INSTALL.COM
+.PP
+This command procedure is run by the system manager, or by the system at
+boot time, to install the IRAF shared library and selected executable
+images.\(dg\(dg
+.FS
+\(dg\(dg\fRIn VMS terminology, \fIimage\fR, as in "executable image" refers
+to the executable program, and has nothing to do with IRAF image data.
+.FE
+Installing images in system memory is necessary to permit memory sharing in
+VMS, and can greatly reduce physical memory usage and paging on a busy
+system, while speeding process startup.  Installing images also consumes
+system global pages, however, of which there is a limited supply.  Hence,
+one should only install those images which will be used enough to make it
+worthwhile.  See \(sc8.2 for more information.
+.PP
+The \f(CWinstall.com\fP procedure both installs the IRAF executables and
+replaces them after any have been changed.  It works from a separate list of
+files, so you should not edit install.com itself.  Instead, edit install.lst
+to select files by commenting out only those which are \fInot\fP to be
+installed (the comment character is a "!" at the beginning of the line).
+.PP
+The IRAF shared library \f(CWs_iraf.exe\fP should always be installed if
+IRAF is going to be used at all, or the system will execute very
+inefficiently (the IRAF shared library is used by all executing IRAF
+processes).  Normally the executables cl.exe and x_system.exe should also be
+installed, since these are used by anyone using IRAF, as well as by all
+batch IRAF jobs.  If IRAF is heavily used and sufficient global pages are
+available it is also desirable to install x_images.exe and x_plot.exe, since
+virtually everyone uses these executable images frequently when using IRAF.
+It is probably not worthwhile to install any other executables, unless usage
+at the local site involves heavy use of specific additional executable
+images.
+.NH 3
+[IRAF.VMS.HLIB.LIBC]IRAF.H
+.PP
+This file (often referred to as "<iraf.h>") is required to compile any of
+the C source files used in IRAF.  Most sites will not need to recompile the
+C sources and indeed may not even have the DEC C compiler, but the file is
+also used by the runtime system in some cases to resolve logical names,
+hence must be edited and installed in the VMS system library.  Change the
+following disk names as required for your system, referencing only system
+wide logical names in the new directory pathnames (e.g. usr1:[IRAF.VMS],
+where usr1 is a system logical name; do not leave the IRAF logicals like
+irafdisk in the definition).
+.DS
+.TS
+ci ci
+n l.
+IRAF Logical Directory	VMS directory
+
+\&HOST	\fIirafdisk\fP:[IRAF.VMS]
+\&IRAF	\fIirafdisk\fP:[IRAF]
+\&TMP	\fItempdisk\fP:[IRAFTMP]    (may vary\(dg\(dg)
+.TE
+.DE
+.FS
+\(dg\(dg\fRIf local system restrictions forbid a public IRAFTMP directory,
+set this entry to the pathname of a suitable directory in IRAF, e.g.,
+[IRAF.LOCAL.UPARM].  This should work in most circumstances, since it is
+most likely to be the IRAF system manager who runs a program that accesses
+these pathnames.  This is separate from the user-level private IRAFTMP
+irectory discussed in Appendix A.
+.sp
+.FE
+.LP
+These directory definitions are referenced only if logical name translation
+fails, as sometimes happens on VMS systems for various reasons.
+It is therefore essential that only system wide logical names be used in
+these directory pathnames.  Do not use job or process logicals.  Do not
+change the order in which the entries appear, or otherwise alter the syntax;
+the kernel code which scans <iraf.h> is very strict about the syntax.
+.NH 2
+Complete the initial system configuration
+.PP
+Login again as SYSTEM and copy the recently edited file
+irafdisk:[iraf.vms.hlib.libc]iraf.h to the system library, ensuring that the
+file has world read permission (be sure not to copy [iraf.vms.hlib]iraf.h by
+mistake):\(dg
+.FS
+\(dg\fROn a VMS cluster, make sure the IRAF.H file is added to
+SYS$COMMON:[SYSLIB] rather than SYS$SYSROOT:[SYSLIB], so that all nodes in
+the cluster may transparently access the file.  The same precaution is
+needed when editing the system-wide login procedure file (e.g.,
+SYLOGIN.COM), which will probably want to go into SYS$COMMON:[SYSMGR].  The
+SYSTARTUP_V5.COM file, on the other hand, should go into
+SYS$SYSROOT:[SYSMGR] if the bootstrap procedure is different for each node.
+.FE
+.XS
+$ set default sys$library
+$ copy \fIdisk\fP:[iraf.vms.hlib.libc]iraf.h []/protection=w:r
+.XE
+.LP
+Add the following statement to the system SYLOGIN.COM file, making the
+appropriate substitution for \fIdisk\fP.
+.XS
+$ iraf :== "@\fIdisk\fP:[iraf.vms.hlib]irafuser.com"
+.XE
+.LP
+Add the following statement to the SYSTARTUP_V5.COM file, read by the system
+at startup time.  This is necessary to cause the IRAF executables to be
+reinstalled in system memory when the system is rebooted.
+.XS
+$ @\fIdisk\fP:[iraf.vms.hlib]install.com
+.XE
+.LP
+While still logged in as SYSTEM, type in the above command interactively to
+perform the initial executable image installation.  It may be necessary to
+increase the number of system global pages for the command to execute
+successfully.  If you do not want to install the set of IRAF executables
+normally installed at NOAO, edit [iraf.vms.hlib]install.lst before
+executing install.com (see \(sc8.2).
+.PP
+Lastly, log out of SYSTEM, and back in as IRAF.  Update the date stamp
+of a file that is used to ensure that newly updated parameter sets are
+used rather than any old versions a user might have around:
+.XS
+$ set default irafhlib
+$ copy utime. utime.
+$ purge utime.
+.XE
+
+.NH
+Testing a Newly Installed or Updated System
+.PP
+At this point it should be possible for any user to run IRAF.  First however, 
+you should verify this by using the IRAF account itself.  
+Before testing a newly installed or upgraded system it is wise to read the
+\fICL User's Guide\fP, the revisions notes, and the list of known bugs,
+if one has not already done so.  
+.NH 2
+Configuring the IRAF account
+.PP
+The default LOGIN.COM in the IRAF login directory [IRAF.LOCAL] will
+automatically execute the globally defined system command `iraf', which
+defines the IRAF logicals.  Login as IRAF so IRAFUSER.COM is executed and
+the IRAF logicals are defined.
+.PP
+Before starting the IRAF CL (command language) you should do what a regular
+user would do, i.e., run \fImkiraf\fR to initialize the IRAF uparm directory
+and create a new LOGIN.CL (answer yes to the purge query, as it is advisable
+to delete the contents of the old uparm).  You may edit the LOGIN.CL created
+by \fImkiraf\fR as desired.
+.XS
+$ set default [iraf.local]
+$ mkiraf
+.XE
+.LP
+Any modifications you wish to preserve across another \fImkiraf\fP may be
+placed into an optional "loginuser.cl" file to avoid having to edit the
+login.cl file.  The loginuser.cl file can have the same kinds of commands in
+it as login.cl, but \fImust\fR have the statement \f(CWkeep\fR as the last
+line.
+.PP
+Once the IRAF environment is configured one need only enter the
+command \fIcl\fP to start up the CL.  From an X windows workstation, you
+should always start the CL from an \fIxterm\fR window (or \fIxgterm\fR if
+available).  See \(sc6.1.
+.XS
+$ cl
+.XE
+.LP
+If the CL runs successfully, the screen will be cleared (if the terminal
+type is set correctly) and the message of the day printed.  You can then
+type \fIlogout\fR to stop the CL and return to DCL, or stay in the CL to
+edit and test the device files described in the next section.  When logging
+back into the CL (as `IRAF'), always return to the [IRAF.LOCAL] directory
+before logging in.  A little command \fIh\fR (for `home') is defined in the
+default IRAF LOGIN.COM file for this purpose.
+.PP
+If the CL does not run successfully, it is probably because the \fIiraf\fR
+command was not executed in the LOGIN.COM file at login time.  The \fIiraf\fR
+command must be executed to define \fIcl\fP and the other VMS logical names
+and symbols used by IRAF, before trying to run the IRAF system.
+.LP
+Important Note:  any users wishing to execute IRAF tasks in VMS batch
+queues \fImust\fP issue the `iraf' command inside their LOGIN.COM, prior
+to any
+.XS
+if f$mode().nes."INTERACTIVE" then exit
+.XE
+.LP
+command, otherwise critical IRAF logical names will be undefined when
+executing tasks remotely using IRAF networking.
+.PP
+Once in the CL, you should be able to draw vector graphics on the
+workstation screen (\fIxterm\fR) or graphics terminal and have printer
+access (device \fIvmsprint\fR).  If working from a workstation on which
+you've started \fIsaoimage\fR (see \(sc6.2), you should be able to display
+images.  In addition, you may have magtape access with minimum modifications
+to dev$tapecap and may or may not have graphics plotter access.  If the
+graphics terminal capability is ready the next step is to run the IRAF test
+procedure to verify that all is working well, as well as try out a few of
+the many tasks in the system.  If the graphics terminal is not up yet, there
+is probably no point in running the test procedure.  To run the test
+procedure, read the documentation in the \fIIRAF User Handbook\fP, Volumn
+1A, and follow the instructions therein.  The test procedure is also
+available separately from the anonftp archive on iraf.noao.edu.
+
+.NH
+Configuring the IRAF Environment
+.PP
+Since IRAF is a machine and operating system independent, distributed system
+capable of executing on a heterogeneous network, it has its own environment
+facility separate from that of the host system.  Host system environment
+variables may be accessed as if they are part of the IRAF environment (which
+is sometimes useful but which can also be dangerous), but if the same
+variable is defined in the IRAF environment it is the IRAF variable which
+will be used.  The IRAF environment definitions, as defined at CL startup
+time, are defined in a number of files in the [IRAF.VMS.HLIB] directory.
+Chief among these is the system wide \f(CWzzsetenv.def\fR file.  Additional
+user modifiable definitions may be given in the user's login.cl file.
+.NH 2
+[IRAF.VMS.HLIB]ZZSETENV.DEF
+.PP
+The zzsetenv.def file contains a number of environment definitions.
+Many of these define IRAF logical directories and should be left alone.
+Only those definitions in the header area of the file should need to be
+edited to customize the file for a site.  It is the default editor,
+default device, etc., definitions in this file which are most likely to
+require modification for a site.
+.PP
+If the name of a default device is modified, the named device must also have
+an entry in the dev$termcap file (terminals and printers) or the
+dev$graphcap file (graphics terminals and image displays).  There must also
+be an \fIeditor\fP.ed file in dev for each supported editor; \fIedt\fR,
+\fIemacs\fR, and \fIvi\fR are examples of currently supported editors.
+.LP
+Sample values of those variables most likely to require modification for
+a site are shown below.
+.XS
+set editor      = "vi"
+set printer     = "versatec"
+set stdplot     = "lw5"
+set stdimage    = "imt512"
+.XE
+.LP
+For example, you may wish to change the default editor to "emacs", the
+default printer to "vmsprint", or the default image display to "imt800".
+Note that the values of terminal and stdgraph, which also appear in the
+zzsetenv.def file, have little meaning except for debugging processes run
+standalone, as the values of the environment variables are reset
+automatically by the IRAF \fIstty\fR task at login time.  The default stty
+setting in VMS/IRAF V2.10 is "xterm".  This is consistent with the default
+values of terminal and stdgraph defined in zzsetenv.def to be "xterm" and
+would be appropriate for users with workstations running X based
+DECwindows/VMS or Motif/VMS.  The issues of interfacing new graphics and
+image display devices are discussed further in \(sc7.5.
+.NH 2
+The template LOGIN.CL
+.PP
+The template login.cl file, hlib$login.cl, is the file used by \fImkiraf\fR
+to produce the user login.cl file.  The user login.cl file, after having
+possibly been edited by the user, is read and executed by the CL every time
+a new CL is started to define the initial configuration of the CL.  Hence
+this file plays an important role in establishing the IRAF environment seen
+by the user.
+.PP
+Examples of things one might want to change in the template login.cl
+are the commented out environment definitions, the commented out CL
+parameter assignments, the foreign task definitions making up the default
+USER package, and the list of packages to be loaded at startup
+time.  For example, if there are host tasks or local packages which
+should be part of the default IRAF operating environment at your site,
+the template login.cl is the place to make the necessary changes.
+.NH 
+Configuring the Device and Networking Files
+.PP
+The files listed below must be edited before IRAF can be used with the
+video terminals, graphics terminals, plotters, printers, magtape devices,
+and so on in use at the local site.
+.NH 2
+[IRAF.DEV]TAPECAP
+.PP
+Beginning with V2.10, IRAF magtape devices are described by the \fBtapecap\fR
+file, dev$tapecap.  This replaces the old "devices" file for all runtime
+access to tape devices (the "devices" file is still used however in a lesser
+role; see below).  The tapecap file describes each local magtape device and
+controls all i/o to the device, as well as device allocation.
+.PP
+The tapecap file included in the distributed system includes some generic
+device entries such as "9t-6250" (9track 1/2 inch tape drive at 6250 bpi), 
+"vms-exabyte" (exabyte EXB-8200 8mm tape drive on VMS), and so on which you 
+may be able to use as-is to access your local magtape devices.   For 
+example, by default, the device known to the CL as "mta" is a TA78 9tk 
+drive known as device TU0:, which is locally defined at the system level as
+a specific tape drive (actually, in our cluster, $1$MUA0:).  Notice how 
+related entries are chained together in the tapecap file with the tc= field:
+.XS
+mta|mtahi|mta6250|TA78 9tk tape drive|         :tc=mttu0-6250:
+
+mttu0-6250|mttu0|TA78 half inch reel tape drive (VMS):\e
+	:al=tu0:dv=tu0:lk=tu0:mr#64512:or#64512:se:tc=9tk-6250:
+
+9tk-6250|9track 1/2 inch tape drive at 6250 bpi:\e
+	:dt=9 track at 6250 bpi:tt=2400 foot:ts#140000:\e
+	:dn#6250:bs#0:mr#65535:or#65535:fb#10:
+.XE
+.LP
+Most likely you will want to add some device aliases, and you may need to 
+prepare custom device entries for local devices.  There must be an entry in 
+the tapecap file for a magtape device in order to be able to access the device 
+from within IRAF.
+.PP
+Instructions for adding devices to the tapecap file are given in 
+the \fIIRAF V2.10 Revisions Summary\fP.  Notes on the VMS specific 
+implementation of the new magtape facilities are found in \(sc7.2 
+of this document.
+.NH 2
+[IRAF.DEV]DEVICES
+.PP
+This file is used to associate IRAF logical device names with VMS device
+names.  This file is no longer used by the IRAF magtape i/o system which is
+now all tapecap based, but is used by host level utilities like
+\fIdevstatus\fR which need a simple way to translate IRAF device names to
+host device names.  The file is optional and need not be configured to run
+IRAF.
+.NH 2
+The DEVICES.HLP file
+.PP
+All physical devices that the user might need to access by name should be
+documented in the file dev$devices.hlp.  Typing
+.XS
+cl> help devices
+.XE
+.LP
+or just
+.XS
+cl> devices
+.XE
+.LP
+in the CL will format and output the contents of this file.  It is the IRAF
+name of the device, as given in files such as termcap, graphcap, and
+tapecap, which should appear in this help file.
+.NH 2
+[IRAF.DEV]TERMCAP
+.PP
+There must be entries in this file for all video terminal, graphics
+terminal, and printer devices you wish to access from IRAF.  The printer is
+easy, since the "vmsprint" entry provided should work on any VMS system.  To
+prepare entries for other devices, simply copy the vmsprint entry and change
+the queue name from SYS$PRINT to the name of the queue for the new
+printer.\(dg
+.FS
+\(dgIf the printer or plotter device is on a remote node which is not
+clustered with the local node but which is accessible remotely, IRAF
+networking must be used to access the remote device.  IRAF networking is
+also frequently used to access devices on non-VMS (e.g., UNIX) nodes.
+.FE
+Any number of these entries may be placed in the termcap file, and there can
+be multiple entries or aliases for each device.  If you have a new terminal
+which has no entry in the termcap file provided, a new entry will have to be
+added.  Termcap is widely used, so it is highly likely that someone
+somewhere will already have written a termcap entry for your terminal.  If
+the terminal in question is a graphics terminal with a device entry in the
+graphcap file, you should add a `:gd' capability to the termcap entry.  If
+the graphcap entry has a different name from the termcap entry, make it
+`:gd=\fIgname\fR'.  Local additions should be placed at the top of the file
+to make it easier to merge the changes into a future IRAF release.
+.NH 2
+[IRAF.DEV]GRAPHCAP
+.PP
+There must be entries in the graphcap file for all graphics terminals, batch
+plotters, and image displays accessed by IRAF programs.  New graphics
+terminals will need a new entry.  The IRAF file gio$doc/gio.hlp contains
+documentation describing how to prepare graphcap device entries.  A printed
+copy of this [60 page] document is available from the iraf/docs directory in
+the IRAF network archive.  However, once IRAF is up you may find it easier
+to generate your own copy using \fIhelp\fR, as follows:
+.XS
+cl> help gio$doc/gio.hlp fi+ | lprint
+.XE
+.LP
+which will print the document on the default IRAF printer device (use the
+"device=" hidden parameter to specify a different device).  Alternatively,
+to view the file on the terminal,
+.XS
+cl> phelp gio$doc/gio.hlp fi+
+.XE
+.LP
+The help pages for the IRAF tasks \fIshowcap\fR and \fIstty\fR should also
+be reviewed as these utilities are useful for generating new graphcap
+entries.  The i/o logging feature of \fIstty\fR is useful for determining
+exactly what characters your graphcap device entry is generating.  The
+\fIgdevices\fR task is useful for printing summary information about the
+available graphics devices.
+.PP
+Help preparing new graphcap device entries is available if needed.  We ask
+that new graphcap entries be sent back to us so that we may include them in
+the master graphcap file for all to benefit.
+.NH 2
+[IRAF.DEV]HOSTS, UHOSTS, and IRAFHOSTS
+.PP
+The dev directory contains several files (\f(CWhosts\fR, \f(CWirafhosts\fR,
+and \f(CWuhosts\fR) used by the IRAF network interface.  IRAF networking is
+used to access remote image displays, printers, magtape devices, files,
+images, etc., via the network.  IRAF network nodes do not have to have the
+same architecture, or even run the same operating system, i.e., one can
+access a UNIX/IRAF node from VMS/IRAF and vice versa.  V2.10 IRAF contains
+extensive changes to the networking code to permit remote client access to a
+VMS node via TCP/IP, and runtime selection of either TCP/IP or DECNET for
+the transport method.  Editing changes to the networking related files in
+[IRAF.DEV] are illustrated here.  Further documentation on the networking
+interface can be found in the \fIIRAF Version 2.10 Revisions Notes\fP and
+\(sc7.1 of this manual.
+.PP
+The \f(CWdev$hosts\fR file is used to configure IRAF networking on the local
+system.  This file tells IRAF what network nodes are defined and how to
+connect to them, including the protocol to be used.  Initially IRAF
+networking is disabled.  To enable networking there must be an entry in
+the hosts file for the host IRAF is running on.  To do anything useful
+with networking there must also be entries for the nodes you wish to
+connect to.  Often a single VMS/IRAF installation and a single copy of
+dev$hosts are shared by several nodes in a VMS cluster.
+.LP
+To connect to a local VMS node via DECNET requires an entry in the hosts
+file like the following (these and the following examples are taken from
+the NOAO VMS/IRAF hosts file).
+.XS
+robur r                 : robur::0=irafks
+draco                   : draco::0=irafks
+.XE
+.LP
+Here, nodes "robur" and "draco" are defined as DECNET-connected nodes with
+the IRAF kernel server (IRAFKS) installed as a "zero numbered" object in
+DECNET.  IRAFKS can also be installed as a numbered DECNET service, in which
+case the hosts file entry should appears as follows.
+.XS
+robur r                 : robur::242
+draco                   : draco::242
+.XE
+.LP
+In this example the IRAFKS service is installed locally as object number
+242 in DECNET.
+.LP
+To connect to a node on a remote UNIX host via TCP/IP requires an entry
+using "!" to indicate the TCP/IP protocol, followed by the UNIX command
+to be executed to start up the IRAF kernel server, as in the following
+examples (note the different machine types).
+.XS
+cephus                  : cephus!/usr/iraf/bin.ddec/irafks.e
+columba                 : columba!/usr1/iraf/iraf/bin.mips/irafks.e
+felis                   : felis!/u1/iraf/iraf/bin.rs6000/irafks.e
+lepus                   : lepus!/usr/iraf/bin.f2c/irafks.e
+noctua                  : noctua!/usr/iraf/iraf/bin.irix/irafks.e
+ursa u                  : ursa!/local/iraf/bin.sparc/irafks.e
+vega                    : vega!/iraf/iraf/bin.hp700/irafks.e
+.XE
+.LP
+Finally, the hosts file may contain logical node entries.  These are not
+real network nodes, but hosts file entries which point to some other entry
+in the same host table.  These are most commonly used to designate logical
+nodes for disposing of output to different classes of devices such as
+printers and plotters, hosted by some node elsewhere on the network, but
+can be used for other purposes such as gateways.
+.XS
+# Logical nodes (lpnode = line printer output, plnode = plotter output).
+lpnode                  : @ursa
+plnode                  : @ursa
+.XE
+.LP
+In the example above node ursa is a Sun server; the hosts file entry for this
+node is given in an earlier example above.
+.PP
+The other files required to configure IRAF networking are the \f(CWuhosts\fR
+and \f(CWirafhosts\fR files.  The \f(CWuhosts\fR file is a standard internet
+host table containing hostnames and internet numbers.  It is used for TCP/IP
+networking unless the logical name IRAFUHNT is defined to point to an
+alternate file (e.g., Multinet uses a hosts file which IRAF networking can
+access directly).  The uhosts file, if used, should be replaced by a host
+listing for your local site.  One way to do this is to copy the /etc/hosts
+file from a local UNIX host.  Note that V2.10 VMS/IRAF TCP/IP networking
+does not support runtime lookup of hostnames via a name service, hence an
+internet host must have an entry in the uhosts or IRAFUHNT file for VMS/IRAF
+to be able to connect to the host.
+.PP
+The \f(CWirafhosts\fP file supplies login information used by IRAF
+networking when a connection is made.  When a network login is attempted the
+networking system will use the user's .irafhosts file if there is one,
+otherwise it defaults to the irafhosts file in dev.  The system version of
+irafhosts should not need to be modified unless proxy logins are enabled on
+the local host.  Proxy logins are used to eliminate password prompts when
+making network connections between cooperating machines in the local VMS
+cluster.  This is a desirable but optional feature in all but one case,
+network gateways.  When IRAF network connections are routed through a local
+VMS machine serving as a gateway machine password prompts are not possible,
+and one must either enable proxy logins or supply each user with a .irafhosts
+file containing their password.  Proxy logins are probably the least
+objectionable of these two options.
+.PP
+Thus far we have discussed the IRAF networking configuration only as it
+appears from the VMS side of the network, i.e., what one sees when
+configuring the dev$hosts and other files on a VMS host.  This is sufficient
+to allow one VMS/IRAF host to network to another, or to allow a VMS/IRAF
+host to connect to an external host machine running UNIX.  The remaining
+case occurs when IRAF running on a UNIX host connects to VMS/IRAF.  To
+enable such "incoming" TCP/IP network connections one must make an entry
+for each VMS host in the dev$hosts file on the UNIX/IRAF (client side) host,
+as in the following example.
+.XS
+# VMS (decnet) nodes, via internet gateway robur.
+robur r                 : -rcb robur!irafks
+draco                   : @robur!draco
+grian                   : @robur!grian
+lenore                  : @robur!lenore
+vela                    : @robur!vela
+.XE
+.LP
+In this example all incoming (TCP/IP) connections are routed via the VMS
+gateway machine robur.  The "irafks" is a DCL symbol defined on the server
+node in hlib$irafuser.com which runs the IRAF kernel server,
+irafbin:irafks.exe.  The "@robur!nodename" syntax for the VMS nodes other
+than robur tells IRAF running on the UNIX host to use node robur as the
+gateway.  The connection to node robur is made via the rexec-callback IRAF
+networking connect protocol (see \(sc7.1 and also the V2.10 IRAF system
+notes file).  The connection from the gateway machine to the target VMS node
+is controlled by the dev$hosts file on the \fIgateway\fR (VMS) node, and
+will often be a DECNET connection, hence the gateway can serve to connect
+the TCP/IP and DECNET domains.
+.PP
+Once again, for gateway connects to succeed either proxy logins must be
+enabled on the gateway machine, or each user must have a .irafhosts file on
+the gateway machine containing password information.  For incoming TCP/IP
+network connections to work the VMS node must support the \fIrexec\fR
+network service, which is only available via third party networking packages
+such as Multinet.  However, since IRAF networking supports gateways only
+the gateway host need run this software.  When properly configured, gateways
+are transparent to the user.
+.PP
+To fully configure IRAF networking some VMS-level configuration is necessary
+in addition to editing the hosts, uhosts, and irafhosts files (for example
+IRAFKS should be defined as a known DECNET service).  This is discussed
+further in \(sc7.1.
+
+.NH
+Vector Graphics and Image Display using X Windows
+.PP
+In this section we discuss some DECwindows/VMS and Motif/VMS (X window
+system) utilities for use with IRAF running on VMS workstations.  Further
+information can be found in the file \f(CW0readme\fR in the [IRAF.VMS.X11]
+directory.  Note that VMS/IRAF can also be used with an X user interface
+running on a remote UNIX workstation, with only VMS/IRAF running on the VMS
+host.  This section is relevant only if you need to run the X clients
+directly on a VMS host.  We discuss only \fIxterm\fR and \fIsaoimage\fR here
+since these were the only X clients available for graphics and image display
+at the time this was written, but newer facilties may be available before
+this document is again revised.  Check with the IRAF group for more current
+information on support for graphics and imaging under the X window system.
+.NH 2
+Xterm
+.PP
+\fIXterm\fR is a public-domain version of the standard MIT X window system
+terminal emulator, modified to work on VMS.  It is a two-window tool capable
+of emulating a VT102 terminal and a Tektronix 4014 terminal.  Appropriate
+escape sequences will cause \fIxterm\fR to switch between these two modes, but
+some programs require the user to make the change (using the CTRL-middle
+mouse button menu).  It is especially valuable for IRAF use since it allows
+a plotted graph to be kept in the Tektronix emulation window while commands
+are given in the VT102 emulation window.
+.PP
+Due to significant changes between VMS and DECwindows versions, there are
+three different versions of \fIxterm\fR:
+.RS
+.LP
+1) Xterm 1.1 (XTERM11.EXE)  -  for VMS 5.1 to 5.3-x, with DECwindows
+.br
+2) Xterm 1.2 (XTERM12.EXE)  -  for VMS 5.4-x and later, with DECwindows
+.br
+3) Xterm 2.1 (XTERM21.EXE)  -  for VMS 5.4-x and later, with DECwindows/Motif
+.RE
+.LP
+A common mistake is to run the CL from a DECterm window, which does not
+support IRAF graphics.  To use IRAF interactive graphics tasks one must
+run IRAF from an \fIxterm\fR window (or any similar terminal emulator
+supported by IRAF, e.g., \fIgterm\fR, \fIxgterm\fR, etc.).  To use
+\fIxterm\fR with IRAF we recommend that the "xtermr" graphcap entry be
+used.  This is set as follows:
+.XS
+cl> stty xtermr nl=54
+.XE
+.LP
+By default, this entry has 65 lines in the text window.  If your setup
+is different (perhaps 54 lines instead of 65) you can make
+changes as shown on the stty command line.  The "xterm" stty setting is
+an alias for the "xtermr" stty setting; they can be used interchangeably.
+.PP
+The xtermr graphcap entry writes the status line in the TEK window, not
+in the text window.   This is the preferred setup, since DEC hasn't yet
+made available the customize feature for "focus follows cursor", meaning
+there is no way around needing to click-to-focus.  Use of xtermr requires
+the least amount of clicking.
+.PP
+You should not click inside the TEK window to focus on it, but on its header
+or border.  Otherwise, the mouse click returns a character which terminates
+cursor mode.  Clicking on the border provides focus without reporting any 
+events, since the cursor is not inside the "active" region.  
+.NH 2
+SAOimage
+.PP
+\fISaoimage\fP is an X-windows based image display server originally
+developed by the Smithsonian Astrophysical Observatory.  It provides a large
+selection of options for zooming, panning, scaling, coloring, pixel
+readback, display blinking, and region specifications.  User interactions
+are usually performed with the mouse.  The version of \fIsaoimage\fR
+included with the VMS/IRAF V2.10 distribution is 1.07; newer versions may be
+available from the IRAF archives.  You must have \fIsaoimage\fR running,
+although it can be iconified, before attempting to write to it.  More
+information may be found in the \f(CW0readme\fR file in the [IRAF.VMS.X11]
+directory.
+
+.NH
+Additional System Configuration Issues
+.NH 2
+New networking driver
+.PP
+This section contains notes on the new V2.10 IRAF networking interface as
+implemented for VMS.  Further information can be found in \(sc5.6 of 
+this manual, the \fIIRAF Version 2.10 Revisions Summary\fP, and the 
+VMS/IRAF system notes file, iraf$local/notes.vms.
+.PP
+The VMS/IRAF networking code was extensively revised for V2.10 to permit
+client access to a VMS node via TCP/IP, and runtime selection of TCP/IP or
+DECNET for the transport method.
+.LP
+Selection of the transport protocol is made in the dev$hosts file, as in
+the examples below.
+.XS
+robur r         : robur::0=irafks
+ursa u          : ursa!/local/iraf/bin.sparc/irafks.e
+.XE
+.LP
+The first example above states that logical node robur, with alias r, is a
+DECNET domain node named robur.  The DECNET connection is to be made by
+executing the command "irafks" on the remote node.  User login information
+is supplied by the user's .irafhosts file if any, otherwise by dev$irafhosts.
+A numbered DECNET object could be used instead, in which case the syntax on
+the right would change to "robur::\fIn\fR", where \fIn\fR is the number
+of the DECNET object to connect to.
+.PP
+The second example states that logical node ursa, with alias u, is a TCP/IP
+domain node with network name ursa.  The network connection is made by
+executing, on the remote node ursa, the host command given after the "!".
+VMS/IRAF supports only the IRAF \fIrexec\fR connect protocol for outgoing
+connections to TCP/IP servers.  TCP/IP connections are discussed in more
+detail below.
+.NH 3
+DECNET networking
+.PP
+In the simplest form of a DECNET connection the hosts file entry for the
+server node will reference a zero-numbered network object as in the example,
+e.g., "hostname::0=irafks" (or "hostname::task=irafks").  If "irafks" is
+\fInot\fR a defined DECNET network object then the user must have a file
+IRAFKS.COM in their login directory, similar to the following:
+.XS
+$! IRAFKS.COM -- Fire up the iraf kernel server under DECNET.
+$!
+$  if f$mode() .nes. "NETWORK" then exit
+$!
+$! iraf                         ! uncomment if not in login.com
+$  irafks :== "$irafbin:irafks" ! define irafks as a foreign task
+$  irafks dn.irafks             ! start the iraf kernel server
+$  logout
+.XE
+.LP
+This works, but has the disadvantage that every user account must have
+an IRAFKS.COM file in the login directory, or IRAF DECNET-based networking
+will not work.  A better approach is to define IRAFKS as a known network
+object which will execute the file IRAFKS.COM supplied in the IRAFHLIB
+directory with V2.10 VMS/IRAF.  This eliminates the need for each user to
+have a private copy of the IRAFKS.COM file, and makes proxy logins possible,
+which can eliminate the need for password prompts.
+.PP
+The following is an example of how to install irafks as a known network
+object.  This must be done on each DECNET host.  The device name USR$3:
+shown in the example should be replaced by the value of IRAFDISK: on the
+local system.
+.XS
+$ run sys$system:ncp
+ncp> define object irafks -
+    number 0 file usr$3:[iraf.vms.hlib]irafks.com
+ncp> set object irafks -
+    number 0 file usr$3:[iraf.vms.hlib]irafks.com
+ncp> exit
+.XE
+.LP
+In normal operation the NCP configuration is automatically preserved when
+the system is rebooted.  If the local system has a network configuration
+procedure to redefine the NCP settings in the event of damage to the network
+database, then an NCP DEFINE command similar to that shown should be added
+to this file.
+.PP
+An alternative to the above scheme is to define IRAFKS as a numbered system
+object.  This works as above, except that the "number 0" becomes "number
+\fIn\fR", where \fIn\fR is the network object number, and the dev$hosts file
+syntax for the server becomes "\fIhostname\fR::\fIn\fR".
+.NH 3
+Proxy logins
+.PP
+The DECNET \fIproxy login\fR capability allows DECNET connections to be made
+between a set of well-known cooperating systems (e.g., the local cluster)
+without the need to supply login authentication information every time a
+network connection is made.  The effect is to eliminate password prompts,
+thereby making networking much more transparent to the user.  In some cases
+eliminating password prompts is necessary to make the software function
+correctly, for example when using a VMS host as a gateway machine
+interactive prompting for passwords is not possible, and the gateway cannot
+function correctly without some way to disable password prompts.  In the
+case of IRAF networking this can be done by having the user put password
+information in their .irafhosts file, but the use of proxy logins is preferred
+since it avoids plaintext passwords and avoids the need for the .irafhosts
+file altogether.
+.PP
+To enable proxy logins for IRAF networking one must first define IRAFKS (the
+IRAF kernel server) as a known network object, as outlined in the previous
+section.  The VMS \fIauthorize\fR utility is then used to enable proxy
+logins.
+.LP
+For example, assume we have two nodes ROBUR and DRACO.
+.XS
+$ run sys$system:authorize                  ! run on node robur
+authorize> add/proxy draco::* */default
+
+$ run sys$system:authorize                  ! run on node draco
+authorize> add/proxy robur::* */default
+.XE
+.LP
+This would enable proxy logins between nodes draco and robur for all user
+accounts that have the same user login name on both systems.  Alternatively
+one could do this for only a specified set of user accounts.  The authorize
+utility automatically updates the affected disk files so that the change
+will be preserved the next time the system is booted.
+.PP
+To eliminate the password prompts during IRAF networking connections one
+must also edit the user .irafhosts file, or the system irafhosts file (in
+dev) to disable login authentication.  For example, if the dev$irafhosts
+file contains
+.XS
+# dev$irafhosts
+
+draco       :  <user> none
+robur       :  <user> none
+*           :  <user> ?
+.XE
+.LP
+then authentication will be disabled for connections made between nodes
+draco and robur, but a password will be required to connect to any other
+node.  The above irafhosts file would result in a DECNET login request
+such as 
+.XS
+hostname"username"::"0=irafks"
+.XE
+.LP
+which forces a login as "username" on the remote host.  If the user name is
+omitted, the default proxy login on the remote node is used.
+The user's .irafhosts file, if present, will be used instead and should
+be configured similarly.
+.PP
+These changes make IRAF DECNET based networking transparent between
+cooperating nodes in a local network, without requiring users to place
+password information in .irafhosts files.  This is especially desirable if a
+routing node is used to route IRAF networking connections between TCP/IP and
+DECNET networks.
+.NH 3
+Configuring a VMS host as a TCP/IP server
+.PP
+For incoming TCP/IP connections (VMS node acting as server) VMS/IRAF supports
+two connect protocols, \fIrexec\fR and \fIrexec-callback\fR.  The \fIrsh\fR
+protocol, the default connect protocol for V2.10 UNIX/IRAF systems, is not
+supported by VMS/IRAF.  To act as a TCP/IP server a VMS node must run a
+host-level networking package (such as Multinet) which supports the
+\fIrexecd\fR networking daemon.
+.LP
+On the UNIX side the dev$hosts entry for a directly-connected VMS node
+should be similar to the following example.
+.XS
+robur r                 : -rcb robur!irafks
+.XE
+.LP
+This specifies that for logical node robur, alias r, the rexec-callback
+connect protocol (TCP/IP) should be used to connect to the network node
+robur.  The command to be executed on the remote node is whatever is to
+the right of the "!", i.e., the command "irafks" in our example.
+.PP
+When the \fIrexecd\fR daemon executing on the remote VMS node responds,
+the first thing it will do is login using the username and password
+supplied with the rexec request, and execute the user's LOGIN.COM file.
+For an IRAF user this must contain the command \fIiraf\fR, which causes
+the IRAFUSER.COM file in [IRAF.VMS.HLIB] to be interpreted by DCL.
+This defines all the IRAF logical names and symbols.  One of the sybols
+defined is the \fIirafks\fR command which is subsequently executed to
+complete the rexec network request.  The \fIirafks\fR command is defined
+in IRAFUSER.COM as follows:
+.XS
+$  irafks       :== $irafbin:irafks     !  IRAF network kernel server
+.XE
+.LP
+Hence, as might be expected, the result of the rexec connect is to run the
+IRAF kernel server irafbin:irafks.exe on the server node.  In the case of
+the rexec-callback connect protocol, the actual command passed to DCL
+includes command line arguments to the IRAF kernel server telling it how to
+call the client back on a private network socket.  What happens is that the
+client reserves a port and creates a socket on this port, then issues a
+rexec call to the VMS system to run the kernel server.  The port and host
+name are passed on the rexec command line.  The \fIrexecd\fR daemon on the
+server runs the irafks.exe process on the VMS node, and irafks calls the
+client back on the socket reserved by the client.  The end result is a high
+bandwidth direct socket connection between the client and server processes.
+.PP
+See the discussion in \(sc5.6 for a discussion of TCP/IP and DECNET
+internetworking, including examples of how to configure a VMS node as an
+Internet gateway for IRAF networking.
+.NH 3
+Network security alarms
+.PP
+One potential consequence of IRAF networking is that, if IRAF networking is
+not properly configured (either at the system level or at the user level),
+network connection attempts may fail, and IRAF in its normal operation may
+repeatedly generate failed connection attempts.  Repeated failed connection
+attempts can trigger network security alarms on a VMS system, even though no
+real security problem exists.  VMS systems managers should be aware of this
+possibility so that they don't waste time trying to track down a potential
+network security problem which doesn't exist.  Should this circumstance
+occur, the best solution is to properly configure IRAF networking so that
+the connection attempts succeed, e.g., by setting up the user's .irafhosts
+file, or by enabling proxy logins for the user.
+.NH  2
+New magtape driver
+.PP
+This section contains notes on the new V2.10 IRAF magtape driver as
+implemented for VMS.  The reader is assumed to be familiar with the
+basics of magtape access in IRAF, including remote access to a drive via
+IRAF networking.  Further information can be found in \(sc5.1 of this
+manual, in the \fIIRAF Version 2.10 Revisions Summary\fP, and in the
+VMS/IRAF system notes file, iraf$local/notes.vms.
+.NH 3
+Allocation
+.PP
+Explicit allocation of magtape devices is now optional.  If the drive is not
+allocated with the CL \fIallocate\fR command it will be automatically
+allocated and mounted when the first tape access occurs.  Once allocated, it
+stays allocated even if you log out of the CL and back in, allowing
+successive IRAF or other processes to access the drive without it being
+deallocated.
+.PP
+The tape drive can be allocated at the VMS level (e.g., "allocate tu4:")
+before starting the CL.  This reserves the drive but if you run
+\fIdevstatus\fR in the CL it will report that the drive has not been
+"allocated", because IRAF doesn't consider the drive allocated in the IRAF
+sense unless it has been both allocated and mounted at the VMS level.  One
+can either allocate the drive in the CL, or run an IRAF magtape task which
+accesses the drive to cause the drive to be automatically allocated and
+mounted.
+.PP
+If the drive is allocated in DCL before starting IRAF, then allocated and
+deallocated in the CL, when you log out of the CL the drive will still be
+allocated at the VMS level even though it was deallocated in the CL.  If the
+drive is NOT allocated in DCL before starting the CL, allocating and
+deallocating the drive in the CL and then exiting will result in the drive
+not being allocated at the VMS level.
+.NH 3
+Density
+.PP
+When a drive is automounted it is possible to set the density.  The V2.10
+implementation supports this (you just write to mta1600 or whatever), but
+this does not work reliably since VMS requires that the first operation
+following a mount which changes the density be a write.  Often the write
+is preceded by a file positioning operation such as a rewind or seek to
+end of tape, which prevents the density from being changed.
+.PP
+To reliably change the tape density, do an "init/density=NNN device" at the
+DCL level and verify the new density with "show magtape" ("!init", "!show"
+in IRAF).  It may be necessary to repeat the operation before it succeeds.
+.NH 3
+Status output logging
+.PP
+Status output logging is fully implemented in VMS/IRAF, i.e., one can
+enable status output and direct the messages to a text file, a terminal, or
+a network socket.
+.PP
+For VMS/IRAF the magtape naming conventions have been extended slightly
+to allow the different types of status output logging devices to be indicated.
+.DS
+.TS
+l l.
+:so=.foo	log to file "foo"
+:so=>foo	log to terminal "foo:"
+:so=foo	log to socket on node "foo"
+.TE
+.DE
+.LP
+For example, "mtexamine mta[:so=orion]" would examine the files on drive
+\f(CWmta\fR, optionally sending status output messages to a tape status
+daemon running on network node orion.  Logging to a named terminal device
+will usually fail due to permission problems, but logging to ">tt" will
+direct status output to the current terminal window.
+.LP
+The VMS version of the driver will print a device type string such as
+.XS
+$2$MUA1: (ROBUR) - 9 track at 6250 bpi
+.XE
+.LP
+where the first part of the message comes from VMS and the " - ..." is from
+tapecap.  The density field can be either the tapecap value or the runtime
+GETDVI value.  For example, if the density is shown as "6250" this is the
+value from the tapecap entry.  If the density is shown as "(6250)", i.e., in
+parentheses, this is the actual device value as determined by a GETDVI call
+to VMS.  Note that it is possible for the density given in the tapecap entry
+to differ from the actual device density setting.  In this case the tape
+will be written correctly, but the "Device Type", "Capacity" and "Tape Used
+(%)" status fields will be incorrect.  To avoid this problem be sure the
+density of the tapecap entry you are using to access the drive matches the
+density value of the physical device.
+.PP
+To enable status output logging to a socket a network magtape status display
+server such as \fIxtapemon\fR must be started on the remote node before
+accessing the tape drive.  To permanently direct status output to a node a
+statement such as 'set tapecap = ":so=\fIhostname\fR"' may be added to the
+login.cl or loginuser.cl file.
+.NH 3
+Using tape drives over the network
+.PP
+Changes in the VMS/IRAF V2.10 magtape and networking interfaces make it
+possible to remotely use VMS tape drives from Internet (UNIX) or DECNET
+hosts.  In practice this is straightforward, but there are two caveats to
+keep in mind: 1) do not explicitly allocate the device, 2) if you run IRAF
+tasks in different packages that access the same tape drive, type \fIflpr\fR
+before running a task in a different package.  Aside from these two items,
+everything should work as when accessing a magtape device directly on a UNIX
+or VMS system.  Both problems arise from the way VMS handles device
+allocation.
+.PP
+Explicitly allocating a device does not work in VMS/IRAF when remotely
+accessing a tape drive because the effect is to allocate the drive to the
+kernel server process for the client CL, thereby preventing other client
+IRAF processes from accessing the drive.  In practice this is not a problem
+since it is not necessary to explicitly allocate the device; the VMS/IRAF
+kernel server will automatically allocate and mount the device when it is
+accessed over the network.
+.PP
+An example of the problem of trying to access a remote VMS drive from two
+different IRAF packages occurs when the \fIrewind\fR task, which is in the
+SYSTEM package, is used in conjunction with DATAIO tasks such as
+\fIrfits\fR, \fIwfits\fR, or \fImtexamine\fR.  You can run tasks in a given
+package at will, but if you try to access the drive with a task in a
+different package there will be a conflict.  Again, the problem is that when
+remotely accessing a device, the VMS device allocation facilities cause the
+device to be allocated to the kernel server \fIprocess\fR, rather than to
+the user.  There is a one-to-one correspondence between client-side IRAF
+processes and kernel server processes.  In IRAF each package has its own
+executable, and hence its own kernel server, leading to the allocate
+conflict.
+.PP
+For example if you have been using \fIrfits\fR (DATAIO) and you want to do a
+\fIrewind\fR (SYSTEM), type "flpr rfits" and wait 5-10 seconds, then you
+should be able to do the rewind.  To run another DATAIO task, type "flpr
+rewind" and again wait 5-10 seconds before running the DATAIO task.  The
+delay is necessary to wait for VMS to shutdown the kernel server for the
+package which previously had the device allocated.
+.NH 2
+Configuring user accounts for IRAF
+.PP
+User accounts should be loosely modeled after the IRAF account.  All that is
+required for a user to run IRAF is that they run \fImkiraf\fR in their
+desired IRAF login directory before starting up the CL.  Each user should
+review the resulting login.cl file and make any changes they wish.  Any user
+wanting to run batch jobs, including printer access, must execute the
+`\fIiraf\fP' command in their LOGIN.COM file, making sure it is executed for
+non-interactive jobs.  Individual process quotas for IRAF users should be
+set as described in the next section.
+.NH 2
+VMS quotas and privileges required to run IRAF
+.PP
+The only privilege required by IRAF is TMPMBX, which is probably
+already standard on your system.  Systems with DECNET capabilities should also
+give their users NETMBX privilege, although it is not required to run IRAF.
+No other privileges are required or useful for normal activities.
+.PP
+Although privileges are no problem for VMS/IRAF, it is essential that the
+IRAF user have sufficient VMS quota, and that the system tuning parameters
+be set correctly, otherwise IRAF will not be able to function well or may
+not function at all.  If a quota is exceeded, or if the system runs out of
+some limited resource, the affected VMS system service will return an error
+code to IRAF and the operation will fail (this frequently happens when
+trying to spawn a connected subprocess).  The current recommended ranges of
+per-user quotas are summarized below.  Users running DECwindows/Motif may
+already have, and may definitely need, larger numbers for these quotas, so
+don't reduce them to these values.
+.DS
+.TS
+ci ci ci
+l n n.
+quota	minimum	recommended
+.sp
+BYTLM	20480	30720
+PGFLQUOTA	15000	30720
+PRCLM	5	10
+WSDEFAULT	512	512
+WSEXTENT	4096	WSMAX
+JTQUOTA	2048	2048
+FILLM	30	60
+.TE
+.DE
+.PP
+The significance of most of these quotas is no different for IRAF than for
+any other VMS program, hence we will not discuss them further here.
+The PRCLM quota is especially significant for IRAF since an IRAF job
+typically executes as several concurrent processes.  The PRCLM quota
+determines the maximum number of subprocesses a root process (user) may have.
+Once the quota has been reached process spawns will fail causing the IRAF
+job or operation to abort.
+.PP
+The minimum number of subprocesses a CL process can have is 1 (x_system.e).
+As soon as a DCL command is executed via OS escape a DCL subprocess is
+spawned, and we have 2 subprocesses.  The typical process cache limit is 3,
+one slot in the cache being used by x_system.e, hence with a full cache we
+have 4 subprocesses (the user can increase the process cache size if
+sufficient quota is available to avoid excessive process spawning when
+running complex scripts).  It is common to have one graphics kernel
+connected, hence in normal use the typical maximum subprocess count is 5.
+However, it is conceivable to have up to 3 graphics kernel processes
+connected at any one time, and whenever a background job is submitted to run
+as a subprocess a whole new subprocess tree is created.  Hence, it is
+possible to run IRAF with a PRCLM of 5, but occasional process spawn
+failures can be expected.  Process spawn failures are possible even with a
+PRCLM of 10 if subprocess type batch jobs are used (the default), but in
+practice such failures are rare.  If all batch jobs are run in batch queues
+it should be possible to work comfortably with a PRCLM of 5-6, but in
+practice users seem to prefer to avoid the use of batch queues, except for
+very large jobs.
+.PP
+Since IRAF uses memory efficiently the working set parameters do not seem
+critical to IRAF, provided the values are not set unrealistically low, and
+provided WSEXTENT is set large enough to permit automatic growth of a
+process working set when needed.  Configuring VMS to steal pages from
+inactive processes is not recommended as it partially cancels the effect of
+the process cache, causing process pagein whenever a task is executed.  It
+is better to allow at least a minimum size working set to each process.
+However, this is not a hard and fast rule, being dependent on individual
+system configurations and workloads.
+.PP
+In addition to sufficient per user authorized quota, the system tuning
+parameters must be set to provide enough dynamically allocatable global
+pages and global sections to handle the expected load.  If these parameters
+are set too small, process connects will fail intermittently, usually when
+the system load is high.  Each subprocess needs about 8 global pages when
+activated (IRAF uses global pages and shared memory for interprocess
+communications, due to the relatively low bandwidth achievable with the
+VMS mailbox facilities).
+.PP
+With IRAF in heavy use (i.e., a dozen simultaneous users) this can easily
+reach a requirement for several hundred additional global pages.  Each
+installed image and subprocess also needs at least one, usually two, global
+sections.  Note that the size of the executable found by doing a
+DIR/SIZE=ALL on [IRAF.BIN]*.EXE can be considered an upper bound to the
+number of pages needed to install it (if anyone wants to play it safe:
+typically, it's about 50-70 percent of this size).  Currently, for 2.10, we
+have CL=357, S_IRAF=1267, IRAFKS=23, X_SYSTEM=106, X_PLOT=159, and
+X_IMAGES=786.  The system parameters on our 8600 (which is probably a worst
+case example) are currently set to GBLPAGES = 12120 and GBLSECTIONS = 230.
+For every increment of 512 in GBLPAGES, GBLSECTIONS must be increased by 4.
+After making any of these changes, we recommend running AUTOGEN to ensure
+correct relationships among the many sysgen parameters.
+.NH 2
+Interfacing new graphics devices
+.PP
+There are three types of graphics devices that concern us here.
+These are the graphics terminals, graphics plotters, and image displays.
+.NH 3
+Graphics terminals
+.PP
+The IRAF system as distributed is capable of talking to just about any
+conventional graphics terminal or terminal emulator, using the stdgraph
+graphics kernel supplied with the system.  All one need do to interface to a
+new graphics terminal is add new graphcap and termcap entries for the
+device.  This can take anywhere from a few hours to a few days, depending on
+one's level of expertise, and the characteristics of the device.  Be sure to
+check the contents of the dev$graphcap file to see if the terminal is
+already supported, before trying to write a new entry.  Useful documentation
+for writing graphcap entries is the GIO reference manual and the HELP pages
+for the \fIshowcap\fP and \fIstty\fP tasks (see \(sc5.5).  Assistance with
+interfacing new graphics terminals is available via the IRAF Hotline.
+.NH 3
+Graphics plotters
+.PP
+The current IRAF system comes with several graphics kernels used to drive
+graphics plotters.  The standard plotter interface is the SGI graphics kernel,
+which is interfaced as the tasks \fIsgikern\fP and \fIstdplot\fP in the
+PLOT package.  Further information on the SGI plotter interface is given in
+the paper \fIThe IRAF Simple Graphics Interface\fP, a copy of which is
+available from the network archive.
+.PP
+SGI device interfaces for most plotter devices already exist, and adding
+support for new devices is straightforward.  Sources for the SGI device
+translators supplied with the distributed system are maintained in the
+directory iraf$vms/gdev/sgidev.  NOAO serves as a clearinghouse for new SGI
+plotter device interfaces; contact us if you do not find support for a local
+plotter device in the distributed system, and if you plan to implement a new
+device interface let us know so that we may help other sites with the same
+device.
+.PP
+The older NCAR kernel is used to generate NCAR metacode and can be
+interfaced to an NCAR metacode translator at the host system level to get
+plots on devices supported by host-level NCAR metacode translators.  The
+host level NCAR metacode translators are not included in the standard IRAF
+distribution, but public domain versions of the NCAR implementation for VMS
+systems are widely available.  A site which already has the NCAR software
+may wish to go this route, but the SGI interface will provide a more
+efficient and simpler solution in most cases.
+.PP
+The remaining possibility with the current system is the calcomp kernel.
+Many sites will have a Calcomp or Versaplot library (or Calcomp compatible
+library) already available locally.  To make use of such a library to get
+plotter output on any devices supported by the interface, one may copy
+the library to the hlib directory and relink the Calcomp graphics
+kernel.
+.PP
+A graphcap entry for each new device will also be required.  Information on
+preparing graphcap entries for graphics devices is given in the GIO design
+document, and many actual working examples will be found in the graphcap
+file.  The best approach is usually to copy one of these and modify it.
+.NH 3
+Image display devices
+.PP
+The majority of VMS/IRAF users will use a networked UNIX or VMS workstation
+running some version of the X window system (DECwindows/VMS or Motif/VMS in
+the case of VMS) for IRAF graphics and image display.  X clients for
+graphics and image display are available for all IRAF platforms.  See \(sc6.1
+of this manual for information about the \fIxterm\fR graphics terminal
+emulator and the \fIsaoimage\fR image display server.
+.PP
+Those VMS/IRAF sites that have VAX/VMS workstations running the VWS display
+system can use the UISDISP.EXE display task in [IRAF.VMS.UIS] for image
+display.  This is a standalone IMFORT program, i.e. it does not communicate
+with the tasks in the TV.DISPLAY package.  See the file uisdisp.txt in the
+same directory for information on using the task.
+.PP
+Some interfaces for hardware image display devices are also available,
+although a general display interface is not yet included in the system.
+Only the IIS model 70 and 75 are currently supported by NOAO.  Interfaces
+for other devices are possible using the current datastream interface,
+which is based on the IIS model 70 datastream protocol with extensions
+for passing the WCS, image cursor readback, etc. (see the ZFIOGD driver
+in iraf$vms/gdev).  This is how all the current displays, e.g., imtool
+and saoimage, and the IIS devices, are interfaced, and there is no reason
+why other devices could not be interfaced to IRAF via the same interface.
+Eventually this prototype interface will be obsoleted and replaced by a
+more general interface.
+.PP
+If there is no IRAF interface for your device, the best approach at present
+is to use the IMFORT interface and whatever non-IRAF display software you
+currently have to construct a host level Fortran or C display program.  The
+IMFORT library provides host system Fortran or C programs with access to
+IRAF images on disk.  Documentation on the IMFORT interface is available in
+\fIA User's Guide to Fortran Programming in IRAF -- The IMFORT Interface\fP,
+Doug Tody, September 1986, a copy of which is included in the IRAF User
+Handbook, Volume 1A.  If you do not have an existing image display program
+into which to insert IMFORT calls, it is not recommended that the TV.DISPLAY
+package code be used as a template.  Rather, a standalone image display
+server should be constructed using the datastream protocol in the
+iraf$vms/gdev/zfiogd.x driver mentioned above (but that could be a very
+lengthy job; contact the Hotline).
+
+.NH 
+Tuning Considerations
+.PP
+There are a number of things that can be done to tune VMS/IRAF for a
+particular host system:
+.RS
+.IP \(bu
+Install the executables to permit shared memory.
+.IP \(bu
+Render the large runtime files contiguous to increase i/o efficiency.
+.IP \(bu
+Precompile selected TERMCAP and GRAPHCAP entries.
+.IP \(bu
+Strip the system to reduce disk consumption.
+.RE
+.NH 2
+Stripping the system to reduce disk consumption
+.PP
+If the system is to be installed on multiple cpu's, or on a particularly
+small host like a MicroVAX, it may be necessary or desirable to strip the
+system of all non-runtime files to save disk space.  This is done by deleting
+all the program sources and all the sources for the reference manuals and
+other printed documentation, but not the online manual pages.  A special
+utility called \fIrmfiles\fP (in the SOFTOOLS package) is provided for this
+purpose.  It is not however necessary to run rmfiles directly to strip
+the system.  This may be done either from DCL or from within the CL.
+.XS
+$ set default [iraf]
+$ mkpkg strip
+$ set default [iraf.noao]
+$ mkpkg strip
+.XE
+.LP
+This will preserve all runtime files, permitting use of the standard runtime
+system as well as user software development.  Stripping the system will
+\fInot\fP, however, permit relinking standard IRAF executables, as would be
+required for bug fixes or caching termcap and graphcap entries.  The size of
+the system is reduced by about half.  We do not recommend stripping the
+system libraries, as this would preclude all IRAF related software
+development or bug fixes, including user written Fortran programs (IMFORT),
+and we no longer provide a "\fIstripall\fR" option.
+.NH 2
+Installing executable images
+.PP
+The standard distribution of VMS/IRAF is configured to use a shared library
+for the bulk of the IRAF runtime system code.  Use of this shared library
+considerably reduces the disk requirements of the system, while reducing
+runtime system memory usage and process pagein time, and speeding up process
+links during software development.
+.PP
+If the goal of minimizing physical memory utilization is to be achieved
+when running IRAF, it is essential that the IRAF shared library be "installed"
+in VMS system shared memory.  Further memory savings through memory sharing
+can be achieved if some of the more commonly used IRAF executables are also
+installed.  This becomes increasingly important as the number of IRAF users
+increases, but some memory savings may result even if there is only one user,
+since a single user may spawn batch jobs.  Hence, the shared library
+s_iraf.exe should always be installed if IRAF is used at all, and
+cl.exe and x_system.exe are used by all IRAF jobs and should
+be installed if there is usually at least one IRAF user on the system.
+If there are usually several IRAF users on the system x_images.exe and
+x_plot.exe are probably worth installing as well.
+.PP
+Installation of task images in system shared memory is done with the VMS
+INSTALL utility, which requires CMKRNL privilege to execute (also discussed
+in \(sc2.3.2).  Installation of the IRAF shared library and other task
+images is most conveniently done by executing the INSTALL.COM command
+procedure in hlib.  The list of files to be installed is in INSTALL.LST.
+This file should be reviewed and edited during system installation to select
+those images to be installed on the local host.  Then INSTALL.COM may be
+directly executed to temporarily install the images, but to permanently
+install the images the system bootstrap procedure should be modified to
+execute the INSTALL.COM script (or explicitly install the images by name)
+whenever the system is booted.  Note that the global pages used by an
+installed image are not actually freed until any and all processes using
+those global pages terminate.
+.PP
+The procedure for installing images will fail if there are insufficient
+global pages available in the system (for example, the number of global
+pages required to install the shared library in VMS/IRAF V2.10 is about
+1267).  If the system has insufficient free global pages to run the
+INSTALL.COM script one must either increase the number of system global
+pages (which requires rebooting the system), or one must edit the
+INSTALL.LST file to reduce the number of images to be installed.
+.NH 2
+Rendering large runtime files contiguous
+.PP
+The speed with which large disk files can be read into memory in VMS can
+degrade significantly if the disk is highly fragmented, which causes a
+large file to be physically stored in many small fragments on the disk.
+IRAF performance as well as VMS system throughput can therefore be improved
+by rendering frequently referenced large files contiguous.  Examples of
+files which it might pay to render contiguous are the executables in
+\f(CWbin\fP, all of the runtime files in \f(CWdev\fP, and the large system
+libraries in \f(CWlib\fP (this last is only useful to speed software
+development, i.e., linking).
+.PP
+The easiest way to render a file contiguous in VMS is to use COPY/CONTIGUOUS
+to copy the file onto itself, and then purge the old version.  Various
+nonstandard utility programs are available commercially which will perform
+this function automatically.  The contents of an entire disk may be rendered
+contiguous or nearly contiguous by backing up the disk onto tape and then
+restoring it onto a clean disk.
+.NH 2
+Precompiling TERMCAP and GRAPHCAP entries
+.PP
+Precompilation of a termcap or graphcap entry is a technique used to speed
+runtime access of the entry for that device.  If the entry is not
+precompiled the termcap or graphcap file must be physically opened and
+scanned at runtime to read the desired entry.  This causes a slight delay
+when clearing the terminal screen or plotting a graph, hence it may be
+worthwhile to cache the entries for commonly used video and graphics
+terminals.  We do not recommend that sites attempt to relink the IRAF system
+to cache new terminal device entries, but system managers may wish to be
+aware of this option.
+.PP
+The system comes with selected termcap and graphcap entries already
+precompiled.  To see which devices are precompiled, page the cache data
+files, dev$cachet.dat (for termcap) and dev$cacheg.dat (for graphcap).  To
+cache a different set of entries one must regenerate these files with the
+\fImkttydata\fP task in the SOFTOOLS package, and then do a full sysgen
+relink with the \fImkpkg\fP utility.  Detailed instructions are given in the
+manual page for \fImkttydata\fR.\(dg
+.FS
+\(dg\fBImportant Note\fR: If the system is configured to use the IRAF shared
+library (the default), you must update the system libraries (\(sc9.7.2) and
+rebuild the shared library (\(sc9.7.3) before relinking the system
+(\(sc9.7.4), else the changes to the termcap and graphcap cache files will
+have no effect.  The use of the shared library is peculiar to VMS/IRAF and
+is not discussed in the \fImkttydata\fR documentation.
+.FE
+
+.NH
+Software Management
+.NH 2
+Shared libraries
+.PP
+VMS/IRAF provides a shared library facility to reduce disk and memory
+requirements.  What the shared library facility does is take most of the
+IRAF system software (currently the contents of the EX, SYS, VOPS, and OS
+libraries) and link it together into a special shareable image, the file
+\f(CWs_iraf.e\fR in the core BIN directory.  This file is mapped into the
+virtual memory of each IRAF process at process startup time.  Since the
+shared image is shared by all IRAF processes, each process uses less
+physical memory, and the process pagein time is reduced, speeding process
+execution.  Likewise, since the subroutines forming the shared image are no
+longer linked into each individual process executable, substantial disk
+space is saved for the BIN directory.  Link time is correspondingly reduced,
+speeding software development.  For the shared library to be effective, it
+must be installed in system memory as described in \(sc8.2.
+.PP
+.NH 2
+Layered software support
+.PP
+An IRAF installation consists of the \fIcore system\fP and any number of
+\fIexternal packages\fP, or "layered" software products.  As the name
+suggests, layered software products are layered upon the core IRAF system.
+Layered software depends upon the core system for all of its functionality
+and is portable to any computer which already runs IRAF.  Any number of
+layered products can be combined with the core system to produce the IRAF
+system used at a specific site.  Due to disk space limitations it is likely
+that a given site will not wish to have all the available layered software
+products installed and on line at any one time.
+.PP
+The support provided for layered software is essentially the same as that
+provided for maintaining the core system itself.  Each "external package"
+(in most cases this actually refers to a tree of packages) is a system in
+itself, similar in structure to the core IRAF system.  Hence, there is a
+LIB, one or more BINs, a HELP database, and all the sources and runtime
+files.  A good example of an external package is the NOAO package.  Except
+for the fact that NOAO happens to be located in the IRAF root directory,
+NOAO is equivalent to any other layered product, e.g., STSDAS, PROS,
+CTIOLOCAL, KPNOLOCAL, etc.  Other layered products should be rooted
+somewhere outside the \f(CW[IRAF]\fR directory tree to simplify updates.
+.NH 2
+Software management tools
+.PP
+IRAF software management is performed with a standard set of tools,
+consisting of the tasks in the SOFTOOLS package, plus the host system
+editors and debuggers.  Some of the most important and often used tools for
+IRAF software development and software maintenance are the following.
+.sp
+.RS
+.IP "\fBmkhelpdb\fP" 20
+Updates the HELP database of the core IRAF system or an external package
+installed in hlib$extern.pkg.
+The core system, and each external package, has its own help database.
+The help database is the machine independent file helpdb.mip in the
+package library (LIB directory).  The help database file is generated with
+\fImkhelpdb\fP by compiling the root.hd file in the same directory.
+.IP "\fBmkpkg\fP" 20
+The "make-package" utility.  Used to make or update package trees.
+Will update the contents of the current directory tree.  When run at
+the root iraf directory, updates the full IRAF system; when run at the
+root directory of an external package, updates the external package.
+Note that updating the core IRAF system does not update any external
+packages (including NOAO).  When updating an external package, the
+package name must be specified, e.g., "mkpkg -p noao", and the command
+issued within the package directory, not from the IRAF root.
+.IP "\fBrmbin\fP" 20
+Descends a directory tree or trees, finding and optionally listing or
+deleting all binary files therein.  This is used, for example, to strip
+the binaries from a directory tree to leave only sources, to force
+\fImkpkg\fP to do a full recompile of a package, or to locate all the
+binary files for some reason.  IRAF has its own notion of what a binary
+file is.  By default, files with the "known" IRAF virtual file extensions
+(.a, .o, .e, .x, .f, .h, etc.) are classified as binary or text
+(machine independent) files immediately,
+while a heuristic involving examination of the file data
+is used to classify other files.  Alternatively, a list of file extensions
+to be searched for may optionally be given.
+.IP "\fBrtar,wtar\fP" 20
+These are the portable IRAF tarfile writer (\fIwtar\fP) and reader
+(\fIrtar\fP) programs.  These tasks produce archives compatible with
+the UNIX \fItar\fP program.  In addition they can move only the machine
+independent or source files
+(\fIwtar\fP, like \fIrmbin\fP, can discriminate between machine
+generated and machine independent files).  A tarfile written on a VMS/IRAF
+system has the files blank padded, but \fIrtar\fP when used on a UNIX
+system will strip the trailing blanks by default.
+.IP "\fBxc\fP" 20
+The X (SPP) compiler.  This task can compile ".x" or SPP source files, knows
+how to link with the IRAF system libraries and the shared library, knows how
+to read the environment of external packages, and so on.
+.RE
+.sp
+.PP
+The SOFTOOLS package contains other tasks of interest, e.g., a program
+\fImktags\fP for making a tags file for the \fIvi\fP editor, a help
+database examine tool, and other tasks.  Further information on these
+tasks is available in the online help pages.
+.NH 2
+Modifying and updating a package
+.PP
+IRAF applications development (including revisions to existing programs)
+is most conveniently performed from within the IRAF environment, since
+testing must be done from within the environment.  The usual development
+cycle is as follows.  This takes place within the \fIpackage directory\fP
+containing all the sources and mkpkg-files for the package.
+.RS
+.IP \(bu
+Edit one or more source files.
+.IP \(bu
+Use \fImkpkg\fP to compile any modified files, or files which include a
+modified file, and relink the package executable.
+.IP \(bu
+Test the new executable.
+.RE
+.LP
+The \fImkpkg\fP file for a package can be written to do anything,
+but by convention the following commands are usually provided.
+.sp
+.RS
+.IP "\fBmkpkg\fP" 20
+Same as \fBmkpkg relink\fP below.
+.IP "\fBmkpkg libpkg.a\fP" 20
+Updates the package library, compiling any files which have been modified
+or which reference include files which have been modified.  Private package
+libraries are intentionally given the generic name libpkg.a to
+symbolize that they are private to the package.
+.IP "\fBmkpkg relink\fP" 20
+Rebuilds the package executable, i.e., updates the package library and
+relinks the package executable.  By convention, this is the file
+xx_foo.e in the package directory, where \fIfoo\fP is the package name.
+.IP "\fBmkpkg install\fP" 20
+Installs the package executable, i.e., renames the xx_foo.e
+file to x_foo.e in the global BIN directory for the system
+to which the package \fIfoo\fP belongs.
+.IP "\fBmkpkg update\fP" 20
+Does everything, i.e., a \fIrelink\fP followed by an \fIinstall\fP.
+.RE
+.sp
+.PP
+If one wishes to test the new program before installing it one should do
+a \fIrelink\fP (i.e., merely type "mkpkg" since that defaults to relink),
+then run the host system debugger on the resultant executable.  The process
+is debugged standalone, running the task by typing its name into the
+standalone process interpreter.  The CL task \fIdparam\fP is useful
+for dumping a task's parameters to a text file to avoid having to answer
+innumerable parameter queries during process execution.  If the new program
+is to be tested under the CL before installation, a \fItask\fP statement
+can be interactively typed into the CL to cause the CL to run the "xx_"
+version of the package executable, rather than the old installed version.
+.PP
+When updating a package other than in the core system, the \fB-p\fP flag,
+or the equivalent PKGENV logical name, \fImust\fP be used
+to indicate the system or layered product being updated.  For example,
+"mkpkg -p noao update" would be used to update one of the packages
+forming the NOAO system of packages.
+.PP
+The CL \fBprocess cache\fP can complicate debugging and testing if one
+forgets that it is there.  Recall that when a task is run under the CL,
+the executing process remains idle in the CL process cache following
+task termination.  If a new executable is installed while the old one
+is still in the process cache, the \fIflprcache\fP command must be
+entered to force the CL to run the new executable.  If an executable is
+currently running, either in the process cache or because some other
+user is using the program, it may not be possible to set breakpoints
+under the debugger.
+.PP
+The \fBshared library\fP can also complicate debugging, although for most
+applications-level debugging the shared library is transparent.  If it
+is necessary to debug IRAF system libraries, contact the IRAF Hotline
+for assistance.
+.PP
+A full description of these techniques is beyond the scope of this manual,
+but one need not be an expert at IRAF software development techniques to
+perform simple updates.  Most simple revisions, e.g., bug fixes or updates,
+can be made by merely editing or replacing the affected files and typing
+.XS
+cl> mkpkg update
+.XE
+.LP
+plus maybe a \fIflpr\fP if the old executable is still sitting idle
+in the process cache.
+.NH 2
+Installing and maintaining layered software
+.PP
+The procedures for installing layered software products are similar to those
+used to install the core IRAF system, or update a package.  Layered software
+may be distributed in source only form, or with binaries.  The exact
+procedures to be followed to install a layered product will in general be
+product dependent, and should be documented in the installation guide for
+the product.
+.LP
+In brief, the procedure to be followed should resemble the following:
+.RS
+.IP \(bu
+Create the root directory for the new software, somewhere outside the
+IRAF directories.
+.IP \(bu
+Restore the files to disk from a tape or network archive distribution file.
+.IP \(bu
+Edit the core system file hlib$extern.pkg to "install" the new package in
+IRAF.  Note that any `$' characters in a VMS pathname should be escaped with
+a backslash as in the examples.  This file is the sole link between the IRAF
+core system and the external package.
+.IP \(bu
+Configure the package BIN directory or directories, either by restoring
+the BIN to disk from an archive file, or by recompiling and relinking the
+package with \fImkpkg\fP.
+.RE
+.LP
+As always, there are some little things to watch out for.  When using
+\fImkpkg\fP on a layered package, you must give the name of the package
+being updated, plus the names of any other external packages used to build
+the target package, e.g.,
+.DS
+\f(CWcl> mkpkg -p foo update\fP
+.DE
+where \fIfoo\fP is the name of the package being update, e.g., "noao",
+"local", etc.  The \fB-p\fP flag can be omitted by defining PKGENV
+as a VMS logical name.
+.PP
+Once installed and configured, a layered product may be deinstalled merely
+by archiving the package directory tree, deleting the files, and commenting
+out the affected lines in hlib$extern.pkg.  With the BINs already configured
+reinstallation is a simple matter of restoring the files to disk and editing
+the extern.pkg file.
+.NH 2
+Configuring a custom LOCAL package
+.PP
+Anyone who uses IRAF enough will eventually want to add their own software
+to the system, by copying and modifying the distributed versions of
+programs, by obtaining and installing isolated programs written elsewhere,
+or by writing new programs of their own.  A single user can do this by
+developing software for personal use, defining the necessary \fItask\fP
+statements, etc.  to run the software in the personal login.cl file.  To go
+one step further and install the new software in IRAF so that it can be used
+by everyone at a site, one must configure a \fBcustom local package\fP.
+.PP
+The procedures for configuring and maintaining a custom LOCAL package are
+similar to those outlined in \(sc9.5 for installing and maintaining layered
+software, since a custom LOCAL will in fact be a layered software product,
+possibly even something one might want to export to another site (although
+custom LOCALs often contain non-portable or site specific software).
+.PP
+To set up a custom LOCAL, start by making a local copy of the \fBtemplate
+local\fP package that comes with the distributed system and editing
+hlib$extern.pkg to make the location of the new package known.  If you make
+a source only \fItar\fR or \fIbackup\fR  archive of iraf$local and install
+it as outlined in \(sc9.4, you will have a custom LOCAL.  The purpose of the
+template LOCAL is to provide the framework necessary for an external
+package; a couple of simple tasks are provided in the template LOCAL to
+serve as examples.  Once you have configured a local copy of the template
+LOCAL and gotten it to compile and link, it should be a simple matter to add
+new tasks to the existing framework.
+.NH 2
+Updating the full IRAF system
+.NH 3
+The BOOTSTRAP
+.PP
+All current IRAF distributions come with the system already bootstrapped,
+i.e., the host system interface (HSI) comes with the HSI binary executables
+already built.  A bootstrap should not be necessary unless one is doing
+something unusual, e.g., installing a bugfix or making some other revision
+to the HSI.
+.PP
+A bootstrap is like a full system sysgen, except that it is the host
+system interface (kernel and bootstrap utilities) which is compiled and
+linked, rather than IRAF itself.  The system must be bootstrapped before
+a sysgen is possible, since the bootstrap utilities are required to do a
+sysgen.  The two operations are distinct because only the bootstrap is
+machine dependent; everything else works the same on all IRAF systems.
+.PP
+The bootstrap utilities are required for system maintenance of the main
+system and hence must be linked first.  However, unless a bug fix or other
+revision is made to one of the main system libraries (particularly LIBOS),
+there should be no reason for a user site ever to need to bootstrap the
+system.  The bootstrap utilities are linked with the option /NOSYSSHARE,
+hence they should run on most versions of VMS.
+.PP
+The bootstrap utilities are written in C, and the DEC C compiler is required
+to compile or link these utilities.  The C compiler is \fInot\fR required to
+run the prelinked binaries distributed with the system.  To recompile and link
+the bootstrap utilities, i.e., to "bootstrap" IRAF, enter the commands shown
+below.  Note that the HSI is always recompiled during a bootstrap; there
+is no provision for merely relinking the entire HSI (some individual programs
+can however be relinked manually by doing a "mkpkg update" in the program
+source directory).
+.XS
+$ set default [iraf.vms]
+$ set verify
+$ @rmbin.com
+$ @mkpkg.com
+.DE
+.LP
+The bootstrap should take 30 to 45 minutes on an unloaded 11/780.  Once the
+bootstrap utilities have been relinked and installed in hlib, the main
+system may be relinked.
+.NH 3
+Updating the system libraries
+.PP
+Updating the system libraries, i.e., recompiling selected object modules and
+inserting them into the system object libraries, is necessary if any system
+source files are edited or otherwise modified.
+.PP
+The system libraries may be updated either from within the IRAF CL, or from
+DCL.  For example, from within DCL:
+.XS
+$ set def [iraf]
+$ mkpkg syslibs \fR[\fPmathlibs\fR]
+.XE
+.LP
+The brackets around mathlibs just mean "optional"; do not actually include
+the brackets if you need to rebuild the math libraries.  This command will
+run the \fImkpkg\fR utility, which will update each system library in turn,
+descending into the tree of source directories and checking the date of each
+object module therein against the dates of the source files and dependency
+files used to produce the object module, and recompiling any object modules
+which are out of date.  In the worst case, e.g., if the system libraries
+have been deleted, the entire VOS (virtual operating system) will be
+recompiled.  If it is known that no changes have been made to the math
+library source files, the optional mathlibs argument may be omitted to save
+some time.
+.NH 3
+Relinking the IRAF shared library
+.PP
+The IRAF shared library ([IRAF.BIN]S_IRAF.EXE) is constructed by linking the
+contents of the four main IRAF system libraries LIBEX, LIBSYS, LIBVOPS, and
+LIBOS.  Hence, the system libraries must exist and be up to date before
+linking the shared library.  The shared library must be installed in
+\f(CWbin\fR before it can be used to link any applications programs.  At
+present, the shared library does not use transfer vectors, hence the full
+system must be relinked following any changes to the shared library.  Note
+that since the shared library is normally installed in system memory, all
+installed IRAF images should be deinstalled and later reinstalled whenever
+the shared library is rebuilt.  IRAF will not be runnable while this is
+taking place.
+.PP
+In the current release of IRAF the procedure for building the shared library
+has not yet been integrated into the automatic system generation procedure.
+Furthermore, utility tasks in the main IRAF system are currently used to
+build the shared library, so it is necessary to have at least part of the
+main system functioning before the shared library can be built.  These
+problems (and the transfer vector problem) will be fixed in a future release
+of VMS/IRAF.
+.PP
+The shared library is rebuilt from within a running IRAF system that
+provides at a minimum the three executables CL.EXE, X_SYSTEM.EXE, and
+X_LISTS.EXE.  If these executables do not yet exist or are not runnable,
+rebuild them as follows.  Note the use of the "-z" link flag to link the new
+executables without the shared library.
+.XS
+$ set default [iraf.pkg.cl]
+$ mkpkg update lflags=-z
+$ set default [iraf.pkg.system]
+$ mkpkg update lflags=-z
+$ set default [iraf.pkg.lists]
+$ mkpkg update lflags=-z\fR
+.XE
+.LP
+Now startup the CL and change to the directory hlib$share, which
+contains the code used to build the shared library.
+.XS
+$ set default [iraf.local]
+$ cl
+    \fR(cl starts up...)\fP
+cl> cd hlib$share
+.XE
+.LP
+The following commands will rebuild the shared library and install it in
+\f(CWbin\fR.  This takes ten minutes or so.
+.XS
+cl> cl < makeshare.cl
+    \fR(takes a while)\fP
+cl> mkpkg install
+cl> purge
+cl> logout
+.XE
+.LP
+The system libraries can be updated (\(sc9.7.2) and the shared library
+rebuilt while IRAF is in use by normal users, however as soon as the command
+\f(CWmkpkg install\fR is executed (moving the new S_IRAF.EXE to bin)
+execution of normal user programs is at risk and one should kick all IRAF
+users off the machine and deinstall any installed IRAF images.  The system
+may now be relinked and the newly linked shared library and images
+reinstalled, after which the system is ready for normal use again.  Note
+that makeshare creates a load map s_iraf.map for s_iraf.e that should be
+deleted when no longer needed (it is quite large).
+.NH 3
+Relinking the main IRAF system
+.PP
+The following DCL commands may be entered to relink the main IRAF system,
+installing the newly linked executables in \f(CWbin\fR.  Note that any
+IRAF executables that have been installed in system memory must be
+deinstalled and reinstalled (\(sc8.2) following the relink.
+.XS
+$ set default [iraf]
+$ mkpkg update
+.XE
+.LP
+The command shown causes the full system to be relinked (or recompiled and
+relinked if any files have been modified) using the default compile and link
+switches defined in the global \fImkpkg\fR include file hlib$mkpkg.inc.  Any
+system wide changes in how the system is generated should be implemented by
+editing the contents of this file.  For example, the default file supplied
+with the system includes the following line:
+.XS
+$set    LFLAGS  = ""            # default XC link flags
+.XE
+.LP
+This switch defines the switches to be passed to the HSI bootstrap utility
+program \fIxc\fR to link the IRAF executables (no switches are given, hence
+the default link action will be taken).  The switch "-z" may be included in
+the \fIxc\fR command line to link an executable directly against the system
+object libraries, rather than using the shared library.  Hence, to relink
+IRAF without using the IRAF shared library (as is necessary for all but one
+system when there are multiple versions of IRAF simultaneously installed on
+the same machine) we would change the definition of LFLAGS as follows:
+.XS
+$set    LFLAGS  = "-z"          # default XC link flags
+.XE
+.LP
+A full system relink takes approximately 30 minutes, or significantly less
+if the shared library is used.  A full system compile and relink takes 9-24
+hours depending upon the host system.
+.PP
+The above procedure only updates the core IRAF system.  To update a layered
+product one must repeat the sysgen process for the layered system.
+For example, to update the NOAO package:
+.XS
+$ set default [iraf.noao]
+$ mkpkg -p noao
+.XE
+.LP
+Layered systems are completely independent of one another and hence must
+be updated separately.
+
+.NH
+Miscellaneous Notes
+.PP
+Magtape deallocation will not work properly in VMS/IRAF if the CL is run from
+a privileged account such as one that has BYPASS or SYSPRV privilege
+(a \f(CWcl> !dismount\fP may unmount the drive).
+.PP
+Under VMS 5, the AUTOGEN procedure includes feedback information.
+It is worth running the system, with IRAF users, for a couple of weeks
+and then re-running AUTOGEN (as detailed in the VMS System Management
+documentation) to adjust some of the system parameters (global pages,
+various memory structures) for the new work load.
+.PP
+"If all else fails", e.g., hung tape drives, etc., \(em our VMS system
+manager recommends kicking everyone off the system, perhaps even rebooting
+if it gets desperate, and then inspecting this Installation Guide again,
+before calling us.  And please, if you need to call, try to have available
+the exact text of any error messages you may have encountered.
+
+.bp
+.DS C
+\fBAppendix A.  Private TMP and IMDIR Directories\fR
+.DE
+.PP
+If local system management policies require that private \f(CWtmp\fP and
+\f(CWimdir\fP directories be defined for each user, you can define these
+directories for each user as subdirectories of their SYS$LOGIN directory.
+One way to do this is define imdir to be the same as tmp, and modify the
+definition of IRAFTMP in the IRAFUSER.COM file as shown below.
+.XS
+$! ----------- add these lines to irafhlib:irafuser.com ----------
+$! This block of DCL assigns the logical name IRAFTMP to a
+$! subdirectory of the user's VMS login directory.  It is necessary
+$! to escape the "$" and "[" because they are IRAF filename
+$! metacharacters.  This block of code should replace the current
+$! definition in irafuser.com of IRAFTMP:
+$!
+$!   define/job  IRAFTMP  TEMPDISK:[IRAFTMP]        ! scratch files
+$!
+$! We assume only one occurrence of "$" or "[".
+$!
+$  tmpdir = f$logical ("SYS$LOGIN")
+$  tmpdir = f$extract (0, f$locate("]",tmpdir), tmpdir) + ".IRAFTMP]"
+$  define/job vmstmp 'tmpdir'
+$  off = f$locate ("$", tmpdir)
+$  tend = f$length (tmpdir)
+$  if (off .ne. tend) then -
+     tmpdir = f$extract (0, off, tmpdir) + -
+       "\e$" + f$extract (off+1, tend, tmpdir)
+$  off = f$locate ("[", tmpdir)
+$  if (off .ne. tend+1) then -
+     tmpdir = f$extract (0, off, tmpdir) + -
+       "\e[" + f$extract (off+1, tend, tmpdir)
+$  define/job iraftmp "''tmpdir'"\s0\fR
+.sp
+In irafhlib:login.cl, replace U_IMDIR with "tmp$".
+.XE
+.LP
+In irafhlib:mkiraf.com, replace the block of statements beginning
+"imdir_file :=" with the following:
+.XS
+$  if (f$search ("sys$login:iraftmp.dir") .eqs. "") then -
+	create/directory vmstmp
+.XE
+.LP