path: root/doc/v210revs.ms

.RP
.TL
IRAF Version 2.10 Revisions Summary
.AU
IRAF Group
.br
.K2 "" "" "\(dg"
.br
July 1992

.AB
A summary of the revisions made to the IRAF for the version 2.10 release are
presented.  V2.10 is a major IRAF release, meaning that there were
significant additions to both the system and applications software, and the
release will eventually be made available on all supported systems.  This
document deals with only the changes to the IRAF core system and NOAO
packages.  The many layered packages available for IRAF follow independent
release schedules and are documented separately.  This revisions summary is
divided into three main sections: system revisions, IRAF and NOAO
applications revisions, and revisions to the IRAF programming environment.
.AE

.pn 1
.bp
.ce
.ps +2
\fBContents\fR
.ps -2
.sp 3
.sp
1.\h'|0.4i'\fBIntroduction\fP\l'|5.6i.'\0\01
.sp
2.\h'|0.4i'\fBIRAF System Revisions\fP\l'|5.6i.'\0\01
.br
\h'|0.4i'2.1.\h'|0.9i'Starting up V2.10 IRAF\l'|5.6i.'\0\01
.br
\h'|0.9i'2.1.1.\h'|1.5i'LOGIN.CL changes\l'|5.6i.'\0\01
.br
\h'|0.9i'2.1.2.\h'|1.5i'Compatibility Issues\l'|5.6i.'\0\02
.br
\h'|0.4i'2.2.\h'|0.9i'CL Enhancements\l'|5.6i.'\0\03
.br
\h'|0.9i'2.2.1.\h'|1.5i'Formatted scans and prints, scan from a pipe\l'|5.6i.'\0\03
.br
\h'|0.9i'2.2.2.\h'|1.5i'Unlearning package parameters\l'|5.6i.'\0\04
.br
\h'|0.9i'2.2.3.\h'|1.5i'Loading packages at login time\l'|5.6i.'\0\04
.br
\h'|0.9i'2.2.4.\h'|1.5i'Environment variables\l'|5.6i.'\0\04
.br
\h'|0.4i'2.3.\h'|0.9i'System Management Related Changes\l'|5.6i.'\0\05
.br
\h'|0.9i'2.3.1.\h'|1.5i'Install script\l'|5.6i.'\0\05
.br
\h'|0.9i'2.3.2.\h'|1.5i'Caching of termcap entries\l'|5.6i.'\0\05
.br
\h'|0.9i'2.3.3.\h'|1.5i'Sorting of UNIX directories\l'|5.6i.'\0\05
.br
\h'|0.9i'2.3.4.\h'|1.5i'UMASK support\l'|5.6i.'\0\05
.br
\h'|0.4i'2.4.\h'|0.9i'Networking Enhancements\l'|5.6i.'\0\05
.br
\h'|0.9i'2.4.1.\h'|1.5i'New networking driver\l'|5.6i.'\0\05
.br
\h'|1.5i'2.4.1.1.\h'|2.2i'How it works\l'|5.6i.'\0\06
.br
\h'|1.5i'2.4.1.2.\h'|2.2i'The .irafhosts file\l'|5.6i.'\0\06
.br
\h'|1.5i'2.4.1.3.\h'|2.2i'Compatibility\l'|5.6i.'\0\07
.br
\h'|0.9i'2.4.2.\h'|1.5i'The hosts file\l'|5.6i.'\0\07
.br
\h'|0.4i'2.5.\h'|0.9i'Magtape System Enhancements\l'|5.6i.'\0\08
.br
\h'|0.9i'2.5.1.\h'|1.5i'Basic usage\l'|5.6i.'\0\08
.br
\h'|1.5i'2.5.1.1.\h'|2.2i'Logical device names\l'|5.6i.'\0\08
.br
\h'|1.5i'2.5.1.2.\h'|2.2i'Device allocation\l'|5.6i.'\0\09
.br
\h'|1.5i'2.5.1.3.\h'|2.2i'Device status\l'|5.6i.'\0\09
.br
\h'|1.5i'2.5.1.4.\h'|2.2i'File positioning\l'|5.6i.'\0\10
.br
\h'|1.5i'2.5.1.5.\h'|2.2i'Rewind\l'|5.6i.'\0\11
.br
\h'|0.9i'2.5.2.\h'|1.5i'New magtape driver\l'|5.6i.'\0\11
.br
\h'|1.5i'2.5.2.1.\h'|2.2i'Software structure\l'|5.6i.'\0\11
.br
\h'|1.5i'2.5.2.2.\h'|2.2i'Driver features\l'|5.6i.'\0\12
.br
\h'|0.9i'2.5.3.\h'|1.5i'Tapecap\l'|5.6i.'\0\12
.br
\h'|1.5i'2.5.3.1.\h'|2.2i'Using tapecap\l'|5.6i.'\0\13
.br
\h'|1.5i'2.5.3.2.\h'|2.2i'Configuring tapecap\l'|5.6i.'\0\13
.br
\h'|1.5i'2.5.3.3.\h'|2.2i'Supported devices\l'|5.6i.'\0\14
.br
\h'|0.9i'2.5.4.\h'|1.5i'Status output\l'|5.6i.'\0\15
.br
\h'|0.9i'2.5.5.\h'|1.5i'Error recovery\l'|5.6i.'\0\16
.br
\h'|0.9i'2.5.6.\h'|1.5i'Device optimization\l'|5.6i.'\0\16
.br
\h'|0.9i'2.5.7.\h'|1.5i'MTIO interface changes\l'|5.6i.'\0\17
.br
\h'|0.4i'2.6.\h'|0.9i'Graphics and Imaging Subsystem Enhancements\l'|5.6i.'\0\17
.br
\h'|0.9i'2.6.1.\h'|1.5i'New graphics applications\l'|5.6i.'\0\17
.br
\h'|0.9i'2.6.2.\h'|1.5i'Graphics system changes\l'|5.6i.'\0\17
.br
\h'|1.5i'2.6.2.1.\h'|2.2i'Encapsulated postscript SGI kernel\l'|5.6i.'\0\17
.br
\h'|1.5i'2.6.2.2.\h'|2.2i'Graphics output to the default printer\l'|5.6i.'\0\17
.br
\h'|1.5i'2.6.2.3.\h'|2.2i'Tick spacing algorithm improved\l'|5.6i.'\0\17
.br
\h'|1.5i'2.6.2.4.\h'|2.2i'Graphics metacode buffer\l'|5.6i.'\0\17
.br
\h'|1.5i'2.6.2.5.\h'|2.2i'IMTOOL changes\l'|5.6i.'\0\17
.br
\h'|1.5i'2.6.2.6.\h'|2.2i'IMTOOLRC changes\l'|5.6i.'\0\18
.br
\h'|1.5i'2.6.2.7.\h'|2.2i'X11 support\l'|5.6i.'\0\18
.br
\h'|0.4i'2.7.\h'|0.9i'Image Structures\l'|5.6i.'\0\18
.br
\h'|0.9i'2.7.1.\h'|1.5i'Image I/O (IMIO)\l'|5.6i.'\0\18
.br
\h'|1.5i'2.7.1.1.\h'|2.2i'Null images\l'|5.6i.'\0\18
.br
\h'|1.5i'2.7.1.2.\h'|2.2i'Preallocating pixel file storage\l'|5.6i.'\0\18
.br
\h'|1.5i'2.7.1.3.\h'|2.2i'Image templates now sorted\l'|5.6i.'\0\19
.br
\h'|1.5i'2.7.1.4.\h'|2.2i'The dev$pix test image\l'|5.6i.'\0\19
.br
\h'|0.9i'2.7.2.\h'|1.5i'Image kernels (IKI)\l'|5.6i.'\0\19
.br
\h'|1.5i'2.7.2.1.\h'|2.2i'New PLF image kernel\l'|5.6i.'\0\19
.br
\h'|1.5i'2.7.2.2.\h'|2.2i'OIF image kernel changes\l'|5.6i.'\0\20
.br
\h'|1.5i'2.7.2.3.\h'|2.2i'STF image kernel changes\l'|5.6i.'\0\20
.br
\h'|1.5i'2.7.2.4.\h'|2.2i'QPF image kernel changes\l'|5.6i.'\0\21
.br
\h'|0.9i'2.7.3.\h'|1.5i'World coordinate system support (MWCS)\l'|5.6i.'\0\22
.br
\h'|1.5i'2.7.3.1.\h'|2.2i'Applications support\l'|5.6i.'\0\22
.br
\h'|1.5i'2.7.3.2.\h'|2.2i'New function drivers\l'|5.6i.'\0\22
.br
\h'|1.5i'2.7.3.3.\h'|2.2i'WCS attributes\l'|5.6i.'\0\22
.br
\h'|1.5i'2.7.3.4.\h'|2.2i'Axis mapping\l'|5.6i.'\0\22
.br
\h'|1.5i'2.7.3.5.\h'|2.2i'MWCS save format\l'|5.6i.'\0\22
.br
\h'|1.5i'2.7.3.6.\h'|2.2i'Bug fixes\l'|5.6i.'\0\22
.br
\h'|0.9i'2.7.4.\h'|1.5i'Event files (QPOE)\l'|5.6i.'\0\23
.br
\h'|1.5i'2.7.4.1.\h'|2.2i'Blocking factors\l'|5.6i.'\0\23
.br
\h'|1.5i'2.7.4.2.\h'|2.2i'Parameter defaults\l'|5.6i.'\0\23
.br
\h'|1.5i'2.7.4.3.\h'|2.2i'Referencing the current datafile in macros\l'|5.6i.'\0\23
.br
\h'|1.5i'2.7.4.4.\h'|2.2i'Bitmask expressions\l'|5.6i.'\0\23
.br
\h'|1.5i'2.7.4.5.\h'|2.2i'Large time filters\l'|5.6i.'\0\23
.br
\h'|1.5i'2.7.4.6.\h'|2.2i'Default filters\l'|5.6i.'\0\24
.br
\h'|1.5i'2.7.4.7.\h'|2.2i'Alternate coordinate systems\l'|5.6i.'\0\24
.br
\h'|0.4i'2.8.\h'|0.9i'System Specific Changes\l'|5.6i.'\0\25
.br
\h'|0.9i'2.8.1.\h'|1.5i'Sun/IRAF\l'|5.6i.'\0\25
.sp
3.\h'|0.4i'\fBIRAF and NOAO package revisions\fP\l'|5.6i.'\0\26
.br
\h'|0.4i'3.1.\h'|0.9i'Changes to the IRAF system packages\l'|5.6i.'\0\26
.br
\h'|0.9i'3.1.1.\h'|1.5i'DATAIO package modifications\l'|5.6i.'\0\26
.br
\h'|0.9i'3.1.2.\h'|1.5i'IMAGES package modifications\l'|5.6i.'\0\27
.br
\h'|0.9i'3.1.3.\h'|1.5i'IMAGES.TV package reorganization and  modifications\l'|5.6i.'\0\27
.br
\h'|0.9i'3.1.4.\h'|1.5i'LISTS package modifications\l'|5.6i.'\0\27
.br
\h'|0.9i'3.1.5.\h'|1.5i'OBSOLETE package added\l'|5.6i.'\0\27
.br
\h'|0.9i'3.1.6.\h'|1.5i'PLOT package modifications\l'|5.6i.'\0\28
.br
\h'|0.9i'3.1.7.\h'|1.5i'PROTO Package reorganization and modifications\l'|5.6i.'\0\28
.br
\h'|0.9i'3.1.8.\h'|1.5i'Additions to XTOOLS and MATH\l'|5.6i.'\0\29
.br
\h'|0.9i'3.1.9.\h'|1.5i'Glossary of new tasks in the IRAF core system\l'|5.6i.'\0\29
.br
\h'|0.4i'3.2.\h'|0.9i'Changes to the NOAO Packages\l'|5.6i.'\0\29
.br
\h'|0.9i'3.2.1.\h'|1.5i'ARTDATA package modifications\l'|5.6i.'\0\29
.br
\h'|0.9i'3.2.2.\h'|1.5i'ASTUTIL package modifications\l'|5.6i.'\0\30
.br
\h'|0.9i'3.2.3.\h'|1.5i'DIGIPHOT package modifications\l'|5.6i.'\0\30
.br
\h'|0.9i'3.2.4.\h'|1.5i'DIGIPHOT.APPHOT package modifications\l'|5.6i.'\0\30
.br
\h'|0.9i'3.2.5.\h'|1.5i'DIGIPHOT.DAOPHOT (TESTPHOT) package modifications\l'|5.6i.'\0\30
.br
\h'|0.9i'3.2.6.\h'|1.5i'IMRED package modifications\l'|5.6i.'\0\31
.br
\h'|0.9i'3.2.7.\h'|1.5i'IMRED.CCDRED package modifications\l'|5.6i.'\0\32
.br
\h'|0.9i'3.2.8.\h'|1.5i'NOBSOLETE package added\l'|5.6i.'\0\32
.br
\h'|0.9i'3.2.9.\h'|1.5i'NPROTO package modifications\l'|5.6i.'\0\32
.br
\h'|0.9i'3.2.10.\h'|1.5i'ONEDSPEC package reductions\l'|5.6i.'\0\32
.br
\h'|0.9i'3.2.11.\h'|1.5i'RV package added\l'|5.6i.'\0\34
.br
\h'|0.9i'3.2.12.\h'|1.5i'TWODSPEC package modifications\l'|5.6i.'\0\34
.br
\h'|0.9i'3.2.13.\h'|1.5i'TWODSPEC.APEXTRACT package modifications\l'|5.6i.'\0\35
.br
\h'|0.9i'3.2.14.\h'|1.5i'TWODSPEC.LONGSLIT package modifications\l'|5.6i.'\0\36
.br
\h'|0.9i'3.2.15.\h'|1.5i'Glossary of new tasks in the NOAO packages\l'|5.6i.'\0\36
.sp
4.\h'|0.4i'\fBProgramming Environment Revisions\fP\l'|5.6i.'\0\39
.br
\h'|0.4i'4.1.\h'|0.9i'Compatibility Issues\l'|5.6i.'\0\39
.br
\h'|0.4i'4.2.\h'|0.9i'Portability Issues\l'|5.6i.'\0\39
.br
\h'|0.4i'4.3.\h'|0.9i'Software Tools\l'|5.6i.'\0\39
.br
\h'|0.9i'4.3.1.\h'|1.5i'LOGIPC feature\l'|5.6i.'\0\39
.br
\h'|0.9i'4.3.2.\h'|1.5i'XC changes\l'|5.6i.'\0\40
.br
\h'|0.9i'4.3.3.\h'|1.5i'SPPLINT code checker\l'|5.6i.'\0\41
.br
\h'|0.9i'4.3.4.\h'|1.5i'Multiple architecture support\l'|5.6i.'\0\41
.br
\h'|0.9i'4.3.5.\h'|1.5i'Package environments\l'|5.6i.'\0\41
.br
\h'|0.9i'4.3.6.\h'|1.5i'Finding module sources\l'|5.6i.'\0\41
.br
\h'|0.4i'4.4.\h'|0.9i'Programming Interface Changes\l'|5.6i.'\0\42
.br
\h'|0.9i'4.4.1.\h'|1.5i'IEEE floating support\l'|5.6i.'\0\42
.br
\h'|0.9i'4.4.2.\h'|1.5i'MATH libraries\l'|5.6i.'\0\42
.br
\h'|0.9i'4.4.3.\h'|1.5i'CLIO interface\l'|5.6i.'\0\42
.br
\h'|0.9i'4.4.4.\h'|1.5i'ETC interface\l'|5.6i.'\0\43
.br
\h'|1.5i'4.4.4.1.\h'|2.2i'Calling sequence for onentry changed\l'|5.6i.'\0\43
.br
\h'|1.5i'4.4.4.2.\h'|2.2i'New onerror and onexit procedures\l'|5.6i.'\0\43
.br
\h'|1.5i'4.4.4.3.\h'|2.2i'New gqsort routine\l'|5.6i.'\0\43
.br
\h'|0.9i'4.4.5.\h'|1.5i'FIO interface\l'|5.6i.'\0\44
.br
\h'|1.5i'4.4.5.1.\h'|2.2i'Nonblocking terminal i/o\l'|5.6i.'\0\44
.br
\h'|0.9i'4.4.6.\h'|1.5i'FMTIO interface\l'|5.6i.'\0\44
.br
\h'|0.9i'4.4.7.\h'|1.5i'GTY interface\l'|5.6i.'\0\45
.br
\h'|0.9i'4.4.8.\h'|1.5i'MTIO interface\l'|5.6i.'\0\45
.br
\h'|1.5i'4.4.8.1.\h'|2.2i'MTIO applications programming interface\l'|5.6i.'\0\45
.br
\h'|1.5i'4.4.8.2.\h'|2.2i'MTIO system procedures\l'|5.6i.'\0\46
.br
\h'|1.5i'4.4.8.3.\h'|2.2i'Magtape driver procedures\l'|5.6i.'\0\46
.br
\h'|0.9i'4.4.9.\h'|1.5i'MWCS interface\l'|5.6i.'\0\46
.sp
5.\h'|0.4i'\fBGetting Copies of this Revisions Summary\fP\l'|5.6i.'\0\47
.nr PN 0
.bp

.de XS
.DS
.ps -1
.vs -1p
.ft CB
..
.de XE
.DE
.ft R
.ps
.vs
..
.de i0  \" usage:  .i0 <pathname> spacing
.fl                                             \" Save the current
.nr xl \\n(nl                                   \"   line number and
.nr xp \\n%                                     \"   page number.
.KS
\\&                                             \" Make space for the
.sp \\$2                                        \"   plot, ejecting
\\&                                             \"   a new page if
.KE                                             \"   necessary.
.fl
.if \\n%>\\n(xp .nr xl 720                      \" New page, 1" margin.
\\!!    /irafsave save def                      \" "Encapsulate" the Post-
\\!!    0 72 \\n(xl 10 div sub translate        \"   Script plot, position
\\!!    /erasepage {} def                       \"   the plot on the page,
\\!!    /initgraphics {} def                    \"   disable irreversible
\\!!    /showpage {} def                        \"   PostScript operations.
.fl                                             \" Cure a bug with ".sy".
.sy     sed 's/^/!/' \\$1                       \" Escape plot for devps.
\\!!    irafsave restore                        \" Restore the P.S. context
.rr xl
.rr xp
..

.NH
Introduction
.PP
This document summarizes the changes made to IRAF in version 2.10.  V2.10
is a major release of IRAF, meaning that there were significant changes to
both the system and applications software, and the release will eventually
be made available on all supported platforms.
.PP
By IRAF version 2.10 we refer only to the core IRAF system and NOAO
packages.  Numerous external or "layered" packages are also available for
IRAF, for example the NSO package (solar astronomy), the ICE package (data
acquisition), the STSDAS package from STScI (HST data reduction and
analysis), the TABLES package from STScI (tabular data), the XRAY package
from SAO (X-ray data analysis), and so on.  These packages are layered upon
the IRAF core system, and once installed, are indistinguishable from the
rest of IRAF.  Layered packages are developed and maintained separately
from the core IRAF release and follow independent release schedules, hence
we will not discuss them further here.  Contact the IRAF project or any
of the outside groups supporting IRAF layered packages for additional
information on what is available.
.PP
This document is intended only as an overview of what is new in version 2.10
IRAF.  More detailed documentation will be found in the systems and
applications notes files (files \f(CWsysnotes.v210.Z\fR and
\f(CWpkgnotes.v210.Z\fR in the network archive), in the online help pages,
and in any reference papers or user's manuals distributed with the software.
The IRAF Newsletter is a good source of information for new IRAF software.
.PP
The reader is assumed to already be familiar with the basic concepts and
operation of the IRAF system.  In particular, familiarity with V2.9 IRAF is
assumed.

.NH
IRAF System Revisions
.NH 2
Starting up V2.10 IRAF
.PP
Before attempting to start V2.10 IRAF each user should run the \fImkiraf\fR
command in their IRAF login directory.  This will create a new \f(CWlogin.cl\fR
file and \f(CWuparm\fR (user parameter) directory.  \fImkiraf\fR should be
allowed to delete any existing parameter files, as there have been many
changes to task parameter sets in the new version of IRAF.
.NH 3
LOGIN.CL changes
.PP
The \f(CWlogin.cl\fR file is read by the CL during startup to perform some
runtime initialization and to customize IRAF for each user.  A standard
\f(CWlogin.cl\fR file is created and initialized by the \fImkiraf\fR command
when the user's IRAF login directory is configured.  For V2.10 IRAF the
\f(CWlogin.cl\fR file has undergone the following changes.
.RS
.IP \(bu
The IRAF version number is now checked automatically whenever you login,
and a warning message will be printed if your \f(CWlogin.cl\fR file is
out of date.  If you see this message it means that important changes have
been made to the \f(CWlogin.cl\fR file and you need to rerun \fImkiraf\fR
to update this file.
.IP \(bu
Most of core IRAF system packages are now loaded automatically at login time
by the \f(CWlogin.cl\fR file.  If you use a personal \f(CWloginuser.cl\fR
file and you previously loaded any core system packages in this file, you
should edit the file and remove those entries.
.IP \(bu
A "quiet" login option is now provided.  If a file named \f(CW.hushiraf\fR
exists in the login directory when you start up the CL, printing of the
usual login messages will be disabled (the only output seen will be the "cl>"
prompt).
.IP \(bu
On UNIX/IRAF systems the login script now looks at the host system
environment variable \f(CWTERM\fR and checks for the common terminal types
"sun" and "xterm", configuring the IRAF \fIstty\fR accordingly if either
terminal type is seen (note that the default number of lines set for an
xterm terminal window may need to be modified).  The logic used to do this
is not foolproof however, and is provided only as an example illustrating
how to make use of the host system terminal definitions.  You may need to
customize this portion of the script, or override it in your
\f(CWloginuser.cl\fR file.
.IP \(bu
The CL hidden parameter \f(CWshowtype\fR is now set to "yes" by default.
This will cause a character to be printed after the name of each package or
named pset in CL package menus to allow these objects to be easily
distinguished from ordinary tasks.  Packages are marked with a trailing
period (".") and psets with an ampersand ("@").  This feature can be
disabled with a "showtype=no" statement.
.IP \(bu
The V2.10 login script contains a call to a new internal (non-user) IRAF
task \fImtclean\fR.  Be sure to leave this alone, it is required for the
correct operation of the new magtape i/o system.
.RE
.LP
The USER package defined in the template \f(CWlogin.cl\fR has been
extensively revised, adding many new tasks.  These are mainly used to
make common UNIX commands available from within the IRAF environment.
Type "?user" in the CL to see what is available, e.g.:
.XS
cl> ?user
     adb     cp      fc      lpq     mv      rlogin  spell   top
     bc      csh     find    ls      nbugs   rsh     sps     touch
     buglog  date    finger  mail    nm      rtar    strings vi
     cal     df      ftp     make    od      ruptime su      w
     cat     diff    generic man     ps      rusers  sync    wc
     cls     du      grep    mkpkg   pwd     rwho    telnet  wtar
     comm    emacs   less    mon     rcp     sh      tip     xc
.XE
.LP
Note that since the USER package is defined in the user's login file it is
easily customized to add new tasks.  Refer to the existing package for
examples illustrating how to do this.
.RE
.NH 3
Compatibility Issues
.PP
Version 2.10 IRAF requires the new \f(CWlogin.cl\fR file; if the CL does not
start up correctly, it may be because the user has not done a \fImkiraf\fR,
or because they have some construct in their \f(CWloginuser.cl\fR file which
is incompatible with V2.10 IRAF.  The V2.10 login file is usable with V2.9
IRAF, however this is not recommended.
.PP
There have been many task \fBparameter changes\fR between V2.9 and V2.10.
If "parameter not found" messages are seen, most likely the user has an old
\f(CWuparm\fR directory, or has been switching back and forth between IRAF
versions.  An \fIunlearn\fR or \fImkiraf\fR should fix the problem.
.PP
The V2.10 IRAF \fBnetworking system\fR is not fully compatible with earlier
versions of IRAF.  This can cause problems when, e.g., a newly installed
V2.10 system is used to communicate with an older version of IRAF on another
system.  The best solution is to update to V2.10 on all systems, but if this
is not convenient it is possible to configure the networking system to avoid
the problems.  See the discussion of the new networking system given below.
.PP
Accessing a \fBremote magtape device\fR via IRAF networking will not work
between V2.10 and older versions of IRAF (the remote procedure calls have
changed).  To remotely access magtape devices you will need to install V2.10
IRAF on both the client and server nodes.
.PP
In most respects installing V2.10 IRAF will be very similar to installing
earlier versions of IRAF.  The main difference is the \fBtapecap file\fR
required to use the new magtape system.  The old \f(CWdev$devices\fR file
is no longer used.  See the discussion of the new magtape system given below
for more details.
.PP
Due to name changes in certain low level system routines (made to avoid name
clashes when linking with host level libraries) the V2.10 libraries are
incompatible with older versions of IRAF.  Any IRAF programs or external
packages \fBrelinked\fR under V2.10 will have to be fully recompiled or the
linker will complain about unresolved externals.  Note that so long as the
old program is not relinked there should be no problem, even if the program
uses the IRAF shared image, since the V2.9 shared image is included in V2.10
(this applies to Sun/IRAF systems only).
.PP
Starting with V2.10, many IRAF applications now fully support generalized
\fBworld coordinates\fR (WCS).  While in principle this should not pose any
compatibility problems, the image headers do contain more information in
V2.10 than previously, and there can be problems if, for example, an input
image contains an illegal WCS.  Previous versions of IRAF would ignore this
but in V2.10 such an image could result in an error or warning message.
If WCS related problems are encountered it is probably best to contact the
IRAF group for help.

.NH 2
CL Enhancements
.NH 3
Formatted scans and prints, scan from a pipe
.PP
New in the V2.10 CL (command language) are formatted scan and print routines,
and the ability to scan from a pipe or other form of redirected input.  These
new facilities will prove most useful in CL scripts.
.PP
The old unformatted scan and print routines are the following.  These are
still available and are the simplest routines to use where they are adequate.
.XS
  scan (arglist)          # scan standard input
 fscan (list, arglist)    # scan a list
 print (expr, exprlist)   # print to standard output
fprint (param, exprlist)  # print to a string buffer
.XE
.LP
For example,
.XS
list = "\fIfilename\fP"
while (fscan (list, x, y) != EOF)
    print ("x=", x, "y=", y)
.XE
.LP
In the above, \fIarglist\fR is a comma delimited list of output arguments
(parameter or parameter field names) and \fIexprlist\fR is a comma delimited
list of expressions to be printed.  \fIlist\fR is the name of a
list-structured parameter to be scanned, and \fIparam\fR is the name of a
parameter, the value field of which is to receive the output string.  The
unformatted scan routines will automatically convert output data values to
match the types of the output arguments.
.PP
The new formatted routines are as follows.  These take an extra
\fIformat\fR argument which tells how to parse the input string in the case
of the \fIscanf\fR routines, or how to format the output in the case of the
\fIprintf\fR routines.
.XS
 scanf (format, arglist)        # formatted scan from stdin
fscanf (list, format, arglist)  # formatted scan from a list
printf (format, exprlist)       # formatted print to standard output
.XE
.PP
Currently there is no \fIfprintf\fR routine.  For the \fIprintf\fR routine
the \fIformat\fR argument is similar to that for the SPP/VOS \fIprintf\fR
(which is similar to the C \fIprintf\fR).  The \fIformat\fR argument for the
\fIscanf\fR routines is the same as the VOS LIBC \fIscanf\fR, which is
patterned after the C \fIscanf\fR (in fact the UNIX manual page for
\fIscanf\fR can be used as a guide to the CL \fIscanf\fR with only minor
deviations).
.LP
The following examples illustrate the new routines.
.XS
cl> printf ("%d foo %7.3f\\\\n", 5, 12.123) | scanf ("%d foo %g", i, x)
cl> printf ("new values are i=%d, x=%g\\\\n", i, x)
new values are i=5, x=12.123
.XE
or,
.XS
while (fscanf (list, " %*d size=%d name=%s", i, s1) != EOF)
    printf ("size=%05o, name=`%s'\\\\n", i, s1)
.XE
.LP
Note in the first example the use of \fIscanf\fR to scan from a pipe.  There
are actually two different versions of \fIscan\fR and \fIscanf\fR in V2.10
IRAF, an intrinsic function version and a procedure version.  When called as
an intrinsic function, a \fIscan\fR routine returns as its function value
the number of operands successfully scanned, or EOF.  When called as a
procedure, the function value of a \fIscan\fR routine is discarded.
.PP
Here is another example illustrating scan from a pipe, in this case using
an unformatted scan since the \fIhselect\fR output is in a simple tabular
format (\fIhselect\fR prints selected fields of the image header).
.XS
cl> hselect dev$pix naxis,naxis1,naxis2 yes | scan (i, j, k)
cl> printf ("naxis=%d, axlen=[%d,%d]\\\\n", i, j, k)
naxis=2, axlen=[512,512]
.XE
.LP
When using the formatted scan routines, care must be taken to ensure that
the data types implied by the \fIformat\fR argument match the actual data
types of the output parameters.  The \fIscanf\fR routines are implemented
using an internal call to the C (LIBC) \fIscanf\fR, with the output
parameter value fields referenced directly via a pointer.  If the data type
is incorrect the output value may be meaningless.
.NH 3
Unlearning package parameters
.PP
The \fIunlearn\fR task now works for package parameters as well as task
parameters.  In a command such as "unlearn pkgname" the package parameters
for the named package will be unlearned, as well as the parameters for
all the tasks in the package.  This works whether or not the package is
loaded.
.NH 3
Loading packages at login time
.PP
A bug has been fixed which affected packages with package parameters loaded
at login time.  It is now permissible to load any package at login time
regardless of whether it has package parameters (V2.9 users will recognize
this bug as one which prevented loading CCDRED in the login script).
.NH 3
Environment variables
.PP
The environment variables \f(CWimtype\fP, \f(CWcmbuflen\fP,
and \f(CWmin_lenuserarea\fP are now defined at login time.  Previously,
explicit values for these variables were not defined, and the system
would use the builtin internal defaults.  Explicit definitions were
added so that the user can query the current value, e.g.
.XS
cl> show cmbuflen
128000
.XE
A \fIshow\fR or \fIset\fR with no arguments will print the full environment
list.  New values for these and other common environment variables may be
set in the user \f(CWlogin.cl\fP file.

.NH 2
System Management Related Changes
.NH 3
Install script
.PP
The UNIX/IRAF install script underwent minor changes to make it more
robust.  Problems are still possible if the IRAF root pathname is set to
different values in the various system dependent files modified by the
script.  The system as shipped from NOAO has the same initial root pathname
set in all such files, but problems can occur if the files are manually
edited during or after installation.  To avoid problems always use the
install script to make system changes such as installing at a different root
directory.
.NH 3
Caching of termcap entries
.PP
User caching of termcap or graphcap entries with the old \f(CWmkttydata\fR
task is no longer recommended.  The most common entries (e.g. sun, xterm,
vt100) are already cached.  Modern workstations are so fast that there is no
longer much point in caching termcap entries; it is sufficient to merely
place local additions near the top of the file.  Most programs that
repeatedly access the terminal cache the entries internally during
execution.  Custom caching of termcap or graphcap device entries requires
that the system be relinked, and the risk inherent in relinking the system
(hence giving up the prebuilt, pretested binaries) is not worth the small
performance gain achieved.
.NH 3
Sorting of UNIX directories
.PP
The UNIX-based versions of IRAF now sort UNIX directories whenever a
directory is accessed to expand a file or image template.  This will fix the
problem sometimes seen in earlier versions of IRAF, in which an image
template could appear to be expanded in a seemingly random fashion.
.NH 3
UMASK support
.PP
The UNIX-based versions of IRAF now support the host level \fIumask\fR file
creation mask correctly.  If files or directories created by V2.10 IRAF do
not have the desired permissions, it is because you do not have umask set
correctly at the UNIX level (most people set umask to 022).

.NH 2
Networking Enhancements
.NH 3
New networking driver
.PP
The UNIX/IRAF networking driver has been completely rewritten for version
2.10 IRAF, with the goals of eliminating redundant password prompts,
improving efficiency, and enhancing system security.  For the most part the
changes will be transparent to the user.  Once the IRAF system manager has
configured the \f(CWdev$hosts\fR file for the local site the networking
system should function automatically; in the default configuration a password
prompt should be seen only when connecting to a server for which \fIrhosts\fR
("trusted" hosts) permission is not granted.
.PP
The following information is provided mainly for IRAF system managers.
In normal use the user does not need to understand how the networking
system functions.
.NH 4
How it works
.PP
The IRAF networking system is an RPC (remote procedure call) mechanism for
the IRAF kernel; all kernel procedures may execute either locally or
remotely, and the client and server nodes do not even need to run the same
operating system.  IRAF applications may be distributed, and may access
resources which reside anywhere on the network.  IRAF networking is layered
upon standard low level networking protocols such as TCP/IP and DECNET.
.PP
The IRAF networking system defines one or more \fIconnection protocols\fR
which are used by a client to connect to the IRAF kernel server on a remote
machine.  The old networking driver supported only one connection protocol,
the \fIrexec\fR protocol, which requires a login name and password.  The new
driver adds support for an \fIrsh\fR based protocol.  This is the default
connection protocol for V2.10 IRAF; automatic fallback to the rexec protocol
is provided in the event that the rsh connect fails.  The rsh connection
protocol bootstraps off the suid-root \fIrsh\fR command found in most BSD
derived UNIX systems (most System V systems provide the equivalent command
\fIremsh\fR).
.PP
The connection protocol is used to start the \fIin.irafksd\fR IRAF
networking daemon on the remote server node.  This daemon executes with the
same uid and permissions as the account which initiated the connection, and
there is one such daemon per user per server node.  Once the daemon has been
started via the rsh or rexec connection protocol, new client connections are
made very quickly, by merely forking the daemon to create the IRAF kernel
server process, and setting up a direct socket connection between the IRAF
client process and the server.  The daemon process runs indefinitely,
shutting down if idle for longer than a certain interval (the current
default is one hour).  When connecting to the daemon a client must supply an
authentication key to gain access to the daemon.  If authentication fails
the daemon shuts down and it is necessary to reestablish the connection.
.NH 4
The .irafhosts file
.PP
The new networking driver retains the old \fIirafhosts\fR file, used to
store information telling how to connect to various IRAF hosts (the
irafhosts file is the file \f(CW.irafhosts\fR in the user's login
directory).  The networking system will automatically create this file for
the user if the file is not found; if an old-style file is found, it will be
edited by the system to make it compatible with the new networking system.
While it is no longer necessary for the irafhosts file to contain password
information to avoid password prompts, the file is used to store the user
authentication key, hence the file should be read protected.  The networking
system will automatically read protect the file if it is not already
protected.
.PP
To avoid authentication failures when clients on different nodes attempt to
connect to the same server, the same authentication code should be used on
all server nodes.  Unfortunately there is no way that the networking system
can do this automatically (without going to some much more complicated
authentication scheme, such as a key server), so users who make heavy use of
the networking system should install a copy of their irafhosts file
in their login directory on all server nodes.  If this is not done the
networking system will still work, but will be less efficient than it could
be, when simultaneously accessing the same server from IRAF sessions running
on multiple client nodes.
.PP
The truly paranoid may not be happy with even the unique user
authentication code used in the current networking system.  If this is the
case the \fIport\fR parameter (see below) may be set to zero to force rsh to
be used for every connection (in effect the in.irafksd daemon has to be
restarted for every connection).  This imposes an overhead of as much as
several seconds on every server connect.  Alternatively, \f(CWKSAUTH\fR can
be defined in the user environment at login time, setting the value string
to some random integer value selected at login time.  If defined in the user
environment, \f(CWKSAUTH\fR will override the value of \fIauth\fR given in
the irafhosts file.  This approach would at least allow efficient connects
for a single login process tree.
.PP
The irafhosts file consists of two sections.  The first section
defines several networking parameters: \f(CWport\fP, \f(CWauth\fP,
\f(CWhiport\fP, and \f(CWtimeout\fP.  The second section is a list of
server nodes, with login and password information describing how to connect
to each node.
.XS
port = default
auth = 1234567890
hiport = default
timeout = default

ursa    : <user> ?
*       : <user> <user>
.XE
.LP
The example above illustrates a typical irafhosts file.  Typically a unique
authentication code is allocated automatically by the system when the file
is first created, and the other parameters retain their default values as
shown (i.e., the string "default").  In the example the host list consists
of an entry for the node "ursa", and an entry for everything else.  The
format of a host entry is "\fIhost-name : login-name password\fP".  If
\fIlogin-name\fR is the reserved string "<user>" the user name on the client
node is used for login authentication on the remote node.  Setting the
password to "<user>" as well causes the rsh connect protocol to be used;
anything else causes the rexec protocol to be used.  If the rexec protocol
is used the password field may be set to the actual password or to the
string "?", in which case the system will prompt for the password whenever a
connection attempt is made.  The "*" entry should always be the last entry
in the list, since it matches all nodes.  The default host list contains
only the "*" entry.
.PP
Additional information on the irafhosts file is provided in the
comments in the file \f(CWdev$irafhosts\fR, and in the system notes file.
.NH 4
Compatibility
.PP
By default the new networking system will try to use the rsh protocol to
connect to the server node.  If the server is running an older version of
IRAF the connection attempt will hang and eventually time out.  If this
occurs the networking system will fall back on the rexec protocol and issue
a password prompt, but by then the user will probably have interrupted the
connect.  The best way to avoid this problem is to update the server node
to V2.10, but if this is not possible, an explicit entry for the node can
be made in the irafhosts file, setting the password field so that
the rexec protocol will be used.
.PP
An older, e.g. V2.9 client connecting to a V2.10 server should not be a
problem.  In this case the V2.10 server will see an attempt to connect with
the rexec protocol, which should be processed as in the past.
.PP
Aside from the problem of making a connection the pre-V2.10 and V2.10
networking systems are compatible, \fIexcept\fR for the magtape i/o calls.
Since the magtape driver calling sequences were changed in V2.10, remote
magtape access between V2.10 and older systems is not supported.
.NH 3
The hosts file
.PP
The file \f(CWdev$hosts\fR is used to interface new host machines to the
IRAF networking system.  This file defines, for each host, the primary
host name, any aliases, and the command to be executed remotely to start
up the IRAF kernel server on a remote node.
.PP
The format and role of the hosts file is unchanged in V2.10.  Two changes
were made which affect the use of this file.
.RS
.IP \(bu
A user can now have a private copy of the hosts file.  To enable this feature,
the variable \f(CWirafhnt\fR (IRAF host name table) should be defined in
the user's IRAF or host level environment, with the string value giving the
file pathname of the user's private host name table file.
.IP \(bu
The maximum number of entries in the host name table has been increased from
64 to 128.  In the current implementation these entries are statically
buffered, so it is necessary to keep the maximum number of entries to a
reasonable value.
.RE
.LP
The hosts file must be configured to enable IRAF networking.  IRAF networking
is disabled if there is no entry for the local host in this file.  The
\fInetstatus\fR command may be used to examine the state of the host name
table after it has been loaded by the networking system.
.PP
There is another file \f(CWdev$uhosts\fR which often confuses people.  This
file is not used by UNIX/IRAF and can be ignored; it is there for VMS/IRAF
and other IRAF implementations which do not provide the equivalent of the
UNIX system routine \fIgethostbyname\fR.  On host machines which implement
name server facilities IRAF will use the name server, allowing any machine
on the internet to be accessed via IRAF networking, so long as there is an
entry in the system wide or user IRAF hosts file.

.NH 2
Magtape System Enhancements
.PP
The magtape subsystem underwent a major revision in V2.10.  The VOS level
MTIO interface was extensively revised, and the host-level IRAF magtape
driver ZFIOMT is completely new.  A new device configuration facility
called \fItapecap\fR was introduced.  Together with the new "programmable"
magtape driver, this makes it possible to interface almost any removable
media mass storage device to the magtape subsystem.  The DATAIO
applications, in particular the FITS programs, underwent minor, but
important revisions.
.PP
A full specification of the new magtape subsystem, particularly the tapecap
facility, is beyond the scope of this document.  Our intention here is
merely to introduce the new facilities.  A reference paper is planned, time
permitting, which will fully document the new magtape system and tapecap.
.NH 3
Basic usage
.PP
In most respects basic usage of the magtape system is unchanged from
previous releases.  Many new capabilities have been added, but these are
upwards compatible with earlier releases.
.NH 4
Logical device names
.PP
Magtape devices are still referred to in IRAF applications much as they
have been in the past.  Whether or not the logical device names are the
same before and after the V2.10 upgrade depends upon how the IRAF system
manager configures the tapecap file.  The new magtape system is much more
flexible than previously regarding device names, but to avoid user confusion
it is recommended that the old names be supported as aliases regardless of
whatever the full device name may be.
.LP
As in earlier versions of IRAF, a simple magtape reference might be
.XS
cl> mtexamine mta
.XE
where "mta" is the device name.  To examine only file 3 on the tape one
might enter
.XS
cl> mtex mta[3]
.XE
If the device is on the remote node "ursa" the command would be
.XS
cl> mtex ursa!mta[3]
.XE
If the device is a 9 track tape supporting multiple densities we might
specify the density explicitly, e.g.
.XS
cl> mtex mta1600[3]
.XE
Device names can be more complex.  For example,
.XS
cl> mtex mtwd
.XE
might refer to a WangDAT drive, and
.XS
cl> mtex mtwdc
.XE
to the same drive, but with data compression enabled.
.PP
Devices can have multiple names, possibly with slightly different behavior
or characteristics.  Device names such as "mta" are usually only host
specific aliases for the lower level, host independent device names.
The names "mta" and "mtb" might be aliases for the actual device
names "mthp0" and "mtxt1".  This can be useful in networked systems
where IRAF and the tapecap file reside on a server node, but the user
is running IRAF on their workstation with a local tape drive attached.
In this case there may be no entry for the local drive in the installed
tapecap file, but the user can still access the local drive using the lower
level, host independent device entry (it is also possible to have a
private tapecap file as we shall see later).
.PP
To see what logical devices are known to the magtape system you can
enter the following command (the task \fIgdevices\fR was intended for
graphics devices but can be pressed into service to list a tapecap
file as well).  Just because a device is listed does not mean that the
physical device actually exists on a particular host system.
.XS
cl> gdev devices='^mt' graphcap=dev$tapecap
.XE
In IRAF V2.10 it is possible to include tapecap parameters in the device
specification to do clever things, as in the following example.
.XS
cl> mtex "mta[:so=lepus:se:nb]"
.XE
This is discussed further below in the section describing the tapecap
facility.
.NH 4
Device allocation
.PP
Device allocation operates much the same in V2.10 as in earlier versions
of IRAF.  The main change is that it is no longer necessary to allocate a
device in order to be able to access it.  It is strongly recommended however
that you always allocate a device before accessing it in IRAF.  If the
device is not allocated anyone can access the drive, e.g., changing the
tape position, and this can cause data to be lost or improperly read back.
The only reason to access the drive without allocating it is if there is
some problem with device allocation on your system.
.LP
A device is allocated with the \fIallocate\fR command, e.g.
.XS
cl> alloc mta
.XE
A device is deallocated with \fIdeallocate\fR.  If the tape has already
been unmounted use the \fIrewind=no\fR option to avoid accessing the drive.
By default the tape will be rewound when it is deallocated.  Deallocating
and reallocating a drive initializes the magtape system, i.e., all cached
knowledge of the status of the drive is discarded.
.NH 4
Device status
.PP
The device status can be examined at any time that the magtape device is
idle (not being actively accessed by an IRAF task) using the \fIdevstatus\fR
task.
.XS
cl> devs mtc
# Magtape unit mtc status Thu 12:54:02 04-Jun-92 user v14
file = 4
record = 1
nfiles = 0
tapeused = 405
pflags = 0
.XE
.LP
Of particular interest are the \fItapeused\fR and \fInfiles\fR fields.
\fInfiles\fR refers to the total number of files on the tape (if a file is
appended to the tape it will be file \fInfiles\fR+1).  If \fInfiles\fR
is given as zero that means that the magtape system does not yet know how
many files are on the tape (it has not seen the end of tape).
.PP
\fItapeused\fR reports the amount of tape used in units of kilobytes.  This
is intended to refer to the amount of tape used up to and including the end
of tape (EOT).  However, the magtape system only knows about data that it
has seen, i.e.  physically read or written, so whether or not \fItapeused\fR
is accurate depends upon how you have accessed the tape.
.PP
For example, if you started out with a fresh tape and appended a number of
files the number should be accurate.  If you just completed a full scan of
the tape with \fImtexamine\fR the number should be accurate, since all the
data was read.  If you just put on a new tape and did a scan of the FITS
headers with "rfits make-", the number may or may not be accurate, depending
upon the device and how file skipping forward was done.  In most cases only
the header area of each file will have been read and \fItapeused\fR will not
reflect the full contents of the tape.  If however, "rfits make-" is done
immediately after writing to a new tape, the number will be accurate, since
all the data was written before the tape was rescanned to print the FITS
headers.
.PP
Be advised that by default an explicit \fIrewind\fR will clear the \fInfiles\fR
and \fItapeused\fR fields, since by default \fIrewind\fR initializes the
magtape system.  See the discussion of \fIrewind\fR below.
.PP
In summary \fItapeused\fR can be useful for monitoring how much space is
left on a tape, but you have to know what you are doing.  When writing to a
new tape the number will be accurate so long as you avoid doing an explicit
\fIrewind\fR.  A simple procedure which will always work when mounting a
non-empty tape and appending files to it, is to do an \fImtexamine\fR of the
tape and then append the new files.  This can be time consuming for large
tapes but does provide a safe and device-independent method for getting the
maximum amount of data on a tape.
.NH 4
File positioning
.PP
File positioning when accessing magtape files in IRAF is straightforward in
the sense that you can simply specify the file number to read an existing
file, or "append" (as in wfits new-) to append a file to an existing tape.
Most tasks accept range lists to access existing files, e.g.
.XS
cl> mtexamine mta file="3,5,9-11"
.XE
It is even possible to position a tape to a specific record within a file.
Opening a tape with file zero (as in "mta[0]") disables file positioning,
allowing the tape to be positioned with host level utilities to workaround
media problems.
.PP
There can be problems with this simple scheme however, with modern tape
devices such as DAT and Exabyte which have capacities in the gigabyte
range and which may be used to store thousands of files.  It is beyond the
scope of a revisions summary to go into this in detail here, but a simple
example will help illustrate the problem.
.PP
Assume we have a tape mounted on device "mtwd" containing 900 files.  We
want to append image "pix" as a FITS file.  The obvious thing to do is enter
the following command.
.XS
cl> wfits pix mtwd new-
.XE
This will certainly work.  The only problem is that if the tape is freshly
mounted the magtape system will not know how many files there are on the
tape, and it will have to skip forward one file at a time to count the files
and determine where EOT is.  In the worst case of a tape containing several
thousand files this could literally take hours.
.PP
If we know apriori the number of files on the tape, e.g., 900 in our example,
the following command would be much faster (something like 10-40 seconds on
most DAT drives, assuming a decent host level driver).
.XS
cl> wfits pix mtwd[901]
.XE
Of course, if there were actually 930 files on the tape, the last 30 files
would be overwritten.
.PP
There is a useful trick which works in some cases if we don't care exactly
how many files are on the tape (whether this works depends upon the specific
device and the host driver).  Assume that we know there are several hundred
files on the tape, but less than 1000.  We enter the following command to
append a file to the tape.
.XS
cl> wfits pix mtwd[1000]
.XE
If this works, after the operation the magtape system will think there are
1000 files on the tape.  A subsequent "wfits new-" would be very fast
regardless of the tape position, since so long as the magtape system knows
where the end of tape is relative to the current position, it can get there
very fast.
.PP
If the trick doesn't work for your particular device or driver you will
probably get a positioning error when attempting to position to a
nonexistent file beyond the EOT.
.PP
More automated techniques for rapid positioning with very high capacity
tapes are still a matter for study.  One promising technique would be to
formalize the above approach by supporting EOT-relative positioning.  A tape
catalog based approach is also possible.  The best approach may simply be to
not write so many small files on large tapes, by grouping images or other
data system files into a single large tape file (as with UNIX \fItar\fR).
None of these approaches are implemented in V2.10.
.NH 4
Rewind
.PP
In IRAF a magtape device is rewound with the \fIrewind\fR command, as in the
following example.
.XS
cl> rewind mta
.XE
By default this will not only rewind the tape but also initialize the
magtape system, in the sense that all cached information regarding the named
device is erased (e.g., \fInfiles\fR and \fItapeused\fR in the cached device
status).  This is necessary when changing tapes without deallocating the
drive; always do an explicit rewind (or deallocate) of the device before
removing a tape or mounting a new one.  Having \fIrewind\fR initialize
things is also useful if error recovery should fail following an interrupt
or program abort.
.PP
In some cases it may be useful to be able to do a rewind without erasing the
cached device status.  This is done by specifying the \fIinit-\fR option on
the command line.
.NH 3
New magtape driver
.PP
The IRAF magtape driver is new for V2.10.  The chief feature of the new
driver is that it is programmable, via the tapecap device entry, making it
possible to interface new devices or host drivers without having to make
any binary code changes to IRAF.  All one has to do is add a device entry
in the tapecap file.
.NH 4
Software structure
.PP
The IRAF magtape system has enough layers that it may be confusing exactly
what the magtape driver is and what role it plays.  A brief review of the
software structure may help clarify things.
.PP
Starting at the top we have applications, such as the DATAIO and MTLOCAL
tasks, which can access magtape files.  These use the IRAF/VOS interfaces
FIO (file i/o) and MTIO (magtape i/o) to do i/o to tape devices.  For the
most part i/o is done with FIO and is device independent, but a call to the
magtape system is required to open a magtape device.  The tapecap file is
read by the GTY interface, which is called by MTIO.  MTIO passes the tapecap
device entry as a string to ZFIOMT, the IRAF magtape device driver, when a
tape file is opened.  All magtape positioning and i/o is done by ZFIOMT
driver under the control of the MTIO interface.  Device allocation is done
prior to accessing the device by the CL and is handled by the allocation
routines in the ETC interface, with kernel support (this is largely
independent of the magtape system).
.PP
All of the code listed above is part of the portable IRAF system (i.e., is
OS independent and shared by all host versions of IRAF) until we get to the
ZFIOMT driver.  This is in the IRAF kernel and is host system dependent.  At
present the only version of ZFIOMT is the UNIX version; other versions,
e.g., for VMS will follow as IRAF is updated to V2.10 on these systems.  The
UNIX version of ZFIOMT uses only generic UNIX ioctls and should compile on
most UNIX systems without change.  All of the system and device dependence
has been concentrated in the tapecap file.  The ioctls used to communicate
with a UNIX tape device are fairly standard, but the semantics are often
poorly defined and are certainly not standardized.
.PP
Beneath the IRAF driver are the host level magtape device drivers.  A given
host system may have more than one of these, typically one for each class of
magtape device.  Some systems, notably Sun with their ST (SCSI tape) driver,
try to control more than one type of device with a single host driver.  The
host driver may come with the OS or may be supplied by a third party vendor.
.PP
Beneath the host driver is the actual tape device.  Often these days this is
a SCSI tape device such as a DAT or Exabyte.  These devices are intelligent
peripherals; control of the physical tape hardware resides in the tape
unit.  There is a small computer in each tape drive which communicates with
the host computer via the SCSI interface, passing commands and data back and
forth.  The drive will buffer 256K to 512K of data passed in bursts over the
SCSI bus, and then copied to or from the physical media at a much slower
rate.  These drives emulate variable size records by blocking and deblocking
within the drive unit, and writing fixed size blocks to the media.  Features
such as error correction and data compression are also handled within the
drive.
.PP
Although we usually speak of tape devices, the "magtape" device does not
have to be a tape device at all.  The IRAF magtape system can also make use
of, e.g., a floppy disk, or anything that looks like a raw disk partition.
The problem with the latter devices is that they usually don't support
files and file positioning, hence can only be used to store one "file".
.NH 4
Driver features
.PP
A detailed description of the magtape driver is beyond the scope of this
document.  Briefly, the driver supports two main classes of devices, variable
record size devices and fixed block devices.  All file positioning is handled
by the driver, and while the driver has the device open it is responsible for
keeping track of the device position (the saved device position is passed
in at open time and saved by the high level code at close time).  A couple of
dozen tapecap parameters are defined which describe the characteristics of
each device, such as whether it supports variable records, the maximum record
size, whether it can backspace, and so on.  A socket or file based status
logging feature is provided which allows detailed monitoring of the tape
status during execution (see below).
.PP
In the simplest case the new magtape system, coupled with the UNIX version
of the magtape driver, will emulate simple UNIX commands such as \fItar\fR
and \fImt\fR insofar as the requests made to the host system and magtape
device are concerned.  That is, if one writes a series of files the only
system requests made for each file will be open, write, and close.  When
reading a series of files in sequence the only requests made will be open,
read, and close.  Providing no file positioning is attempted it is possible
to get by with no file positioning requests other than rewind.  The driver
provides extensive facilities for file positioning, using tapecap parameters
to work around any shortcomings of the host system or device, but in case
of trouble it is possible to operate with only open, close, read, and write
requests, which should work for any device (unless it is truly broken).
.NH 3
Tapecap
.PP
The tapecap file, or magtape device capabilities file, defines the magtape
devices known to the system and how to access these devices.  While large
portions of this file depend only upon the host operating system and device
type and hence are fairly site independent, it will typically be necessary
to customize the tapecap file to configure the IRAF magtape system for a
site.  In normal use the tapecap file is invisible to the user, but users
with special problems may wish to learn more about tapecap to gain more
control over the behavior of the magtape system.
.NH 4
Using tapecap
.PP
The standard tapecap file is the file \f(CWdev$tapecap\fR.  A system
environment variable \f(CWtapecap\fR is defined which by default points to
this file.
.PP
Users can customize or manipulate tapecap entries in either of two ways.
The user can have their own private copy of the tapecap file (much as is
currently done with the termcap and graphcap files), by resetting the
value of the \f(CWtapecap\fR environment variable to point to their local
copy of the file.  For example,
.XS
cl> reset tapecap = home$tapecap
.XE
This may be necessary to customize a device entry, or add support for a
local device not supported by the system wide tapecap file.
.PP
It is also possible to modify a tapecap device entry "on the fly", by
overriding the values of specific tapecap parameters on the command line
when the device is accessed.  For example,
.XS
cl> mtex "mta[:so=/dev/tty]"
.XE
would override the default value of the tapecap parameter "so" for device
mta (in this case enabling status output logging and directing this output
to the user terminal).
.PP
Specifying tapecap parameters on the command line is useful for
experimentation but rapidly becomes tiresome if many commands are entered.
In this case it becomes simpler to redefine \f(CWtapecap\fR to include
the desired tapecap parameter overrides.
.XS
cl> reset tapecap = ":so=/dev/tty"
.XE
As we see, the \f(CWtapecap\fR environment variable can be used to either
specify the tapecap file name, or globally override specific tapecap
parameters (all device entries are affected).  The full form of the value
string for \f(CWtapecap\fR is
.XS
cl> reset tapecap = \fR[\fP\fItapecap-file\fP\fR] [\fP`:' \fIcapabilities-list\fP\fR]\fP
.XE
Any number of colon-delimited tapecap capabilities or parameters may be
given.
.PP
It is beyond the scope of this document to detail all the tapecap parameters
here.  A reference paper for the magtape system is planned.  For the
present, there is a summary of the tapecap parameters in the ZFIOMT driver
source file, \f(CWos$zfiomt.c\fR.  For examples of actual usage refer to the
tapecap file in the distributed system.
.NH 4
Configuring tapecap
.PP
The tapecap file uses the standard "termcap" file format, originally developed
for BSD UNIX and adopted long ago for IRAF.  Any UNIX system will probably
have a manual page defining the termcap file format, if not this can be
obtained from the IRAF group.
.PP
The distributed tapecap file is divided into three sections: the host machine
specific device aliases (names like "mta" etc.), the site logical devices,
and the generic device entries.  To customize the tapecap file for a site
you modify the first and second sections.  To configure the tapecap file for
a particular host machine you uncomment the entries for that host in the
first section of the file.  Sites which don't have a large network of hosts
may prefer to combine the first two sections to simplify things.  Site
specific changes should never be made to the bottom, or generic, part of
the tapecap file, as you will want to update this portion of the file when
new versions of IRAF are released.
.PP
Don't be intimidated by the apparent complexity of some of the tapecap device
entries.  In most cases the generic device entry will already exist for the
device you need to interface, and all you need to do is add a site entry
which references the generic entry.  In some cases the generic entry itself
may be sufficient (for example, in the distributed SunOS version of tapecap,
logical device "mtxb0" would provide access to Exabyte unit 0 interfaced
with the Sun ST driver, "mtxb1" would be the same but unit 1, "mthp0" the
HP 9 track tape on unit 0, and so on).
.PP
For example to interface Exabyte unit 2, using the Sun ST driver, as local
device "mta", the following entry would suffice.
.XS
mta|        :tc=mtst2-exb:
.XE
If the generic device entry provided doesn't quite work and minor
modifications are needed, these should be made to the \fIlocal\fR entry and
not the standard generic entry.  This is easily done with termcap parameter
redefinitions.  For example, in SunOS 4.1.2 (but not earlier versions of
SunOS) there is a bug in the Sun ST driver which necessitates rewinding the
tape after a tape scan is made to position to EOT (!).  The capabilities
":se:nb" can be added to the tapecap entry for the device to workaround this
bug, as in the following example.
.XS
mta|        :se:nb:tc=mtst2-exb:
.XE
The parameters mean that the device spaces past EOT in a read (se) and
cannot backspace (nb).  Neither of these things is actually true, but the
effect is that the tape is rewound and spaced forward to get back to the
desired file, working around the host level driver bug.  Access will be
less efficient than it should be, but the interface will work properly and
the user does not have to be concerned with the problem.
.PP
As a final example, suppose we need to write a new tapecap entry from
scratch because there is no generic entry for the device in the distributed
tapecap file.  To simplify things we assume that no special tapecap
parameters are needed, i.e., that the standard UNIX defaults builtin to
the driver will work for the device.  We are upgrading from an old version
of IRAF so we already have an old \f(CWdev$devices\fR file to work with.
For the purposes of our example we use an old HP 88780 1/2 tape drive entry,
but pretend that the device is something which is not already supported.
.LP
The old devices file entry was as follows.
.XS
mta         nrst20 nrst4 nrst12 nrst28 rst4 rst12 rst20 rst28
mta.6250    nrst20 nrst4 nrst12 nrst28 rst4 rst12 rst20 rst28
.XE
The minimal tapecap entry required to duplicate this is the following.
.XS
mta|mta6250|HP 88780 1/2 inch tape drive:\\\\
        :al=nrst4 nrst12 nrst20 nrst28 rst4 rst12 rst20 rst28:\\\\
        :dv=nrst20:lk=st4:tc=9tk-6250:
.XE
Here, the "al" parameter lists the device files to be allocated, the "dv"
parameter is the device file to be used for i/o at the desired density
(6250bpi in this case), and "lk" is the root file name to be used for the
".lok", or device status file.  The "tc=" picks up the standard parameters
for a 9 track 1/2 inch tape drive operating at 6250 bpi.  Two device
aliases are defined, "mta" and "mta6250".
.NH 4
Supported devices
.PP
The IRAF magtape system itself should support almost any magtape device if
properly configured.  What devices are actually supported at a site depends
upon the tapecap file, and in particular upon the host system (different
host systems have different tapecap files).
.TS
center;
ci ci
l l.
Device	Driver

QIC-11 cartridge tape	Sun st
QIC-24 cartridge tape	Sun st
QIC-150 cartridge tape	Sun st
Pertec compatible 1/2 inch drives	Xylogics
HP 88780 1/2 inch drive	Sun st
WangDAT 1300, 2000	ApUNIX
HP DAT	ApUNIX
Exabyte 8200, 8500	ApUNIX, Sun st, Ciprico
DC2000 cartridge tape	A/UX tc
FDHD floppy disk	A/UX fd
.TE
.PP
As an example, the tapecap file distributed in the V2.10.0 release of Sun/IRAF
supported the devices listed in the table above.  New devices are constantly
being added.  As V2.10 IRAF propagates to the various platforms on which IRAF
is supported, similar tapecap files will be configured for those systems.
.NH 3
Status output
.PP
The new magtape driver has a facility known as status output logging which
can be used to monitor interactively lengthy tape jobs while i/o is in
progress.  The status output facility can also be useful for debugging
magtape problems.
.PP
In its simplest form, the status output may be directed to a file, e.g., an
actual text file, or a terminal device.  Status output is enabled by setting
the "so" option in tapecap.  For example,
.XS
cl> mtex "mta[:so=/tmp/mta.out]"
.XE
would enable status output logging and direct the output text to the file
/tmp/mta.out.  Likewise,
.XS
cl> mtex "mta[:so=/dev/ttyp7]"
.XE
would enable status output and direct the output to a pseudoterminal, e.g.,
an xterm window.  When this form of status output logging is used one
sees the raw, driver level status messages, as in the following example.
.XS
cl> mtex "mta[:so=/dev/tty]"
open device tc2n\\\\n
devtype = Apple Tape 40SC
tapetype = DC2000
tapesize = 38500
density = na
blksize = 8192
acmode = read
file = -1
record = -1
nfiles = 0
tapeused = 0
device tc2n opened on descriptor 4\n
rewinding...
done\\\\n
position to file 1\\\\n
file = 1
record = 1
reading...\\\\n
recsize = 65536
record = 9
tapeused = 64
   \fI(etc.)\fP
.XE
.LP
The UNIX version of the new magtape driver also has an option to direct
status output to a TCP/IP socket, which can be anywhere on the network.
For this option to be useful one must have a program which will listen
on the designated socket, accept the connection when the magtape driver 
tries to open a connection, and then read and process the status messages
(which are still text, exactly as in the example above).
.PP
Status output to a socket is enabled by giving a host name instead of a
file name in the "so" directive:
.XS
cl> mtex "mta[3:so=lepus]"
.XE
to examine file 3, directing status messages to a socket on node "lepus".
.PP
An X11 client application called \fIxtapemon\fR has been developed to listen
on a socket, read messages from the tape driver, and provide a real-time
display of the status of the tape device.  While not included in the V2.10
IRAF distribution, this utility will be available later in 1992 as part of
the X11 support package currently under development.
.NH 3
Error recovery
.PP
Considerable effort went into "bullet proofing" the new magtape system to
make it recover gracefully from ctrl/c interrupts or other program aborts.
In practice it can be very difficult to reliably catch and recover from
interrupts in a multiprocess, distributed system such as IRAF.  No doubt
there are still conditions under which an interrupt will leave the magtape
system in a bad state, but in most circumstances the system should now be
able to successfully recover gracefully from an interrupt.
.PP
If it is necessary to interrupt a tape operation, it is important to
understand that the host system will not deliver the interrupt signal to the
IRAF process until any pending i/o operation or other driver request
completes.  For example, in a read operation the interrupt will not be acted
upon until the read operation completes, or in a tape positioning operation
such as a rewind or file skip forward, the interrupt will not be acted upon
until the tape gets to the requested position.  For a device such as a disk
you rarely notice the delay to complete a driver request, but for a magtape
device these operations will take anywhere from a few seconds to a few tens
of seconds to complete.  Type ctrl/c once, and wait until the operation
completes and the system responds.
.PP
If a magtape operation is interrupted, the IRAF error recovery code will
mark the tape position as undefined (\fIdevstatus\fR will report a file
number of -1).  This will automatically cause a rewind and space forward
the next time the tape is accessed.  The rewind is necessary to return the
tape to a known position.
.NH 3
Device optimization
.PP
In addition to making it possible to characterize the behavior of a magtape
device to permit the device to be accessed reliably, the tapecap facility is
used to optimize i/o to the device.  The parameter "fb" may be specified for
a device to define the "optimum" FITS blocking factor for the device.
Unless the user explicitly specifies the blocking factor, this is the value
that the V2.10 \fIwfits\fR task will use when writing FITS files to a tape.
Note that for cartridge devices a FITS blocking factor of 22 is used for
some devices; at first this may seem non-standard FITS, but it is perfectly
legal, since for a fixed block size device the FITS blocking factor serves
only to determine how the program buffers the data (for a fixed block device
you get exactly the same tape regardless of the logical blocking factor).
For non-FITS device access the magtape system defines an optimum record size
which is used to do things like buffer data for cartridge tape devices to
allow streaming.
.PP
Some devices, i.e., some DAT and Exabyte devices, are slow to switch between
read and skip mode, and for files smaller than a certain size, when skipping
forward to the next file, it will be faster to read the remainder of the
file than to close the file and do a file skip forward.  The "fe" parameter
is provided for such devices, to define the "file equivalent" in kilobytes
of file data, which can be read in the time that it takes to complete a
short file positioning operation and resume reading.  Use of this device
parameter in a tape scanning application such as \fIrfits\fR can make a
factor of 5-10 difference in the time required to execute a tape scan of
a tape containing many small files.
.PP
On most cartridge tape devices backspacing, if permitted at all, is very
slow.  On such devices it may be best to set the "nf" parameter to tell
the driver to rewind and space forward when backspacing to a file.
.NH 3
MTIO interface changes
.PP
A number of new routines were added to the MTIO (magtape i/o) programming
interface.  These are documented in the summary of programming environment
revisions given below.  Existing magtape applications may benefit from
being modified to make use of these new routines.

.NH 2
Graphics and Imaging Subsystem Enhancements
.NH 3
New graphics applications
.PP
New tasks for histogram plotting, radial profile plotting, and producing
lists of the available graphics devices have been added to the PLOT
package.  All of the tasks in this package were revised to add support for
world coordinates.  A related task for drawing world coordinate grid
overlays on images or plots was added to the IMAGES.TV package.  See the
appropriate sections of \fIIRAF and NOAO package revisions\fP below for
further information on these changes.
.NH 3
Graphics system changes
.NH 4
Encapsulated postscript SGI kernel
.PP
A new encapsulated postscript SGI kernel has been added.  Graphics output
may be directed to any of the logical graphics devices \fIeps\fR, \fIepsl\fR,
\fIepshalf\fR, etc. to render a plot in encapsulated postscript, e.g., for
inclusion as a figure in a document.  For example,
.XS
cl> prow dev$pix 101 dev=eps; gflush
.XE
will leave a ".eps" file containing the plot in the current directory.
The command "gdev dev=eps" will produce a list of the available EPS
logical graphics devices.
.NH 4
Graphics output to the default printer
.PP
Graphics output (SGI postscript) can now be directed to the UNIX default
printer device by directing output to any of the logical devices "lpr",
"lp", or "lw".
.XS
cl> prow dev$pix 101 dev=lpr
.XE
.PP
Output will be sent to the default device for the UNIX
\fIlpr\fR command (set by defining "PRINTER" in your UNIX environment).
This makes it possible to make immediate use the distributed IRAF graphcap
without having to add entries for specific local devices (although you
may still wish to do so).
.NH 4
Tick spacing algorithm improved
.PP
The algorithm used to draw the minor ticks on IRAF plots was replaced by an
improved algorithm contributed by the STScI STSDAS group (Jonathan
Eisenhamer in particular).  This was derived from similar code in Mongo.
.NH 4
Graphics metacode buffer
.PP
The default maximum size of the graphics metacode buffer in the CL, used to
buffer graphics output for cursor mode interaction, was increased from 64K
to 128K graphics metacode words (256Kb).  The \f(CWcmbuflen\fR environment
variable may be used to change this value.
.NH 4
IMTOOL changes
.PP
The \fIimtool\fR display server (SunView) was enhanced to add additional
builtin color tables, support for user color tables, and setup panel control
over the screen capture facilities.  A version supporting encapsulated
postscript output is in testing.  This will be the final version of the
SunView based version of imtool (the new display servers are all X
window system based).
.NH 4
IMTOOLRC changes
.PP
The \f(CWimtoolrc\fR file, used by display servers such as \fIimtool\fR and 
\fIsaoimage\fR to define the available image frame buffer configurations,
has been relocated to the DEV directory to make it easier for local site
managers to customize.  The IRAF install script now uses a link to point to
this file, rather than copying it to /usr/local/lib.  The maximum number of
frame buffer configurations was increased from 64 to 128.
.NH 4
X11 support
.PP
The released version of V2.10 does not contain any changes insofar as X11
support is concerned.  Since our X11 support code is host level stuff, with
minimal ties to IRAF per se, it is being developed independently of the V2.10
release and will be distributed and installed as a separate product.

.NH 2
Image Structures
.NH 3
Image I/O (IMIO)
.PP
The image i/o interface (IMIO) is that part of the IRAF system responsible
for imagefile access and management.  The changes to IMIO for V2.10 included
the following.
.NH 4
Null images
.PP
Null images are now supported for image output, much like the null files
long supported by the file i/o system.  For example,
.XS
cl> imcopy pix dev$null
.XE
would copy the image "pix" to the null image.  This exercises the software
but produces no actual output image.  Unlike null files, null images do not
work for input since images have some minimal required structure, whereas
files can be zero length.
.NH 4
Preallocating pixel file storage
.PP
In the UNIX versions of IRAF, when a new image is created storage is not
physically allocated for the output image until the data is written.  This
is because most UNIX systems do not provide any means to preallocate file
system storage.  The UNIX/IRAF file creation primitive \fIzfaloc\fR, used by
IMIO to create pixel files, now provides an option which can be used to
force storage to be physically allocated at file creation time.  This feature
is enabled by defining the environment variable \f(CWZFALOC\fR in the UNIX
environment.  For example,
.XS
% setenv ZFALOC
.XE
can be entered before starting IRAF to cause space for all pixel files to
be preallocated as images are created.  If it is not desired to preallocate
all image storage (there is a significant runtime overhead associated with
preallocating large images) then a value string can be given to specify
which types of images to preallocate storage for.  For example,
.XS
% setenv ZFALOC /scr5
.XE
would preallocate only those pixel files stored on the /scr5 disk, and
.XS
% setenv ZFALOC "/scr5,zero"
.XE
would preallocate only images on /scr5, or images containing the substring
"zero" in the image name.  In general, the string value of \f(CWZFALOC\fR
may be the null string, which matches all images, or a list of simple
pattern substrings identifying the images to be matched.
.PP
In most cases the default behavior of the system, which is to not physically
allocate storage until the data is written, is preferable since it is more
efficient.  The preallocation option is provided for users who, for example
might have an application which spends a lot of time computing an image,
and they want to ensure that the disk space will be available to finish
writing out the image.
.NH 4
Image templates now sorted
.PP
As mentioned earlier in the \fISystem Management\fR section, UNIX/IRAF now
sorts UNIX directories.  One result of this is that the sections of image
templates which are expanded via pattern matching against a directory will
now be sorted, or at least logically ordered (the final output list will not
necessarily be fully sorted if string substitution is being performed - this
is the reason the output list itself is not sorted).
.NH 4
The dev$pix test image
.PP
Minor changes were made to clean up the image header of the standard test
image \f(CWdev$pix\fR.  A second test image \f(CWdev$wpix\fR has been
added.  This is the same image, but with a different header containing a
test world coordinate system (actually the image is just a second image
header pointing to the \f(CWdev$pix\fR pixel file, now shared by both
images).
.NH 3
Image kernels (IKI)
.PP
The IMIO image kernels are the data format specific part of the IRAF image
i/o subsystem.  Each kernel supports a different image format.  Existing
disk image formats range from the conventional image raster formats (OIF
and STF) to the photon image format (QPF and QPOE) and the pixel mask
image format (PLF and PMIO/PLIO).  There also exist special image kernels
which allow IMIO to be used to access non-disk storage devices such as
image display frame buffers.
.NH 4
New PLF image kernel
.PP
A new image kernel, the PLF image kernel, has been added which allows IRAF
PMIO/PLIO pixel masks to be stored as images.  This kernel first appeared
as a patch to version 2.9 IRAF but was actually developed within V2.10.
.PP
Pixel mask images may be created, deleted, read, written, etc. like other
IRAF images, but the image is stored in a special compressed format designed
specially for image masks.  An image mask is an N-dimensional raster-like
object wherein typically there are regions of constant value but arbitrary
shape.  Masks are used by applications involving image decomposition.  The
image is decomposed into regions of different types, the type of region
being very dependent upon the type of image analysis being performed.  A
special type of mask image is the bad pixel mask, used to flag the bad
pixels in an image.  Other applications use masks for data quality, to
identify the region or regions to be used for analysis, and so on.
.PP
A PMIO image mask is a special case of a PLIO pixel list.  Masks can exist
and be accessed independently of the image i/o system, but the PLF image
kernel allows a mask to be stored and accessed as an IRAF image.  Any IRAF
application which operates upon images can operated upon a mask image.
For example, the \fIimcalc\fR (image calculator) program in the SAO XRAY
package can be used to combine images and masks, or compute new masks
by evaluating an algebraic expression over an image.
.PP
Mask images have the reserved image extension ".pl".  Some of the features
of mask images are illustrated by the following example.
.XS
cl> imcopy dev$pix pix.pl
dev$pix -> pix.pl
cl> imstat dev$pix,pix.pl
#     IMAGE      NPIX      MEAN    STDDEV       MIN       MAX
    dev$pix    262144     108.3     131.3       -1.    19936.
     pix.pl    262144     108.3     131.3        6.    19936.
.XE
This is a sort of worst case test of the mask encoding algorithm, since
our test image is not a mask but a noisy image (and hence not very
compressible).  Note that masks must be positive valued, hence the MIN
value is different for the two images.  Storing \f(CWdev$pix\fR as a
mask does not result in any significant compression, but for a real
mask very high compression factors are possible.  The compression algorithm
used in PLIO is simple and fast, combining 2D run length encoding and a
differencing technique in a data structure allowing random access of
multidimensional masks (masks are not limited to one or two dimensions).
.PP
For further information on pixel lists and pixel masks, see the document
\f(CWplio$PLIO.hlp\fR in the online system.  This is also available as
\f(CWplio.txt.Z\fR in the IRAF network archive.
.NH 4
OIF image kernel changes
.PP
The OIF image kernel is the kernel for the old IRAF image format - this is
still the default IRAF image format.  Revisions to the OIF kernel for V2.10
included the following items.
.RS
.IP \(bu
A valid image header is now written even if an application which writes to
a new image is aborted.  Previously, the pixel file would be written but
the image header would be zero length until the image was closed.  If an
image creation task aborts the image will likely be incomplete in some way,
e.g., part of the pixels may not have been written to, or the header may
be missing application specific keywords.  By valid image header we mean
that the header will be valid to IMIO, allowing the image to be accessed
to try to recover the data, or to delete the image.
.IP \(bu
The image header file of a new image is now written to and closed at image
create time, then reopened at image close time to update the header.  This
frees one file descriptor, an important consideration for applications
which for some reason need to write to dozens of output images
simultaneously.
.IP \(bu
The OIF image kernel uses file protection to prevent inadvertent deletion of
the image header file.  In UNIX/IRAF systems file delete protection is
simulated by creating a ".." prefixed hard link to the file.  This could
cause problems with images if the user deleted the image header file outside
of IRAF, leaving the ".." prefixed link to the file behind.  A subsequent
image create operation with the same image name would fail due to the
existence of the hidden ".." prefixed file.  It is unlikely that such a
file (with a ".." prefix and a ".imh" extension) could ever be anything but
an old IRAF image header file, so the system will now silently replace such
files when creating a new image.
.RE
.PP
A couple of related system changes were made which, while not implemented in
the OIF kernel, do involve the OIF or ".imh" image format.  The default
template \f(CWlogin.cl\fR now defines the environment variable
\f(CWimtype\fR and sets it to "imh".  The environment variable
\f(CWmin_lenuserarea\fR is also defined now at login time, with a default
value of 20000, allowing image headers with up to about 250 header
parameters.
.NH 4
STF image kernel changes
.PP
The STF image kernel is the kernel for the online HST (Hubble Space Telescope)
image format.  This format allows multiple images to be grouped together in
a single "group format" image.  There is a common image header stored in a
FITS-like format, as well as a small fixed format binary header associated
with each image in the group.
.RS
.IP \(bu
A check was added for a group index out of range.  This yields a more
meaningful error message about no such group, rather than having IMIO
complain about a reference out of bounds on the pixel file.
.IP \(bu
Support was added for non-group STF images (GROUPS=F in the header).
At first glance a non-group group format image might seem a little silly,
but it turns out that a non-group STF image with a zero length group
parameter block is very close to "FITS on disk", since the header is
FITS-like and the image matrix is simple.  It is still not true FITS
since the header and pixels are stored in separate files and the pixels
are not encoded in a machine independent form, but on UNIX hosts which
are IEEE standard and not byte swapped, it comes close enough to be useful
for communicating with external applications in some cases.
.RE
.PP
A true FITS image kernel is planned for IRAF.  This will probably appear
in one of the V2.10 patches, sometime during 1992.
.NH 4
QPF image kernel changes
.PP
The QPF image kernel is the interface between the QPOE (position ordered
event file) interface and IMIO, allowing QPOE event files to be accessed as
images by general IRAF applications.  Photon "images" are unique in that the
image raster is generated at runtime as the image is accessed, optionally
passing the photon list through event attribute and spatial filters, and
sampling the photons to produce a raster image.  For example,
.XS
cl> imcopy "snr[time=@snr.tf,bl=4]" snr.imh
.XE
would filter the event list stored in the file "snr.qp" by the time filter
stored in file "snr.tf", sample the image space blocking by a factor of 4,
and store the resultant image raster in the OIF image file "snr.imh".
.XS
cl> display "snr[time=@snr.tf,bl=4]" 1
.XE
would display the same image raster without creating an intermediate disk
image.
.LP
The changes to the QPF interface for V2.10 included the following.
.RS
.IP \(bu
A bug was fixed which would prevent very long filter expressions from being
correctly recorded in the IMIO image header.  The current version of IMIO
stores applications header parameters in FITS format, hence multiple FITS
cards are required to store long filter expressions.  The bug would cause
only one such card to be output.
.IP \(bu
A new facility was added which allows general expressions to be computed for
the input event list and stored as keywords in the output image header.  The
header of the input QPOE file can contain one or more parameters named
\fIdefattr1\fR, \fIdefattr2\fR, and so on.  If present, the string value of
each such parameter should be a statement such as
.XS
exptime = integral time:d
.XE
which will cause a keyword named "exptime" to be added to the output image
header, the scalar value of the keyword being the value of the expression on
the right.  Currently, only the integral function is provided.  This
computes the included area of a range list field of the event attribute
expression, such as a time filter.  In the example, "time" is the name of
the event attribute to be integrated, and the ":d" means use a range list of
type double for the computation.  The data types currently supported are
integer, real and double.
.RE
.PP
Other minor changes to QPF included improvements to the error recovery,
and other changes to support very large filters.
.NH 3
World coordinate system support (MWCS)
.PP
MWCS is the IRAF world coordinate system package, one of the major new
system interfaces developed for the new image structures project.
A full description of the MWCS interface is given in the file
\f(CWmwcs$MWCS.hlp\fR in the online system, and in the file \f(CWmwcs.txt.Z\fR
in the IRAF network archive.
.NH 4
Applications support
.PP
MWCS was first released in V2.9 IRAF and at the time the interface was new
and few applications were yet using it.  In V2.10 IRAF most (but not all)
applications which deal with coordinates now use MWCS.  These include all of
the system plotting tasks, and the spectral reduction packages.  Details of
the MWCS support added to the system and science applications in V2.10 are
given in the \fIIRAF and NOAO package revisions\fR section of this revisions
summary.
.NH 4
New function drivers
.PP
Function drivers for the \fIarc\fR, \fIsin\fR, and \fIgls\fR nonlinear sky
projections were added, as well as a special function driver for the 
\fImultispec\fR image format.  The latter allows general programs which
don't know anything about spectra to access and display spectra in world
coordinates, e.g., for plotting.
.NH 4
WCS attributes
.PP
The maximum number of "attributes" per WCS was increased from 64 to 256,
mainly to support the multispec function driver, which makes heavy use of
attributes.  A limit on the size of a single attribute value string was
removed, allowing arbitrarily large attribute values to be stored.
.NH 4
Axis mapping
.PP
Axis mapping is now fully implemented.  Axis mapping is used when, for
example, you extract a 2 dimensional section from a 3 dimensional image
and write the result to a new image.  Axis mapping allows the 2 dimensions
of the new image to be mapped backed into the original 3 dimensional WCS,
making it possible to get the full physical coordinates (which are 3
dimensional) for any point in the extracted image.  A new header keyword
\f(CWWAXMAP\fInn\fR was added to store the axis map in image headers.
.NH 4
MWCS save format
.PP
The newer IRAF image formats such as QPOE are capable of storing arbitrarily
complex objects such as a MWCS in an image header keyword.  In the case of a
stored MWCS object, the MWCS interface is responsible for encoding the
object in its external storage format, and restoring it to a MWCS descriptor
when the MWCS is accessed.  The code which does this was revised to add a
new version number for the stored V2.10 MWCS, to make it possible to
differentiate between the MWCS save formats used in V2.9 and V2.10 and allow
recovery of MWCS objects from data files written under V2.9.
.NH 4
Bug fixes
.PP
Since MWCS is a new interface and V2.10 saw its first real use in
applications, a number of interface bugs were discovered and fixed.  Most of
the bugs turned out to be in the part of MWCS which converts between the
internal MWCS WCS representation, and the FITS WCS representation, used for
those image formats that still use FITS-like headers.  Bug fixes included a
problem with the treatment of CROTA2, a problem with the FITS CD matrix, an
axis mapping problem that caused "dimension mismatch" errors, and a problem
with support for the old-style CDELT/CROTA which could result in a singular
matrix during WCS inversion when compiling a transformation.
.NH 3
Event files (QPOE)
.PP
The QPOE interface is the interface responsible for creating and accessing
\fIevent files\fR, the main data format produced by event counting
detectors.  We summarize here the main enhancements to QPOE made during the
preparation of V2.10.  Some of these features appeared earlier in the
patches made to V2.9 IRAF but these revisions have never been formally
documented so we summarize both the old and new revisions here.  See also
the discussion of the QPF image kernel given earlier.
.NH 4
Blocking factors
.PP
The builtin default blocking factor, when sampling the event list to make
an image raster, is one.  This may be changed on a per-datafile basis by
defining the parameter \fIdefblock\fR in the QPOE file header.
.NH 4
Parameter defaults
.PP
Since parameters such as the blocking factor can be set at a number of levels,
a parameter defaulting scheme was defined to determine the precedence of
parameter overrides.  The lowest level of precedence is the builtin default.
Next is any datafile specific value such as \fIdefblock\fR.  A value such
as \fIblockfactor\fR set in the QPDEFS file will override the datafile
default value if any.  Specifying the parameter value in a runtime filter
expression or \fIqpseti\fR call is the highest order of precedence and will
override any other setting.
.PP
Another way to think of this is the more recently the parameter was set, the
higher the precedence.  The oldest value is the default builtin to the
code.  Next is the datafile value, usually set when the datafile was
created.  Next is the QPDEFS macro file, usually set by the user or for a
site.  Last (highest precedence) is the value set by the user when the data
is accessed.
.NH 4
Referencing the current datafile in macros
.PP
A special symbol \f(CW$DFN\fR is now recognized during macro expansion and
if present is replaced by the filename of the current QPOE file.  This allows
macros to be written which automatically perform some operation involving
the datafile to which they applied, e.g., computing an attribute list from
aspect or data quality information stored in the datafile header.
.NH 4
Bitmask expressions
.PP
Bitmask expressions may now be negated, e.g., "%3B" is the mask 03 octal,
"!%3B" or "!(%3B)" is the complement of 03 octal.
.NH 4
Large time filters
.PP
A number of changes and bug fixes were made to QPOE for V2.10 to support
large time filters.  These are lists of "good time" intervals used to filter
the event list.  These large time filters may contain several hundred
double precision time intervals spanning the exposure period.  Often a
large time filter is combined with a complex spatial filter (PLIO mask) to
filter an event list consisting of from several hundred thousand to several
million events.  QPOE can handle this efficiently regardless of whether
the data is temporarily or spatially sorted and regardless of the complexity
of the temporal or spatial filters.
.PP
A number of minor bugs were fixed caused by the large filter expressions
overflowing various buffers.  The default sizes of the program and data
buffers used to compile filter expressions were increased to allow all but
very large filters to be compiled without having to change the defaults.
If the buffers overflow more space can be allocated by setting the
\f(CWprogbuflen\fR and \f(CWdatabuflen\fR parameters in QPDEFS (these
buffers are not dynamically resized at runtime for efficiency reasons).
During testing with large time filters it was discovered that a routine
used to test floating point equality was being used inefficiently, and
compilation of large time filters was taking a surprisingly long time.
A change was made which reduced the time to compile large filters by a
factor of 10 to 15.
.NH 4
Default filters
.PP
QPOE now fully supports default event attribute and spatial filtering of
data at runtime.  The idea is that the full data set (all events) is stored
in the QPOE file, along with default event attribute and spatial filters.
When the data is accessed these filters are, by default, automatically
applied.  Any user specified event attribute or spatial filters are "added"
to the builtin default filters to produce the combined filter used when the
event list is accessed.  The point of all this is to make it easy for the
user to modify or replace the default filters and "reprocess" the raw event
list.  In effect the raw and processed event list are available in the same
file.
.PP
The default filter and mask, if any, are stored in the datafile header
parameters \f(CWdeffilt\fR and \f(CWdefmask\fR.  If the datafile contains
multiple event lists a default filter or mask may be associated with
each list by adding a period and the name of the event list parameter,
e.g., "deffilt.foo" would be the default filter for the event list "foo".
.PP
By default, if a default filter or mask exists for an event list it is
automatically applied when the event list is accessed.
Use of the default filter or mask can be disabled in QPDEFS with either
of the following statements:
.XS
set nodeffilt
set nodefmask
.XE
The default filter and mask can also be disabled in a filter expression
by adding a "!" before the expression, as in the following example.
.XS
display "snr[!time=@times.lst,pha=(3,8:11)]"
.XE
There are actually several variants on the "=" assignment operator used
in filter expressions such as that above.  The operator "=" is equivalent
to "+=", meaning the expression term on the right adds to any existing
filter specified for the event attribute on the left.  The operator ":="
on the other hand, means \fIreplace\fR any existing filter by the new
filter expression.
.NH 4
Alternate coordinate systems
.PP
The event structure used to represent each event in an event list may
contain multiple coordinate systems if desired, for example, detector and
sky coordinates.  One coordinate system should be defined as the default
when the event list is created, and if the event list is to be indexed
it must be sorted using the coordinate system specified as the default.
Any coordinate system may be used when the data is accessed however;
this can result in quite different views of the same data set.  For example,
.XS
cl> display snr.qp 1
.XE
would display the QPOE file "snr.qp" in display frame 1, using all defaults
for the event list, blocking factor, filter, mask, and so on.  The default
event coordinate system would probably be sky coordinates.  To display the
same event list in detector coordinates, one could enter the following
command.
.XS
cl> display "snr.qp[key=(dx,dy)]" 1
.XE
This assumes that the event structure fields "dx" and "dy" are defined
somewhere, either in the datafile header or in QPDEFS (otherwise the actual
field datatype-offset codes must be given).
.PP
Currently if the QPOE datafile has a WCS associated with it this WCS can
only refer to one coordinate system, normally the default event coordinate
system.  Additional WCS can be stored in the QPOE file, either in the stored
MWCS object or as separate MWCS objects, but at present there is no
mechanism for selecting which will be used (if the parameter \f(CWqpwcs\fR
exists in the QPOE file header, this is assumed to be a stored MWCS object
and this is the WCS which will be used).

.NH 2
System Specific Changes
.NH 3
Sun/IRAF
.PP
Since V2.10 has only just been completed and at this stage has only been
released on Sun platforms, there are few system specific revisions to report.
For SunOS there were several system specific revisions worth noting here.
.RS
.IP \(bu
The HSI binaries for the sparc architecture are now statically linked.
This makes them considerably larger, but avoids problems with SunOS
complaining about shared library version mismatches (note that we refer
here to to Sun shared libraries - this is not a problem with the IRAF
shared library facility since we control the version numbers).
.IP \(bu
The HSI binaries for the Motorola architectures (f68881 and ffpa) are
\fInot\fR statically linked since they cannot be without running into
linker problems warning about f68881_used etc.  To avoid or at least
minimize warnings about SunOS shared library versions the system was
linked on 4.1.1 instead of 4.1.2.  SunOS 4.0.3 versions of the Motorola
HSI binaries are also available upon request.
.IP \(bu
The system as distributed was linked with the name server library,
\f(CW-lresolv\fR.  This means that if the local host is configured to
use the name server, IRAF will be able to access almost any host on the
Internet without an entry in the \f(CW/etc/hosts\fR file on the local host.
.RE
.PP
Additional system specific changes will be reported in the documentation
distributed with each release, as V2.10 is moved to the various platforms
for which IRAF is supported.

.bp
.NH
IRAF and NOAO package revisions
.PP
The revisions for the various packages in the IRAF core system and in the
NOAO packages are summarized below. There have been many changes with this
release.  Users are encouraged to refer to the help pages, user's guides
provided with some packages, revisions notes, and more recent issues of IRAF
Newsletters for more details.  Comprehensive notes on systems and
applications modifications are in the files \f(CWpkgnotes.v210.Z\fP and
\f(CWsysnotes.v210.Z\fP in the directory \f(CWiraf/v210\fP in the network
archive.  This summary can be read online by typing \fInews\fP.  Revisions
notes for the various packages can also be accessed online as in the
following example.
.XS
cl> phelp dataio.revisions opt=sys
.XE
.PP
One of the system changes that affects many tasks in the IMAGES, PLOT, and
LISTS packages as well as most tasks in the spectroscopic packages in NOAO
is the full implementation of the world coordinate system (WCS), introduced
in V2.9 but not fully integrated into the IRAF and NOAO tasks at that time.
There are currently three classes of coordinate systems: the logical system
is in pixel units of the current image section; the physical system is in
pixel units of the parent image (for a WCS associated with a raster image);
the world system can be any system defined by the application, e.g. RA and
DEC or wavelength.  In general, this should be transparent to the user since
most defaults have been chosen carefully so that tasks perform the same as
in V2.9.  The NOAO spectroscopic tasks also use the WCS extensively, but
again, this should be transparent to the user, although it can cause some
problems with backward compatibility.  Users will notice the biggest
difference in the image headers with additional keywords added by the
interface.  Two tasks in the PROTO package may help the interested user
understand more about the WCS - see \fIwcsedit\fP and \fIwcsreset\fP.
Technical notes on the WCS are available in a paper in the
\f(CWiraf$sys/mwcs\fP directory.  Type the following to read more about the
MWCS interface.
.XS
cl> phelp mwcs$MWCS.hlp fi+
.XE
.NH 2
Changes to the IRAF system packages
.NH 3
DATAIO package modifications
.IP \(bu
The output defaults for \fIwfits\fP have been modified.  If the pixel type on
disk is real or double precision the output will be IEEE format (FITS
bitpix = -32 or -64, respectively).  If the pixel type on disk is short
integer then the output will be integer format (bitpix = 16) as before.
These defaults can of course be changed by modifying the parameters for
\fIwfits\fP.
.IP \(bu
The \fIwfits\fP "blocking_factor" parameter can accept values up to and
including 10 for variable blocked devices, i.e. 1/2" tape drives, Exabytes,
and DATs.  If the "blocking_factor" parameter is set to "0", as in the
default, the value is read from the "fb" parameter in the tapecap file
(usually 10 for variable blocked devices).  For fixed blocked devices such
as cartridge tape drives the default value for the "fb" parameter in the
tapecap file is 22 (used to determine a buffer size) and the block size
of the device is given by the "bs" parameter.
.IP \(bu
All tasks were modified to accept tapecap parameters as part of the magtape
file name syntax.  Tapecap
parameters can now be appended to the magtape file name to add to or
override values in the tapecap file.  For example,
\f(CW"mta6250[:se]"\fP is a valid magtape file name (the "" are important
when tapecap parameters are specified at execution time).  See the file
\f(CWos$zfiomt.c\fP for more details about the tapecap parameters.
.IP \(bu
The \fIrfits\fP task has been modified to permit a short last record, i.e. a last
record that has not been padded out to 2880 bytes.  No warning messages
are issued.
.IP \(bu
\fIrfits\fP was modified to map ASCII control characters in the header to blanks.
.IP \(bu
The sequence number appended to disk file names by \fIrfits\fP and \fIwfits\fP was
modified to 4 digits, i.e. 0001 - 9999.
.NH 3
IMAGES package modifications
.IP \(bu
WCS (world coordinate system) support was added to all tasks in the IMAGES 
package that could introduce a coordinate transformation.  Some tasks had 
already been modified for the V2.9 release.  These tasks
(\fIblkavg\fP, \fIblkrep\fP, \fIgeotran\fP, \fIimcopy\fP, \fIimlintran\fP, \fIimshift\fP, \fIimslice\fP, \fIimstack\fP, 
\fIimtranspose\fP, \fImagnify\fP, \fIregister\fP, \fIrotate\fP, and \fIshiftlines\fP), upon execution,
will update the image header to reflect any transformation.
.IP \(bu
The \fIlistpixels\fP task was modified to list the pixel coordinates in either
logical, physical, or world coordinates.  A format parameter was added to
the task for formatting the output pixel coordinates taking precedence over
the WCS in the image header, if used.
.IP \(bu
A new \fIimcombine\fP task was added to the package.  This new task supports 
image masks and offsets, and has an assortment of new combining algorithms.
See the help pages for complete details on this powerful new task.
.IP \(bu
The \fIimhistogram\fP task has a new "binwidth" parameter for setting histogram
resolution in intensity units.
.IP \(bu
The default values for the parameters "xscale" and "yscale" in the
\fIregister\fP and \fIgeotran\fP tasks were changed from INDEF to 1.0, to preserve the
scale of the reference image.
.NH 3
IMAGES.TV package reorganization and  modifications
.IP \(bu
The TV package has been reorganized.  The IIS dependent tasks have been moved
into a subpackage, TV.IIS.  The \fIimedit\fP, \fIimexamine\fP, and \fItvmark\fP tasks that were
previously in PROTO have been moved to TV.
.IP \(bu
A new task \fIwcslab\fP developed at STScI by Jonathan Eisenhamer was added
to the package.  \fIwcslab\fP overlays a labeled world coordinate grid on an
image using WCS information stored in the header of the image or in
parameters of the task.
.IP \(bu
\fIimexamine\fP was modified to use WCS information in axis labels and
coordinate readback, if selected by the user.  Two new parameters, "xformat"
and "yformat", were added to specify the format of the WCS if it is not
present in the header of the image.
.IP \(bu
A new option was added to \fIimexamine\fP to allow for fitting 1D gaussians to
lines or columns.
.IP \(bu
\fItvmark\fP had two cursor key changes.  The "d" keystroke command that marked
an object with a dot was changed to "."; the "u" keystroke command that
deleted a point was changed to "d".
.NH 3
LISTS package modifications
.IP \(bu
Two new parameters were added to the \fIrimcursor\fP task, "wxformat" and 
"wyformat". These parameters allow the user to specify the coordinate
formats for the output of the task and override any values stored in the
WCS in the image header.
.NH 3
OBSOLETE package added
.IP \(bu
An new package called OBSOLETE was added.  Tasks will be moved to this
package as they are replaced by newer tasks in the system.  OBSOLETE tasks
will then be removed at the time of the next release.
.IP \(bu
\fImkhistogram\fP, \fIimtitle\fP, \fIradplt\fP, and the old \fIimcombine\fP task have been moved to the
OBSOLETE package.  Users should become familiar with \fIphistogram\fP, \fIhedit\fP,
\fIpradprof\fP, and the new \fIimcombine\fP and use
them instead since \fImkhistogram\fP, \fIimtitle\fP, \fIradplt\fP, and \fIoimcombine\fP will be
retired with the next release.
.NH 3
PLOT package modifications
.IP \(bu
A new task called \fIphistogram\fP was added to the PLOT package.  This task
takes input from an image or from a list and allows full control
over the plotting parameters.  This task replaces the \fIobsolete.mkhistogram\fP
task.
.IP \(bu
A new task \fIpradprof\fP was added to the PLOT package.  This task plots or lists
the radial profile of a stellar object.  This task replaces the
\fIobsolete.radplt\fP task.
.IP \(bu
A new task called \fIgdevices\fP was added to the package.  \fIgdevices\fP prints
available information known about a particular class of device.  The
default parameters are set up to print a list of the available stdimage
devices in the standard graphcap file.
.IP \(bu
WCS support was added to the tasks \fIgraph\fP, \fIpcol(s)\fP, and \fIprow(s)\fP.  A new
parameter called "wcs" was added to define the coordinate system to be
used on the axis, either logical, physical or world.  Two additional
parameters, "xformat" and "yformat", were also added to allow the user to set
the format for axis labels overriding any values in the image header.
The "xlabel" parameter values were extended to include the special word
"wcslabel" to select the WCS label for the x axis from the image header.
.IP \(bu
WCS support was added to the task \fIimplot\fP.  A new parameter called
"wcs" was added to define the coordinate system for plotting, either logical,
physical, or world.  Two new ":" commands were also added: ":w" allows
the user to set a new WCS type interactively; ":f" allows the user
to change the axis format, for instance, ":f %H" would change the axis
to read h:m:s, if the world coordinate RA had been defined in the image
header.  The "space" key now prints out the coordinate and pixel value
information.
.IP \(bu
\fIgraph\fP has a another new parameter "overplot" that allows the user to overplot
multiple plots with different axes.
.IP \(bu
The default parameters for "floor" and "ceiling" in \fIcontour\fP and \fIsurface\fP were
changed to INDEF.
.NH 3
PROTO package reorganization and modifications
.PP
This package has been reorganized.  The PROTO package now resides in the
core system.  Tasks in the old PROTO package that were general image
processing tools were kept in this new PROTO package.  Tasks that were more
data reduction specific were moved to the new NPROTO package in the NOAO
package.  The current PROTO package now contains the tasks \fIbinfil\fP,
\fIbscale\fP, \fIepix\fP, \fIfields\fP, \fIfixpix\fP, \fIhfix\fP,
\fIimalign\fP, \fIimcentroid\fP, \fIincntr\fP, \fIimfunction\fP,
\fIimreplace\fP, \fIimscale\fP, \fIinterp\fP, \fIirafil\fP, \fIjoinlines\fP,
\fIsuntoiraf\fP, \fIwcsedit\fP, and \fIwcsreset\fP.
.IP \(bu
The new task \fIhfix\fP was added to the package. This task allows the user to
extract the image headers into a text file, view or modify this file with a 
specified command, and then update the image header with the modified file.
.IP \(bu
A new task called \fIsuntoiraf\fP was added to this package.  This is a host
dependent task that will most likely be useful only on Sun's.  This task
converts a Sun raster file into an IRAF image.
.IP \(bu
Two new tasks dealing with the WCS were added to this package,
\fIwcsreset\fP and \fIwcsedit\fP.  \fIwcsreset\fP resets the coordinate
systems in the image header to the logical coordinate system.  \fIwcsedit\fP
allows the user to modify the existing WCS or to create a new WCS and then
update the image header.
.IP \(bu
A new version of \fIbscale\fP was added to the package.  The task now takes a 
list of input images and output images.
.IP \(bu
A new version of \fIimfunction\fP was added to the package.  The task supports
many more functions, for example log10, alog10, ln, aln, sqrt, square, cbrt,
cube, abs, neg, cos, sin, tan, acos, asin, atan, hcos, hsin, htan, and
reciprocal.
.IP \(bu
\fIimreplace\fP was modified to support the "ushort" pixel type.
.IP \(bu
The task \fIjoin\fP has been renamed \fIjoinlines\fP.
.NH 3
Additions to XTOOLS and MATH
.PP
Programmers may be interested in the following new additions to the XTOOLS
and MATH libraries.
.IP \(bu
The interactive non-linear least squares fitting package INLFIT, developed by
Pedro Gigoux at CTIO, was added to XTOOLS.
.IP \(bu
The 1D image interpolation routines in the MATH library were modified
to support sinc interpolation.
.NH 3
Glossary of new tasks in the IRAF core system
.sp 0.5
\fR
.TS
center;
c c c c c
l c l c lw(4i).
Task		Package		Description
_

gdevices	-	plot	-	List available imaging or other graphics devices
hfix	-	proto	-	Fix image headers with a user specified command
imcombine	-	images	-	Combine images pixel-by-pixel using various algorithms
phistogram	-	plot	-	Plot or print the histogram of an image or list
pradprof	-	plot	-	Plot or list the radial profile of a stellar object
suntoiraf	-	proto	-	Convert Sun rasters into IRAF images
wcsedit	-	proto	-	Edit the image coordinate system
wcslab	-	tv	-	Overlay a displayed image with a world coordinate grid
wcsreset	-	proto	-	Reset the image coordinate system
.TE
.NH 2
Changes to the NOAO Packages
.PP
An updated version of the \fIobservatory\fP task has been installed at the
NOAO level.  The task sets observatory parameters from a 
database of observatories or from the parameters in the task itself.
Many packages and tasks within the NOAO packages that need information
about where the data was observed use information supplied by
the \fIobservatory\fP task.
.NH 3
ARTDATA package modifications
.PP
A new version of the ARTDATA package was released with IRAF version 2.9.1.
A summary of those changes plus modifications since that update are listed
below.  A more comprehensive list of the changes included in V2.9.1 are
discussed in IRAF Newsletter Number 10.
.IP \(bu
A new task \fImkechelle\fP has been added that creates artificial 2D echelle
images.
.IP \(bu
A new task \fImkexamples\fP has been added.  The task is intended to generate a
variety of artificial images to be used in testing or demonstrations.
.IP \(bu
A new task \fImkheader\fP adds or modifies
image headers using a header keyword data file.
.IP \(bu
The \fImk1dspec\fP task was modified to create multispec and echelle format
images, line by line.
.IP \(bu
A parameter "header" was added to \fImkobjects\fP, \fImknoise\fP, \fImk1dspec\fP, and
\fImk2dspec\fP so that a header data file could be added to the output image.
Other header parameters are also added to the image header such as 
gain, rdnoise, and exptime.
.IP \(bu
A "comments" parameter was added to various tasks to include/exclude comments
in the header of the output image that describe the data parameters.
.NH 3
ASTUTIL package modifications
.IP \(bu
A new task \fIgratings\fP has been added to the package. This task computes
grating parameters; five of the seven parameters must be specified at
one time.
.IP \(bu
A new task \fIsetjd\fP has been added to the package.  \fIsetjd\fP computes the geocentric,
heliocentric, and integer local Julian dates from information given in the
headers of the input list of images.  This information is then listed or
added to the image headers.
.IP \(bu
A few changes were made to \fIsetairmass\fP. The default value for "update"
was changed to "yes"; an update field was added to the "show" messages;
a warning is printed if both "show" and "update" are set to "no"
indicating that nothing was done.
.NH 3
DIGIPHOT package modifications
.PP
A new version of the DIGIPHOT package was installed.  Some changes were
made to the existing APPHOT package used for aperture photometry, and those
are mentioned below.  But three new packages have also been installed, DAOPHOT,
PHOTCAL, and PTOOLS.  
.PP
DAOPHOT has been available for the past two years as an add-on package known
as TESTPHOT.  It is now part of the distributed system.  The IRAF version of
DAOPHOT, used to do photometry in crowded fields, has been a collaborative
effort with Peter Stetson and Dennis Crabtree of the DAO.  For the
convenience of the many TESTPHOT users, changes to the package since the
last release of TESTPHOT are summarized below.
.PP
PHOTCAL is the photometric calibration package for computing the transformations
of the instrumental magnitudes output from APPHOT and DAOPHOT
to the standard photometric system.  This
package has been a collaborative effort with Pedro Gigoux at CTIO.
.PP
PTOOLS is a package containing an assortment of tools for manipulating
the data files produced from APPHOT and DAOPHOT.  If users are using
STSDAS TABLES format data files then they must first install the
TABLES layered package.  This package can be obtained from either STScI or
NOAO (see \f(CWiraf/contrib\fR in the IRAF network archive).
.NH 3
DIGIPHOT.APPHOT package modifications
.IP \(bu
The \fIapselect\fP task was replaced with the functionally equivalent \fItxdump\fP task.
\fItxdump\fP allows
the user to select fields of data from the output data files produced
from APPHOT tasks and either simply list the extracted data or save it
in another file.
.IP \(bu
A new task called \fIpexamine\fP has been added to the package.  \fIpexamine\fP is a
general purpose tool for interactively examining and editing the data
files produced from tasks in either APPHOT or DAOPHOT.  This task is 
intended to complement the batch oriented task \fItxdump\fP.
.IP \(bu
All of the APPHOT tasks will now query to verify the "datamin" and "datamax"
values, if these values are used by the tasks.
.IP \(bu
The time of the observation, i.e. UT, can now be carried over into the output
data files, if a keyword in the image header contains this information.  
.IP \(bu
If there is bad data within the photometry aperture a value of INDEF will
be stored in the data file for that magnitude.
.NH 3
DIGIPHOT.DAOPHOT (TESTPHOT) package modifications
.PP
This is a new package but for the convenience of the many users of the 
TESTPHOT add-on package,
the changes to TESTPHOT between its last release and its installation into
the DIGIPHOT package as DAOPHOT are summarized below.
.IP \(bu
The \fIappend\fP, \fIconvert\fP, \fIdump\fP, \fIrenumber\fP, \fIselect\fP, and \fIsort\fP tasks were renamed
to \fIpappend\fP, \fIpconvert\fP, \fIpdump\fP, \fIprenumber\fP, \fIpselect\fP, and \fIpsort\fP.
.IP \(bu
The "text" parameter was moved from \fIdaopars\fP to the DAOPHOT package parameters.
.IP \(bu
All the DAOPHOT routines were modified so that "psfrad", "fitrad", and 
"matchrad" are defined in terms of scale.
.IP \(bu
The tasks \fIallstar\fP, \fIgroup\fP, \fInstar\fP, \fIpeak\fP, \fIpsf\fP, and \fIsubstar\fP were all modified
to include "datamin" and "datamax" in their verify routines.
.IP \(bu
Support was added for a time of observation parameter to all the 
appropriate DAOPHOT tasks.  If present, this time will be carried over
into the output data files.
.IP \(bu
All the DAOPHOT tasks except \fIpsf\fP have been modified to accept lists of input
and output files.
.IP \(bu
The new \fIpexamine\fP task was added to this package. \fIpexamine\fP is a
general purpose tool for interactively examining and editing the data
files produced from tasks in either APPHOT or DAOPHOT.  This task is
intended to complement the batch oriented task \fItxdump\fP.
.IP \(bu
Several changes were made to \fIpsf\fP: the default PSF image header will now
hold up to 66 stars (but it is still dependent on the environment
variable \f(CWmin_lenuserarea\fP); a check was added so that the same star can 
not be added to the PSF twice; potential PSF stars are now rejected if
their sky or magnitude values are INDEF; a check was added so that stars
with INDEF valued positions are treated as stars that were not found.
.IP \(bu
\fIgroup\fP was modified so that the groups are output in y order instead of in 
order of the size of the group.
.IP \(bu
Both \fIgroup\fP and \fIpeak\fP were modified so that stars with INDEF centers are not
written to the output file.
.NH 3
IMRED package modifications
.PP
The spectroscopic packages within the IMRED package have undergone quite a bit
of work and reorganization.  The spectroscopic packages are now ARGUS,
CTIOSLIT, ECHELLE, HYDRA, IIDS, IRS, KPNOCOUDE, KPNOSLIT, and SPECRED.
These packages are a collection of tasks from APEXTRACT and ONEDSPEC that are
appropriate for the specific applications.
All these packages use the new versions of the APEXTRACT and ONEDSPEC packages;
the changes for APEXTRACT and ONEDSPEC are summarized below.
Earlier versions of all these packages were released as the NEWIMRED add-on 
package.  The NEWIMRED package is now defunct and the distributed system
contains the latest versions of these packages.
.PP
The spectroscopic packages now contain "DO" tasks that are scripts that
streamline the reduction process for the user.  The "DO" tasks have been
modified for each particular application.
.PP
The ARGUS package is for the reduction of data taken with the CTIO \fIargus\fP
instrument.  Its corresponding script task is \fIdoargus\fP.
.PP
The CTIOSLIT package is similar to the ARGUS package except that is a 
collection of spectroscopic tasks used for general CTIO slit reductions.  The
\fIdoslit\fP task allows for streamlined reductions.
.PP
The ECHELLE package  has the addition of the \fIdoecslit\fP task for
simplied echelle reductions.  The \fIdofoe\fP task has been added for the reduction
of Fiber Optic Echelle (FOE) spectra.
.PP
The HYDRA package is used for the reduction of multifiber data taken at
KPNO.  The \fIdohydra\fP task has been customized for streamlining \fInessie\fP
and \fIhydra\fP reductions.
.PP
The KPNOCOUDE package has been customized for the KPNO Coude.  The \fIdoslit\fP
task allows the user to go through the reduction process with as few 
keystrokes as possible.  The \fIdo3fiber\fP task is specialized for the 3 fiber
(two arc and one object) instrument.
.PP
The KPNOSLIT package can be used for general slit reductions at KPNO.  The
\fIdoslit\fP task in this package is similar to that in the other packages.
.PP
The SPECRED package is the old MSRED package, used for general multispectral
reductions.  This is a generic package that can be used for slit and multifiber/
aperture data.  General \fIdoslit\fP and \fIdofibers\fP tasks are available.
.PP
Several of the spectroscopic packages has a special task called \fImsresp1d\fP
for creating 1d aperture response corrections from flat and
throughput data.  This task is specialized for multiaperture or
multifiber data.
.PP
All of the "DO" tasks have reference manuals that are available in the 
network archive in the \f(CWiraf/docs\fP directory.
.NH 3
IMRED.CCDRED package modifications
.IP \(bu
A new task \fIccdinstrument\fP was added to the package.  The purpose of this
task is to help users create new CCD instrument translation files to use
with the package.
.IP \(bu
The \fIcombine\fP task (as well as \fIdarkcombine\fP, \fIflatcombine\fP, and \fIzerocombine\fP) is
the same task as the new \fIimcombine\fP task in IMAGES.  A few parameters were
added for compatibility with the CCDRED tasks.
.IP \(bu
A new parameter was added to \fIccdproc\fP called "minreplace".  Pixel values
in flat fields below the value for "minreplace" are replaced by the same
value (after overscan, zero, and dark corrections).  This avoids dividing
by zero problems.
.IP \(bu
The default computation and output "pixeltype" in the package parameter
for CCDRED are both real.  Note that both can now be specified separately.
.IP \(bu
The default parameters for \fIdarkcombine\fP and \fIflatcombine\fP have been changed.
.NH 3
NOBSOLETE package added
.PP
This new package has been defined but currently no tasks reside in it.  This
package will be used as a repository for tasks that have been replaced by
newer tasks in the NOAO packages.  The NOBSOLETE tasks will then be removed
at the time of the next release.
.NH 3
NPROTO package modifications
.PP
The old PROTO package was divided into two separate packages, one called
PROTO that now resides in the IRAF core system and the other called
NPROTO that resides in the NOAO package.  The current NPROTO tasks
are \fIbinpairs\fP, \fIfindgain\fP, \fIfindthresh\fP, \fIiralign\fP, \fIirmatch1d\fP, \fIirmatch2d\fP, \fIirmosaic\fP,
\fIlinpol\fP, and \fIslitpic\fP.  The \fIimedit\fP, \fIimexamine\fP, and \fItvmark\fP tasks were moved to
the IMAGES.TV package. The \fIndprep\fP task was moved to ONEDSPEC.  All other tasks 
were moved to the PROTO package at the core level.
.IP \(bu
Two new tasks called \fIfindgain\fP and \fIfindthresh\fP were added to this package.
\fIfindgain\fP determines the gain and read noise of a CCD from a pair of dome
flats and from a pair of bias/zero frames using the Janesick method.
\fIfindthresh\fP estimates the background noise level of the CCD using a sky
frame and the gain and readnoise of the CCD.
.IP \(bu
A new task called \fIlinpol\fP has been added to the PROTO package.  This task
calculates the pixel-by-pixel fractional linear polarization
and polarization angle for three or four images.  The polarizer must be
set at even multiples of a 45 degree position angle.
.IP \(bu
The task \fIndprep\fP used for CTIO 2DFRUTTI reductions was moved to the 
ONEDSPEC package.
.IP \(bu
The task \fItoonedspec\fP was removed since its function can now be performed
by the \fIonedspec.scopy\fP task.
.NH 3
ONEDSPEC package reductions
.PP
There have been significant changes to the ONEDSPEC package.
A more detailed revisions summary is available
in the IRAF network archive as file \f(CWonedv210.ps.Z\fP in the
subdirectory \f(CWiraf/docs\fP.
.PP
The new package supports a variety of spectral image formats.  The older
formats can still be read.  In particular the one
dimensional "onedspec" and the two dimensional "multispec" format will
still be acceptable as input.  Note that the image naming syntax for the
"onedspec" format using record number extensions is a separate issue and is
still provided but only in the IMRED.IIDS and IMRED.IRS packages.  Any new
spectra created are either a one dimensional format using relatively simple
keywords and a two or three dimensional format which treats each line of
the image as a separate spectrum and uses a more complex world coordinate
system and keywords.  For the sake of discussion the two formats are still
called "onedspec" and "multispec" though they are not equivalent to the
earlier formats.
.PP
In addition, the one dimensional spectral tasks may also operate on two
dimensional images.  This is done by using the "dispaxis" keyword in the
image header or a package dispaxis parameter if the keyword is missing to
define the dispersion axis.  In addition there is a summing parameter in
the package to allow summing a number of lines or columns.  If the spectra
are wavelength calibrated long slit spectra, the product of the
\fIlongslit.transform\fP task, the wavelength information will also be properly
handled.  Thus, one may use \fIsplot\fP or \fIspecplot\fP for plotting such data
without having to extract them to another format.  If one wants to extract
one dimensional spectra by summing columns or lines, as opposed to using
the more complex APEXTRACT package, then one can simply use \fIscopy\fP (this
effectively replaces \fIproto.toonedspec\fP)
.PP
Another major change to the package is that spectra no
longer need to be interpolated to a uniform sampling in wavelength.  The
dispersion functions determined by \fIidentify\fP/\fIreidentify\fP can now be carried along
with the spectra in the image headers and recognized throughout the package and
the IRAF core system.  Thus the WCS has been fully implemented in the ONEDSPEC
tasks and although much is to be gained by this it can cause problems with
earlier IRAF systems as well as making it difficult to import data into
non-IRAF software.  But it is now possible to use \fIimcopy\fP with an image section
on a spectrum, for instance, and have the wavelength information retained
correctly.
.PP
A sinc interpolator is now available
for those tasks doing geometric corrections or interpolations.  This option
can be selected by setting the "interp" parameter in the ONEDSPEC package
parameters.  
.PP
Other changes are summarized:
.IP \(bu
The new task \fIderedden\fP corrects input spectra for interstellar extinction, or
reddening.
.IP \(bu
The new task \fIdopcor\fP corrects input spectra by removing a specified doppler
velocity.  The opposite sign can be used to add a doppler shift to a spectrum.
.IP \(bu
The new task \fIfitprofs\fP fits 1D gaussian profiles to spectral lines or
features in an image line or column.  This is done noninteractively and
driven by an input list of feature positions.
.IP \(bu
The task \fIndprep\fP was moved to this package from the PROTO package.  \fIndprep\fP
is used for CTIO \fI2DFRUTTI\fP reductions.
.IP \(bu
The new task \fIsapertures\fP adds or modifies beam numbers and
aperture titles for selected apertures based on an aperture
identification file.
.IP \(bu
The new task \fIsarith\fP does spectral arithmetic and includes unary operators.
The arithmetic can be performed on separate input spectra or on apertures
within a multispec format image.
.IP \(bu
The task \fIscombine\fP has been added to the package.  This new task is similar
to the new \fIimcombine\fP task in the IMAGES package but is specialized for
spectral data.
.IP \(bu
The new task \fIscopy\fP copies subsets of apertures and does format
conversions between the different spectrum formats.
.IP \(bu
The new task \fIsfit\fP fits spectra and outputs the fits in various ways.
This includes a new feature to replace deviant points by the fit.
Apertures in  multispec and echelle format are fit independently.
.IP \(bu
The tasks \fIaddsets\fP, \fIbatchred\fP, \fIbswitch\fP, \fIcoincor\fP, \fIflatdiv\fP, \fIflatfit\fP, \fIsubsets\fP
and \fIsums\fP were moved to the IIDS and IRS packages.
.IP \(bu
The task \fIcombine\fP was removed with the all new \fIscombine\fP suggested in its place.
.IP \(bu
The tasks \fIrebin\fP, \fIsflip\fP and \fIshedit\fP were removed from the package.
Rebinning of spectra can now be done with \fIscopy\fP or \fIdispcor\fP.  \fIscopy\fP and \fIimcopy\fP
can now be used in place of \fIsflip\fP.  And \fIhedit\fP is an alternative for \fIshedit\fP.
.IP \(bu
\fIbplot\fP and \fIslist\fP have been modified to support the multispec format.
.IP \(bu
The task \fIcontinuum\fP now does independent fits for multispec and
echelle format spectra.
.IP \(bu
There is now only one \fIdispcor\fP task doing the work of the three previous
tasks \fIdispcor\fP, \fImsdispcor\fP and \fIecdispcor\fP.  Several of the parameters for this
task have been changed.  The old "recformat" and "records" parameters for 
supporting the old onedspec format have been removed except in the IIDS/IRS
packages.  A "linearize" parameter has been added for setting the interpolation
to yes or no on output.  The "interpolation" parameter was removed since this 
information is now read from the package parameter "interp".  The "ignoreaps"
parameter has been changed to "samedisp".
.IP \(bu
\fIidentify\fP and \fIreidentify\fP now treat multispec format spectra
and two dimensional images as a unit allowing easy movement between
different image lines or columns.  The database is only updated upon
exiting the image.  The "j", "k", and "o" keys have been added to the
interactive sessions to allow for scrolling through the different lines 
in a two dimensional image.  The database format now uses aperture numbers
rather than image sections for multispec format spectra.
.IP \(bu
The task \fIspecplot\fP has new parameters "apertures" and "bands" to select
spectra for plotting in the multispec format.
.IP \(bu
\fIsplot\fP now allows deblending of any number of components and
allows simultaneous fitting of a linear background.  Several cursor keys 
have been redefined and colon commands have been added to fully support
the new multispec format and to add even more flexibility to the task than
before! Please see the help pages for details.
.IP \(bu
The \fIreidentify\fP task is essentially a new task.  The important changes
are an interactive review option, the ability to add features from
a line list, using the same reference spectrum for all other spectra in
a 2D reference image rather than "tracing" (using the results of the
last reidentification as the initial guess for the next one) across the
image, and matching image lines/columns/apertures from a 2D reference
image to other 2D images rather than "tracing" again.
.NH 3
RV package added
.PP
This is a new package installed with IRAF version 2.10.  A version of this
package, RV0, has been available as an add-on for the past year or so.  The
package contains one main task \fIfxcor\fP that performs a Fourier
cross-correlation on the input list of spectra.  The package supports the
multispec format.
.NH 3
TWODSPEC package modifications
.PP
The old MULTISPEC package that has resided in the TWODSPEC package for
years has been disabled.  The code is still there for browsing, however, and
the package can be resurrected easily if needed.
.PP
The \fIobservatory\fP task was moved to the NOAO package itself.  The \fIsetairmass\fP
task was moved to LONGSLIT.  And the \fIsetdisp\fP task is no longer needed;
task or package parameters are used in its place.
.PP
Changes to the APEXTRACT and LONGSLIT packages are summarized below.
.NH 3
TWODSPEC.APEXTRACT package modifications
.PP
A new version, version 3, of the IRAF APEXTRACT package has been
completed.  A detailed revisions summary is available in the IRAF
network archive (file \f(CWapexv210.ps.Z\fP in \f(CWiraf/docs\fP).
.PP
There were three goals for the new package: new and improved cleaning
and variance weighting (optimal extraction) algorithms, the addition of
recommended or desirable new tasks and algorithms (particularly to
support large numbers of spectra from fiber and aperture mask
instruments), and special support for the new image reduction scripts in
the various IMRED packages.
.PP
The multispec format, the default image format for all spectroscopic packages
except IIDS and IRS, is either 2D or 3D (the 3D format is new with this
release).
The 3D format is produced when the parameter "extras" is set to yes in the 
extraction tasks.  The basic 2D format, which applies to
the first plane of the 3D format, has each 1D aperture spectra extracted
in a line.  Thus, the first coordinate is the pixel coordinate along the
spectra.  The second coordinate refers to the separate apertures.  The
third coordinate contains extra information associated with the spectrum
in the first plane.  The extra planes are:
.DS L
	1: Primary spectra which are variance and/or cosmic ray cleaned
	2: Spectra which are not weighted or cleaned
	3: Sky spectra when using background subtraction
	4: Estimated sigma of the extracted spectra
.DE
If background subtraction is not done then 4 moves down to plane 3.
Thus:
.DS L
	output.ms[*,*,1] = all primary spectra
	output.ms[*,5,1] = 5th aperture spectrum which is cleaned
	output.ms[*,5,2] = raw/uncleaned 5th aperture spectrum
	output.ms[*,5,3] = sky for 5th spectrum
	output.ms[*,5,4] = sigma of 5th spectrum
.DE
.LP
The following summarizes the major new features and changes.
.IP \(bu
New techniques for cleaning and variance weighting extracted spectra have 
been implemented.
.IP \(bu
Special features for automatically numbering and identifying large
numbers of apertures have been added.
.IP \(bu
There is no longer a limit to the number of apertures that can be extracted.
.IP \(bu
The new task \fIapall\fP integrates all the parameters used for
one dimensional extraction of spectra.
.IP \(bu
The new task \fIapfit\fP provides various types of fitting for two dimensional
multiobject spectra.
.IP \(bu
The new task \fIapflatten\fP creates flat fields from fiber and slitlet
spectra.
.IP \(bu
The new task \fIapmask\fP creates mask images from aperture definitions using the
new pixel list image format. No tasks
have yet been written, however, to use this new mask image format.
.IP \(bu
The new tasks and algorithms, \fIaprecenter\fP and \fIapresize\fP, will
automatically recenter and resize aperture definitions.
.IP \(bu
The task \fIapio\fP is defunct.  Its functionality has been replaced by the
APEXTRACT package parameters.
.IP \(bu
The task \fIapstrip\fP has been removed.
.IP \(bu
Minor changes have been made to the old "AP" tasks to accommodate these 
new changes in the package; in some cases new parameters have been added to
the task and in other cases new cursor options have been implemented.  See the
help pages for details.
.NH 3
TWODSPEC.LONGSLIT package modifications
.IP \(bu
The "dispaxis" parameter was added to the package parameters.  This value
is used unless DISPAXIS is in the image header.
.NH 3
Glossary of new tasks in the NOAO packages
.sp 0.5
\fR
.TS
center;
c c c c c
l c l c lw(4i).
Task		Package		Description
_

addstar	-	daophot	-	Add artificial stars to an image using the computed psf
allstar	-	daophot	-	Group and fit psf to multiple stars simultaneously
apall	-	apextract	-	Extract 1D spectra (all parameters in one task)
apfit	-	apextract	-	Fit 2D spectra and output the fit, difference, or ratio
apflatten	-	apextract	-	Remove overall spectral and profile shapes from flat fields
apmask	-	apextract	-	Create and IRAF pixel list mask of the apertures
aprecenter	-	apextract	-	Recenter apertures
apresize	-	apextract	-	Resize apertures
ccdinstrument	-	ccdred	-	Review and edit instrument translation files
centerpars	-	daophot	-	Edit the centering algorithm parameters
chkconfig	-	photcal	-	Check the configuration file for grammar and syntax errors
continpars	-	rv	-	Edit continuum subtraction parameters
daofind	-	daophot	-	Find stars in an image using the DAO algorithm
daopars	-	daophot	-	Edit the daophot algorithms parameter set
datapars	-	daophot	-	Edit the data dependent parameters
deredden	-	onedspec	-	Apply interstellar extinction correction
do3fiber	-	kpnocoude	-	Process KPNO coude three fiber spectra
doargus	-	argus	-	Process ARGUS spectra
doecslit	-	echelle	-	Process Echelle slit spectra
dofibers	-	specred	-	Process fiber spectra
dofoe	-	echelle	-	Process Fiber Optic Echelle (FOE) spectra
dohydra	-	hydra	-	Process HYDRA spectra
dopcor	-	onedspec	-	Apply doppler corrections
doslit	-	ctioslit	-	Process CTIO slit spectra
doslit	-	kpnocoude	-	Process KPNO coude slit spectra
doslit	-	kpnoslit	-	Process slit spectra
doslit	-	specred	-	Process slit spectra
evalfit	-	photcal	-	Compute the standard indices by evaluating the fit
filtpars	-	rv	-	Edit the filter function parameters
findgain	-	nproto	-	Estimate the gain and readnoise of a CCD
findthresh	-	nproto	-	Estimate a CCD's sky noise from the gain and readnoise
fitparams	-	photcal	-	Compute the parameters of the transformation equations
fitprofs	-	onedspec	-	Fit gaussian profiles
fitskypars	-	daophot	-	Edit the sky fitting algorithm parameters
fxcor	-	rv	-	Radial velocities via Fourier cross correlation
gratings	-	astutil	-	Compute and print grating parameters
group	-	daophot	-	Group stars based on positional overlap and signal/noise
grpselect	-	daophot	-	Select groups of a specified size from a daophot database
invertfit	-	photcal	-	Compute the standard indices by inverting the fit
istable	-	ptools	-	Is a file a table or text database file ?
linpol	-	nproto	-	Calculate polarization frames and Stoke's parameters
keywpars	-	rv	-	Translate the image header keywords used in RV package
mkcatalog	-	photcal	-	Type in a standard star catalog or observations file
mkconfig	-	photcal	-	Prepare a configuration file
mkechelle	-	artdata	-	Make artificial 1D and 2D echelle spectra
mkexamples	-	artdata	-	Make artificial data examples
mkheader	-	artdata	-	Append/replace header parameters
mkimsets	-	photcal	-	Prepare an image set file for input to (mk)(n)obsfile
mk(n)obsfile	-	photcal	-	T{
Prepare a single (multi)-starfield observations file from apphot/daophot output
T}
mkphotcors	-	photcal	-	T{
Type in/check any photometric corrections files required by mk(n)obsfile
T}
msresp1d	-	argus	-	Create 1D response spectra from flat field and sky spectra
msresp1d	-	hydra	-	Create 1D response spectra from flat field and sky spectra
msresp1d	-	kpnocoude	-	Create fiber response spectra from flat field and sky spectra
msresp1d	-	specred	-	Create 1D response spectra from flat field and sky spectra
nstar	-	daophot	-	Fit the psf to groups of stars simultaneously
obsfile	-	photcal	-	T{
Prepare a single (multi)-starfield observations file from a user-created text file
T}
pappend	-	daophot	-	Concatenate a list of daophot databases
pappend	-	ptools	-	Concatenate a list of apphot/daophot databases
pconvert	-	daophot	-	Convert a text database to a tables database
pconvert	-	ptools	-	Convert from an apphot/daophot text to tables database
pdump	-	daophot	-	Print selected fields from a list of daophot databases
pdump	-	ptools	-	Print selected columns of a list of  daophot/apphot databases
peak	-	daophot	-	Fit the psf to single stars
pexamine	-	apphot	-	Interactively examine or edit an apphot output file
pexamine	-	daophot	-	Interactively examine and edit a daophot database
pexamine	-	ptools	-	Interactively examine and edit an apphot/daophot database
phot	-	daophot	-	Compute sky values and initial magnitudes for a list of stars
photpars	-	daophot	-	Edit the photometry parameters
prenumber	-	daophot	-	Renumber stars in a daophot database
prenumber	-	ptools	-	Renumber a list of apphot/daophot databases
pselect	-	daophot	-	Select records from a daophot database
pselect	-	ptools	-	Select records from a list of apphot/daophot databases
psf	-	daophot	-	Fit the point spread function
psort	-	daophot	-	Sort a daophot database
psort	-	ptools	-	Sort a list of apphot/daophot databases
sapertures	-	onedspec	-	Set or change aperture header information
sarith	-	onedspec	-	Spectrum arithmetic
scombine	-	onedspec	-	Combine spectra having different wavelength ranges
scopy	-	onedspec	-	Select and copy apertures in different spectral formats
seepsf	-	daophot	-	Compute an image of the point spread function
setjd	-	astutil	-	Compute and set Julian dates in images
sfit	-	onedspec	-	Fit spectra and output fit, ratio, or difference
substar	-	daophot	-	Subtract the fitted stars from the original image
tbappend	-	ptools	-	Concatenate a list of apphot/daophot tables databases
tbdump	-	ptools	-	Print selected columns of a list of tables databases
tbrenumber	-	ptools	-	Renumber a list of  apphot/daophot tables databases
tbselect	-	ptools	-	Select records from a list of apphot/daophot tables databases
tbsort	-	ptools	-	Sort a list of apphot/daophot tables databases
txappend	-	ptools	-	Concatenate a list of apphot/daophot text databases
txdump	-	apphot	-	Dump selected fields from an apphot output file
txdump	-	ptools	-	Print selected columns of a list of apphot/daophot text databases
txrenumber	-	ptools	-	Renumber a list of apphot/daophot text databases
txselect	-	ptools	-	Select records from a list of apphot/daophot text databases
txsort	-	ptools	-	Sort a list of apphot/daophot text databases
.TE

.bp
.NH
Programming Environment Revisions

.NH 2
Compatibility Issues
.PP
V2.10 IRAF requires that any local IRAF programs external to the V2.10
system (such as layered packages or locally written tasks) be \fIfully
recompiled\fR if they are relinked against V2.10.  The problem arises only
if the programs are relinked; external programs will continue to run after
V2.10 is installed, but linker errors will be seen if the programs are
relinked without being fully recompiled.  This is because the internal names
of some important system routines were changed in V2.10 to avoid name
clashes with host system routines.  For example, the SPP procedure "rename"
is now translated to "xfrnam" when the SPP code it appears in is compiled.
.PP
As always, actual interface changes affecting existing source code were very
few.  The macro "E" in \f(CW<math.h>\fR was renamed to "BASE_E" to minimize
the chance of an accidental name collision.  The calling sequence for the
\fIonentry\fR procedure (ETC) was changed, but since this is a little used
system procedure very few tasks should be affected.  A number of new
procedures were added to MTIO and the syntax of a magtape device has
changed; old applications should be modified to use the MTIO procedures to
operate upon magtape device names.
.PP
These and other revisions affecting the programming environment
are discussed in more detail below.

.NH 2
Portability Issues
.PP
The V2.10 UNIX/IRAF kernel now includes "#ifdef SYSV" support for System V
UNIX, making it easier to port IRAF to SysV based systems.  The UNIX/IRAF
HSI (host system interface) is still not as portable to UNIX variants as it
could be, but at this point it is easier for us to make the minor revisions
required for a new port than to further refine the HSI.  The disadvantage is
that it is harder than it should be for people in the community to do their
own IRAF ports, due to the level of IRAF expertise required to tune the
code.  Someday we plan to generate a generic-UNIX HSI.  Note that these
comments pertain only to the few thousand lines of code in the HSI - the
bulk of the IRAF code is 100% portable (identical on all IRAF systems) as it
has always been.
.PP
The recent port of IRAF to A/UX (the Apple Macintosh UNIX) is interesting
from a portability standpoint because we used the publically available
Fortran to C translator \fIf2c\fR plus the GNU C compiler \fIgcc\fR to
compile all the SPP and Fortran code in IRAF.  This was remarkably
successful and means that the IRAF code is now portable to any system with a
C compiler.  In the process of performing these compilations a few dozen
minor bugs were found by the static compile time checking performed by
\fIf2c\fR and \fIgcc\fR.  The IRAF C code was run through \fIgcc\fR with
ANSI mode enabled, and hence should now be ANSI-C compatible.  The GNU
debugger \fIgdb\fR proved to be an effective tool for debugging of IRAF code
compiled with \fIgcc\fR.

.NH 2
Software Tools
.NH 3
LOGIPC feature
.PP
A new facility has been added to UNIX/IRAF (all systems) for debugging
interprocess communication (IPC).  This feature will also be useful for
debugging tasks standalone, particularly in cases where a bug seen when
running a task from the CL is difficult to reproduce when the task is run
standalone.  The new facility allows one to carry out a normal IRAF session
while transparently logging all interprocess communications.  Each process
can then be rerun individually using the logged IPC to exactly duplicate
the functioning of the process to, e.g., examine the program operation in
detail under a debugger.
.PP
The facility is this: if LOGIPC is defined in the host environment when an
iraf process is started, the process will create two files \fIpid\f(CW.in\fR
and \fIpid\f(CW.out\fR, where \fIpid\fR is the process id.  Everything read
from the IPC input file is copied to the \f(CW.in\fR file, and everything
written to the IPC output (i.e., sent back to the CL) is copied to
the \f(CW.out\fR file.  This is done only for connected subprocesses.
It will work for any connected subprocess, e.g., normal cached processes and
graphics subkernels in both foreground and background CLs, but not the i/o
of the CL itself since the CL is not driven by IPC.
.PP
The IPC streams saved are an exact binary copy of whatever was sent via IPC,
including the binary IPC packet headers, and binary graphics data, and so
on.  All the IPC communications used to start up the process, run zero or
more tasks, and close the process down will be logged.  Most IPC traffic is
textual in nature so it will usually be possible to examine the IPC files
with a file pager, although the results may be less than satisfactory if
binary data such as a graphics metacode stream is logged.  It is not
necessary to examine the IPC files to use them for process execution or
debugging.
.PP
A particularly interesting use of this feature is to allow a process to be
run under the CL in the normal fashion, then rerun under a host level
debugger using the saved IPC input to duplicate the input and actions of the
process when run under the CL.  For example,
.XS
% setenv LOGIPC
% cl
cl> dir
cl> logout
% unsetenv LOGIPC
.XE
will run the CL, saving the IPC of all subprocesses, e.g. \f(CWx_system.e\fR.
We can then run the system process manually, using the saved IPC input:
.XS
% $iraf/bin/x_system.e -c < \fIpid\fR.in
.XE
To run the process under \fIadb\fR or \fIdbx\fR, using the saved input:
.XS
% adb $iraf/bin/x_system.e
:r <\fIpid\fR.in -c
.XE
or
.XS
% dbx $iraf/bin/x_system.e
dbx> r -c < \fIpid\fR.in
.XE
Note that the redirection has to be given first for \fIadb\fR, and last for
\fIdbx\fR. This also works for \fIgdb\fR using the \fIrun\fR command.  Some
implementations of \fIadb\fR are picky about syntax and will not allow a
space between the "<" and the process id in the :r command.
.PP
Running a task in this way is not identical to running the task standalone,
e.g. using a \fIdparam\fR file for parameter input, because the full
runtime context of the process as run under the CL is reproduced by LOGIPC
but not when the task is run standalone.  The differences are subtle but can
be important when trying to reproduce a bug seen when the process is run
under the CL.  It is often the case that a bug seen when a task is run
from the CL will disappear when the task is run standalone, but in most
cases LOGIPC will duplicate the bug.
.NH 3
XC changes
.PP
The \fIxc\fR program (IRAF compiler-linker) underwent the following changes for
V2.10, in addition to the usual host-system specific changes required to
support new host compiler versions.
.PP
Multiple "-p pkgname" arguments are now supported.  These are used when
compiling a module which uses multiple package environments, e.g.,
.XS
cl> xc -p noao -p tables foo.x
.XE
Each package environment may define package environment variables,
directories to be searched for include files and libraries, and so on.
Package environments are used by the IRAF layered packages.
.PP
Host libraries named on the command line using the -l switch (e.g.,
"-lresolv") are now searched after the IRAF system libraries, rather than
before as in previous versions of \fIxc\fR.  If the host library is
referenced by absolute pathname it is still searched before the IRAF
libraries, since the command line order determines the search order.
.NH 3
SPPLINT code checker
.PP
A static code checker utility \fIspplint\fR has been developed for checking
SPP programs.  This uses the SPP translation utilities in IRAF to convert
SPP to Fortran, \fIf2c\fR to generate C code, and \fIlint\fR to check the C
code.  The code is checked in various ways at all phases of translation.
Some of the most useful checking are performed by \fIf2c\fR, which checks
the number and type of arguments in all calls to IRAF VOS library
procedures.  In other words, \fIspplint\fR will determine if an IRAF library
procedure is called incorrectly, as well as perform a variety of other
checks.
.PP
The \fIspplint\fR utility is not included in the main IRAF release, but is
available separately.  Contact the IRAF project for information on the
availability of this and other optional code development utilities.
.NH 3
Multiple architecture support
.PP
Multiple architecture support is a way of using multiple sets of compiled
program binaries within a single copy of IRAF.  Multiple sets of binaries
are used to support different machine architectures (e.g. sparc and Motorola),
different compiler options (floating point options, vectorization options,
profiling options), different compilers, and so on.
.PP
The command for checking the architecture of the IRAF core system or a
layered package has been changed from \fIshowfloat\fR to \fIarch\fR to
reflect the fact that multiple architecture support is no longer used merely
to select the floating point option.
.XS
cl> mkpkg arch
sparc
.XE
The default architecture of the distributed system is "generic", meaning
no specific architecture has been set (the source tree is generic, not
configured for any particular architecture).
.PP
It is suggested that developers of layered software for IRAF adopt this
same convention in their root \fImkpkg\fR files.
.NH 3
Package environments
.PP
All the HSI software utilities now permit multiple "-p pkgname" package
environment references.  The host \f(CWPKGENV\fR environment variable now
also permits multiple package environments to be referenced, e.g.
.XS
% setenv PKGENV "noao tables xray"
.XE
The package names should be whitespace delimited (\f(CWPKGENV\fR is used to
avoid having to give the "-p" flags on the \fImkpkg\fR or \fIxc\fR command
line).  To successfully load a package enironment, the package root
directory must be defined in \f(CWhlib$extern.pkg\fR or in the user's host
environment.  A host environment definition will override the value given in
extern.pkg.
.NH 3
Finding module sources
.PP
IRAF V2.10 includes a "tags" file in the IRAF root directory to aid software
development.  This file contains an index to all procedures in the IRAF VOS
and HSI and can be used with host editors such as \fIvi\fR to rapidly find
and display the source for IRAF system procedures.  Note that the names of
the kernel procedures are given in upper case, e.g., "ZOPNBF", whereas the
names of the VOS procedures are given in lower case.  To use the tags file
with \fIvi\fR, start the editor at the IRAF root directory and while in the
editor, type a command such as ":ta foo" to view the source for procedure
\fIfoo\fR.

.NH 2
Programming Interface Changes
.NH 3
IEEE floating support
.PP
Modifications were made to the IEEE floating conversion routines in the OSB
package to support NaN mapping.  This is a low level package used by, e.g.,
the MII package in ETC.  The interface as it currently stands is summarized
below.
.XS
     ieepak[rd] (datum)               # pack scalar value
     ieeupk[rd] (datum)               # unpack scalar value
    ieevpak[rd] (native, ieee, nelem) # pack vector
    ieevupk[rd] (ieee, native, nelem) # unpack vector
 iee[sg]nan[rd] (NaN)                 # set/get NaN value
     ieemap[rd] (mapin, mapout)       # enable/disable NaN mapping
    ieestat[rd] (nin, nout)           # get count of NaN values
   ieezstat[rd] ()                    # zero NaN counters
.XE
.PP
The new or modified routines are \fIieesnan\fR, \fIieegnan\fR, \fIieemap\fR,
\fIieestat\fR, and \fIieezstat\fR.  By NaN (not-a-number) we refer
collectively to all IEEE non-arithmetic values, not just IEEE NaN.  The
routines \fIieesnan\fR and \fIieegnan\fR set or get the native floating
value used to replace NaNs or overflows occurring when converting IEEE to the
native floating format (any floating value will do, e.g., zero or INDEF).
If NaN mapping is enabled, the \fIieestat\fR routines may be used to
determine the number of input or output NaN conversions occurring since the
last call to \fIieezstat\fR.  Both real and double versions of all routines
are provided.
.PP
The NaN mapping enable switch and statistics counters are undefined at
process startup; programs which use the IEEE conversion package should call
\fIieemap\fR to enable or disable NaN mapping, and \fIieezstat\fR to
initialize the statistics counters.
.NH 3
MATH libraries
.PP
The following changes were made to the MATH libraries in the IRAF core
system.  Refer to the online help pages of the affected routines for
detailed information.
.RS
.IP \(bu
The one-dimensional image interpolation library \fBiminterp\fR was modified
to add support for sinc interpolation.
.IP \(bu
A new library \fBnlfit\fR was added for non-linear function fitting.
An interactive graphics front end to this was also added in XTOOLS.
.IP \(bu
The name of the symbol \f(CWE\fR in \f(CW<math.h>\fR was changed to
\f(CWBASE_E\fR to minimize the chance of name clashes.
.RE
.NH 3
CLIO interface
.PP
The CLIO (command language i/o) interface underwent the following changes
for version 2.10 IRAF.
.RS
.IP \(bu
A README file was added to the source directory containing an up to date
interface summary.
.IP \(bu
The routines \fIclgpset\fR and \fIclppset\fR (get/put string valued
parameter) were renamed \fIclgpseta\fR and \fIclppseta\fR.  The old
procedures were retained for compatibility but are now obsolete and may at
some point in the future disappear or be reused for some other function.
.IP \(bu
Two new routines \fIcllpset\fR and \fIclepset\fR were added for listing
and editing psets (parameter sets).
.RE
.LP
The calling sequences for the new pset routines are as follows.
.XS
cllpset (pp, fd, format)    # list pset
clepset (pp)                # edit pset
.XE
These new routines are still considered experimental and should be avoided
or used with caution (they could change).
.PP
Internal to the CLIO code, the CLIO parameter caching package underwent
minor changes to add a new \fIclc_compress\fR routine and improve pset
handling, as part of the minilanguage support effort.
.RE
.NH 3
ETC interface
.PP
The ETC interface contains miscellaneous system interface routines.
The ETC interface underwent the following changes for V2.10 IRAF.
.NH 4
Calling sequence for onentry changed
.PP
The calling sequence for the \fIonentry\fR routine was changed.  The new
calling sequence is as follows.
.XS
    action = onentry (prtype, bkgfile, cmd)
.XE
The \fIonentry\fR procedure is an optional procedure which is called when an
IRAF process starts up.  Normally the onentry procedure is a no-op, passing
control to the IRAF main in-task interpreter.  Custom IRAF applications,
e.g., the CL, have a special \fIonentry\fR procedure which replaces the
default in-task interpreter.
.PP
The change made to the \fIonentry\fR calling sequence was the addition of
the additional argument \fIcmd\fR.  This argument receives the command line
used to invoke the IRAF process at the host level.  The application can
parse this command line to extract arguments, allowing the IRAF process to
operate as a host program (it is already possible to call any IRAF task from
the host level, but use of an \fIonentry\fR procedure allows the in-task
interpreter to be bypassed and gives the application control over parsing
the command line).
.PP
See \f(CWetc$onentry.x\fR for additional information on how to use this
procedure.
.NH 4
New onerror and onexit procedures
.PP
Two new procedures \fIonerror_remove\fR and \fIonexit_remove\fR were added.
These have the following calling sequences.
.XS
    onerror_remove (proc)      # remove posted onerror procedure
     onexit_remove (proc)      # remove posted onexit procedure
.XE
The new routines are used to remove \fIonerror\fR or \fIonexit\fR procedures
posted by a task during task execution.  Such user procedures are called
if the task aborts (\fIonerror\fR procedures) or during normal task exit
(\fIonexit\fR procedures).  Formerly there was no way to "unpost" the
procedures other than by the normal cleanup occurring during task termination.
.NH 4
New gqsort routine
.PP
A new quick-sort routine \fIgqsort\fR (generalized quick sort) was added.
This has the following calling sequence.
.XS
    gqsort (x, nelem, compare, client_data)
.XE
\fIgqsort\fR is identical to the old \fIqsort\fR routine except for the
addition of the fourth argument \fIclient_data\fR.  This is an integer value
which is passed on to the \fIcompare\fR procedure during sorting to compare
two data values.  The \fIcompare\fR routine is called as follows.
.XS
    result = compare (client_data, x1, x2)
.XE
The new routine eliminates the need to use a common area to pass information
to the compare routine, as was often necessary with \fIqsort\fR.
.NH 3
FIO interface
.PP
The FIO interface (file i/o) underwent minor changes to fix some bugs
affecting pushed back data.  The \f(CWF_UNREAD\fR file status parameter
will now correctly report pushed back data as well as any buffered
input file data.  The \f(CWF_CANCEL\fR file set option will now cancel
any pushed back data.
.NH 4
Nonblocking terminal i/o
.PP
A new nonblocking form of raw mode terminal input has been added.  This
permits polling the terminal for input without blocking (suspending process
execution) if no input is available.  In a character read, EOF is returned
if no input is available otherwise the character value is returned.
An example illustrating the use of nonblocking terminal i/o follows.
.XS
include <fset.h>

task foo

procedure foo()
.sp 0.5v
int     fd, ch
int     getci()
.sp 0.5v
begin
        fd = STDIN
        call fseti (fd, F_IOMODE, IO_RAW+IO_NDELAY)
.sp 0.5v
        repeat {
            if (getci(fd,ch) == EOF)
                call printf ("no pending input\\\\r\\\\n")
            else {
                call printf ("ch = %03o\\\\r\\\\n")
                    call pargi (ch)
            }
            call sleep (1)
        } until (ch == '\\\\004' || ch == 'q')
.sp 0.5v
        call fseti (fd, F_IOMODE, IO_NORMAL)
end
.XE
.PP
This sample program sets the terminal i/o mode to nonblocking raw mode and
polls the terminal once per second, printing the character value in octal if
a character is typed on the terminal, exiting when ctrl/d or 'q' is typed.
Note that in raw mode characters such as ctrl/d or ctrl/c are passed through
as data and do not get mapped to EOF, generate an interrupt, and so on.
Raw mode i/o such as this will work both when running a task under the CL
and standalone, and in combination with IRAF networking (e.g. to access a
remote device).
.PP
Nonblocking terminal input is used in applications which run continuously
but which we wish to be able to control interactively.
.NH 3
FMTIO interface
.PP
The FMTIO interface (formatted i/o) is used to format output text or decode
input text.  The V2.10 release adds two new \fIprintf\fR output formats,
\f(CW%H\fR and \f(CW%M\fR.  These are used to print numbers in
hours-minutes-seconds or minutes-seconds format and are equivalent to the
older output formats \f(CW%h\fR and \f(CW%m\fR except that the number is
first divided by 15.  This converts degrees to hours allowing values given
in units of degrees to be printed as hours with just a change of the output
format.  In other words, given a number N in units of degrees, \f(CW%H\fR
would print the number in hours-minutes-seconds, i.e., "hh:mm:ss.ss",
whereas \f(CW%h\fR would print the same number as degrees-minutes-seconds,
"dd:mm:ss.ss".  The \f(CW%m\fR formats are similar except that only two of
the three fields are printed.
.NH 3
GTY interface
.PP
The GTY interface is a generalized version of that portion of the older TTY
interface dealing with termcap format files.  The TTY code which accesses
termcap format files has been extracted to form the new GTY interface,
allowing arbitrary termcap format files to be accessed by filename, unlike
TTY which returns TTY descriptors given the termcap or graphcap device
name.  GTY was contributed by Skip Schaller of Steward Observatory.
.XS
        gty = gtyopen (termcap_file, device, ufields)
             gtyclose (gty)
         cp = gtycaps (gty)
   pval = gtyget[bir] (gty, cap)
     nchars = gtygets (gty, cap, outstr, maxch)
.XE
.PP
The \fIgtyopen\fR call returns the GTY descriptor for the named \fIdevice\fR
from the file \fItermcap_file\fR.  The \fIufields\fR string may be either
NULL or a list of colon-delimited device capabilities, which will override
the corresponding capabilities in the device entry given in the termcap
file.  If \fItermcap_file\fR is the null string \fIufields\fR is taken to be
the device entry for the named device.  The \fIgtycaps\fR routine may be
used to get the entire device entry as a string, whereas the \fIgtyget\fR
and \fIgtygets\fR routines are used to get the values of individual
capabilities or parameters.
.NH 3
MTIO interface
.PP
MTIO is the magtape i/o interface.  The magtape i/o subsystem was
extensively revised for V2.10 IRAF, as documented earlier in this revisions
summary.  The VOS level MTIO interface itself was not changed other than to
add a few new routines.  The \fItapecap\fR facility is new in V2.10.  The
revisions to the host level magtape driver ZFIOMT required that the
calling sequences of some of the interface routines be changed.
.NH 4
MTIO applications programming interface
.PP
The current MTIO applications programming interface is summarized below.
Most of these routines are new: the old routines are \fImtfile\fR,
\fImtopen\fR, \fImtrewind\fR and \fImtposition\fR.
.XS
      yes|no = mtfile (fname)
yes|no = mtneedfileno (mtname)
          gty = mtcap (mtname)
              mtfname (mtname, file, outstr, maxch)
.sp 0.5v
              mtparse (mtname, device, fileno, recno, attrl, maxch)
             mtencode (mtname, maxch, device, fileno, recno, attrl)
.sp 0.5v
          fd = mtopen (mtname, acmode, bufsize)
             mtrewind (mtname, initcache)
           mtposition (mtname, file, record)
.XE
.PP
The \fImtfile\fR routine is used to test whether the given filename is a
magtape file or something else, i.e., a disk file.  \fImtneedfileno\fR
tests whether a file number has been specified in \fImtname\fR (e.g.,
to determine whether or not to query for a file number parameter).
\fImtfname\fR takes \fImtname\fR and a file number and constructs a new
magtape device name in the output string.  \fImtparse\fR parses a magtape
device name into its component parts, and \fImtencode\fR does the reverse.
\fImtcap\fR returns the GTY descriptor of the tapecap entry for the device.
\fIgtyclose\fR should be used to free this descriptor when it is no longer
needed.
.PP
Some older magtape applications programs parse the magtape device name
directly, looking for characters like `['.  These old programs are making
assumptions about the form of a magtape device name which are probably
no longer true.  Such old applications should be rewritten to use the
new MTIO procedures for all magtape device name operations.
.NH 4
MTIO system procedures
.PP
The MTIO interface also includes a number of procedures intended for use
in systems code.  These are summarized in the table below.
.XS
    mtallocate (mtname)
  mtdeallocate (mtname, rewind_tape)
      mtstatus (out, mtname)
       mtclean (level, stale, out)
.XE
.PP
The only new routine here is \fImtclean\fR.  This is called by the
\fImtclean\fR task in the V2.10 SYSTEM package and is used to scan the
magtape status file storage area to delete old magtape position status
files.  Prior to V2.10 these files were stored in the user's UPARM
directory, but in V2.10 the files are stored in \f(CW/tmp\fR so that
multiple IRAF sessions will share the same tape position information.  A
special task is needed to delete old position files in order to protect
against, e.g., one user deleting another user's device position file while
the device is actively in use.
.NH 4
Magtape driver procedures
.PP
All access to the physical magtape device is via the host level IRAF magtape
device driver ZFIOMT.  The driver procedures had to be revised for
V2.10 to add support for the tapecap facility and to accommodate changes in
the way the device position is maintained.  The new driver procedures are
summarized below.
.XS
    zzopmt (device, acmode, devcap, devpos, newfile, chan)
    zzrdmt (chan, buf, maxbytes, offset)
    zzwrmt (chan, buf, nbytes, offset)
    zzwtmt (chan, devpos, status)
    zzstmt (chan, param, value)
    zzclmt (chan, devpos, status)
    zzrwmt (device, devcap, status)
.XE
.PP
The corresponding KI (kernel interface) routines were also modified to
reflect the new calling sequences.  A result of this is that IRAF networking
for magtape devices is incompatible between V2.10 and earlier versions of
IRAF.
.PP
The host level device driver procedures are not normally called directly
in applications code (applications use \fImtopen\fR).  Refer to the comments
in the source file \f(CWos$zfiomt.c\fR for additional details.
.NH 3
MWCS interface
.PP
The MWCS interface provides world coordinate system support for the IRAF
system and applications.  The main changes in the MWCS interface for V2.10
were bug fixes and semantic changes, e.g. various restrictions having to do
with WCS attributes were removed, new function drivers were added, and so
on.  These changes are documented elsewhere in this revisions summary.
.PP
The only interface change affecting MWCS was the addition of the new MWCS
procedure \fImw_show\fR.
.XS
    mw_show (mw, fd, what)
.XE
.PP
This is used to dump a MWCS descriptor to the given output file, and is
useful for examining MWCS descriptors while debugging applications.

.NH
Getting Copies of this Revisions Summary
.PP
Additional copies of this revisions summary are available via anonymous ftp
from node \f(CWiraf.noao.edu\fR in the directory \f(CWiraf/v210\fR, or via
email from \f(CWiraf@noao.edu\fR.