diff options
Diffstat (limited to 'doc/vmsiraf.ms.v29')
| -rw-r--r-- | doc/vmsiraf.ms.v29 | 2673 |
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. + + |