Repatch (from linux) of OSX IRAF

1 files changed, 2673 insertions, 0 deletions

diff --git a/doc/vmsiraf.ms.v29 b/doc/vmsiraf.ms.v29
new file mode 100644
index 00000000..ed3c271b
--- /dev/null
+++ b/doc/vmsiraf.ms.v29
@@ -0,0 +1,2673 @@
+.RP
+.TL
+VMS/IRAF Installation and Maintenance Guide
+.AU
+Doug Tody
+.br
+Steve Rooke, Suzanne Jacoby, Nigel Sharp
+.AI
+.K2 "" "" "*"
+July 1987, Revised July 1989
+
+.AB
+.ti 0.75i
+Instructions are presented for installing, updating, and maintaining the VMS
+version of the portable IRAF system (Image Reduction and Analysis Facility).
+Step by step procedures are presented both for the initial IRAF installation
+and for updating an existing installation to the latest release of the system.
+Procedures for improving performance, minimizing disk and memory usage, and
+interfacing site dependent devices such as video or graphics terminals,
+plotters, image displays, and magnetic tape drives are discussed.
+.AE
+
+.pn 1
+.bp
+.sp 2.5i
+.ce
+.ps 11
+.ps +2
+\fBHistorical Notes\fR
+.ps -2
+.sp 3
+The initial port of IRAF to VMS was carried out during 1984 and early 1985
+at STScI (the Space Telescope Science Institute) by Jay Travisano
+and Fred Romelfanger, working under the supervision of Peter Shames, with
+some assistance early on from Jim Rose.  The major system components
+implemented during this period were the SPP compiler (XC) and the OS
+interface routines for VMS, as specified in \fIA Reference Manual for the
+IRAF System Interface\fP, Doug Tody, May 1984.
+.sp
+Completion of VMS/IRAF took place at NOAO in the fall of 1985.  This period
+saw the definition of a major new interface, the HSI (host system interface),
+and the implementation of the \f(CWmkpkg\fP system maintenance utility and
+many of the other HSI bootstrap utilities.  This eliminated the final
+differences between the different versions of IRAF, allowing software to be
+routinely ported between UNIX/IRAF, VMS/IRAF, and so on, without any changes
+to the program sources or configuration control files, and allowing full
+automation of the system configuration control procedures.
+.sp
+The initial implementation of shared libraries for VMS/IRAF was carried out
+in the fall of 1986 by Dennis Crabtree of DAO (the Dominion Astrophysical
+Observatory, UBC, Canada), while on leave at STScI.
+
+.pn 1
+.bp
+.ce
+.ps +2
+\fBContents\fP
+.ps -2
+.sp 3
+.sp
+1.\h'|0.4i'\fBIntroduction\fP\l'|5.6i.'\0\01
+.sp
+2.\h'|0.4i'\fBInitial System Installation\fP\l'|5.6i.'\0\02
+.br
+\h'|0.4i'2.1.\h'|0.9i'Create the IRAF Account\l'|5.6i.'\0\02
+.br
+\h'|0.4i'2.2.\h'|0.9i'Read the BACKUP Tape\l'|5.6i.'\0\03
+.br
+\h'|0.4i'2.3.\h'|0.9i'Edit the System Configuration Files\l'|5.6i.'\0\03
+.br
+\h'|0.9i'2.3.1.\h'|1.5i'[IRAF.VMS.HLIB]IRAFUSER.COM\l'|5.6i.'\0\04
+.br
+\h'|0.9i'2.3.2.\h'|1.5i'[IRAF.VMS.HLIB]INSTALL.COM\l'|5.6i.'\0\05
+.br
+\h'|0.9i'2.3.3.\h'|1.5i'[IRAF.VMS.HLIB.LIBC]IRAF.H\l'|5.6i.'\0\05
+.br
+\h'|0.4i'2.4.\h'|0.9i'Relink If Necessary\l'|5.6i.'\0\06
+.br
+\h'|0.4i'2.5.\h'|0.9i'Complete the Initial System Configuration\l'|5.6i.'\0\06
+.br
+\h'|0.4i'2.6.\h'|0.9i'Edit the System Dependent Device Files\l'|5.6i.'\0\07
+.br
+\h'|0.9i'2.6.1.\h'|1.5i'[IRAF.VMS.HLIB]ZZSETENV.DEF\l'|5.6i.'\0\07
+.br
+\h'|0.9i'2.6.2.\h'|1.5i'[IRAF.DEV]DEVICES\l'|5.6i.'\0\08
+.br
+\h'|0.9i'2.6.3.\h'|1.5i'[IRAF.DEV]TERMCAP\l'|5.6i.'\0\08
+.br
+\h'|0.9i'2.6.4.\h'|1.5i'[IRAF.DEV]GRAPHCAP\l'|5.6i.'\0\08
+.br
+\h'|0.9i'2.6.5.\h'|1.5i'IRAF Networking\l'|5.6i.'\0\09
+.sp
+3.\h'|0.4i'\fBUpdating an Existing IRAF Installation\fP\l'|5.6i.'\0\09
+.br
+\h'|0.4i'3.1.\h'|0.9i'Save Locally Modified Files\l'|5.6i.'\0\09
+.br
+\h'|0.4i'3.2.\h'|0.9i'Read the Distribution Tape or Tapes\l'|5.6i.'\0\10
+.br
+\h'|0.4i'3.3.\h'|0.9i'Merge Saved Files Back Into the New System\l'|5.6i.'\0\10
+.br
+\h'|0.4i'3.4.\h'|0.9i'Relink If Necessary\l'|5.6i.'\0\11
+.br
+\h'|0.4i'3.5.\h'|0.9i'Update VMS\l'|5.6i.'\0\11
+.sp
+4.\h'|0.4i'\fBTesting a Newly Installed or Updated System\fP\l'|5.6i.'\0\12
+.sp
+5.\h'|0.4i'\fBSystem Maintenance\fP\l'|5.6i.'\0\12
+.br
+\h'|0.4i'5.1.\h'|0.9i'Software Management\l'|5.6i.'\0\12
+.br
+\h'|0.9i'5.1.1.\h'|1.5i'Layered Software Support\l'|5.6i.'\0\12
+.br
+\h'|0.9i'5.1.2.\h'|1.5i'Software Management Tools\l'|5.6i.'\0\13
+.br
+\h'|0.9i'5.1.3.\h'|1.5i'Modifying and Updating a Package\l'|5.6i.'\0\14
+.br
+\h'|0.9i'5.1.4.\h'|1.5i'Installing and maintaining layered software\l'|5.6i.'\0\15
+.br
+\h'|0.9i'5.1.5.\h'|1.5i'Configuring a custom LOCAL package\l'|5.6i.'\0\16
+.br
+\h'|0.9i'5.1.6.\h'|1.5i'Bootstrapping the HSI\l'|5.6i.'\0\16
+.br
+\h'|0.9i'5.1.7.\h'|1.5i'Updating the System Libraries\l'|5.6i.'\0\17
+.br
+\h'|0.9i'5.1.8.\h'|1.5i'Relinking the IRAF Shared Library\l'|5.6i.'\0\17
+.br
+\h'|0.9i'5.1.9.\h'|1.5i'Relinking the Main IRAF System\l'|5.6i.'\0\18
+.br
+\h'|0.4i'5.2.\h'|0.9i'Tuning Considerations\l'|5.6i.'\0\19
+.br
+\h'|0.9i'5.2.1.\h'|1.5i'Installing Executable Images\l'|5.6i.'\0\19
+.br
+\h'|0.9i'5.2.2.\h'|1.5i'Rendering Large Runtime Files Contiguous\l'|5.6i.'\0\20
+.br
+\h'|0.9i'5.2.3.\h'|1.5i'Precompiling TERMCAP and GRAPHCAP Entries\l'|5.6i.'\0\20
+.br
+\h'|0.9i'5.2.4.\h'|1.5i'Stripping the System to Reduce Disk Consumption\l'|5.6i.'\0\20
+.br
+\h'|0.4i'5.3.\h'|0.9i'VMS Quotas and Privileges Required to Run IRAF\l'|5.6i.'\0\21
+.br
+\h'|0.4i'5.4.\h'|0.9i'Miscellaneous Notes\l'|5.6i.'\0\22
+.sp
+6.\h'|0.4i'\fBInterfacing New Graphics Devices\fP\l'|5.6i.'\0\22
+.br
+\h'|0.4i'6.1.\h'|0.9i'Graphics Terminals\l'|5.6i.'\0\22
+.br
+\h'|0.4i'6.2.\h'|0.9i'Graphics Plotters\l'|5.6i.'\0\23
+.br
+\h'|0.4i'6.3.\h'|0.9i'Image Display Devices\l'|5.6i.'\0\23
+.sp
+7.\h'|0.4i'\fBThe IRAF Directory Structure\fP\l'|5.6i.'\0\24
+.sp
+\fBAppendix A. \0Private TMP and IMDIR Directories\fR\l'|5.6i.'\0\26
+.sp
+\fBAppendix B. \0Upgrading a Pre-IRAF 2.8 [iraf.local] Directory\fR\l'|5.6i.'\0\27
+.sp
+\fBAppendix C. \0Notes on Networking with DECNET in VMS/IRAF V2.8\fR\l'|5.6i.'\0\31
+
+.nr PN 0
+.bp
+.NH
+Introduction
+.PP
+Installing VMS/IRAF is easy and fast, provided one takes the trouble to read
+and follow the instructions in this installation guide.  Instructions are given
+both for the initial system installation (\(sc2, immediately following)
+and for updating an existing installation (\(sc3).  Variations on the
+recommended system configuration are certainly possible and may be necessary
+at some sites due to restrictions or quotas, but not following the standard
+installation procedure or departing from the recommended system configuration
+may cause the system to function incorrectly, inefficiently, or not at all.
+.PP
+The distribution tape is a snapshot of our local (NOAO/Tucson) VMS/IRAF system.
+The device and system configuration tables come configured 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 \f(CW[IRAF.DEV]\fP, \f(CW[IRAF.VMS.HLIB]\fP,
+and \f(CW[IRAF.LOCAL]\fP).
+The remainder of the system should not require any modifications.
+.PP
+An installation typically takes about an hour, perhaps longer if relinking is
+necessary.  Interfacing new graphics terminals, plotters, or image displays
+can take considerably longer, of course, and we will only touch upon such
+matters in the installation guide.  Feel free to contact the IRAF hotline for
+assistance if any problems should arise during the installation, or for help
+in interfacing new devices.
+.sp
+.TS
+center;
+cb s s
+l l l.
+IRAF HOTLINE
+.sp
+telephone	\f(CW(602) 323-4160\fP
+internet	\f(CWiraf@noao.edu\fP
+span/hepnet	\f(CWnoao::iraf\fP	(noao = 5355)
+uucp	\f(CW{arizona,decvax,ncar}!noao!iraf\fP or
+uucp	\f(CWuunet!noao.edu!iraf\fP
+bitnet	\f(CWiraf@noao.edu\fP (through a gateway)
+.TE
+
+.NH
+Initial System Installation
+.PP
+It is only necessary to follow the full installation procedure if IRAF has
+not yet been installed on your system.  If an old version of IRAF has already
+been installed, proceed to \(sc3.
+.PP
+Briefly, the steps to be followed to install IRAF for the first time are the
+following.  This summary is provided only to introduce the basic installation
+procedure: it is important to read the detailed installation instructions
+for additional details, to avoid certain errors or omissions which are
+otherwise highly likely (IRAF does not always follow VMS conventions).
+.RS
+.IP \(bu
+Login as SYSTEM and create an account for user IRAF, root directory
+\f(CW[IRAF]\fP, login directory \f(CW[IRAF.LOCAL]\fP, to be used by the IRAF
+system manager to maintain IRAF.
+.IP \(bu
+Login as IRAF and run the \f(CWBACKUP\fP utility to restore the IRAF distribution
+tape or tapes to disk.  Make sure the files belong to user IRAF.
+.IP \(bu
+Edit the basic IRAF system configuration files \f(CWIRAFUSER.COM\fP and
+\f(CWIRAF.H\fP (in \f(CWhlib\fP and \f(CWhlib/libc\fP), e.g., to change the system
+dependent disk and batch queue names, and define the VMS pathnames to
+the major IRAF directories.
+.IP \(bu
+Login again as SYSTEM and [1] copy the \f(CWIRAF.H\fP file edited above
+to the VMS system library directory \f(CWSYS$LIBRARY\fP,
+[2] add a global symbol \f(CWiraf\fP to the system-wide user login procedure
+(e.g. \f(CWSYLOGIN.COM\fP) which when
+executed by the user will execute the \f(CWIRAFUSER.COM\fP file to define the
+rest of the IRAF logicals, and
+[3] edit \f(CWINSTALL.LST\fP and execute the \f(CWINSTALL.COM\fP script
+(in \f(CWhlib\fP) to "install"
+in system shared memory at least the IRAF shared library, and probably some of
+the most frequently used executables as well.
+.RE
+.PP
+Although the system installation is not yet complete,
+any user should now be able to run IRAF, i.e.,
+run the \f(CWiraf\fP command procedure to define the IRAF logicals,
+run the \f(CWmkiraf\fP command procedure to initialize the IRAF environment,
+and type the command \f(CWcl\fP to start up the IRAF Command Language (CL).
+Following the basic installation procedure shown here,
+it will still be necessary to modify the IRAF device tables to tell the system
+about the local magtape devices, line printers, terminals, plotters, and so on.
+This should be done from within the running IRAF system to facilitate
+testing of the new device interfaces, and is an ongoing activity as new
+devices are interfaced to the system.
+
+.NH 2
+Create the IRAF Account
+.PP
+Create an account for user `\f(CWIRAF\fP'.  This is recommended for the
+following reasons:
+.DS
+.IP \(bu
+All IRAF system management should be performed using the default protections
+etc. provided in the IRAF \f(CWlogin.com\fP.
+.IP \(bu
+Multiple people may need to be IRAF system manager.  Having a separate account
+avoids the need for one user to know another user's password.  Even if there
+is only one site manager at your site, it may be necessary to give login
+information to the IRAF HOTLINE personnel to allow them to investigate a
+problem.
+.IP \(bu
+Having IRAF owned by SYSMAN, SYSTEM or other management account is not a good
+solution as then anyone who needs to serve as IRAF site manager would
+require the manager's password, and furthermore, the protections etc. of
+a privileged account would cause problems for normal users.
+.DE
+.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 (see \(sc2.2
+below).  If necessary, the system can be stripped after installation to save
+space (\(sc5.2.4), 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 \f(CW[IRAF]\fP,
+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
+\f(CW[IRAF.LOCAL]\fP
+rather than \f(CW[IRAF]\fP as one would expect, as we want to keep all the
+locally modified files in subdirectories off the iraf login 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 \f(CWLOGIN.COM\fP for IRAF; one will be read from the
+distribution tape, as will the \f(CW[IRAF.LOCAL]\fR directory.
+(If for some local management reason the directory \f(CW[IRAF.LOCAL]\fR 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 (\(sc5.3).
+.RE
+.NH 2
+Read the BACKUP Tape
+.PP
+Login as IRAF (ignore any \f(CWLOGIN.COM\fP not found error message)
+and run the VMS \f(CWBACKUP\fP utility to read the BACKUP tape or tapes provided.
+The tape contains approximately 8500 files in 300 directories, for a total
+of 48 Mb or 96000 512-byte blocks (including binaries).  This disk size
+assumes a Disk Cluster Factor of 1; if your site has a larger DCF, IRAF
+will take more space (you can distinguish between allocated size and used size
+with \f(CW$dir/size=all\fP).
+The system as distributed uses a shared library to reduce disk and
+memory requirements.
+If IRAF is relinked and run without the shared library (e.g., if two or
+more versions of IRAF are installed on the same machine), the system will
+take up about 63 Mb or 125000 blocks.
+.DS
+\f(CW\s-1$ mount/foreign \fItape\f(CW:
+$ set default \fIdisk\f(CW:[iraf]
+$ backup/rew \fItape\f(CW:iraf.bck/select=[iraf...] [...]/own=iraf/prot=w:r
+\s0\fP
+.DE
+In this and all the following examples, names like \fIdisk:\fP, \fItape:\fP,
+etc. denote site dependent device names for which you must supply values.
+The tape may be restored while logged in as SYSTEM if desired, but the switch
+\f(CW/OWNER=IRAF\fP 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 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.
+
+.IP \f(CWIRAFDISK\fP
+.br
+Set to the name of the disk the \f(CW[IRAF]\fP 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 \f(CWmkiraf\fP script will try to create the default user image storage
+directories on this disk, e.g., \f(CWIMDIRDISK:[\fIuser\f(CW]\fR.
+All potential IRAF users should have write permission and quota on this
+device.  IRAF does not yet know about ACLs (access control lists).
+.sp
+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.\(dg
+.sp
+[Note for sites that use "rooted logicals":  the VMS/IRAF kernel
+does not yet understand rooted logicals.  If you use one, e.g. for
+\f(CWIMDIRDISK\fR, batch jobs that need to access it will fail.  To avoid
+problems, you must either choose \f(CWIMDIRDISK\fR to be truly just a disk
+specification, or inform all users to edit their \f(CWlogin.cl\fR files after
+a \f(CWMKIRAF\fR.
+For example, if you define \f(CWIMDIRDISK\fR to be \f(CWDATA_DISK:\fR,
+where \f(CWDATA_DISK\fR is a logical name for \f(CWdub4:[data.]\fR,
+user ICHABOD's \f(CWlogin.cl\fR would have: 
+"\f(CWset imdir = DATA_DISK:[ICHABOD]\fR",
+but this would not work for batch jobs.
+The user should edit \f(CWlogin.cl\fR after a \f(CWMKIRAF\fR to use an
+expanded directory specification, in this case:
+"\f(CWset imdir = dub4:[data.ichabod]\fR".]
+.IP \f(CWTEMPDISK\fR
+.br
+Set to the name of a public scratch device and create a public directory
+\f(CW[IRAFTMP]\fR on this device.
+The device may be the same as is used for \f(CWIMDIRDISK\fP if desired.
+The IRAF logical directory "\f(CWtmp\fR"
+(known as \f(CWIRAFTMP\fP in the \f(CWIRAFUSER.COM\fR file)
+is defined as \f(CWTEMPDISK:[IRAFTMP]\fR.\(dg
+.FS
+\(dgIf local system management or accounting policies require that
+private \f(CWtmp\fR and \f(CWimdir\fR 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 "\f(CWtmp\fP" older than a day or so are garbage and should
+be deleted.  It is best if "\f(CWtmp\fP" 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 \f(CWtmp\fP are rarely very large.
+.sp
+[See note under \f(CWIMDIRDISK\fP concerning rooted logicals, if you plan to
+locate \f(CWTEMPDISK\fP at a rooted logical.]
+
+.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 \f(CWSYS$BATCH\fP (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.
+
+.IP \f(CWSYS$NODE\fP
+.br
+If you have DECNET installed, the system logical \f(CWSYS$NODE\fP will 
+probably already be defined (\f(CW$ show logical sys$node\fP).  If it
+is not defined, uncomment the line containing the sys$node definition,
+and set \f(CWNODE\fP to "::", as:
+.br
+.sp
+	\f(CW$  define/job SYS$NODE "::"\fP
+.sp
+.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
+.FS
+\(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.
+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 \(sc5.2.1 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 \f(CWinstall.com\fP itself.  Instead, edit
+\f(CWinstall.lst\fP to select files by commenting out only those which are
+\fInot\fP to be installed (the comment character is a "\f(CW!\fP" at the 
+beginning of the line).
+The 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 \f(CWcl.exe\fP and \f(CWx_system.exe\fP
+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 \f(CWx_images.exe\fP and
+\f(CWx_plot.exe\fP, 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 \f(CW<iraf.h>\fP)
+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
+(i.e. \f(CWusr1:[IRAF.VMS]\fP, where \f(CWusr1\fP is a system logical name;
+do not leave the IRAF logicals like \f(CWirafdisk\fP in the definition).
+.DS
+.TS
+center;
+ci ci
+n l.
+IRAF Logical Directory	VMS directory
+
+\f(CW\&HOST\fP	\fIirafdisk\f(CW:[IRAF.VMS]\fP
+\f(CW\&IRAF\fP	\fIirafdisk\f(CW:[IRAF]\fP
+\f(CW\&TMP\fP	\fItempdisk\f(CW:[IRAFTMP]\fP (may vary\(dg\(dg)
+.TE
+.DE
+.FS
+\(dg\(dg\fRIf local system restrictions forbid a
+public \f(CWIRAFTMP\fP directory,
+set this entry to the pathname of a suitable directory in IRAF, e.g.,
+\f(CW[IRAF.LOCAL.UPARM]\fP.  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 \f(CWtmp\fR directory discussed
+in Appendix A.
+.FE
+.PP
+These directory definitions are referenced only if logical name translation
+fails for some reason, 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 \f(CW<iraf.h>\fP is very strict about the syntax.
+
+.NH 2
+Relink If Necessary
+.PP
+If you received a full binary distribution of VMS/IRAF and you are not running
+an old version of VMS, you do not need to relink the system and may proceed
+to \(sc2.5.  A "you relink" distribution is shipped without binaries so of
+course requires linking.  Linking may also be necessary when running a version
+of VMS older than that installed on our NOAO system when the executables in
+a binary release were linked, since the VMS operating system may refuse to
+run executables linked on a possibly incompatible "future" revision of VMS.
+.PP
+In any case, relinking the system is easy and fast.  The basic procedure is
+outlined below; additional information is given in \(sc5.1.9.
+The following commands should be executed while logged in as IRAF.
+.DS
+\f(CW$ set default [iraf]
+$ mkpkg update
+$ set default [iraf.noao]
+$ mkpkg update\fR
+.DE
+.PP
+By default, the system is linked against the IRAF shared library
+\f(CWS_IRAF.EXE\fP which should already be present in the \f(CW[IRAF.BIN]\fP
+directory after restoring the distribution tape.  This speeds up linking and
+considerably reduces the size of the resultant executables.  It should not
+be necessary to relink the HSI executables (in \f(CWhlib\fP), as these are
+linked with \f(CW/NOSYSSHARE\fP on our system and are included in all VMS/IRAF
+distributions.
+
+.NH 2
+Complete the Initial System Configuration
+.PP
+Login again as SYSTEM and copy the recently edited file
+\f(CWirafdisk:[iraf.vms.hlib.libc]iraf.h\fP to the system library,
+ensuring that the file has world read permission (be sure not to
+copy \f(CW[iraf.vms.hlib]iraf.h\fR by mistake):\(dg
+.FS
+\(dg\fROn a VMS cluster, make sure the \f(CWIRAF.H\fR file is added to
+\f(CWSYS$COMMON:[SYSLIB]\fR rather than \f(CWSYS$SYSROOT:[SYSLIB]\fR,
+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. \f(CWSYLOGIN.COM\fR),
+which will probably want to go into \f(CWSYS$COMMON:[SYSMGR]\fP.
+The \f(CWSYSTARTUP.COM\fR file (or \f(CWSYSTARTUP_V5.COM\fR in VMS V5.x),
+on the other hand,
+should go into \f(CWSYS$SYSROOT:[SYSMGR]\fP if the bootstrap procedure is
+different for each node.
+.FE
+.DS
+\f(CW$ set default sys$library
+$ copy \fIdisk\f(CW:[iraf.vms.hlib.libc]iraf.h []/protection=w:r
+.DE
+.PP
+Add the following statement to the system \f(CWSYLOGIN.COM\fP file, making the
+appropriate substitution for \fIdisk\fP.
+.DS
+\f(CW$ iraf :== "@\fIdisk\f(CW:[iraf.vms.hlib]irafuser.com"\fP
+.DE
+.PP
+Add the following statement to the \f(CWSYSTARTUP.COM\fP file 
+(or \f(CWSYSTARTUP_V5.COM\fP), 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.
+.DS
+\f(CW$ @\fIdisk\fP:[iraf.vms.hlib]install.com\fP
+.DE
+.PP
+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 \f(CW[iraf.vms.hlib]install.lst\fR before
+executing \f(CWinstall.com\fR; see \(sc5.2.1.
+.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:
+.DS
+\f(CW$ set default irafhlib
+$ copy utime. utime.
+$ purge utime.
+.DE
+.PP
+At this point it should be possible for any user to run IRAF.  First you
+can verify this by using the IRAF account itself; then individual users
+should set up their own IRAF startup directory by running \f(CWmkiraf\fR.
+The default \f(CWLOGIN.COM\fR in the IRAF
+login directory \f(CW[IRAF.LOCAL]\fR will automatically execute
+the \f(CWiraf\fR
+command to read the \f(CWIRAFUSER.COM\fR file and define the IRAF logicals.
+Type \f(CWmkiraf\fR to initialize the IRAF \f(CWuparm\fR directory and create
+a new \f(CWLOGIN.CL\fR (answer yes to the \f(CWpurge\fR query, as it is
+advisable to delete the contents of the old \f(CWuparm\fR).
+Typing \f(CWcl\fR next should cause the CL to run.  If the CL runs successfully,
+the screen should be cleared (if the terminal is set correctly) and the
+message of the day printed.  You can then type \f(CWlogout\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 \f(CW[IRAF.LOCAL]\fR directory before logging in.
+A little command \f(CWh\fR (for `home') is defined in the default IRAF
+\f(CWLOGIN.COM\fR file for this purpose.
+
+.NH 2
+Edit the System Dependent Device 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 3
+[IRAF.VMS.HLIB]ZZSETENV.DEF
+.PP
+This file contains the name of the default editor, the default names of all
+the standard devices, and a number of other definitions which are not site
+dependent and which can therefore be ignored.  To be accessible by the IRAF
+system, each local device named must also have an entry in the \f(CWTERMCAP\fP
+file (terminals and printers) or \f(CWGRAPHCAP\fP file (graphics terminals,
+image displays, and plotters) in \f(CW[IRAF.DEV]\fP.
+There must also be an "\fIeditor\f(CW.ED\fR"
+file in \f(CW[IRAF.DEV]\fR for the named editor; EDT, EMACS, and VI are currently
+supported (VI support is approximate).  Edit the quoted value in the
+following entries to change the defaults.  Sample values are shown.
+.DS
+\f(CWset editor	= "vi"
+set printer	= "imagen"
+set terminal	= "vt640"
+set stdgraph	= "vt640"
+set stdimage	= "iism70l"
+set stdplot	= "versatec"\fR
+.DE
+For example, you may wish to change the default editor to "\f(CWedt\fR",
+the default printer to "\f(CWvmsprint\fR",
+the default image display to "\f(CWiism75\fR",
+and the default terminal to "\f(CWvt100\fR".
+Note that only a limited number of image displays is currently supported.
+Most video terminals, graphics terminals, and plotters are already supported
+by the current system.  If you have no device in a given class, you may
+wish to set the default to a nonexistent name, to generate a meaningful
+error message if someone should try to access it (e.g. \f(CWset stdimage =
+"nosuchdev"\fR).
+.NH 3
+[IRAF.DEV]DEVICES
+.PP
+This file contains a list of the allocatable devices (primarily tape drives)
+for the local system.  It should be obvious how to change it by reading the
+comments in the file and studying the current values, which are for our system.
+By convention drives are assigned the logical names \f(CWmta\fP, \f(CWmtb\fP,
+and so on.  The "\f(CWmt\fP" part is \fIrequired\fP for a magtape device.
+Note that in a VMS cluster where all nodes access the same version
+of IRAF, the tape drives for all systems must be defined in this one file,
+even though an individual drive may not be accessible on all nodes.
+.NH 3
+[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
+"\f(CWvmsprint\fP" entry provided should work on any VMS system.
+To prepare entries for other devices, simply copy the "\f(CWvmsprint\fP"
+entry and change the queue name from \f(CWSYS$PRINT\fR 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 via DECNET, 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.  See Appendix C or 
+contact us for assistance
+to help configure your system for IRAF networking.
+.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 it).
+A copy of the UNIX manual page documenting the termcap database is included
+with the installation kit
+in case you need to construct a new termcap entry for some device.  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 3
+[IRAF.DEV]GRAPHCAP
+.PP
+There must be entries in this file for all graphics terminals, batch plotters,
+and image displays accessed by IRAF programs.  Many graphics terminals are
+already supported; page the file to determine if entries are already available
+for the graphics terminals in use at your site, before attempting to write a
+new one.  The IRAF file \f(CWsys$gio/doc/gio.hlp\fR contains a description of
+the graphcap database and instructions for adding an entry for a new device.
+A printed copy of this document is available upon request, however once IRAF
+is up you may find it easier to generate your own copy using \f(CWhelp\fP
+(the document is some 60 pages long), as follows:
+.DS
+\f(CWcl> cd sys$gio/doc
+cl> help gio.hlp fi+ | lprint\fP
+.DE
+The manual page for the \f(CWshowcap\fP and \f(CWstty\fP tasks should also be
+printed since these
+utilities are useful for generating new graphcap entries.
+More focused documentation will be available eventually.
+Telephone consultation via the IRAF Hotline is available for those
+who need it.  We ask that new graphcap entries be sent back to us so
+that we may include them in the master graphcap file for other sites
+to use.
+
+.NH 3
+IRAF Networking
+.PP
+The \f(CWdev\fP directory also contains the files (\f(CWHOSTS\fP, \f(CWHOSTLOGIN\fP,
+and \f(CWUHOSTS\fP), which are used by the IRAF networking software.
+Sites which have a local TCP/IP based network can enable IRAF networking
+by editing these files, substituting the hostnames and network
+addresses of the machines in the local network for the entries currently
+in the files, and by installing IRAF on the other nodes (or enough of IRAF
+to run the IRAF kernel server).  It does not matter what native operating
+system runs on the remote nodes, so long as it runs IRAF as well.
+.PP
+We also provide limited support for DECNET based networking, but the current
+system as distributed must be relinked before DECNET networking can be used.
+Appendix C is included with notes on steps to be taken to implement DECNET
+networking, which should work in most cases.  Be warned that only TCP/IP or
+DECNET style networking can be implemented, but not both.
+As this capability is still under development, please contact the Hotline for
+advice if you wish to use the IRAF DECNET interface.
+
+.NH
+Updating an Existing IRAF Installation
+.PP
+Skip to \(sc4 if you have just completed the initial IRAF installation.
+This section is for sites upgrading to a new version of IRAF.
+.PP
+Updating is very similar to the initial installation (\(sc2).
+The main difference is that material which has been added to the site
+dependent files since the initial installation should be saved and then
+merged back into the generic system from the distribution tape.
+The typical update process is summarized in the following steps and detailed
+further below:
+.RS
+.IP \(bu
+Save any site-specific files.
+.IP \(bu
+Delete the old system.
+.IP \(bu
+Restore the new system to disk from the distribution tape or network archive.
+.IP \(bu
+Merge contents of saved site-specific files into new system.
+.IP \(bu
+Relink the system if necessary.
+.IP \(bu
+Update any "installed" images, the \f(CW<iraf.h>\fP file, etc.
+.RE
+.PP
+Variations on this basic procedure are possible and may be preferred at
+some sites.  For example, sites which make heavy use of IRAF and which have
+sufficient disk space may wish to install the new version of the system as
+a separate version on disk, e.g., calling the new version of the system
+the new `IRAF' and keeping the old version around as `IRAFO'.  At NOAO we
+maintain three separate versions of the system, IRAF (the current default user
+system), IRAFO (the old system, for backup), and IRAFX (the developmental
+system).  Sites which wish to maintain multiple versions of the system
+should beware that only one version of the system can use the shared library,
+due to global section name conflicts.  For efficiency reasons the default
+user version of the system `IRAF' should use the shared library.
+The remaining versions of the system must be relinked (\(sc5.1.9) to keep
+them from erroneously trying to use the shared library from a different
+release of IRAF.
+
+.NH 2
+Save Locally Modified Files \(dg
+.FS
+\(dgNOTE:  Even if you had not modified the pre-2.8 \f(CW[iraf.local]\fR
+directory, you may want to save it.
+If you are installing IRAF 2.8 for the first time, with an earlier
+version of the system already present, it may be \fIvery\fP important that you
+preserve the \f(CW[iraf.local]\fP directory, as a number of things have changed,
+and certain \f(CWlocal\fP tasks that were present in earlier releases are no
+longer supported in the standard system (e.g. \f(CWdsttoi, itodst, peritek,
+grinnell\fP tasks).  This is not necessary if you do not plan to use these
+unsupported tasks from the pre-2.8 \f(CWlocal\fP directory.
+.FE
+
+.PP
+Login as IRAF.
+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:
+.DS
+\f(CW$ set default [iraf]
+$ rename dev.dir,local.dir,[.vms]hlib.dir [\fIdirectory\fP]\fP
+.DE
+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 \f(CW[IRAF]\fP.  Many variations on this are possible.
+The destination directory should be somewhere \fIoutside\fP the \f(CW[IRAF...]\fP
+directory tree, else it may get deleted when we delete the old system, below.
+
+.NH 2
+Read the Distribution Tape or Tapes
+.PP
+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 (e.g. if something were to have
+happened to the distribution tape en route).  Using only the standard
+VMS utilities, the old system may be deleted as follows (assuming IRAF
+owns all the files in \f(CW[IRAF...]\fP).
+.DS
+\f(CW$ set default [iraf]
+$ delete [...]*.*;* /nolog/noconfirm
+$ set protection=(owner:wd) [...]*.*;*
+$ delete [...]*.*;* /nolog/noconfirm
+    \fP(repeat \f(CWdelete\fR command with <ctrl/b> until done)
+.DE
+.LP
+It is normal for the \f(CWdelete\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.
+.LP
+Now read the new distribution tape(s); it is important that this be done
+from the IRAF account, so the ownership and protections will be correct.
+.DS
+\f(CW$ mount/foreign \fItape\f(CW:
+$ set default \fIdisk\f(CW:[iraf]
+$ backup/rew \fItape\f(CW:iraf.bck/select=[iraf...] [...]\fP
+.DE
+.LP
+Instead of explicitly deleting the old system it is possible to read the
+distribution tape with \f(CWBACKUP/REPLACE\fP, but this really isn't any
+faster since a delete of each existing file is implied, and for
+those files or directories that have been renamed in the new release, junk
+files or directories will be left behind.
+
+.NH 2
+Merge Saved Files Back Into the New System
+.PP
+You can either merge the contents of locally modified files saved from
+the previous installation into their counterparts in the new system, or edit
+the new ones from scratch.  Whichever is easier depends on how much editing
+you had to do in the first place, which probably depends upon the complexity
+of your local computer network and the number of peripheral devices.
+Any of the site configuration files might be modified in the distributed
+system from version to version of IRAF, so in general one cannot simply
+replace such a file with the one that was saved.
+.PP
+Merging means inspecting the two files (newly distributed vs. its
+saved counterpart) for differences, and deciding how to update the new
+file with local device names, directory pathnames, etc.
+The VMS \f(CWDIFFERENCES\fP utility may or may not be useful for this,
+depending on how much a file has changed, and how extensively it
+was modified locally.  One thing that is a big help is to keep track of
+all local changes made to the standard system in a local "notes" file;
+when the next system update occurs or when the installation is repeated on
+another cpu at the local site, one can then go down the list and make all
+the same changes to the newly installed system.  By convention, that file
+would be called \f(CWnotes.\fImysite\fR, in the \f(CW[iraf.local]\fR directory.
+.KS
+.TS
+center;
+ci ci
+l l.
+directory	files
+.sp
+\f(CWdev	devices, graphcap, termcap, devices.hlp \fRif present
+\f(CWhlib	irafuser.com, install.lst\fR\(dg\f(CW, zzsetenv.def, login.cl
+\f(CWhlib/libc	iraf.h (\(-> sys$library:iraf.h
+\f(CWlocal	\fR(see Appendix B)
+.TE
+.KE
+.FS
+\(dgSee \(sc5.2.1; if you are just now upgrading to IRAF 2.8, your old file
+will still be \f(CWinstall.com\fR, but you will want to edit only the new
+\f(CWinstall.lst\fR.
+.FE
+.PP
+The files which must be edited, via a diff/merge operation on the saved
+files or otherwise, are summarized in the table above.
+If you have added packages or tasks of your own to IRAF in versions prior
+to V2.8, you will probably no longer want to install them under the
+\f(CW[iraf]\fP directory tree, as facilities are now available for external
+layered packages; see \(sc5.1.4.  This may be deferred until the system is
+up and running if desired.  The \f(CW[iraf.local]\fR directory is covered in
+Appendix B and in \(sc5.1.5.
+
+.NH 2
+Relink If Necessary
+.PP
+If you received a fully binary distribution of VMS/IRAF and you are not
+running an old version of VMS, you do not need to relink and may proceed
+to the next section.  See \(sc5.1.9 for further information on relinking the
+system.
+
+.NH 2
+Update VMS
+.PP
+These next operations require system privileges, so login as SYSTEM.
+Perform the following series of operations:
+.RS
+.IP \(bu
+The \f(CW<iraf.h>\fP file (\f(CW[iraf.vms.hlib.libc]iraf.h\fP) may have
+changed in the new version of the system,
+so it should be recopied into the VMS system library \f(CWsys$library\fP
+after editing HOST, IRAF, and TMP for local pathnames as described in \(sc2.3.3.
+.IP \(bu
+The \f(CWinstall.com\fP procedure was changed at version 2.8 to allow for simple
+updating of the installed files.  If you are already running IRAF 2.8 or later,
+and are now installing an even newer version,
+simply replace your old version of \f(CWinstall.lst\fP and re-run
+\f(CWinstall.com\fP.  [Otherwise, if you have been running a version of IRAF prior
+to 2.8, then you should not
+replace your old version of \f(CWinstall.com\fP, but instead compare the
+set of executables you had installed in it to those in the new
+file \f(CWinstall.lst\fP.
+This latter file contains a list of all of the IRAF executables.
+Files which are \fInot\fP to be installed should be commented out,
+using a "!" at
+the beginning of the line.  This list of installed files should agree with
+those from your old \f(CWinstall.com\fP.]  Make sure that nobody on the system is
+running IRAF, and thereby locking the old IRAF executables, and then execute
+the new \f(CWINSTALL\fP procedure.  This will clear away
+the old installed executables
+and install the new ones, paying as much attention as possible to clearing
+the global page structures.
+.RE
+.PP
+In a VMS cluster, the shared images must be deinstalled and
+reinstalled on all nodes in the cluster which share the same version of IRAF.
+These steps are as discussed in \(sc5.2.1; please refer to that
+section for additional information.
+.PP
+Lastly, logged 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:
+.DS
+\f(CW$ set default irafhlib
+$ copy utime. utime.
+$ purge utime.
+.DE
+
+.NH
+Testing a Newly Installed or Updated System
+.PP
+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.  Before starting the CL you should
+do what a regular user would do, i.e., run \f(CWmkiraf\fP to initialize
+the IRAF environment, and then edit the \f(CWlogin.cl\fP file created by
+\f(CWmkiraf\fP as desired.  Any modifications you wish to preserve across
+another \f(CWmkiraf\fP should be placed into the
+optional \f(CWloginuser.cl\fP file
+to avoid having to edit the \f(CWlogin.cl\fP file.  (The \f(CWloginuser.cl\fR
+file can have the same kinds of commands in it as the
+template login.cl, but \fImust\fR have the statement \f(CWkeep\fR as the last
+line.)
+.DS
+\f(CW$ set default [iraf.local]
+$ mkiraf\fP
+.DE
+.LP
+Once the IRAF environment is configured one need only enter the command
+`\f(CWcl\fP' to start up the CL.  After a bit IRAF should print the message of
+the day and type out the root IRAF menu, then issue the "\f(CWcl> \fP" prompt
+indicating that it is ready for the first command.
+This assumes that the `\f(CWiraf\fP' command is executed in the \f(CWLOGIN.COM\fP
+file at login time; if this is not the case, the command `\f(CWiraf\fP' must
+first be entered from VMS
+to define \f(CWcl\fP and the other VMS logical names and symbols used by IRAF.
+.sp
+[Important Note:  any users wishing to execute IRAF tasks in VMS batch
+queues \fImust\fP issue the `\f(CWiraf\fP' command inside their
+\f(CWlogin.com\fP, prior to any "\f(CWif f$mode().nes."INTERACTIVE" then
+exit\fR" command, otherwise critical IRAF logical names will be undefined.]
+.DS
+\f(CW$ cl\fP
+.DE
+.LP
+Once in the CL, you will probably have magtape and printer access, are likely
+to have graphics terminal access, and very possibly will not have either
+image display access or 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.  You may also wish to run some of the benchmarks
+described in the benchmarks paper included with the installation materials,
+to make sure that your VMS system (user quotas and working set) is configured
+properly for efficient execution of IRAF.
+
+.NH
+System Maintenance
+.NH 2
+Software Management
+.NH 3
+Layered software support
+.PP
+An IRAF installation consists of the \fBcore system\fP and any number of
+\fBexternal packages\fP, or \fBlayered software products\fP.  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"
+(usually this 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 rooted in the \f(CWiraf\fP 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 3
+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 \f(CWmkhelpdb\fP 20
+Updates the HELP database of the core IRAF system or an external package
+installed in \f(CWhlib$extern.pkg\fR.
+The core system, and each external package, has its own help database.
+The help database is the machine independent file \f(CWhelpdb.mip\fP in the
+package library (LIB directory).  The help database file is generated with
+\f(CWmkhelpdb\fP by compiling the \f(CWroot.hd\fP file in the same directory.
+.IP \f(CWmkpkg\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., "\f(CWmkpkg -p noao\fP", and the command
+issued within the package directory, not from the IRAF root.
+.IP \f(CWrmbin\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
+\f(CWmkpkg\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 \f(CWrtar,wtar\fP 20
+These are the portable IRAF tarfile writer (\f(CWwtar\fP) and reader
+(\f(CWrtar\fP) programs.  These tasks produce archives compatible with
+the UNIX \f(CWtar\fP program.  In addition they
+can move only the machine independent or source files
+(\f(CWwtar\fP, like \f(CWrmbin\fP, can discriminate between machine
+generated and machine independent files).  A tarfile written on a VMS/IRAF
+system has the files blank padded, but \f(CWrtar\fP when used on a UNIX
+system will strip the trailing blanks by default.
+.IP \f(CWxc\fP 20
+The X (SPP) compiler.  This is analogous to the VMS \f(CWFORTRAN\fP except
+that it can compile "\f(CW.x\fR" 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
+\f(CWmktags\fP for making a tags file for the \f(CWvi\fP editor, a HELP
+database examine tool, and other tasks.  Further information on these
+tasks is available in the online HELP pages.
+
+.NH 3
+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 \f(CWmkpkg\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
+.PP
+The \f(CWmkpkg\fP file for a package can be written to do anything,
+but by convention the following commands are usually provided.
+.sp
+.RS 
+.IP "\f(CWmkpkg\fP" 20
+Same as \f(CWmkpkg relink\fP below.
+.IP "\f(CWmkpkg 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 \f(CWlibpkg.a\fP to
+symbolize that they are private to the package.
+.IP "\f(CWmkpkg relink\fP" 20
+Rebuilds the package executable, i.e., updates the package library and
+relinks the package executable.  By convention, this is the file
+\f(CWxx_foo.e\fP in the package directory, where \fIfoo\fP is the
+package name.
+.IP "\f(CWmkpkg install\fP" 20
+Installs the package executable, i.e., renames the \f(CWxx_foo.e\fP
+file to \f(CWx_foo.e\fP in the global BIN directory for the system
+to which the package \fIfoo\fP belongs.
+.IP "\f(CWmkpkg 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 \f(CWdparam\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 \f(CWPKGENV\fP logical name, \fImust\fP be used
+to indicate the system or layered product being updated.  For example,
+"\f(CWmkpkg -p noao update\fP" 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 \f(CWflprcache\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
+.DS
+\f(CWcl> mkpkg update\fP
+.DE
+plus maybe a \f(CWflpr\fP if the old executable is still sitting idle
+in the process cache.
+
+.NH 3
+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 \f(CWhlib$extern.pkg\fP to "install" the new
+package in IRAF.  Note that any \f(CW$\fR in a VMS pathname should be 
+escaped with a backslash as in some of 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 \f(CWmkpkg\fP.
+.RE
+.LP
+As always, there are some little things to watch out for.
+When using \f(CWmkpkg\fP on a layered product, you must give the name
+of the system being operated upon, e.g.,
+.DS
+\f(CWcl> mkpkg -p foo update\fP
+.DE
+where \fIfoo\fP is the system or package name, e.g., "noao", "local", etc.
+The \fB-p\fP flag can be omitted by defining \f(CWPKGENV\fP as a VMS logical
+name, but this only works for updates to a single package.
+.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 of \f(CWhlib$extern.pkg\fP.  With the BINs already
+configured reinstallation is a simple matter of restoring the files to disk
+and editing the \f(CWextern.pkg\fP file.
+
+.NH 3
+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 \f(CWlogin.cl\fP 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 \(sc5.1.4 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 \f(CWhlib$extern.pkg\fR to make the location of the new
+package known.
+If you make a source only \f(CWwtar\fR or \f(CWBACKUP\fR  archive
+of \f(CWiraf$local\fR and install
+it as outlined in \(sc5.1.3, 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 3
+Bootstrapping the HSI
+.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 \f(CWlibos\fR), there
+should be no reason for a user site ever to need to bootstrap the system.
+The bootstrap utilities are linked with the option \f(CW/NOSYSSHARE\fR, 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 \f(CWmkpkg update\fR in the program
+source directory).
+.DS
+\f(CW$ set default [iraf.vms]
+$ set verify
+$ @rmbin.com
+$ @mkpkg.com\fR
+.DE
+.PP
+The bootstrap should take 30 to 45 minutes on an unloaded 11/780.
+Once the bootstrap utilities have been relinked and installed in \f(CWhlib\fR,
+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, as when using the
+\f(CWmkttydata\fR utility program to cache new termcap or graphcap device
+entries, or switching from TCP/IP to DECNET networking.
+.PP
+The system libraries may be updated either from within the IRAF CL, or from
+DCL.  For example, from within DCL:
+.DS
+\f(CW$ set def [iraf]
+$ mkpkg syslibs \fR[\fPmathlibs\fR]\fR
+.DE
+The brackets around \f(CWmathlibs\fR just mean "optional"; do not actually
+include the brackets if you need to rebuild the math libraries.
+This command will run the \f(CWmkpkg\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 \f(CWmathlibs\fR argument may be
+omitted to save some time.
+
+.NH 3
+Relinking the IRAF Shared Library
+.PP
+The IRAF shared library (\f(CW[IRAF.BIN]S_IRAF.EXE\fR) is constructed by
+linking the contents of the four main IRAF system libraries \f(CWLIBEX\fR,
+\f(CWLIBSYS\fR, \f(CWLIBVOPS\fR, and \f(CWLIBOS\fR.  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 (V2.8) 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 \f(CWCL.EXE\fR, \f(CWX_SYSTEM.EXE\fR, and
+\f(CWX_LISTS.EXE\fR.  If these executables do not yet exist or are 
+not runnable,
+rebuild them as follows.  Note the use of the \f(CW-z\fR link flag to link
+the new executables without the shared library.
+.DS
+\f(CW$ 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
+.DE
+.LP
+Now login to the CL and proceed to the directory \f(CWhlib$share\fR, which
+contains the code used to build the shared library.
+.DS
+\f(CW$ set default [iraf.local]
+$ cl
+    \fR(cl starts up...)\fP
+cl> cd hlib$share\fR
+.LP
+.DE
+The following commands will rebuild the shared library and install it in
+\f(CWbin\fR.  This takes ten minutes or so.
+.DS
+\f(CWcl> cl < makeshare.cl
+    \fR(takes a while)\fP
+cl> mkpkg install
+cl> purge
+cl> logout\fR
+.DE
+.PP
+The system libraries can be updated (\(sc5.1.7) 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 \f(CWS_IRAF.EXE\fR to
+\f(CWbin\fR) 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.
+
+.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 (\(sc5.2.1) following the relink.
+.DS
+\f(CW$ set default [iraf]
+$ mkpkg update\fR
+.DE
+.PP
+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 \f(CWmkpkg\fR include file \f(CWmkpkg.inc\fR
+in \f(CWhlib\fR.  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:
+.DS
+\f(CW$set    LFLAGS  = ""            # default XC link flags\fR
+.DE
+This switch defines the switches to be passed to the HSI bootstrap utility
+program \f(CWxc\fR to link the IRAF executables (no switches are given, hence
+the default link action will be taken).
+The switch \f(CW-z\fR may be included in the \f(CWxc\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 \f(CWLFLAGS\fR as follows:
+.DS
+\f(CW$set    LFLAGS  = "-z"          # default XC link flags\fR
+.DE
+.PP
+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:
+.DS
+\f(CW$ set default [iraf.noao]
+$ mkpkg -p noao\fP
+.DE
+Layered systems are
+completely independent of one another and hence must be updated separately.
+
+.NH 2
+Tuning Considerations
+.PP
+There are a number of things that can be done to tune VMS/IRAF for a
+particular host system:
+.sp
+.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 \f(CWTERMCAP\fP and \f(CWGRAPHCAP\fP entries.
+.IP \(bu
+Strip the system to reduce disk consumption.
+.RE
+
+.NH 3
+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
+\f(CWs_iraf.exe\fP should always be installed if IRAF is used at all, and
+\f(CWcl.exe\fP and \f(CWx_system.exe\fP 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 \f(CWx_images.exe\fP and
+\f(CWx_plot.exe\fP are probably worth installing as well.
+.PP
+Installation of task images in system shared memory is done with the VMS
+\f(CWINSTALL\fP 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 \f(CWINSTALL.COM\fP command procedure in \f(CWhlib\fP.
+In IRAF 2.8 or later, the list of files to be installed is in
+\f(CWinstall.lst\fP.
+This file should be reviewed and edited during system installation to
+select those images to be installed on the local host.
+Then \f(CWINSTALL.COM\fP 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 \f(CWINSTALL.COM\fP script (or explicitly install the images by
+name) whenever the system is booted.  Note that any currently installed
+images must be explicitly deinstalled before a new version can be installed
+(handled automatically in 2.8 by \f(CWinstall.com, install.lst\fP),
+and 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.8 is about 1062).
+If the system has insufficient free global pages to run the \f(CWINSTALL.COM\fP
+script one must either increase the number of system global pages (which
+requires rebooting the system), or one must edit the \f(CWINSTALL.COM\fP
+script to reduce the number of images to be installed.
+
+.NH 3
+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
+\f(CWCOPY/CONTIGUOUS\fP 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 3
+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 noticeable
+delay of as much as a second when clearing the terminal screen or plotting
+a graph, hence it is usually worthwhile to cache the entries for commonly
+used video and graphics terminals.  It is generally not worthwhile for
+printers, plotters, and image displays.
+.PP
+The system comes with selected termcap and graphcap entries already
+precompiled.  To see which devices are precompiled, page the cache data files,
+\f(CWdev$cachet.dat\fP (for termcap) and \f(CWdev$cacheg.dat\fP (for graphcap).
+To cache a different set of entries one must regenerate these files with the
+\f(CWmkttydata\fP task in the SOFTOOLS package, and then do a full sysgen relink
+with the \f(CWmkpkg\fP utility.  Detailed instructions are given in the manual
+page for \f(CWmkttydata\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 (\(sc5.1.7) and
+rebuild the shared library (\(sc5.1.8) before relinking the system \(sc5.1.9),
+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 \f(CWmkttydata\fP documentation.
+.FE
+
+.NH 3
+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 \f(CWrmfiles\fP (in the SOFTOOLS package) is provided for this
+purpose.  It is not however necessary to run \f(CWrmfiles\fP directly to strip
+the system.  This may be done either from DCL or from within the CL.
+.DS
+\f(CW$ set default [iraf]
+$ mkpkg strip
+$ set default [iraf.noao]
+$ mkpkg strip\fR
+.DE
+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, caching termcap and graphcap entries, or
+switching to DECNET networking.
+The size of the system (the
+figures are for V2.8) is reduced from about 48 Mb (megabytes) to around
+25 Mb.\(dg
+.FS
+\(dg\fRDue to a bug in the stripping files in VMS/IRAF 2.8 not caught
+before the distribution tapes were cut, a \f(CWstrip\fR will not
+delete quite as many files as it should (a few Mb).
+Contact the hotline for help in further stripping the system if this is
+necessary.
+.FE
+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 "\f(CWstripall\fR"
+option.
+
+.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.
+.KS
+.TS
+center;
+ci ci ci
+l n n.
+quota	minimum	recommended
+.sp
+\f(CWBYTLM\fP	20480	30720
+\f(CWPGFLQUOTA\fP	15000	30720
+\f(CWPRCLM\fP	5	10
+\f(CWWSDEFAULT\fP	512	512
+\f(CWWSEXTENT\fP	4096	WSMAX
+\f(CWJTQUOTA\fP	2048	2048
+\f(CWFILLM\fP	30	60
+.TE
+.KE
+.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 \f(CWPRCLM\fP quota is especially significant for IRAF since an IRAF job
+typically executes as several concurrent processes.  The \f(CWPRCLM\fP 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 (\f(CWx_system.e\fP).  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
+\f(CWx_system.e\fP, 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 \f(CWPRCLM\fP of
+5, but occasional process spawn failures can be expected.  Process spawn
+failures are possible even with a \f(CWPRCLM\fP 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 \f(CWPRCLM\fP of 5-6, but in practice users seem to prefer
+to not use the 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 \f(CWWSEXTENT\fP 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).
+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 \f(CWdir/size=all\fP on
+\f(CW[iraf.bin]*.exe\fP 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.8, we have CL=324,
+S_IRAF=1062, X_SYSTEM=103, X_PLOT=118, and X_IMAGES=789.
+The system parameters on our 8600 (which is probably a
+worst case example) are currently set to \f(CWGBLPAGES\fP = 12120
+and \f(CWGBLSECTIONS\fP = 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
+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 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.
+
+.NH
+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 2
+Graphics terminals
+.PP
+The IRAF system as distributed is capable of talking to just about any
+conventional graphics terminal or terminal emulator, using the \f(CWstdgraph\fP
+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 \f(CWdev$graphcap\fP 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 \f(CWshowcap\fP and \f(CWstty\fP tasks (see \(sc2.6.4).  Assistance with
+interfacing new graphics terminals is available via the IRAF Hotline.
+.NH 2
+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 \f(CWsgikern\fP and \f(CWstdplot\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
+included with the IRAF installation kit.
+.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 \f(CW$iraf/vms/gdev/sgidev\fP.
+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 \f(CWNCAR\fP 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 \f(CWcalcomp\fP 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 \f(CWhlib\fP 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 2
+Image display devices
+.PP
+The current IRAF system does not yet have a well defined and well isolated
+device independent image display interface.  Work on such an interface is
+currently underway; contact the IRAF group at NOAO for further information
+on the status of the new display interfaces.  Further information on the
+image display interfaces currently available may be found in the
+\fIIRAF Newsletter\fP.
+.PP
+Those VMS/IRAF sites that have VAX/VMS workstations running the VWS display
+system (e.g. VAXstation) may run the \f(CWNEWUISDISP.EXE\fP
+display task directly in \f(CW[IRAF.VMS.UIS]\fP.
+This is a standalone IMFORT program,
+i.e. it does not communicate with the tasks in the \f(CWtv$display\fP package.
+See the file \f(CWnewuisdisp.txt\fP in the same directory for help.
+.PP
+Sun workstations running \f(CWIMTOOL\fP and \f(CWGTERM\fP may be used as front
+ends to VAXes that use the default TCP/IP networking.  See the \f(CWimtool(1)\fP
+manual pages on the Sun.
+.PP
+Likewise, workstations running the MIT X window system may also be used as
+front ends, using the \fIximage\fP display server \(dg.
+.FS
+\(dgAt press time for IRAF 2.8, \f(CWximage\fR was only available for X10,
+with an X11 version under development.
+.FE
+This was developed
+for IRAF by CfA (SIAO), but is distributed by the IRAF project; a distribution
+kit is available upon request.  We are looking forward to the release of
+X11/NeWS by Sun sometime during 1989, and will provide X11 based versions
+of gterm and imtool for Sun/IRAF once a vendor supported version of X11 is
+available for the Sun (the X11 versions of imtool and gterm should run on
+any manufacturer's X11 based workstation).  Contact the hotline for advice.
+.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 \f(CWvms/gdev\fP).  This is how all the current displays, e.g., imtool
+and ximage, 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
+\f(CWtv$display\fR package code be used as a template.
+Rather, a standalone image display server should be constructed using the
+datastream protocol in the \f(CWvms/gdev/zfiogd.x\fR driver mentioned above
+(but that could be a very lengthy job; contact the hotline).
+.PP
+A few sites may have the Gould IP8400 or IP8500 displays; code for the
+Gould is not automatically supplied with VMS/IRAF, and must be requested
+separately.  The interface is not very satisfactory, but can be used in
+a pinch.
+(If you are installing IRAF 2.8, the Gould interface has not changed since
+version 2.5, so if you have an old version, you will not need to request a
+new one.)
+
+.NH
+The IRAF Directory Structure
+.PP
+A graph of the current full VMS/IRAF directory structure is given at the
+end of this document.  The main branches of the tree are summarized below.
+Beneath the directories shown are some 300 subdirectories, the largest
+directory trees being \f(CWsys\fP, \f(CWpkg\fP, and \f(CWnoao\fP.
+The entire contents of all directories other than \f(CWvms\fP, \f(CWlocal\fP,
+and \f(CWdev\fP are fully portable, and are identical in all installations
+of IRAF sharing the same version number.
+.DS
+\f(CWbin        \fP- the IRAF BIN directories
+\f(CWdev        \fP- device tables (\f(CWtermcap\fP, \f(CWgraphcap\fP, etc.)
+\f(CWdoc        \fP- assorted IRAF manuals
+\f(CWlib        \fP- the system library; global files
+\f(CWlocal      \fP- iraf login directory; locally added software
+\f(CWmath       \fP- sources for the mathematical libraries
+\f(CWnoao       \fP- packages for NOAO data reduction
+\f(CWpkg        \fP- the IRAF applications packages
+\f(CWsys        \fP- the virtual operating system (VOS)
+\f(CWvms        \fP- the VMS host system interface (HSI = kernel + bootstrap utilities)
+.DE
+.LP
+The contents of the \f(CWvms\fP directory (host system interface) are
+as follows:
+.DS
+\f(CWas         \fP- assembler sources for VMS/IRAF
+\f(CWboot       \fP- bootstrap utilities (mkpkg, rtar, wtar, etc.)
+\f(CWgdev       \fP- graphics device interfaces (SGI device translators)
+\f(CWhlib       \fP- host dependent runtime files
+\f(CWmkpkg.com  \fP- executed to bootstrap the VMS/IRAF HSI
+\f(CWos         \fP- OS interface routines (VMS/IRAF kernel)
+\f(CWrmbin.com  \fP- executed to delete binary files in subdirectories
+\f(CWuis        \fP- UIS display program for VAX workstations
+.DE
+.PP
+If you will be working with the system much at the system level, it will be
+well worthwhile to spend some time exploring these directories and gaining
+familiarity with the system.
+
+.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 \f(CWSYS$LOGIN\fP
+directory.  One way to do this is define \f(CWimdir\fP to be the same as
+\f(CWtmp\fP, and modify the definition of \f(CWIRAFTMP\fP in the
+\f(CWIRAFUSER.COM\fP file as shown below.
+.nf
+.sp
+\f(CW\s-1
+$! ----------- 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 \f(CWirafhlib:login.cl\fR, replace \f(CWU_IMDIR\fR with \f(CWtmp$\fP
+.fi
+.sp
+In \f(CWirafhlib:mkiraf.com\fR, replace the block of statements beginning
+"\f(CWimdir_file :=\fR" with the following:
+.sp
+.nf
+\f(CW$  if (f$search ("sys$login:iraftmp.dir") .eqs. "") then -
+	create/directory vmstmp\fR
+.fi
+
+.bp
+.DS C
+\fBAppendix B.  Upgrading a Pre-IRAF 2.8 \f(CW[iraf.local]\fP Directory\fR
+.DE
+.PP
+If you are installing IRAF 2.8 for the first time on a system which had
+an earlier version of IRAF, \fIand\fP you either had your own tasks in 
+\f(CW[iraf.local]\fP or you want to use the unsupported tasks formerly
+distributed in \f(CWlocal\fP (\f(CWdsttoi, itodst, peritek, grinnell\fP), you
+will need to change a few things.  If you did not make local additions or
+use those unsupported tasks, or if you are installing a later version of IRAF
+than 2.8, you may skip the rest of this section.
+.PP
+Starting at IRAF 2.8, there is support
+for external layered packages, which will largely free you from having to merge
+local additions into future updates.  The new \f(CWlocal\fP directory is
+set up as a \fItemplate\fP external package, and it is best that it remain
+that way.  True local additions (plus the former, unsupported tasks mentioned
+above) are best placed in a directory of your choice outside the IRAF tree.
+The external layered package mechanism is discussed in \(sc5.1.4 and
+5.1.5, to which you should refer for background information now,
+prior to completing this section.  The instructions below are intended as
+a guide and may not be enough for all sites, depending on the complexity of
+the local additions.  The \f(CW[iraf.noao]\fR directory may be used as an
+additional guide.  This all sounds a bit complex, but it will be worth it
+because it only need be done once, and all you will need to do in future
+IRAF releases is edit \f(CWhlib$extern.pkg\fR to hook up your local package.
+.PP
+Briefly, you will need to create your own \f(CWlocal\fP directory, preferably
+outside the IRAF tree, e.g. \f(CW[kpnolocal]\fR, (\fIyourlocal\fR used for
+explanatory purposes below).
+Copy the \fInew template\fR \f(CW[iraf.local]\fP directory into it:
+.DS
+\f(CW$ set default [\fIyourlocal\f(CW]
+$ backup [iraf.local...] [...]
+$ delete login.*;*, bugs.*;*, notes.*;*, irafks.*;*
+$ delete $forward.;*, *readme.;*, telinit.;*, [.uparm]*.*;*
+$ set protection=(owner:wd) uparm.dir
+$ delete uparm.dir;*\fR
+.DE
+This is a summary of the steps needed to upgrade a pre-2.8 local directory
+to use the new layered package mechanism; an example follows:
+.RS
+.IP \(bu
+In what follows it is assumed you want your new package to be known only
+as \f(CWlocal\fR; the pathname for \f(CWlocal\fR defined
+in \f(CW[iraf.vms.hlib]extern.pkg\fR will take care of its location.
+.IP \(bu
+Copy the source, parameter, and  object files and libraries from your
+saved copy of the 
+old \f(CW[iraf.local]\fR directory tree (as saved in \(sc3.1)
+into \f(CW[\fIyourlocal\f(CW.src]\fR or subdirectories, and any executables
+into \f(CW[\fIyourlocal\f(CW.bin]\fR.  Help files (\f(CW.hlp\fR) should
+go into \f(CW[\fIyourlocal\f(CW.src.doc]\fR.
+.IP \(bu
+In \f(CW[\fIyourlocal\f(CW.src]\fR edit \f(CWx_local.x\fR to add your tasks,
+and edit the \f(CWmkpkg\fR file along the lines of the templates.
+.IP \(bu
+Edit the package \f(CWlocal.cl, .hd, \fR and \f(CW.men\fR files
+in \f(CW[\fIyourlocal\f(CW.src]\fR.
+.IP \(bu
+Edit \f(CW[iraf.vms.hlib]extern.pkg\fP to replace the \f(CWiraf$local/\fR
+pathname with your VMS specific one as in the commented-out example
+for \f(CWkpnolocal\fR,
+escaping any \f(CW$\fR in VMS pathnames with a backslash.
+.IP \(bu
+Execute \f(CWMKPKG\fR from \f(CW[\fIyourlocal\f(CW]\fR to build the
+package (\f(CW$ mkpkg -p local update\fR).
+.IP \(bu
+After logging into the CL, execute \f(CWMKHELPDB\fR to install your package and
+task help pages into IRAF from the package directory,
+giving \f(CWlib/root.hd\fR and \f(CWlib/helpdb.mip\fR as the task parameters.
+
+.RE
+When finished, the next time a user logs into the CL, the \f(CWlocal\fR
+package will
+appear listed in the main package menu, help will be available, and the tasks
+will be installed.
+.sp
+.LP
+\fBExample:\fR  Add a brand new task to the new \f(CWlocal\fR package.
+.PP
+Let's add a simple "hello world" task to a new copy of the template local
+package in the directory \f(CW[ourlocal]\fR on disk \f(CWscr$2\fR.
+Log into the IRAF account.
+.sp
+.nf
+\f(CW\s-1$ create/directory scr$2:[ourlocal]
+$ set default scr$2:[ourlocal]
+$ backup irafdisk:[iraf.local...] [...]
+$ delete login.*;*, bugs.*;*, notes.*;*, irafks.*;*
+$ delete $forward.;*, *readme.;*, telinit.;*, [.uparm]*.*;*
+$ set protection=(owner:wd) uparm.dir
+$ delete uparm.dir;*
+$ edit irafhlib:extern.pkg\s0\fR
+.fi
+.sp
+Change the pathname of the local directory:
+.DS
+\f(CW\s-1reset local = scr\e$2:[ourlocal]\s0
+.DE
+.nf
+\f(CW\s-1$ set default sys$login
+$ cl
+cl> cd local$src
+cl> ed x_local.x\s0
+.fi
+.DS
+\f(CW\s-1task	bswap		= t_bswap,
+	pavg		= t_pavg,
+	hello		= t_hello\s0
+.DE
+.sp
+\f(CW\s-1cl> ed hello.x\s0
+.DS
+\f(CW\s-1procedure t_hello
+.sp
+bool	verbose
+bool	clgetb()
+.sp
+begin
+	verbose = clgetb ("verbose")
+
+	if (verbose)
+	    call printf ("Hello world!  (the long version)\en")
+	else
+	    call printf ("Hello\en")
+end\s0
+.DE
+\f(CW\s-1cl> ed hello.par\s0
+.DS
+\f(CW\s-1verbose,b,h,no,,,"use the long form of hello?"\s0
+.DE
+\f(CW\s-1cl> ed local.cl\s0
+.DS
+\f(CW\s-1#{ Package script task for the LOCAL package.  Add task declarations here
+# for any locally added tasks or subpackages.
+.sp
+cl < "local$lib/zzsetenv.def"
+package local, bin=localbin$
+.sp
+task	bswap,
+	pavg,
+	hello = "local$src/x_local.e"
+.sp
+clbye()\s0
+.DE
+\f(CW\s-1cl> ed local.hd\s0
+.DS
+\f(CW\s-1# Help directory for the LOCAL package.
+.sp
+$defdir		= "local$src/"
+$doc		= "local$src/doc/"
+.sp
+bswap		hlp=doc$bswap.hlp,	src=bswap.x
+pavg		hlp=doc$pavg.hlp,	src=pavg.x
+hello		hlp=doc$hello.hlp,	src=hello.x\s0
+.DE
+\f(CW\s-1cl> ed local.men\s0
+.DS
+\f(CW\s-1
+bswap - Swap the bytes in a file
+ pavg - Plot the average of the lines of an image or image section
+hello - Hello world demo task\s0
+.DE
+.nf
+\f(CW\s-1cl> cd doc
+cl> ed hello.hlp\s0
+.fi
+.DS
+\f(CW\s-1
+ .help hello Jul89 local
+ .ih
+ NAME
+ hello - demo task
+ .ih
+ USAGE
+ hello verbose
+ .ih
+ PARAMETERS
+ .ls verbose
+ Use verbose=yes to test the parameter mechanism.
+ .le
+ .ih
+ DESCRIPTION
+ This is a demo task to assist in adding local additions to the template
+ local package.
+ .ih
+ EXAMPLE
+ 1. Use the long version
+.sp
+	cl> hello verbose+
+ .ih
+ BUGS
+.sp
+ .ih
+ SEE ALSO
+ .endhelp\s0
+.DE
+.nf
+\f(CW\s-1cl> cd local
+([ourlocal])\s0
+.sp
+\f(CW\s-1cl> softools
+so> mkpkg -p local update
+so> mkhelpdb lib/root.hd lib/helpdb.mip
+so> bye
+cl> local
+	bswap hello pavg
+.sp
+lo> hello
+.sp
+Hello
+.sp
+lo> hello verbose+
+.sp
+Hello world!  (the long version)
+.sp
+lo> help hello\s0\fR
+(etc.)
+.sp
+.fi
+
+.bp
+.LP
+.DS C
+\fBAppendix C.  Notes on Networking with DECNET in VMS/IRAF V2.8\fR
+.DE
+.LP
+IRAF networking is the preferred way to gain access to peripherals on a
+remote computer.  These peripherals might include printers, plotters, 
+disks, image display devices and possibly magnetic tape drives.  IRAF
+networking can be used to access peripherals on nodes in a local area
+network, where the networking protocol in use is internally supported by IRAF.
+We presently distribute IRAF configured for TCP/IP networking.  A DECNET
+networking interface is also available for VMS nodes and is the focus of
+this document.  The IRAF/DECNET network interface does not, at present,
+permit access to tape drives on a remote machine [contact the hotline for
+advice; there may be a workaround for this before long].
+If tape drive access
+is needed, it will be necessary to perform a normal IRAF installation on
+the remote node and use the tape reading facilities on that machine directly
+(once installed, the system may be stripped considerably).
+.LP
+If your system uses only DECNET, it may or may not be necessary to use IRAF
+networking, depending upon what peripherals it is desired to access on the
+remote node.  Installing IRAF networking with a minimal 'kernel server'
+implementation is easy to set up.  An alternative to this approach may
+be to supply DCL command procedures IRAF can use to send printer and plotter
+output to the remote node without using IRAF networking.  Contact us to find 
+out if this will work on your system.
+.LP
+The default network protocol on the distributed systems is TCP/IP, because
+that is what we use in the local NOAO network.  In its present form, the
+choice of network protocol is a compile-time option.  In IRAF V2.8 the
+appropriate object file is supplied automatically (unless you have a
+source-only distribution or have stripped all object files from the system), 
+but you still need to rebuild the shared library and perform a relink sysgen.
+.LP
+There are two ways to use internal IRAF networking:  between two fully
+installed IRAF systems, and between one fully-installed system and a
+`kernel server' system.  The steps below under `Configuring IRAF networking
+for DECNET' apply to a fully-installed system, and would have to be taken
+for at least one node in an IRAF network.  See the section below under
+"Server Nodes" if you are using the remote purely for access to peripheral
+devices, but not for running IRAF.  In node name references in these notes
+we will use the convention HOMENODE = fully-installed system, and SERVERNODE =
+the server-only node.
+.LP
+VMS/IRAF networking using DECNET continues to be supported in a limited way
+in IRAF V2.8.  These notes should be sufficient for you to successfully
+install IRAF/DECNET networking, but don't hesitate to call the HOTLINE if
+questions arise.  We have not tested these procedures in all possible
+environments, so they may be inaccurate or incomplete for some configurations.
+There are at least two special situations to be aware of:
+.IP [1]
+If you use "rooted logicals" for the IRAF root directory on any of
+your nodes, you will need to get some modified networking code from us.
+.IP [2]
+If your system management policies prohibit establishing a logical
+link connection with a remote task addressed as object type 0,
+you will not be able to use IRAF/DECNET networking without a possible
+workaround from the hotline.  The task
+specification string used in the networking code is of the form:
+.sp
+.DS
+	\f(CWNODE"USERNAME PASSWORD"::"TASK=IRAFKS"\fR
+.DE
+.sp
+.IP [3]
+An additional note for users rebuilding the VMS/IRAF shared library is
+that when you remake the shared library (\f(CWmakeshare.cl\fR) on a MicroVAX,
+warning messages may appear from the linker.  These are harmless,
+and are due to the fact that on a MicroVAX (as opposed to 
+other VAXes) the system services show up in a load map as virtual
+addresses (\f(CW7FFF****\fR).  You can modify \f(CWhlib$share/makeshare.cl\fR so
+it filters these addresses out of the load map generated when
+rebuilding the shared library.  The warnings are harmless, but
+can be avoided by editing \f(CWmakeshare.cl\fR so the section of the script
+that filters the addresses using the IRAF match task reads as follows:\f(CW
+.sp
+.nf
+\f(CW\s-1
+# Now do the UNIVERSAL symbols
+# Select out those psects with attributes like Fortran Common blocks
+.sp
+match (pattern = "-R", files = "common.map") | words | 
+        match (pattern = "^00", stop=yes) |
+        match (pattern = "^7FF", stop=yes) |
+        match (pattern = "^CC_", stop=yes) |
+        sort > symbol.tab\s0\fR
+.fi
+.sp
+.SH 
+I. Configuring IRAF networking for DECNET on a fully-installed system
+.LP
+This is a summary of the steps you will take:
+.sp
+.RS
+.IP \(bu
+build a decnet version of \f(CWzfioks.obj\fR and load it into a library
+.IP \(bu
+rebuild the shared library
+.IP \(bu
+relink all the IRAF executables
+.IP \(bu
+relink irafks.e without the shared library
+.IP \(bu
+edit \f(CWdev$hosts\fR
+.IP \(bu
+create \f(CW.irafhosts\fR files in IRAF home directories on home node
+.IP \(bu
+create \f(CWirafks.com\fR files in VMS login directories on server node
+.RE
+.sp
+.IP [1]
+Get into the directory \f(CWos$net\fR (\f(CW[iraf.vms.os.net]\fR).
+Check to see if there
+is a file \f(CWzfioks_obj.dna\fR.
+If there is not, go to step [2].  If there is, copy it:\f(CW
+.sp
+.DS
+\f(CW
+$ copy zfioks_obj.dna zfioks.obj\fR
+.DE
+.sp
+...and proceed to step [3].
+.sp
+.IP [2]
+(There was no \f(CWzfioks_obj.dna\fR file in \f(CW[iraf.vms.os.net]\fR,
+so we will attempt to create one.)
+.sp
+If you do not have a DEC C compiler, contact us to see about getting
+a copy of \f(CWzfioks.obj\fR built for DECNET; you will not be able to proceed
+further until you do.
+.sp
+.IP
+You do have a DEC C compiler, so edit \f(CWzfioks.c\fR and compile it:
+.sp
+.DS
+\f(CW$ edit zfioks.c\fR
+.sp
+change from:\f(CW
+.sp
+#define DECNET  0
+#define TCP     1\fR
+.sp
+to:\f(CW
+.sp
+#define DECNET  1
+#define TCP     0
+.sp
+$ cc/nolist zfioks.c\fR
+.DE
+.sp
+.IP [3]
+Load the zfioks object file into the IRAF kernel library:\f(CW
+.sp
+.DS
+\f(CW
+$ lib/replace [iraf.vms.hlib]libos.olb zfioks.obj
+$ delete zfioks.obj;*\fR
+.DE
+.sp
+.IP [4]
+Make sure the system is configured for IRAF networking.  Examine
+the file \f(CW[iraf.vms.hlib]mkpkg.inc\fR, and make sure \f(CWUSE_KNET = yes:
+.sp
+.DS
+\f(CW
+$set USE_KNET = yes	 # use the KI (network interface)\fR
+.DE
+.sp
+.IP [5]
+\fRAssuming you are using the shared library, the default, you now
+need to regenerate that library.  If for some reason you are not
+using the shared library, you may proceed to step [6].  To rebuild
+the shared library, carry out the steps in section 5.1.8 
+then proceed to step [6].
+.IP [6]
+Relink the main IRAF system.  To do this, carry out the instructions
+in section 5.1.9 of the Installation Guide.  Make sure you have 
+deinstalled all IRAF executables before relinking.  A common mistake
+is to have the old shared library installed while trying to relink
+with the new version.  The iraf kernel server executable (\f(CWbin$irafks.e\fR)
+should NOT be linked against the shared library.  So, after you have 
+relinked the IRAF executables (including \f(CWirafks.e\fR) with the new shared
+library, go back to the \f(CWiraf$sys/ki\fR directory and relink the kernel
+server without the shared library:\f(CW
+.sp
+.DS
+\f(CW
+$ xc -z irafks.o
+.DE
+.sp
+\fRReplace the \f(CWirafks.e\fR currently in \f(CWiraf$bin\fR with this version.
+.IP [7]
+Edit two files in \f(CWdev$:
+.sp
+.DS
+\f(CW
+hosts\fR			set up node names for your site\f(CW
+hostlogin\fR		(optional) set up default public logins if any
+.DE
+.sp
+\fRA common error is to edit the \f(CWdev$hosts\fR file incorrectly.  Make sure
+you add an entry for each node, including the local node, to this file.  
+.IP [8]
+Create \f(CW.irafhosts\fR files in the IRAF login directories of users who plan
+to use networking on HOMENODE.  The file format is a series of lines
+of the form:
+.sp
+.DS
+\f(CWalias1 alias2 ... aliasN : loginname password\fR
+.DE
+.sp
+If the same login name and password are used on several nodes,
+an "\f(CW*\fR" may
+be used as the alias.  The file should be read protected; also,
+a "\f(CW?\fR" may
+be used in place of the password (you will be prompted).  For example:
+.sp
+.DS
+\f(CW
+# .irafhosts file
+node1 node3 : mylogin mypassword
+* : otherlogin ?\fR
+.DE
+.sp
+.IP [9]
+Place a DCL command file called "\f(CWirafks.com\fR" in the VMS
+login directories
+of all IRAF network users on SERVERNODE (or on both nodes for two-way
+network traffic); note the editing required after\f(CW
+"$! If this is a standalone...\fR", if the target node is a fully
+configured IRAF system \(em the default assumes the target is a kernel
+server only system:\f(CW
+.sp
+.nf
+\f(CW\s-1
+$! IRAFKS.COM -- DCL command file to run the IRAF/DECNET kernel server.
+$! Note:  the path to the server directory MUST be fully specified
+$! below (i.e. substitute your actual disk name for "DISK").
+$!
+$! set verify							!*debug*
+$! netserver$verify = 1						!*debug*
+$!
+$! If this is a standalone irafks server,...
+$  set default DISK:[irafserve]  	     ! comment out if full IRAF
+$  @irafuser.com			     ! comment out if full IRAF
+$  run irafks.exe			     ! comment out if full IRAF
+$! ..., else if this is a fully-configured IRAF system,...
+$! iraf					     ! <- uncomment if full IRAF
+$! run irafbin:irafks.exe		     ! <- uncomment if full IRAF
+$  logout\s0\fR
+.fi
+.sp
+where \f(CWDISK\fR is of course the IRAF disk; the decnet server has no access
+to globally defined IRAF symbols or logicals like \f(CWIRAFDISK\fR until it can
+execute \f(CWirafuser.com\fR.
+.LP
+This completes the basic installation; the steps are the same for both
+nodes if two-way IRAF network traffic is desired.
+.SH 
+II. Server Nodes
+.LP
+If a remote node is to be used purely for access to peripherals (you don't
+plan actually to run anything in IRAF on the remote node directly), you need
+only install a small subset of the IRAF system on it.
+This is a summary of the steps you will take:
+.sp
+.RS
+.IP \(bu
+build a version of \f(CWirafks.exe\fR without the shared library
+.IP \(bu
+install and edit the following files in \f(CW[irafserve]\fR on the server node:
+.sp
+.DS
+\f(CWirafks.exe
+irafuser.com
+irafks.com
+login.com
+zzsetenv.def\fR
+.DE
+.RE
+.sp
+.IP [1]
+On the existing fully-installed IRAF system, HOMENODE, verify that
+the kernel server executable in \f(CWirafbin\fR is indeed the version you just
+created, linked without the shared library.  You will be copying it
+to the SERVERNODE in a following step.
+.IP [2]
+On the remote, or `kernel server' system, SERVERNODE, create an IRAF
+account as was done for the the main IRAF installation,
+as in section 2.1 of the 
+Installation Guide.  Although it is not strictly necessary to have an
+actual account for IRAF on this machine, it would be helpful should
+it ever be necessary for us to debug anything on it.  Have its default
+directory set to \f(CW[IRAFSERVE]\fR rather than \f(CW[iraf.local]\fR,
+and create the
+directory \f(CW[irafserve]\fR (this could be put elsewhere; you would simply
+change all references to \f(CW[irafserve]\fR in these notes).
+.sp
+Also have the system manager insert the following global symbol definition
+into the system-wide login file (e.g. \f(CWsys$manager:sylogin.com\fR):\f(CW
+.sp
+.DS
+\f(CW
+$  irafserve :== @DISK:[irafserve]irafuser.com\fR
+.DE
+.sp
+\fRIf this is not done, then each user must explicitly execute that `@'
+command in their own \f(CWlogin.com\fR files.
+.IP [3]
+On the remote, or `kernel server' system, SERVERNODE, log in as IRAF.
+You should be in the \f(CW[irafserve]\fR directory.
+Copy the newly-created kernel server executable and some other files
+from the fully-installed system onto the kernel server system.
+The file \f(CWirafks.com\fR was discussed in step [9] above; if you do not
+have one on HOMENODE, just create it here.\f(CW
+.sp
+.nf
+\f(CW\s-1
+$ set def [irafserve]
+$ copy HOMENODE"account password"::DISK:[iraf.bin]irafks.exe []
+$ copy HOMENODE"account password"::DISK:[iraf.vms.hlib]irafuser.com []
+$ copy HOMENODE"account password"::DISK:[iraf.vms.hlib]zzsetenv.def []
+$ copy HOMENODE"account password"::DISK:[iraf.local]login.com []
+$ copy HOMENODE"account password"::DISK:[iraf.local]irafks.com []\s0
+.fi
+.sp
+\fRwith the appropriate substitutions of course.
+.sp
+Edit \f(CWirafuser.com\fR to set the logical name definitions \f(CWIRAFDISK, 
+IMDIRDISK\fR, and \f(CWTEMPDISK\fR for the server node.\f(CW
+.sp
+.DS
+\f(CW
+$ edit irafuser.com\fR		(etc.)
+.DE
+.sp
+\fRMake sure the first executable lines in \f(CWlogin.com\fR are as below:\f(CW
+.sp
+\f(CW$ edit login.com
+.DS
+\f(CW
+$  set prot=(s:rwd,o:rwd,g:rwd,w:r)/default
+$  if (f$mode() .eqs. "NETWORK") then exit
+.DE
+.sp
+\fRChange the DISK specification for the server system in \f(CWirafks.com\fR to
+be the actual disk (or a system-wide logical name for it) -- see
+step [9] above.\f(CW
+.sp
+\f(CW
+$ edit irafks.com\fR		(etc.)
+.sp
+.IP [4]
+Insert \f(CWirafks.com\fR files into the VMS login directories on the server
+node of any IRAF users wanting access to this node.  If plotter
+access is desired, it is essential that the users' \f(CWlogin.com\fR files
+explicitly execute the \f(CW[irafserve]irafuser.com\fR file, and desirable
+that they exit if mode = \f(CWNETWORK\fR (to avoid lots of error messages
+in \f(CWNETSERVER.LOG\fR files).  For example
+(in user's \f(CWlogin.com\fR):\f(CW
+.sp
+.DS
+\f(CW
+$  set prot=(s:rwd,o:rwd,g:rwd,w:r)/default
+$  if (f$mode() .eqs. "NETWORK") then exit
+...
+$  irafserve	 ! define IRAF logicals for plotting\fR
+.DE
+.sp
+\fR(The global symbol "\f(CWirafserve\fR" was defined in the system-wide login
+file in step [2] above.)
+.sp
+.LP
+This completes the basic network configuration.  Although setting up plotting
+devices in a network environment can be complicated, here are some guidelines
+for installing SGI translators on a kernel server node.
+.SH 
+III. Guidelines for installing SGI translators on kernel server node
+.LP
+This is a summary of the steps needed:
+.sp
+.RS
+.IP \(bu
+on home node, edit \f(CWdev$graphcap\fR (and \f(CWdev$hosts\fR if necessary)
+.IP \(bu
+copy \f(CWhlib$sgiqueue.com\fR to server and edit it
+.IP \(bu
+copy \f(CWhlib$sgi2XXXX.exe\fR to server (one for each XXXX SGI translator)
+.RE
+.sp
+.IP [1]
+On the home node, edit the graphcap file (\f(CWdev$graphcap\fR) to insert the
+server node prefix into the device name part of the \f(CWDD\fR string.  For
+example, if device \f(CWvver\fR lives on SERVERNODE, and the \f(CWDD\fR string
+for that device begins with:\f(CW
+.sp
+.DS
+\f(CW
+:DD=vver,tmp$sgk,\fR...
+.DE
+.sp
+\fRchange it to:\f(CW
+.sp
+.DS
+\f(CW
+:DD=SERVERNODE!vver,tmp$sgk,\fR...
+.DE
+.sp
+\fRwith appropriate substitution for SERVERNODE.  If all the plotters to
+which you want access are on the same node, you can use the \f(CWplnode\fR
+alias; just make sure \f(CWplnode\fR is an alias for SERVERNODE
+in \f(CWdev$hosts\fR
+(see `Configuring IRAF networking for DECNET' above).  Also make sure
+the printer queue names in the \f(CWDD\fR string are appropriate for SERVERNODE
+or "\f(CWnone\fR" if the devices are not spooled.  E.g.:\f(CW
+.sp
+.DS
+\f(CW
+:DD=plot!vver,tmp$sgk,submit/que=fast/noprint/nolog \e
+/para=\e050"vver","$F","$(PX) $(PY) VERSAQUEUE"\e051 \e
+irafhlib\e072sgiqueue.com:tc=sgi_versatec:
+.DE
+.sp
+.IP [2]
+\fRCopy the home node's \f(CWhlib$sgiqueue.com\fR file to the\f(CW
+[irafserve]\fR directory
+on SERVERNODE and edit it for the local printer queue names, etc.
+Also replace the "\f(CWirafhlib\fR" in the VMS task definitions,
+as the translators
+on SERVERNODE reside in the same directory as \f(CWsgiqueue.com\fR, i.e.\f(CW
+[irafserve]\fR.  E.g.:\f(CW
+.sp
+.DS
+\f(CW
+$  sgi2vver := $DISK:[irafserve]sgi2vver  !  versatec interface\fR
+.DE
+.sp
+.IP [3]
+Copy the home node's SGI translators to the \f(CW[irafserve]\fR directory on 
+SERVERNODE.
+.sp
+There are many different ways of interfacing plotters in VMS environments,
+so these notes will not work in all cases.  Call the IRAF Hotline if you 
+have any trouble at all [(602) 323-4160].
+.SH
+IV. Using the network
+.LP
+Each user desiring IRAF network access should have the
+following files, as described above:
+.sp
+.nf
+    on HOMENODE:	\f(CW.irafhosts\fR in IRAF home directory
+    on SERVERNODE:	\f(CWirafks.com\fR in VMS login directory
+    on SERVERNODE:	"\f(CWirafserve\fR" command in VMS \f(CWlogin.com\fR file
+.fi
+.sp
+.LP
+In some cases, for example where the local node is a MicroVAX with
+comparatively slow disk drives and the remote is a big VAX with very
+fast disk drives, an image may actually be accessed faster on the remote
+over the IRAF network than it can be locally.
+.LP
+When working on images across the network, it is best to store the pixel
+files in the same directory as the image headers, or in a subdirectory.
+This is done by "\f(CWcl> set imdir = HDR$\fR".
+Or, to cut the size of the directory
+in half by placing the pixel files in a subdirectory called "\f(CWpixels\fR",
+"\f(CWset imdir = HDR$pixels/\fR".  To cut down on typing, you might also define
+a logical directory for your data area on the remote, "\f(CWdd\fR" for example.
+Thus you could place the following lines in your \f(CWlogin.cl\fR file:
+.sp
+.DS
+\f(CW
+set imdir = HDR$pixels/
+set dd    = bigvax!mydisk:\e[mydir.iraf.data]\fR
+.DE
+.sp
+Suppose you are now in the CL on the HOMENODE, and you want to
+run \f(CWIMPLOT\fR
+on an image called \f(CWtest001\fR on the remote node BIGVAX, in directory
+\f(CW[mydir.iraf.data]\fR, and then copy it to your current directory on node A:
+.sp
+.DS
+\f(CWpl> implot dd$test001
+pl> imcopy dd$test001 test001\fR
+.DE
+.sp
+The logical directory \f(CWdd$\fR may be used
+in most of the normal fashions (you
+won't be able to "\f(CWchdir\fR" to it).
+Both IRAF virtual file names may be used
+(including all the usual system logical directories) and host file names.
+As usual in VMS/IRAF, any "$" and "[" in host-system pathnames must be
+escaped with "\e", and lowercase filenames should only be used in IRAF
+virtual filenames.  Various file access examples follow:
+.sp
+Use of environment variable (see above) to cut down on typing:
+.sp
+.DS
+\f(CWcl> set dd = bigvax!mydisk\e$1:\e[mydir.iraf.data]
+cl> dir dd$
+cl> page dd$README
+im> imhead dd$*.imh\fR
+.DE
+.sp
+Use of IRAF virtual filenames explicitly:  (this will only work on
+systems where bigvax is a fully-installed system; the IRAF virtual
+directories may not be present on a server-only system)
+.sp
+.DS
+\f(CWcl> count bigvax!local$notes
+cl> tail bigvax!local$notes nl=100 | page
+cl> dir bigvax!hlib$*.com long+
+cl> dir bigvax!sys$gio/R* long+
+cl> page bigvax!sys$gio/README
+cl> page bigvax!home$login.cl
+cl> dir bigvax!tmp$sgk* long+\fR
+.DE
+.sp
+Use of host-system pathnames:
+.sp
+.DS
+\f(CWcl> dir bigvax!usr\e$0:\e[mydir.iraf]*.imh
+cl> copy bigvax!usr\e$0:\e[mydir.doc]letter.txt newletter.txt
+cl> history 100 > bigvax!usr1:\e[mydir]test.his\fR
+.DE
+.sp
+.LP
+Please remember that this is a developing interface, and that it has not
+yet been tested as extensively as we would like.  We would appreciate being
+contacted about any problems you uncover.
+
+